Metadata-Version: 2.4
Name: meihuayishu
Version: 0.1.3
Summary: 梅花易数占卜库 - 支持时间、数字等多种起卦方式
Home-page: https://github.com/pyscaffold/pyscaffold/
Author: 2301_76282700
Author-email: 你的名字 <your.email@example.com>
License: MIT
Project-URL: Homepage, https://gitcode.com/2301_76282700/MeihuaYishu
Project-URL: Repository, https://gitcode.com/2301_76282700/MeihuaYishu.git
Project-URL: Documentation, https://gitcode.com/2301_76282700/MeihuaYishu
Platform: any
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: License :: OSI Approved :: MIT License
Description-Content-Type: text/x-rst
License-File: LICENSE.txt
Provides-Extra: calendar
Requires-Dist: lunardate<1.0.0,>=0.2.0; extra == "calendar"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: mypy>=1.0; extra == "dev"
Dynamic: license-file

===========
MeihuaYishu
===========

梅花易数占卜库 - 让梅花易数占卜变得像一行 Python 代码一样简单。

|PyPI version| |Python versions| |License|

.. |PyPI version| image:: https://img.shields.io/pypi/v/meihuayishu.svg
    :alt: PyPI version
    :target: https://pypi.org/project/meihuayishu/

.. |Python versions| image:: https://img.shields.io/pypi/pyversions/meihuayishu.svg
    :alt: Python versions
    :target: https://pypi.org/project/meihuayishu/

.. |License| image:: https://img.shields.io/github/license/2301_76282700/MeihuaYishu.svg
    :alt: License
    :target: https://gitcode.com/2301_76282700/MeihuaYishu

----

📖 简介
========

**MeihuaYishu** 是一个轻量级的 Python 库，将梅花易数的起卦、解卦逻辑封装成简单易用的 API。

无论你是想在 AI 应用中集成占卜功能、开发占卜类小程序，还是只是对梅花易数感兴趣想用 Python 探索，这个库都能让你几秒钟内上手。

✨ 特性
=======

- **多种起卦方式**：支持时间起卦、数字起卦、随机起卦、声音起卦
- **正统卦名**：内置完整的六十四卦名称（如 "天泽履" 而非 "乾兑"）
- **完整卦象**：返回本卦、互卦、变卦、动爻、五行等信息
- **公历/农历转换**：时间起卦自动转换，用户只需输入公历时间
- **零依赖核心**：核心算法无第三方依赖（农历转换为可选安装）
- **类型安全**：提供数据模型（dataclass），享受 IDE 自动补全
- **统一入口**：`Diviner` 类提供简洁的链式调用接口

📦 安装
========

.. code-block:: bash

    pip install meihuayishu

如果需要农历转换功能（时间起卦必需）：

.. code-block:: bash

    pip install meihuayishu[calendar]

从源码安装（开发模式）：

.. code-block:: bash

    git clone https://gitcode.com/2301_76282700/MeihuaYishu.git
    cd MeihuaYishu
    pip install -e ".[calendar,dev]"

🚀 快速上手
============

最简单的示例 - 当前时间起卦：

.. code-block:: python

    from meihuayishu import Diviner

    # 当前时间起卦（最便捷）
    result = Diviner.now()

    print(f"本卦：{result['benGuaName']} {result['benGuaSymbol']}")
    print(f"互卦：{result['huGuaName']} {result['huGuaSymbol']}")
    print(f"变卦：{result['bianGuaName']} {result['bianGuaSymbol']}")
    print(f"动爻：第{result['movingYao']}爻")

输出示例：

.. code-block:: text

    本卦：山风蛊 ☶☴
    互卦：雷泽归妹 ☳☱
    变卦：巽为风 ☴☴
    动爻：第5爻

📖 使用指南
============

时间起卦
--------

最常用的起卦方式，根据公历时间自动转换为农历：

.. code-block:: python

    from meihuayishu import castByTime

    # 2026年7月20日 10:00 起卦
    result = castByTime(2026, 7, 20, 10)

    print(result["benGuaName"])  # 本卦名称
    print(result["movingYao"])   # 动爻位置

不传小时则使用当前时间：

.. code-block:: python

    result = castByTime(2026, 7, 20)  # 自动使用当前小时

数字起卦
--------

用户提供一组数字，自动分组计算：

.. code-block:: python

    from meihuayishu import castByNumbers

    result = castByNumbers([3, 6, 9])

    # 或使用 Diviner 类
    from meihuayishu import Diviner
    result = Diviner.byNumbers(3, 6, 9)

    print(result["benGuaName"])  # 火水未济

随机起卦
--------

无需任何输入，完全随机生成卦象：

.. code-block:: python

    from meihuayishu import castRandom

    result = castRandom()
    print(result["benGuaName"])

声音起卦
--------

根据听到的声音次数和时辰起卦：

.. code-block:: python

    from meihuayishu import castBySound

    # 听到3声响，在巳时（上午9-11点）
    result = castBySound(3, 10)
    print(result["benGuaName"])

📊 返回数据结构
================

起卦结果是一个字典，包含以下字段：

.. code-block:: python

    {
        # -------- 本卦 --------
        "benGuaName": "山风蛊",           # 本卦名称
        "benGuaSymbol": "☶☴",            # 本卦卦符
        "benGuaDisplay": "☶\n☴",         # 本卦分行显示
        "upperGua": {"name": "艮", ...},  # 上卦详情
        "lowerGua": {"name": "巽", ...},  # 下卦详情
        "upperWuXing": "土",              # 上卦五行
        "lowerWuXing": "木",              # 下卦五行
        "movingYao": 5,                   # 动爻位置（1-6）

        # -------- 互卦 --------
        "huGuaName": "雷泽归妹",
        "huGuaSymbol": "☳☱",
        "huGuaDisplay": "☳\n☱",
        "huUpperGua": {"name": "震", ...},
        "huLowerGua": {"name": "兑", ...},

        # -------- 变卦 --------
        "bianGuaName": "巽为风",
        "bianGuaSymbol": "☴☴",
        "bianGuaDisplay": "☴\n☴",
        "bianUpperGua": {"name": "巽", ...},
        "bianLowerGua": {"name": "巽", ...},
    }

📋 字段详细说明
----------------

.. list-table:: 返回字典字段说明
    :header-rows: 1
    :widths: 15 10 20 25

    * - 字段名
      - 类型
      - 说明
      - 示例
    * - **本卦**
      - 
      - 
      - 
    * - ``benGuaName``
      - str
      - 六十四卦正统名称
      - ``"风水涣"``
    * - ``benGuaSymbol``
      - str
      - 上下卦符号横向拼接
      - ``"☴☵"``
    * - ``benGuaDisplay``
      - str
      - 上下卦符号分行显示（含 ``\\n``）
      - ``"☴\\n☵"``
    * - ``upperGua``
      - dict
      - 上卦详情（含 name/symbol/wuXing/nature）
      - ``{"name":"巽","symbol":"☴",...}``
    * - ``lowerGua``
      - dict
      - 下卦详情
      - ``{"name":"坎","symbol":"☵",...}``
    * - ``upperWuXing``
      - str
      - 上卦五行（金/木/水/火/土）
      - ``"木"``
    * - ``lowerWuXing``
      - str
      - 下卦五行
      - ``"水"``
    * - ``benYaoLines``
      - List[int]
      - 本卦六爻结构（1=阳，0=阴，从下往上）
      - ``[0, 1, 0, 0, 1, 1]``
    * - ``movingYao``
      - int
      - 动爻位置（1=初爻 ~ 6=上爻）
      - ``5``
    * - **互卦**
      - 
      - 
      - 
    * - ``huGuaName``
      - str
      - 互卦名称
      - ``"山雷颐"``
    * - ``huGuaSymbol``
      - str
      - 互卦横向卦符
      - ``"☶☳"``
    * - ``huGuaDisplay``
      - str
      - 互卦竖向卦符
      - ``"☶\\n☳"``
    * - ``huUpperGua``
      - dict
      - 互卦上卦详情
      - ``{"name":"艮","symbol":"☶",...}``
    * - ``huLowerGua``
      - dict
      - 互卦下卦详情
      - ``{"name":"震","symbol":"☳",...}``
    * - ``huUpperWuXing``
      - str
      - 互卦上卦五行
      - ``"土"``
    * - ``huLowerWuXing``
      - str
      - 互卦下卦五行
      - ``"木"``
    * - **变卦**
      - 
      - 
      - 
    * - ``bianGuaName``
      - str
      - 变卦名称
      - ``"山水蒙"``
    * - ``bianGuaSymbol``
      - str
      - 变卦横向卦符
      - ``"☶☵"``
    * - ``bianGuaDisplay``
      - str
      - 变卦竖向卦符
      - ``"☶\\n☵"``
    * - ``bianUpperGua``
      - dict
      - 变卦上卦详情
      - ``{"name":"艮","symbol":"☶",...}``
    * - ``bianLowerGua``
      - dict
      - 变卦下卦详情
      - ``{"name":"坎","symbol":"☵",...}``
    * - ``bianUpperWuXing``
      - str
      - 变卦上卦五行
      - ``"土"``
    * - ``bianLowerWuXing``
      - str
      - 变卦下卦五行
      - ``"水"``
    * - ``bianYaoLines``
      - List[int]
      - 变卦六爻结构
      - ``[0, 1, 0, 0, 0, 1]``
    * - **元数据**
      - 
      - 
      - 
    * - ``method``
      - str
      - 起卦方式（time/numbers/random/sound）
      - ``"numbers"``
    * - ``inputNumbers``
      - List[int]
      - 用户输入的数字（仅数字起卦时存在）
      - ``[5, 6]``
    * - ``solarDate``
      - str
      - 公历日期（仅时间起卦时存在）
      - ``"2026-07-20"``
    * - ``lunarYear``
      - int
      - 农历年（仅时间起卦时存在）
      - ``2026``
    * - ``lunarMonth``
      - int
      - 农历月（仅时间起卦时存在）
      - ``6``
    * - ``lunarDay``
      - int
      - 农历日（仅时间起卦时存在）
      - ``7``
    * - ``dizhiName``
      - str
      - 时辰地支名称（仅时间/声音起卦时存在）
      - ``"巳"``
    * - ``dizhiNumber``
      - int
      - 时辰地支序数（仅时间/声音起卦时存在）
      - ``6``
    * - ``isLeapMonth``
      - bool
      - 是否为闰月（仅时间起卦时存在）
      - ``False``
    * - ``soundCount``
      - int
      - 声音次数（仅声音起卦时存在）
      - ``3``
    * - ``hour``
      - int
      - 小时（仅声音起卦时存在）
      - ``10``

🔄 使用数据模型（类型安全）
===========================

如果你希望获得更好的 IDE 支持和类型提示，可以使用 `models` 模块：

.. code-block:: python

    from meihuayishu import castByTime, DivinationResult

    # 起卦得到字典
    result_dict = castByTime(2026, 7, 20, 10)

    # 转换为结构化对象
    result = DivinationResult.from_core_dict(result_dict)

    # 享受 IDE 自动补全
    print(result.ben_gua.name)      # 本卦名称
    print(result.ben_gua.upper.wu_xing)  # 上卦五行
    print(result.moving_yao)        # 动爻

    # 友好的字符串输出
    print(result)

输出：

.. code-block:: text

    ========================================
    本卦：山风蛊 ☶☴
    互卦：雷泽归妹 ☳☱
    变卦：巽为风 ☴☴
    动爻：第 5 爻
    方式：time
    日期：2026-07-20 巳时
    ========================================

🛠️ 农历工具
=============

库也提供了独立的农历转换工具：

.. code-block:: python

    from meihuayishu import solarToLunar, getDiZhiName

    # 公历转农历
    lunar = solarToLunar(2026, 7, 20)
    print(lunar)  # (2026, 6, 6)  -> 农历二零二六年六月初六

    # 获取时辰名称
    print(getDiZhiName(10))  # 巳

📋 命令行工具（可选）
=====================

如果项目中的 `skeleton.py` 被配置为 CLI 入口，安装后可以使用命令行占卜：

.. code-block:: bash

    meihuayishu --help

（此功能默认为示例，如需使用请自行配置 entry_points）

📄 许可证
==========

本项目使用 MIT 许可证。详见 `LICENSE`_ 文件。

.. _LICENSE: https://gitcode.com/2301_76282700/MeihuaYishu/blob/main/LICENSE.txt

🤝 贡献
========

欢迎提交 Issue 和 Pull Request！

- 项目主页：https://gitcode.com/2301_76282700/MeihuaYishu
- 问题反馈：https://gitcode.com/2301_76282700/MeihuaYishu/issues

📚 相关链接
============

- `GitCode 仓库 <https://gitcode.com/2301_76282700/MeihuaYishu>`_
- `PyPI 页面 <https://pypi.org/project/meihuayishu/>`_

---

.. note::

    本项目使用 PyScaffold 4.6 初始化。
    详见 https://pyscaffold.org/
