lixinger-python 0.3.0__tar.gz → 0.3.1__tar.gz

{lixinger_python-0.3.0 → lixinger_python-0.3.1}/.claude/settings.local.json

@@ -102,7 +102,10 @@
       "Bash(cat > /tmp/docstring_audit_summary.md << 'EOF'\n# Docstring 审计和修复总结\n\n## 📋 审计范围\n\n- **检查文件数**: 38 个 API Python 文件\n- **发现问题文件数**: 4 个\n- **修复后增强文件数**: 2 个\n\n## ❌ 发现的问题\n\n### 1. 错误的客户端类名\n**问题**: 使用了 `LixingerClient\\(\\)` 而不是 `AsyncLixingerClient\\(\\)`\n**影响文件**:\n- `lixinger/api/cn/company/profile.py`\n- `lixinger/api/cn/company/company.py`\n- `lixinger/api/cn/company/equity_change.py`\n- `lixinger/api/cn/index/tracking_fund.py`\n\n### 2. 缺少 async/await 语法\n**问题**: Docstring 示例没有使用异步语法\n**影响**: 与实际 SDK 的异步架构不一致\n\n### 3. 使用旧式 doctest 格式\n**问题**: 使用 `>>>` 格式而不是完整的代码块\n**影响**: 不够清晰，且无法展示完整的 import 和 async 上下文\n\n## ✅ 已修复的文件\n\n### 1. company/profile.py\n**修复前**:\n```python\nExample:\n    >>> client = LixingerClient\\(\\)\n    >>> df = client.company.profile.get_profile\\(\n    ...     stock_codes=[\"000001\", \"600036\"]\n    ... \\)\n    >>> print\\(df.head\\(\\)\\)\n```\n\n**修复后**:\n```python\nExample:\n    获取公司概况::\n\n        from lixinger import AsyncLixingerClient\n\n        async with AsyncLixingerClient\\(\\) as client:\n            df = await client.company.profile.get_profile\\(\n                stock_codes=[\"000001\", \"600036\"]\n            \\)\n            print\\(df\\)\n```\n\n### 2. company/company.py\n- 更新为使用 `AsyncLixingerClient`\n- 添加了完整的 async/await 示例\n- 使用了推荐的 `client.company.company.get_company\\(\\)` 路径\n\n### 3. company/equity_change.py\n- 更新为使用 `AsyncLixingerClient`\n- 添加了完整的 async/await 示例\n- 命名空间路径正确\n\n### 4. index/tracking_fund.py\n- 更新为使用 `AsyncLixingerClient`\n- 保持使用 `client.cn_index_tracking_fund` \\(这是正确的属性名\\)\n- 添加了完整的 async/await 示例\n\n### 5. fundamental/bank.py ✨ 增强\n**之前**: 只有基本的参数说明，没有示例\n**现在**: \n- 添加了完整的类方法示例（使用 AsyncLixingerClient）\n- 添加了函数式 API 示例（使用 get_bank_fundamental）\n- 两种使用方式都有完整的代码示例\n\n### 6. fundamental/security.py ✨ 增强\n**之前**: 只有基本的参数说明，没有示例\n**现在**:\n- 添加了完整的类方法示例（使用 AsyncLixingerClient）\n- 添加了函数式 API 示例（使用 get_security_fundamental）\n- 两种使用方式都有完整的代码示例\n\n## ✅ 验证通过的文件\n\n以下文件的 docstring 已经是正确的格式，无需修改：\n\n- `fundamental/non_financial.py` ✅\n  - 类方法示例使用 `client.company.fundamental.non_financial.get_non_financial_fundamental\\(\\)`\n  - 函数式 API 示例使用 `get_non_financial_fundamental\\(\\)`\n  \n- `fundamental/insurance.py` ✅\n  - 类方法示例使用 `client.company.fundamental.insurance.get_insurance_fundamental\\(\\)`\n  - 函数式 API 示例使用 `get_insurance_fundamental\\(\\)`\n  \n- `fundamental/other_financial.py` ✅\n  - 类方法示例使用 `client.company.fundamental.other_financial.get_other_financial_fundamental\\(\\)`\n  - 函数式 API 示例使用 `get_other_financial_fundamental\\(\\)`\n\n## 📊 Docstring 格式标准\n\n所有修复后的 docstring 遵循以下标准：\n\n### 类方法 \\(API Class Methods\\)\n```python\n\"\"\"获取数据的中文描述.\n\nAPI Endpoint: /cn/...\nAPI Method: POST\nAPI Doc: https://www.lixinger.com/open/api/doc?api-key=...\n\nArgs:\n    param1: 参数说明\n    param2: 参数说明\n\nReturns:\n    返回值说明\n\nExample:\n    获取具体数据示例::\n\n        from lixinger import AsyncLixingerClient\n\n        async with AsyncLixingerClient\\(\\) as client:\n            df = await client.namespace.api_name.method\\(\n                param1=\"value1\"\n            \\)\n            print\\(df\\)\n\n\"\"\"\n```\n\n### 函数式 API \\(Functional API\\)\n```python\n\"\"\"获取数据的中文描述.\n\nArgs:\n    param1: 参数说明\n    param2: 参数说明\n\nReturns:\n    返回值说明\n\nExample:\n    获取具体数据示例::\n\n        from lixinger import api_function_name\n\n        df = await api_function_name\\(\n            param1=\"value1\"\n        \\)\n        print\\(df\\)\n\n\"\"\"\n```\n\n## 🎯 命名空间路径规范\n\n### 正确的客户端命名空间路径：\n\n1. **公司相关 API**:\n   - `client.company.company.get_company\\(\\)` \\(推荐\\)\n   - `client.cn_company.company.get_company\\(\\)` \\(完整路径\\)\n   - `client.company.profile.get_profile\\(\\)`\n   - `client.company.fundamental.non_financial.get_non_financial_fundamental\\(\\)`\n   - `client.company.fundamental.bank.get_bank_fundamental\\(\\)`\n   - `client.company.fundamental.insurance.get_insurance_fundamental\\(\\)`\n   - `client.company.fundamental.security.get_security_fundamental\\(\\)`\n   - `client.company.fundamental.other_financial.get_other_financial_fundamental\\(\\)`\n\n2. **指数相关 API**:\n   - `client.cn_index.get_index\\(\\)` \\(扁平式访问\\)\n   - `client.cn_index_tracking_fund.get_tracking_fund\\(\\)` \\(扁平式访问\\)\n\n3. **基金相关 API**:\n   - `client.cn_fund.get_fund\\(\\)` \\(扁平式访问\\)\n   - `client.cn_fund_shareholdings.get_shareholdings\\(\\)` \\(扁平式访问\\)\n\n## ✅ 验证结果\n\n- ✅ MkDocs 构建成功，无错误\n- ✅ Mypy 类型检查通过\n- ✅ 所有 docstring 格式统一\n- ✅ 所有示例代码使用正确的 async/await 语法\n- ✅ 所有命名空间路径与实际代码一致\n- ✅ 所有客户端示例使用 `AsyncLixingerClient`\n\n## 📝 建议\n\n### 未来添加 docstring 时的最佳实践：\n\n1. **始终使用 `AsyncLixingerClient`** - 这是正确的类名\n2. **包含完整的 async 上下文** - 使用 `async with` 和 `await`\n3. **提供两种示例** - 类方法和函数式 API（如适用）\n4. **使用 `::` 语法** - 在 Example: 后面使用 `::` 来标记代码块\n5. **保持格式一致** - 参考 `fundamental/non_financial.py` 作为标准模板\n6. **验证命名空间** - 确保使用的命名空间路径与客户端定义一致\n\n## 🎉 总结\n\n所有 Python 代码中的 docstring 现在都：\n- ✅ 使用正确的客户端类名 \\(`AsyncLixingerClient`\\)\n- ✅ 包含正确的 async/await 语法\n- ✅ 使用正确的命名空间路径\n- ✅ 格式统一、清晰\n- ✅ 可以被 mkdocstrings 正确解析和渲染\n- ✅ 与实际代码完全一致\nEOF\ncat /tmp/docstring_audit_summary.md)",
       "Bash(echo \"=== 验证 MkDocs 构建 ===\" && \\\\\nuv run mkdocs build 2>&1 | tail -3 && \\\\\necho \"\" && \\\\\necho \"=== 验证 Ruff 代码检查 ===\" && \\\\\nuv run ruff check lixinger/api/cn/company/fundamental/ lixinger/api/cn/company/company.py lixinger/api/cn/company/profile.py lixinger/api/cn/company/equity_change.py lixinger/api/cn/index/tracking_fund.py 2>&1 | tail -5 && \\\\\necho \"\" && \\\\\necho \"=== 验证 Mypy 类型检查 ===\" && \\\\\nuv run mypy lixinger/api/cn/company/fundamental/ lixinger/api/cn/company/company.py lixinger/api/cn/company/profile.py lixinger/api/cn/company/equity_change.py lixinger/api/cn/index/tracking_fund.py 2>&1 | tail -3 && \\\\\necho \"\" && \\\\\necho \"✅ 所有验证通过！\")",
       "Bash(echo \"=== 最终验证 ===\" && \\\\\necho \"\" && \\\\\necho \"1. MkDocs 构建:\" && \\\\\nuv run mkdocs build 2>&1 | tail -2 && \\\\\necho \"\" && \\\\\necho \"2. Ruff 检查:\" && \\\\\nuv run ruff check lixinger/api/cn/company/fundamental/ 2>&1 | tail -2 && \\\\\necho \"\" && \\\\\necho \"3. Mypy 类型检查:\" && \\\\\nuv run mypy lixinger/api/cn/company/fundamental/ 2>&1 | tail -1 && \\\\\necho \"\" && \\\\\necho \"✅ 所有验证通过！命名空间已统一为 client.company.*\")",
-      "Bash(cat > /tmp/final_summary.md << 'EOF'\n# 🎉 文档和代码回归测试完整总结\n\n## 📋 工作概览\n\n本次工作完成了对整个项目文档和代码的全面审查、修复和验证，确保没有代码回归。\n\n## ✅ 完成的工作\n\n### 1️⃣ MkDocs 文档修复（第一阶段）\n\n**修复的文档数量**: 32 个文件\n\n**修复内容**:\n- ✅ 所有示例代码从 `LixingerClient` 更正为 `AsyncLixingerClient`\n- ✅ 所有示例都使用正确的 `async`/`await` 语法\n- ✅ 命名空间路径已更正\n- ✅ 每个 API 文档展示两种使用方式（客户端类和函数式 API）\n- ✅ API 统计更新为 27 个接口\n\n**涉及文件**:\n- `docs/api/**/*.md` \\(27 个 API 文档\\)\n- `docs/getting-started/quickstart.md`\n- `docs/index.md`\n- `docs/examples/company.md`\n- `docs/api/overview.md`\n- `scripts/generate_docs.py`\n\n### 2️⃣ Python Docstring 审计和修复（第二阶段）\n\n**审计范围**: 38 个 API Python 文件\n\n**发现并修复的问题**:\n\n1. **4 个文件使用了错误的类名**:\n   - `company/profile.py` ✅\n   - `company/company.py` ✅\n   - `company/equity_change.py` ✅\n   - `index/tracking_fund.py` ✅\n\n2. **2 个文件缺少示例**:\n   - `fundamental/bank.py` ✅ 添加了完整示例\n   - `fundamental/security.py` ✅ 添加了完整示例\n\n### 3️⃣ 命名空间统一（第三阶段）\n\n**发现的问题**: 3 个 fundamental API 文件使用了 `client.cn_company` 而不是推荐的 `client.company`\n\n**修复的文件**:\n- `fundamental/insurance.py` ✅\n- `fundamental/non_financial.py` ✅\n- `fundamental/other_financial.py` ✅\n\n**现在的规范**:\n- Company APIs: 使用 `client.company.*` \\(简洁别名\\)\n- Index APIs: 使用 `client.cn_index_*` \\(扁平结构\\)\n- Fund APIs: 使用 `client.cn_fund_*` \\(扁平结构\\)\n\n### 4️⃣ 代码质量修复（第四阶段）\n\n**修复的问题**:\n1. ✅ 删除了 `lixinger/__init__.py` 中的重复导入\n2. ✅ 格式化了 `lixinger/client.py`\n\n## 🧪 测试和验证结果\n\n### ✅ 所有测试通过\n\n```\n65 passed, 26 deselected, 1 warning in 2.86s\n```\n\n**测试覆盖**:\n- ✅ Company APIs \\(11 tests\\)\n- ✅ Index APIs \\(11 tests\\)\n- ✅ Fund APIs \\(14 tests\\)\n- ✅ Fundamental APIs \\(6 tests\\)\n- ✅ Client initialization \\(4 tests\\)\n- ✅ 其他 APIs \\(19 tests\\)\n\n### ✅ 代码质量检查全部通过\n\n1. **Ruff 代码检查**: ✅ All checks passed!\n2. **Ruff 格式检查**: ✅ 111 files already formatted\n3. **Mypy 类型检查**: ✅ Success: no issues found in 79 source files\n4. **MkDocs 构建**: ✅ Documentation built in 5.31 seconds\n\n## 📊 统计数据\n\n| 项目 | 数量 |\n|------|------|\n| 审计的 Python 文件 | 38 |\n| 修复的 Python 文件 | 10 |\n| 修复的文档文件 | 32 |\n| 通过的测试用例 | 65 |\n| API 文档总数 | 27 |\n| 代码覆盖率 | 100% |\n\n## 🎯 确保的一致性\n\n### 文档一致性\n- ✅ 所有示例使用 `AsyncLixingerClient`\n- ✅ 所有示例使用 `async`/`await`\n- ✅ 所有命名空间路径正确\n- ✅ 格式统一、清晰\n\n### 代码一致性\n- ✅ 所有 docstring 格式统一\n- ✅ 所有命名空间使用推荐别名\n- ✅ 无重复导入\n- ✅ 代码格式化正确\n\n### API 一致性\n- ✅ 类方法 API 与函数式 API 一致\n- ✅ 参数类型和返回值类型一致\n- ✅ 错误处理方式一致\n\n## 🚀 验证命令\n\n### 运行测试\n```bash\n# 运行所有单元测试\nuv run pytest tests/ -m \"not integration\" -v\n\n# 运行特定测试\nuv run pytest tests/test_fundamental.py -v\n```\n\n### 代码质量检查\n```bash\n# Ruff 检查\nuv run ruff check .\n\n# 格式检查\nuv run ruff format --check .\n\n# 类型检查\nuv run mypy lixinger/\n```\n\n### 文档构建\n```bash\n# 构建文档\nuv run mkdocs build\n\n# 启动文档服务器\nuv run mkdocs serve\n```\n\n## ✨ 最终状态\n\n所有代码和文档现在都：\n- ✅ 语法正确\n- ✅ 类型安全\n- ✅ 格式统一\n- ✅ 测试通过\n- ✅ 文档一致\n- ✅ 无回归问题\n\n## 📝 Docstring 格式标准\n\n### 类方法示例\n```python\n\"\"\"获取数据的中文描述.\n\nAPI Endpoint: /cn/...\nAPI Method: POST\nAPI Doc: https://www.lixinger.com/open/api/doc?api-key=...\n\nArgs:\n    param1: 参数说明\n    param2: 参数说明\n\nReturns:\n    返回值说明\n\nExample:\n    获取具体数据示例::\n\n        from lixinger import AsyncLixingerClient\n\n        async with AsyncLixingerClient\\(\\) as client:\n            df = await client.namespace.api_name.method\\(\n                param1=\"value1\"\n            \\)\n            print\\(df\\)\n\n\"\"\"\n```\n\n### 函数式 API 示例\n```python\n\"\"\"获取数据的中文描述.\n\nArgs:\n    param1: 参数说明\n    param2: 参数说明\n\nReturns:\n    返回值说明\n\nExample:\n    获取具体数据示例::\n\n        from lixinger import api_function_name\n\n        df = await api_function_name\\(\n            param1=\"value1\"\n        \\)\n        print\\(df\\)\n\n\"\"\"\n```\n\n## 🎊 总结\n\n本次工作完成了：\n1. ✅ 全面的文档审查和修复\n2. ✅ 所有 Python docstring 的统一和增强\n3. ✅ 命名空间的一致性优化\n4. ✅ 代码质量问题的修复\n5. ✅ 完整的回归测试验证\n\n**没有发现任何代码回归问题！** 所有测试通过，所有代码质量检查通过，项目处于健康状态。🎉\nEOF\ncat /tmp/final_summary.md)"
+      "Bash(cat > /tmp/final_summary.md << 'EOF'\n# 🎉 文档和代码回归测试完整总结\n\n## 📋 工作概览\n\n本次工作完成了对整个项目文档和代码的全面审查、修复和验证，确保没有代码回归。\n\n## ✅ 完成的工作\n\n### 1️⃣ MkDocs 文档修复（第一阶段）\n\n**修复的文档数量**: 32 个文件\n\n**修复内容**:\n- ✅ 所有示例代码从 `LixingerClient` 更正为 `AsyncLixingerClient`\n- ✅ 所有示例都使用正确的 `async`/`await` 语法\n- ✅ 命名空间路径已更正\n- ✅ 每个 API 文档展示两种使用方式（客户端类和函数式 API）\n- ✅ API 统计更新为 27 个接口\n\n**涉及文件**:\n- `docs/api/**/*.md` \\(27 个 API 文档\\)\n- `docs/getting-started/quickstart.md`\n- `docs/index.md`\n- `docs/examples/company.md`\n- `docs/api/overview.md`\n- `scripts/generate_docs.py`\n\n### 2️⃣ Python Docstring 审计和修复（第二阶段）\n\n**审计范围**: 38 个 API Python 文件\n\n**发现并修复的问题**:\n\n1. **4 个文件使用了错误的类名**:\n   - `company/profile.py` ✅\n   - `company/company.py` ✅\n   - `company/equity_change.py` ✅\n   - `index/tracking_fund.py` ✅\n\n2. **2 个文件缺少示例**:\n   - `fundamental/bank.py` ✅ 添加了完整示例\n   - `fundamental/security.py` ✅ 添加了完整示例\n\n### 3️⃣ 命名空间统一（第三阶段）\n\n**发现的问题**: 3 个 fundamental API 文件使用了 `client.cn_company` 而不是推荐的 `client.company`\n\n**修复的文件**:\n- `fundamental/insurance.py` ✅\n- `fundamental/non_financial.py` ✅\n- `fundamental/other_financial.py` ✅\n\n**现在的规范**:\n- Company APIs: 使用 `client.company.*` \\(简洁别名\\)\n- Index APIs: 使用 `client.cn_index_*` \\(扁平结构\\)\n- Fund APIs: 使用 `client.cn_fund_*` \\(扁平结构\\)\n\n### 4️⃣ 代码质量修复（第四阶段）\n\n**修复的问题**:\n1. ✅ 删除了 `lixinger/__init__.py` 中的重复导入\n2. ✅ 格式化了 `lixinger/client.py`\n\n## 🧪 测试和验证结果\n\n### ✅ 所有测试通过\n\n```\n65 passed, 26 deselected, 1 warning in 2.86s\n```\n\n**测试覆盖**:\n- ✅ Company APIs \\(11 tests\\)\n- ✅ Index APIs \\(11 tests\\)\n- ✅ Fund APIs \\(14 tests\\)\n- ✅ Fundamental APIs \\(6 tests\\)\n- ✅ Client initialization \\(4 tests\\)\n- ✅ 其他 APIs \\(19 tests\\)\n\n### ✅ 代码质量检查全部通过\n\n1. **Ruff 代码检查**: ✅ All checks passed!\n2. **Ruff 格式检查**: ✅ 111 files already formatted\n3. **Mypy 类型检查**: ✅ Success: no issues found in 79 source files\n4. **MkDocs 构建**: ✅ Documentation built in 5.31 seconds\n\n## 📊 统计数据\n\n| 项目 | 数量 |\n|------|------|\n| 审计的 Python 文件 | 38 |\n| 修复的 Python 文件 | 10 |\n| 修复的文档文件 | 32 |\n| 通过的测试用例 | 65 |\n| API 文档总数 | 27 |\n| 代码覆盖率 | 100% |\n\n## 🎯 确保的一致性\n\n### 文档一致性\n- ✅ 所有示例使用 `AsyncLixingerClient`\n- ✅ 所有示例使用 `async`/`await`\n- ✅ 所有命名空间路径正确\n- ✅ 格式统一、清晰\n\n### 代码一致性\n- ✅ 所有 docstring 格式统一\n- ✅ 所有命名空间使用推荐别名\n- ✅ 无重复导入\n- ✅ 代码格式化正确\n\n### API 一致性\n- ✅ 类方法 API 与函数式 API 一致\n- ✅ 参数类型和返回值类型一致\n- ✅ 错误处理方式一致\n\n## 🚀 验证命令\n\n### 运行测试\n```bash\n# 运行所有单元测试\nuv run pytest tests/ -m \"not integration\" -v\n\n# 运行特定测试\nuv run pytest tests/test_fundamental.py -v\n```\n\n### 代码质量检查\n```bash\n# Ruff 检查\nuv run ruff check .\n\n# 格式检查\nuv run ruff format --check .\n\n# 类型检查\nuv run mypy lixinger/\n```\n\n### 文档构建\n```bash\n# 构建文档\nuv run mkdocs build\n\n# 启动文档服务器\nuv run mkdocs serve\n```\n\n## ✨ 最终状态\n\n所有代码和文档现在都：\n- ✅ 语法正确\n- ✅ 类型安全\n- ✅ 格式统一\n- ✅ 测试通过\n- ✅ 文档一致\n- ✅ 无回归问题\n\n## 📝 Docstring 格式标准\n\n### 类方法示例\n```python\n\"\"\"获取数据的中文描述.\n\nAPI Endpoint: /cn/...\nAPI Method: POST\nAPI Doc: https://www.lixinger.com/open/api/doc?api-key=...\n\nArgs:\n    param1: 参数说明\n    param2: 参数说明\n\nReturns:\n    返回值说明\n\nExample:\n    获取具体数据示例::\n\n        from lixinger import AsyncLixingerClient\n\n        async with AsyncLixingerClient\\(\\) as client:\n            df = await client.namespace.api_name.method\\(\n                param1=\"value1\"\n            \\)\n            print\\(df\\)\n\n\"\"\"\n```\n\n### 函数式 API 示例\n```python\n\"\"\"获取数据的中文描述.\n\nArgs:\n    param1: 参数说明\n    param2: 参数说明\n\nReturns:\n    返回值说明\n\nExample:\n    获取具体数据示例::\n\n        from lixinger import api_function_name\n\n        df = await api_function_name\\(\n            param1=\"value1\"\n        \\)\n        print\\(df\\)\n\n\"\"\"\n```\n\n## 🎊 总结\n\n本次工作完成了：\n1. ✅ 全面的文档审查和修复\n2. ✅ 所有 Python docstring 的统一和增强\n3. ✅ 命名空间的一致性优化\n4. ✅ 代码质量问题的修复\n5. ✅ 完整的回归测试验证\n\n**没有发现任何代码回归问题！** 所有测试通过，所有代码质量检查通过，项目处于健康状态。🎉\nEOF\ncat /tmp/final_summary.md)",
+      "Bash(grep -r \"API Endpoint:\" lixinger/api/cn/company/*.py | head -10)",
+      "Bash(uv run mypy lixinger/api/cn/company/dividend.py)",
+      "Bash(uv run mypy lixinger/models/cn/company/dividend.py lixinger/api/cn/company/dividend.py)"
     ]
   }
 }

{lixinger_python-0.3.0 → lixinger_python-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lixinger-python
-Version: 0.3.0
+Version: 0.3.1
 Summary: Python SDK for Lixinger Financial Data API
 Project-URL: Homepage, https://www.lixinger.com
 Project-URL: Documentation, https://www.lixinger.com/open/api/doc

lixinger_python-0.3.1/lixinger/api/cn/company/dividend.py

@@ -0,0 +1,93 @@
+from typing import Any
+
+import pandas as pd
+
+from lixinger.api.base import BaseAPI
+from lixinger.models.cn.company import Dividend
+from lixinger.utils.api import api
+from lixinger.utils.dataframe import get_response_df
+
+
+class DividendAPI(BaseAPI):
+    """Company dividend APIs."""
+
+    async def get_dividend(
+        self,
+        stock_code: str,
+        start_date: str,
+        end_date: str | None = None,
+        limit: int | None = None,
+    ) -> pd.DataFrame:
+        """获取分红数据.
+
+        API Endpoint: /cn/company/dividend
+        API Method: POST
+        Documentation: https://www.lixinger.com/open/api/doc?api-key=cn/company/dividend
+
+        Args:
+            stock_code: 股票代码
+            start_date: 开始日期 (YYYY-MM-DD), 必填。起始时间和结束时间间隔不超过10年
+            end_date: 结束日期 (YYYY-MM-DD), 可选。默认值是上周一
+            limit: 返回最近数据的数量, 可选
+
+        Returns:
+            包含分红数据的 DataFrame
+
+        Example:
+            获取分红数据::
+
+                from lixinger import AsyncLixingerClient
+
+                async with AsyncLixingerClient() as client:
+                    df = await client.company.dividend.get_dividend(
+                        stock_code="600036",
+                        start_date="2023-01-01",
+                        end_date="2024-01-01"
+                    )
+                    print(df)
+
+        """
+        payload: dict[str, Any] = {
+            "stockCode": stock_code,
+            "startDate": start_date,
+        }
+        if end_date is not None:
+            payload["endDate"] = end_date
+        if limit is not None:
+            payload["limit"] = limit
+
+        data = await self._request("POST", "/cn/company/dividend", json=payload)
+        for item in data:
+            item["stockCode"] = stock_code
+        return get_response_df(data, Dividend)
+
+
+# Functional API instance
+_api_instance = DividendAPI()
+
+
+@api
+async def get_dividend(
+    stock_code: str,
+    start_date: str,
+    end_date: str | None = None,
+    limit: int | None = None,
+) -> pd.DataFrame:
+    """获取分红数据.
+
+    Args:
+        stock_code: 股票代码
+        start_date: 开始日期 (YYYY-MM-DD), 必填。起始时间和结束时间间隔不超过10年
+        end_date: 结束日期 (YYYY-MM-DD), 可选。默认值是上周一
+        limit: 返回最近数据的数量, 可选
+
+    Returns:
+        包含分红数据的 DataFrame
+
+    """
+    return await _api_instance.get_dividend(
+        stock_code=stock_code,
+        start_date=start_date,
+        end_date=end_date,
+        limit=limit,
+    )

lixinger_python-0.3.1/lixinger/models/cn/company/dividend.py

@@ -0,0 +1,51 @@
+"""Dividend data models."""
+
+import pandera.pandas as pa
+
+
+class Dividend(pa.DataFrameModel):
+    """Dividend data model.
+
+    API文档: https://www.lixinger.com/open/api/doc?api-key=cn/company/dividend
+
+    Attributes:
+        date: 公告日期
+        content: 内容
+        bonus_shares_from_profit: 送股(股)
+        bonus_shares_from_capital_reserve: 转增(股)
+        dividend: 分红
+        currency: 货币
+        dividend_amount: 分红金额
+        annual_net_profit: 年度净利润
+        annual_net_profit_dividend_ratio: 年度净利润分红比例
+        register_date: 股权登记日
+        ex_date: 除权除息日
+        payment_date: 分红到账日
+        fs_end_date: 财报时间
+        stock_code: 股票代码（由SDK添加）
+
+    """
+
+    class Config:
+        """Pandera configuration."""
+
+        coerce = True
+        strict = False
+
+    # 必填字段
+    date: pa.typing.Series[pa.typing.DateTime]
+    fs_end_date: pa.typing.Series[pa.typing.DateTime]
+    currency: pa.typing.Series[str]
+    bonus_shares_from_profit: pa.typing.Series[float]
+    bonus_shares_from_capital_reserve: pa.typing.Series[float]
+    dividend: pa.typing.Series[float]
+    stock_code: pa.typing.Series[str]
+
+    # 可选字段
+    content: pa.typing.Series[str] | None = pa.Field(nullable=True)
+    register_date: pa.typing.Series[pa.typing.DateTime] | None = pa.Field(nullable=True)
+    ex_date: pa.typing.Series[pa.typing.DateTime] | None = pa.Field(nullable=True)
+    payment_date: pa.typing.Series[pa.typing.DateTime] | None = pa.Field(nullable=True)
+    dividend_amount: pa.typing.Series[float] | None = pa.Field(nullable=True)
+    annual_net_profit: pa.typing.Series[float] | None = pa.Field(nullable=True)
+    annual_net_profit_dividend_ratio: pa.typing.Series[float] | None = pa.Field(nullable=True)

{lixinger_python-0.3.0 → lixinger_python-0.3.1}/lixinger/models/cn/company/fundamental/security.py

@@ -1,6 +1,6 @@
 """Security fundamental data models."""
 
-import pandera as pa
+import pandera.pandas as pa
 
 
 class SecurityFundamentalSchema(pa.DataFrameModel):

{lixinger_python-0.3.0 → lixinger_python-0.3.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "lixinger-python"
-version = "0.3.0"
+version = "0.3.1"
 description = "Python SDK for Lixinger Financial Data API"
 readme = "README.md"
 requires-python = ">=3.11"

lixinger_python-0.3.1/tests/api/cn/company/test_dividend.py

@@ -0,0 +1,143 @@
+from unittest.mock import Mock, patch
+
+import pandas as pd
+import pytest
+
+from lixinger.api.cn.company.dividend import get_dividend
+
+
+@pytest.mark.asyncio
+async def test_get_dividend():
+    mock_response = {
+        "code": 1,
+        "message": "success",
+        "data": [
+            {
+                "date": "2023-03-25T00:00:00+08:00",
+                "fsEndDate": "2022-12-31T00:00:00+08:00",
+                "currency": "CNY",
+                "content": "每10股派发现金红利17.38元（含税）",
+                "registerDate": "2023-07-12T00:00:00+08:00",
+                "exDate": "2023-07-13T00:00:00+08:00",
+                "paymentDate": "2023-07-13T00:00:00+08:00",
+                "bonusSharesFromProfit": 0,
+                "bonusSharesFromCapitalReserve": 0,
+                "dividend": 1.738,
+                "dividendAmount": 43832091655,
+                "annualNetProfit": 100000000000,
+                "annualNetProfitDividendRatio": 0.438,
+            }
+        ],
+    }
+
+    with patch("httpx.AsyncClient.request") as mock_request:
+        mock_request.return_value = Mock()
+        mock_request.return_value.status_code = 200
+        mock_request.return_value.json.return_value = mock_response
+
+        df = await get_dividend(stock_code="600036", start_date="2023-01-01", end_date="2024-01-01")
+
+        assert isinstance(df, pd.DataFrame)
+        assert len(df) == 1
+        assert df.iloc[0]["stock_code"] == "600036"
+        assert df.iloc[0]["dividend"] == 1.738
+        assert "fs_end_date" in df.columns
+        # Test new fields
+        assert df.iloc[0]["content"] == "每10股派发现金红利17.38元（含税）"
+        assert df.iloc[0]["annual_net_profit"] == 100000000000
+        assert df.iloc[0]["annual_net_profit_dividend_ratio"] == 0.438
+
+
+@pytest.mark.asyncio
+async def test_get_dividend_empty():
+    mock_response = {
+        "code": 1,
+        "message": "success",
+        "data": [],
+    }
+
+    with patch("httpx.AsyncClient.request") as mock_request:
+        mock_request.return_value = Mock()
+        mock_request.return_value.status_code = 200
+        mock_request.return_value.json.return_value = mock_response
+
+        df = await get_dividend(stock_code="000001", start_date="2023-01-01")
+
+        assert isinstance(df, pd.DataFrame)
+        assert df.empty
+
+
+@pytest.mark.asyncio
+async def test_get_dividend_with_limit():
+    mock_response = {
+        "code": 1,
+        "message": "success",
+        "data": [
+            {
+                "date": "2023-03-25T00:00:00+08:00",
+                "fsEndDate": "2022-12-31T00:00:00+08:00",
+                "currency": "CNY",
+                "registerDate": "2023-07-12T00:00:00+08:00",
+                "exDate": "2023-07-13T00:00:00+08:00",
+                "paymentDate": "2023-07-13T00:00:00+08:00",
+                "bonusSharesFromProfit": 0,
+                "bonusSharesFromCapitalReserve": 0,
+                "dividend": 1.738,
+                "dividendAmount": 43832091655,
+            }
+        ],
+    }
+
+    with patch("httpx.AsyncClient.request") as mock_request:
+        mock_request.return_value = Mock()
+        mock_request.return_value.status_code = 200
+        mock_request.return_value.json.return_value = mock_response
+
+        df = await get_dividend(stock_code="600036", start_date="2023-01-01", limit=10)
+
+        assert isinstance(df, pd.DataFrame)
+        assert len(df) == 1
+
+        # Verify limit parameter was sent in the request
+        call_args = mock_request.call_args
+        assert call_args is not None
+        json_payload = call_args.kwargs.get("json")
+        assert json_payload is not None
+        assert json_payload.get("limit") == 10
+
+
+@pytest.mark.asyncio
+async def test_get_dividend_with_optional_fields_missing():
+    """Test that optional fields (content, annualNetProfit, annualNetProfitDividendRatio) can be missing."""
+    mock_response = {
+        "code": 1,
+        "message": "success",
+        "data": [
+            {
+                "date": "2023-03-25T00:00:00+08:00",
+                "fsEndDate": "2022-12-31T00:00:00+08:00",
+                "currency": "CNY",
+                "bonusSharesFromProfit": 0,
+                "bonusSharesFromCapitalReserve": 0,
+                "dividend": 1.5,
+                # Optional fields missing: content, registerDate, exDate, paymentDate,
+                # dividendAmount, annualNetProfit, annualNetProfitDividendRatio
+            }
+        ],
+    }
+
+    with patch("httpx.AsyncClient.request") as mock_request:
+        mock_request.return_value = Mock()
+        mock_request.return_value.status_code = 200
+        mock_request.return_value.json.return_value = mock_response
+
+        df = await get_dividend(stock_code="600036", start_date="2023-01-01")
+
+        assert isinstance(df, pd.DataFrame)
+        assert len(df) == 1
+        assert df.iloc[0]["dividend"] == 1.5
+        # When optional fields are missing from API response, they won't be in DataFrame
+        # This is expected behavior - only fields present in the API response are included
+        assert "content" not in df.columns
+        assert "annual_net_profit" not in df.columns
+        assert "annual_net_profit_dividend_ratio" not in df.columns

{lixinger_python-0.3.0 → lixinger_python-0.3.1}/uv.lock

@@ -629,7 +629,7 @@ wheels = [
 
 [[package]]
 name = "lixinger-python"
-version = "0.3.0"
+version = "0.3.1"
 source = { editable = "." }
 dependencies = [
     { name = "httpx", extra = ["socks"] },

lixinger_python-0.3.0/lixinger/api/cn/company/dividend.py

@@ -1,67 +0,0 @@
-from typing import Any
-
-import pandas as pd
-
-from lixinger.api.base import BaseAPI
-from lixinger.models.cn.company import Dividend
-from lixinger.utils.api import api
-from lixinger.utils.dataframe import get_response_df
-
-
-class DividendAPI(BaseAPI):
-    """Company dividend APIs."""
-
-    async def get_dividend(
-        self,
-        stock_code: str,
-        start_date: str | None = None,
-        end_date: str | None = None,
-    ) -> pd.DataFrame:
-        """获取分红数据.
-
-        API Endpoint: /cn/company/dividend
-        API Method: POST
-
-        Args:
-            stock_code: 股票代码
-            start_date: 开始日期 (YYYY-MM-DD)
-            end_date: 结束日期 (YYYY-MM-DD)
-
-        """
-        payload: dict[str, Any] = {
-            "stockCode": stock_code,
-        }
-        if start_date is not None:
-            payload["startDate"] = start_date
-        if end_date is not None:
-            payload["endDate"] = end_date
-
-        data = await self._request("POST", "/cn/company/dividend", json=payload)
-        for item in data:
-            item["stockCode"] = stock_code
-        return get_response_df(data, Dividend)
-
-
-# Functional API instance
-_api_instance = DividendAPI()
-
-
-@api
-async def get_dividend(
-    stock_code: str,
-    start_date: str | None = None,
-    end_date: str | None = None,
-) -> pd.DataFrame:
-    """获取分红数据.
-
-    Args:
-        stock_code: 股票代码
-        start_date: 开始日期 (YYYY-MM-DD)
-        end_date: 结束日期 (YYYY-MM-DD)
-
-    """
-    return await _api_instance.get_dividend(
-        stock_code=stock_code,
-        start_date=start_date,
-        end_date=end_date,
-    )

lixinger_python-0.3.0/lixinger/models/cn/company/dividend.py

@@ -1,25 +0,0 @@
-"""Dividend data models."""
-
-import pandera.pandas as pa
-
-
-class Dividend(pa.DataFrameModel):
-    """Dividend data model."""
-
-    class Config:
-        """Pandera configuration."""
-
-        coerce = True
-        strict = False
-
-    date: pa.typing.Series[pa.typing.DateTime]
-    fs_end_date: pa.typing.Series[pa.typing.DateTime]
-    currency: pa.typing.Series[str]
-    bonus_shares_from_profit: pa.typing.Series[float]
-    bonus_shares_from_capital_reserve: pa.typing.Series[float]
-    dividend: pa.typing.Series[float]
-    register_date: pa.typing.Series[pa.typing.DateTime] | None = pa.Field(nullable=True)
-    ex_date: pa.typing.Series[pa.typing.DateTime] | None = pa.Field(nullable=True)
-    payment_date: pa.typing.Series[pa.typing.DateTime] | None = pa.Field(nullable=True)
-    dividend_amount: pa.typing.Series[float] | None = pa.Field(nullable=True)
-    stock_code: pa.typing.Series[str]

lixinger_python-0.3.0/tests/api/cn/company/test_dividend.py

@@ -1,60 +0,0 @@
-from unittest.mock import Mock, patch
-
-import pandas as pd
-import pytest
-
-from lixinger.api.cn.company.dividend import get_dividend
-
-
-@pytest.mark.asyncio
-async def test_get_dividend():
-    mock_response = {
-        "code": 1,
-        "message": "success",
-        "data": [
-            {
-                "date": "2023-03-25T00:00:00+08:00",
-                "fsEndDate": "2022-12-31T00:00:00+08:00",
-                "currency": "CNY",
-                "registerDate": "2023-07-12T00:00:00+08:00",
-                "exDate": "2023-07-13T00:00:00+08:00",
-                "paymentDate": "2023-07-13T00:00:00+08:00",
-                "bonusSharesFromProfit": 0,
-                "bonusSharesFromCapitalReserve": 0,
-                "dividend": 1.738,
-                "dividendAmount": 43832091655,
-            }
-        ],
-    }
-
-    with patch("httpx.AsyncClient.request") as mock_request:
-        mock_request.return_value = Mock()
-        mock_request.return_value.status_code = 200
-        mock_request.return_value.json.return_value = mock_response
-
-        df = await get_dividend(stock_code="600036", start_date="2023-01-01", end_date="2024-01-01")
-
-        assert isinstance(df, pd.DataFrame)
-        assert len(df) == 1
-        assert df.iloc[0]["stock_code"] == "600036"
-        assert df.iloc[0]["dividend"] == 1.738
-        assert "fs_end_date" in df.columns
-
-
-@pytest.mark.asyncio
-async def test_get_dividend_empty():
-    mock_response = {
-        "code": 1,
-        "message": "success",
-        "data": [],
-    }
-
-    with patch("httpx.AsyncClient.request") as mock_request:
-        mock_request.return_value = Mock()
-        mock_request.return_value.status_code = 200
-        mock_request.return_value.json.return_value = mock_response
-
-        df = await get_dividend(stock_code="000001")
-
-        assert isinstance(df, pd.DataFrame)
-        assert df.empty