lixinger-python 0.1.2__tar.gz → 0.2.0__tar.gz

lixinger_python-0.2.0/.claude/settings.local.json

@@ -0,0 +1,81 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(tree -L 3 -I \".venv|venv|__pycache__|*.pyc\")",
+      "Bash(find . -type d -not -path ./.venv/* -not -path ./.git/*)",
+      "Bash(uv --version)",
+      "WebFetch(domain:www.lixinger.com)",
+      "Bash(uv add python-dotenv)",
+      "Bash(python -c \"from lixinger.config import get_config_from_env; print\\(''Config module loads successfully''\\)\")",
+      "Bash(python -c \"from lixinger import LixingerClient; print\\(''LixingerClient imports successfully''\\)\")",
+      "Bash(ls -la .env*)",
+      "Bash(python -c \"\nimport sys\nsys.path.insert\\(0, ''.''\\)\n\n# Test that api_key parameter doesn''t exist\nfrom lixinger.client import LixingerClient\nimport inspect\n\nsig = inspect.signature\\(LixingerClient.__init__\\)\nparams = list\\(sig.parameters.keys\\(\\)\\)\nprint\\(''LixingerClient.__init__ parameters:'', params\\)\nprint\\(\\)\nprint\\(''✓ api_key parameter removed!'' if ''api_key'' not in params else ''✗ api_key still exists!''\\)\nprint\\(''✓ Only keyword-only parameters remain''\\)\n\")",
+      "Bash(uv add --dev pre-commit)",
+      "Bash(uv pip install -e .)",
+      "Bash(python -c \"import lixinger; print\\(''✓ lixinger imports successfully''\\)\")",
+      "Bash(python -c \"from lixinger import LixingerClient; print\\(''✓ LixingerClient imports successfully''\\)\")",
+      "Bash(python -c \"import yaml; yaml.safe_load\\(open\\(''codecov.yml''\\)\\)\")",
+      "Bash(python3 -c \"\nimport yaml\n\nwith open\\(''codecov.yml'', ''r''\\) as f:\n    config = yaml.safe_load\\(f\\)\n\nprint\\(''✅ Codecov Configuration Validation\\\\n''\\)\nprint\\(f''Project Coverage Target: {config[\"\"coverage\"\"][\"\"status\"\"][\"\"project\"\"][\"\"default\"\"][\"\"target\"\"]}''\\)\nprint\\(f''Project Threshold: {config[\"\"coverage\"\"][\"\"status\"\"][\"\"project\"\"][\"\"default\"\"][\"\"threshold\"\"]}''\\)\nprint\\(f''Patch Coverage Target: {config[\"\"coverage\"\"][\"\"status\"\"][\"\"patch\"\"][\"\"default\"\"][\"\"target\"\"]}''\\)\nprint\\(f''Patch Threshold: {config[\"\"coverage\"\"][\"\"status\"\"][\"\"patch\"\"][\"\"default\"\"][\"\"threshold\"\"]}''\\)\nprint\\(f''\\\\nFlags Configured: {list\\(config[\"\"flags\"\"].keys\\(\\)\\)}''\\)\nprint\\(f''Components: {len\\(config[\"\"component_management\"\"][\"\"individual_components\"\"]\\)} defined''\\)\nprint\\(f''GitHub Annotations: {config[\"\"github_checks\"\"][\"\"annotations\"\"]}''\\)\nprint\\(f''\\\\n✅ All fields are valid!''\\)\n\")",
+      "Bash(curl --data-binary @codecov.yml https://codecov.io/validate)",
+      "WebFetch(domain:docs.codecov.com)",
+      "WebSearch",
+      "Bash(python3 -c \"import yaml; yaml.safe_load\\(open\\(''''codecov.yml''''\\)\\)\")",
+      "Bash(ls -1 codecov.yml docs/CODECOV*.md)",
+      "Bash(curl -s --data-binary @codecov.yml https://codecov.io/validate)",
+      "Bash(uv run ruff check /Users/JianGuo/Documents/CursorProject/lixinger-python/AGENTS.md)",
+      "Bash(ls -la /Users/JianGuo/Documents/CursorProject/lixinger-python/*.md)",
+      "Bash(tree /Users/JianGuo/Documents/CursorProject/lixinger-python/lixinger/api -L 3)",
+      "Bash(tree /Users/JianGuo/Documents/CursorProject/lixinger-python/lixinger/models -L 3)",
+      "Bash(uv run pytest tests/ -m \"not integration\" -v)",
+      "Bash(uv run ruff check lixinger/)",
+      "Bash(uv run mypy lixinger/)",
+      "Bash(uv run pytest tests/ -m \"not integration\" --tb=short)",
+      "Bash(tree /Users/JianGuo/Documents/CursorProject/lixinger-python/lixinger -L 4 -I __pycache__)",
+      "Bash(uv run ruff check .)",
+      "Bash(find /Users/JianGuo/Documents/CursorProject/lixinger-python/examples -name *.py)",
+      "Bash(tree /Users/JianGuo/Documents/CursorProject/lixinger-python/lixinger -L 4 -I '__pycache__|*.pyc' --dirsfirst)",
+      "Bash(uv run pytest tests/ -m \"not integration\" --tb=short -q)",
+      "Bash(uv run pytest tests/ -m \"not integration\" -q)",
+      "Bash(uv add:*)",
+      "Bash(uv run python:*)",
+      "Bash(uv run mkdocs build:*)",
+      "Bash(git check-ignore:*)",
+      "Bash(uv run pytest:*)",
+      "Bash(uv run ruff check:*)",
+      "Bash(uv run ruff format:*)",
+      "Bash(lsof:*)",
+      "Bash(xargs kill:*)",
+      "Bash(chmod +x scripts/publish.sh)",
+      "Bash(chmod +x scripts/check_before_publish.py)",
+      "Bash(uv run twine check dist/*)",
+      "Bash(unzip -l dist/lixinger_python-0.1.0-py3-none-any.whl | head -30)",
+      "Bash(find lixinger -type f -name \"*.py\" -exec grep -l \"^import pandera as pa\" {} \\\\;)",
+      "Bash(find lixinger -type f -name \"*.py\" -exec sed -i '' 's/^import pandera as pa$/import pandera.pandas as pa/' {} \\\\;)",
+      "Bash(uv pip list 2>/dev/null | grep -E \"\\(pandas|llama\\)\" || echo \"No packages found\")",
+      "Bash(uv pip index versions llama-index 2>/dev/null | head -20 || echo \"Checking package info...\")",
+      "Bash(pip index versions llama-index 2>&1 | head -5 || uv pip show llama-index 2>&1 | head -10 || echo \"Checking...\")",
+      "WebFetch(domain:pypi.org)",
+      "Bash(curl -s \"https://pypi.org/pypi/llama-index/0.14.15/json\" | python3 -c \"import json,sys; data=json.load\\(sys.stdin\\); deps=[d for d in data['info'].get\\('requires_dist',[]\\) if 'pandas' in d.lower\\(\\)]; print\\('\\\\n'.join\\(deps\\) if deps else 'No pandas dependency'\\)\")",
+      "Bash(curl -s \"https://pypi.org/pypi/llama-index-readers-file/0.5.6/json\" | python3 -c \"import json,sys; data=json.load\\(sys.stdin\\); deps=[d for d in data['info'].get\\('requires_dist',[]\\) if 'pandas' in d.lower\\(\\)]; print\\('\\\\n'.join\\(deps\\) if deps else 'No pandas dependency'\\)\")",
+      "Bash(uv sync)",
+      "Bash(wc -l /Users/JianGuo/Documents/CursorProject/lixinger-python/tests/*.py | tail -1)",
+      "Bash(uv pip list | grep -E \"pytest|asyncio\")",
+      "Bash(uv run mypy lixinger/utils/)",
+      "Bash(uv run mypy lixinger/api/base.py)",
+      "Bash(uv run mypy lixinger/api/cn/)",
+      "Bash(uv run mypy lixinger/client.py)",
+      "Bash(python3 -c \"from lixinger import AsyncLixingerClient; print\\('✅ AsyncLixingerClient imported'\\)\")",
+      "Bash(python3 -c \"from lixinger import LixingerClient\" 2>&1 || echo \"✅ LixingerClient correctly removed\")",
+      "Bash(grep -l \"LixingerClient\\\\|with client\\\\|client\\\\.company\\\\.get\" --include=\"*.md\" -r . 2>/dev/null | grep -v \".venv\" | grep -v \"site/\" | grep -v \".git/\" | head -20)",
+      "Bash(grep -n \"from lixinger import\\\\|LixingerClient\\\\|with client\\\\|def main\" docs/getting-started/quickstart.md docs/index.md docs/examples/*.md 2>/dev/null | head -40)",
+      "Bash(cat > /tmp/async_docs_update_summary.md << 'EOF'\n# 异步文档更新总结\n\n## ✅ 已完成更新的文件\n\n### 核心文档\n1. **README.md** - 完全重写，展示异步特性\n2. **SETUP.md** - 更新所有示例为 async/await\n3. **CHANGELOG.md** - 添加 v2.0.0 迁移指南\n4. **AGENTS.md** - 强调 async 要求，更新所有示例\n5. **ADD_NEW_API_QUICK.md** - 所有模板改为 async\n\n### 开发指南\n6. **docs/getting-started/quickstart.md** - 完全重写为异步版本\n   - 添加醒目的异步警告\n   - 所有示例使用 asyncio.run\\(main\\(\\)\\)\n   - 新增并发请求示例\n   - 新增 Jupyter 用法说明\n\n7. **docs/index.md** - 更新首页示例为异步\n\n### 示例文件\n8. **examples/company_example.py** - 异步版本\n9. **examples/company_profile_example.py** - 异步版本\n\n## ⚠️ 需要检查的文件\n\n以下文件可能包含同步代码示例，需要批量更新：\n\n### API 文档（自动生成部分）\n- `docs/api/company/*.md` \\(9个文件\\)\n- `docs/api/index/*.md` \\(7个文件\\)\n- `docs/api/fund/*.md` \\(7个文件\\)\n\n**处理建议**: 这些文件由 mkdocstrings 自动生成，只要源码的 docstrings 是正确的（已完成），重新生成文档即可。\n\n### 示例文档\n- `docs/examples/company.md`\n- `docs/examples/fund.md`\n- `docs/examples/index.md`\n\n### 其他配置文档\n- `docs/getting-started/configuration.md`\n- `docs/getting-started/installation.md`\n\n## 🔧 修复步骤\n\n### 方法1：重新生成 API 文档（推荐）\n```bash\nuv run python scripts/generate_docs.py\n```\n这会基于最新的 docstrings 重新生成所有 API 文档。\n\n### 方法2：手动修复剩余文件\n逐个检查并更新 docs/examples/*.md 等手写文档文件。\n\n## 📋 检查清单\n\n- [x] README.md\n- [x] SETUP.md\n- [x] CHANGELOG.md\n- [x] AGENTS.md\n- [x] ADD_NEW_API_QUICK.md\n- [x] docs/getting-started/quickstart.md\n- [x] docs/index.md\n- [x] examples/*.py\n- [ ] docs/examples/*.md \\(3个\\)\n- [ ] docs/getting-started/configuration.md\n- [ ] docs/getting-started/installation.md\n- [ ] docs/api/*/*.md \\(重新生成\\)\n\n## 🎯 关键改进点\n\n所有更新的文档都包含：\n1. ✅ 使用 `AsyncLixingerClient` 而不是 `LixingerClient`\n2. ✅ 使用 `async def main\\(\\)` 包装代码\n3. ✅ 使用 `async with` 上下文管理器\n4. ✅ 所有 API 调用前加 `await`\n5. ✅ 使用 `asyncio.run\\(main\\(\\)\\)` 运行\n6. ✅ 说明 Jupyter 可以直接使用 await\n7. ✅ 展示并发请求示例（where appropriate）\nEOF\ncat /tmp/async_docs_update_summary.md)",
+      "Bash(ls -lah scripts/*.py | grep -E \"\\(convert|fix\\)\")",
+      "Bash(ls -1 scripts/*.py)",
+      "Bash(grep -rn \"client\\\\.company\\\\.get_company\\\\|client\\\\.company\\\\.get_profile\" --include=\"*.md\" . 2>/dev/null | grep -v \".venv\\\\|site\\\\|.git\" | head -20)",
+      "Bash(cat > /tmp/fix_api_paths.sh << 'EOF'\n#!/bin/bash\n# Fix incorrect API paths in documentation\n\n# Find all markdown files \\(excluding .venv, site, .git\\)\nfind . -name \"*.md\" -type f ! -path \"./.venv/*\" ! -path \"./site/*\" ! -path \"./.git/*\" | while read file; do\n    # Check if file contains the incorrect patterns\n    if grep -q \"client\\\\.company\\\\.get_company\\\\|client\\\\.company\\\\.get_profile\" \"$file\"; then\n        echo \"Fixing: $file\"\n        \n        # Fix get_company\n        sed -i '' 's/client\\\\.company\\\\.get_company/client.company.company.get_company/g' \"$file\"\n        \n        # Fix get_profile\n        sed -i '' 's/client\\\\.company\\\\.get_profile/client.company.profile.get_profile/g' \"$file\"\n    fi\ndone\n\necho \"Done!\"\nEOF\n\nchmod +x /tmp/fix_api_paths.sh\n/tmp/fix_api_paths.sh)",
+      "Bash(grep -rn \"client\\\\.company\\\\.get_company\\\\|client\\\\.company\\\\.get_profile\" --include=\"*.md\" . 2>/dev/null | grep -v \".venv\\\\|site\\\\|.git\\\\|\\\\.company\\\\.company\\\\|\\\\.company\\\\.profile\" | head -5)",
+      "Bash(cat > /tmp/api_path_fix_summary.md << 'EOF'\n# API 路径修复总结\n\n## 🐛 发现的问题\n\n文档中使用了错误的 API 调用路径：\n\n### ❌ 错误示例\n```python\nclient.company.get_company\\(...\\)  # 错误！\nclient.company.get_profile\\(...\\)  # 错误！\n```\n\n### ✅ 正确示例\n```python\nclient.company.company.get_company\\(...\\)  # 正确\nclient.company.profile.get_profile\\(...\\)  # 正确\n```\n\n## 📐 客户端结构\n\n```python\nAsyncLixingerClient\n├── company \\(CompanyNamespace\\)\n│   ├── company \\(CompanyAPI\\)\n│   │   └── get_company\\(\\)\n│   ├── profile \\(CompanyProfileAPI\\)\n│   │   └── get_profile\\(\\)\n│   ├── fundamental \\(FundamentalAPI\\)\n│   │   ├── get_non_financial\\(\\)\n│   │   ├── get_bank\\(\\)\n│   │   └── ...\n│   ├── candlestick \\(CandlestickAPI\\)\n│   ├── equity_change \\(EquityChangeAPI\\)\n│   ├── fs\n│   │   └── non_financial \\(NonFinancialStatementAPI\\)\n│   ├── indices \\(IndicesAPI\\)\n│   ├── dividend \\(DividendAPI\\)\n│   └── announcement \\(AnnouncementAPI\\)\n│\n├── cn_index \\(IndexAPI\\)\n├── cn_index_constituents \\(ConstituentsAPI\\)\n└── ...\n```\n\n## ✅ 修复的文件（7个）\n\n1. **README.md** - 5处修复\n   - 基础用法示例\n   - 并发请求示例\n   - Jupyter 用法\n   - Import 示例\n\n2. **SETUP.md** - 4处修复\n   - 使用示例\n   - 配置覆盖\n   - Jupyter 示例\n   - 测试示例\n\n3. **CHANGELOG.md** - 2处修复\n   - v0.x 示例\n   - v2.0 迁移示例\n\n4. **docs/getting-started/quickstart.md** - 3处修复\n   - 并发查询示例\n   - 客户端配置示例\n   - Jupyter 用法\n\n5. **docs/index.md** - 1处修复\n   - Jupyter 使用示例\n\n6. **docs/examples/company.md** - 3处修复\n   - 并发查询示例\n\n7. **PUBLISHING.md** - 1处修复\n   - 示例代码\n\n## 🎯 正确的 API 调用模式\n\n### Company APIs\n```python\n# Company information\nawait client.company.company.get_company\\(stock_codes=[\"000001\"]\\)\n\n# Company profile  \nawait client.company.profile.get_profile\\(stock_codes=[\"000001\"]\\)\n\n# Fundamental data\nawait client.company.fundamental.get_non_financial\\(\n    stock_codes=[\"000001\"],\n    metrics=[\"pe\", \"pb\"]\n\\)\n\n# Candlestick data\nawait client.company.candlestick.get_candlestick\\(...\\)\n\n# Equity change\nawait client.company.equity_change.get_equity_change\\(...\\)\n\n# Financial statements\nawait client.company.fs.non_financial.get_non_financial_statements\\(...\\)\n\n# Indices membership\nawait client.company.indices.get_indices\\(...\\)\n\n# Dividend\nawait client.company.dividend.get_dividend\\(...\\)\n\n# Announcements\nawait client.company.announcement.get_announcement\\(...\\)\n```\n\n### Index APIs\n```python\n# 使用扁平访问（旧版兼容）\nawait client.cn_index.get_index\\(...\\)\nawait client.cn_index_constituents.get_constituents\\(...\\)\nawait client.cn_index_candlestick.get_candlestick\\(...\\)\n```\n\n### Fund APIs\n```python\n# 使用扁平访问（旧版兼容）\nawait client.cn_fund.get_fund\\(...\\)\nawait client.cn_fund_profile.get_profile\\(...\\)\nawait client.cn_fund_candlestick.get_candlestick\\(...\\)\n```\n\n## 📊 修复统计\n\n- **文件数量**: 7个文档文件\n- **修复点**: 19处 API 调用路径\n- **覆盖范围**: \n  - ✅ README.md\n  - ✅ SETUP.md  \n  - ✅ CHANGELOG.md\n  - ✅ 快速入门文档\n  - ✅ 首页文档\n  - ✅ 示例文档\n  - ✅ 发布文档\n\n## ✨ 验证\n\n所有修复后的代码现在都使用正确的 API 路径：\n- `client.company.company.get_company\\(\\)` ✅\n- `client.company.profile.get_profile\\(\\)` ✅\n- `client.company.fundamental.get_non_financial\\(\\)` ✅\n\n用户现在可以直接复制文档中的代码并成功运行！\nEOF\ncat /tmp/api_path_fix_summary.md)",
+      "Bash(grep -rn \"client\\\\.[a-z_]*\\\\.\\\\\\(get_\\\\|fetch_\\\\\\)\" --include=\"*.md\" README.md SETUP.md docs/getting-started/quickstart.md 2>/dev/null | grep -v \"company\\\\.company\\\\|company\\\\.profile\\\\|company\\\\.fundamental\\\\|company\\\\.candlestick\\\\|company\\\\.equity_change\\\\|company\\\\.fs\\\\|company\\\\.indices\\\\|company\\\\.dividend\\\\|company\\\\.announcement\\\\|cn_index\\\\|cn_fund\" | head -10)"
+    ]
+  }
+}

lixinger_python-0.2.0/ADD_NEW_API_QUICK.md

@@ -0,0 +1,203 @@
+# 📚 添加新 API - 快速参考
+
+## ⚠️ 重要：SDK 采用完全异步架构
+
+所有 API 方法必须使用 `async def` 并用 `await` 调用。
+
+## 🎯 三步添加新 API
+
+### 1️⃣ 写代码 + Docstrings
+
+```python
+# lixinger/api/cn/company/your_api.py
+
+class YourAPI(BaseAPI):
+    """Your API description."""
+
+    async def get_data(
+        self,
+        stock_code: str,
+        param: str | None = None,
+    ) -> pd.DataFrame:
+        """一行描述.
+
+        Args:
+            stock_code: 股票代码
+            param: 参数说明
+
+        Returns:
+            返回值说明
+
+        Example:
+            >>> import asyncio
+            >>> async def main():
+            ...     client = AsyncLixingerClient()
+            ...     df = await client.your_api.get_data("000001")
+            >>> asyncio.run(main())
+
+        """
+        # 使用 await 调用 _request
+        data = await self._request("POST", "/endpoint", json=payload)
+        return get_response_df(data, Model)
+```
+
+**关键**：
+- ✅ 使用 `async def` 定义所有方法
+- ✅ 使用 `await self._request(...)`
+- ✅ 使用 **Google-style docstrings** + 完整**类型注解**
+- ✅ Example 中展示 async/await 用法
+
+---
+
+### 2️⃣ 生成文档
+
+**方式 A: 自动生成（推荐）**
+
+```bash
+# 1. 编辑 scripts/generate_docs.py，添加配置
+vim scripts/generate_docs.py
+
+# 2. 运行生成脚本
+uv run python scripts/generate_docs.py
+```
+
+**方式 B: 手动创建**
+
+```bash
+# 创建文档文件
+cat > docs/api/company/your_api.md << 'EOF'
+# API 名称
+
+## 类参考
+
+::: lixinger.api.cn.company.your_api.YourAPI
+    options:
+      show_root_heading: true
+      show_source: true
+EOF
+```
+
+---
+
+### 3️⃣ 预览 & 部署
+
+```bash
+# 本地预览
+uv run mkdocs serve
+
+# 部署到线上
+uv run mkdocs gh-deploy
+```
+
+---
+
+## ✅ 检查清单
+
+添加新 API 时确保：
+
+- [ ] **所有方法使用 `async def`**
+- [ ] **所有 `_request` 调用使用 `await`**
+- [ ] 代码使用 Google-style docstrings
+- [ ] 包含 `Args`, `Returns`, `Example` 部分
+- [ ] **Example 展示 async/await 用法**
+- [ ] 完整的类型注解（`str`, `int | None`, `pd.DataFrame` 等）
+- [ ] 运行了文档生成脚本或手动创建了文档页面
+- [ ] 本地预览文档正常：`uv run mkdocs serve`
+- [ ] **测试函数使用 `async def` 和 `@pytest.mark.asyncio`**
+
+---
+
+## 🔑 关键点
+
+### ✅ DO (推荐做法)
+
+```python
+async def get_data(self, code: str) -> pd.DataFrame:
+    """获取数据.
+
+    Args:
+        code: 股票代码
+
+    Returns:
+        数据 DataFrame
+
+    Example:
+        >>> import asyncio
+        >>> async def main():
+        ...     df = await get_data("000001")
+        >>> asyncio.run(main())
+
+    """
+    data = await self._request("POST", "/endpoint", json={"code": code})
+    return get_response_df(data, Model)
+```
+
+### ❌ DON'T (避免)
+
+```python
+def get_data(self, code):  # ❌ 缺少 async、类型注解
+    """Get data."""        # ❌ Docstring 太简单、缺少 Example
+    # ❌ 缺少 await
+    data = self._request("POST", "/endpoint", json={"code": code})
+    return data
+```
+
+---
+
+## 📖 Docstring 最小模板
+
+```python
+async def method_name(param: type) -> return_type:
+    """一行简短描述.
+
+    Args:
+        param: 参数说明
+
+    Returns:
+        返回值说明
+
+    Example:
+        >>> import asyncio
+        >>> async def main():
+        ...     result = await method_name("value")
+        >>> asyncio.run(main())
+
+    """
+    data = await self._request("POST", "/endpoint", json={"param": param})
+    return data
+```
+
+---
+
+## 🧪 测试模板
+
+```python
+import pytest
+
+@pytest.mark.asyncio
+async def test_your_api(monkeypatch):
+    """测试你的 API."""
+
+    # Mock async _request
+    async def mock_request(*args, **kwargs):
+        return [{"field": "value"}]
+
+    monkeypatch.setattr(YourAPI, "_request", mock_request)
+    monkeypatch.setenv("LIXINGER_API_KEY", "test_key")
+
+    # 使用 await 调用
+    client = AsyncLixingerClient()
+    df = await client.your_api.get_data("000001")
+
+    assert not df.empty
+```
+
+---
+
+## 🔗 完整文档
+
+详细指南请查看：[ADD_NEW_API.md](ADD_NEW_API.md)
+
+---
+
+**重点**：只要写好 docstrings，文档会自动生成！✨

{lixinger_python-0.1.2 → lixinger_python-0.2.0}/AGENTS.md

@@ -7,6 +7,14 @@ Instructions for LLM agents implementing the Lixinger API Python SDK.
 - **API Docs**: <https://www.lixinger.com/open/api/doc>
 - **Code Examples**: See `lixinger/api/` and `lixinger/models/` for patterns
 
+## Architecture
+
+**⚠️ IMPORTANT: This SDK is fully async/await based.**
+
+- All API methods are `async def` and must be awaited
+- Uses `httpx.AsyncClient` for non-blocking I/O
+- Perfect for AI agents, Jupyter notebooks, and async web frameworks
+
 ## Critical: API Response Format
 
 All responses follow this format:
@@ -31,10 +39,10 @@ All responses follow this format:
 
 ```python
 # ✅ Correct
-client = LixingerClient()
+client = AsyncLixingerClient()
 
 # ❌ Wrong - will raise TypeError
-client = LixingerClient(api_key="key")
+client = AsyncLixingerClient(api_key="key")
 ```
 
 **Optional env vars:** `LIXINGER_BASE_URL`, `LIXINGER_TIMEOUT`, `LIXINGER_MAX_RETRIES`, `LIXINGER_PROXY`, `LIXINGER_MAX_REQUESTS_PER_MINUTE`
@@ -127,6 +135,7 @@ curl -X POST https://open.lixinger.com/api/cn/company \
 
 2. **API class** (`lixinger/api/cn/{endpoint}/`)
    - Inherit from `BaseAPI`
+   - **All methods MUST be async** (`async def`)
    - **Method parameters MUST match API documentation exactly**
    - Add docstring with:
      - Endpoint URL
@@ -134,10 +143,11 @@ curl -X POST https://open.lixinger.com/api/cn/company \
      - Parameter descriptions from docs
    - Use proper type hints (match API docs)
    - **Validate parameters against documented constraints**
+   - All API calls use `await self._request(...)`
    - Add `__init__.py` with exports
 
 3. **Integrate**
-   - Add to `LixingerClient` in `client.py`
+   - Add to `AsyncLixingerClient` in `client.py`
    - Export in `lixinger/__init__.py`
 
 **Compliance Checklist:**
@@ -152,13 +162,18 @@ curl -X POST https://open.lixinger.com/api/cn/company \
 ### 3. Add Tests
 
 **Unit tests** (`tests/test_*.py`):
+- **All test functions MUST be async** (`async def test_...()`)
+- Add `@pytest.mark.asyncio` decorator to all async tests
+- Use `await` for all API calls
 - Mock with full `{code, message, data}` format
+- Mock `_request` as async: `async def mock_request(...)`
 - Test success, errors, edge cases
 - Use `monkeypatch.setenv("LIXINGER_API_KEY", "test_key")`
 
 **Integration tests** (`tests/test_integration.py`):
 - Mark with `@pytest.mark.integration`
-- Test with real API
+- Use `async with AsyncLixingerClient() as client:`
+- Test with real API using `await`
 
 **Coverage:** >80% on new code
 
@@ -175,7 +190,7 @@ uv run pytest --cov=lixinger --cov-report=term-missing -m "not integration"
 All public methods **MUST** have complete Google-style docstrings:
 
 ```python
-def get_data(
+async def get_data(
     self,
     stock_code: str,
     start_date: str | None = None,
@@ -205,19 +220,23 @@ def get_data(
     Example:
         获取平安银行的市盈率和市净率：
 
-        >>> client = LixingerClient()
-        >>> df = client.company.data.get_data(
-        ...     stock_code="000001",
-        ...     start_date="2023-01-01",
-        ...     metrics=["pe", "pb"]
-        ... )
-        >>> print(df.head())
+        >>> import asyncio
+        >>> async def main():
+        ...     client = AsyncLixingerClient()
+        ...     df = await client.company.data.get_data(
+        ...         stock_code="000001",
+        ...         start_date="2023-01-01",
+        ...         metrics=["pe", "pb"]
+        ...     )
+        ...     print(df.head())
+        >>> asyncio.run(main())
 
     Note:
         API 限制每分钟最多 1000 次请求。
 
     """
-    pass
+    data = await self._request("POST", "/cn/company/data", json=payload)
+    return get_response_df(data, DataModel)
 ```
 
 **Required Sections**:
@@ -251,13 +270,17 @@ API_DOCS = {
         "endpoint": "POST /cn/company/your-api",
         "module": "lixinger.api.cn.company.your_api.YourAPI",
         "example": """```python
-from lixinger import LixingerClient
+import asyncio
+from lixinger import AsyncLixingerClient
+
+async def main():
+    client = AsyncLixingerClient()
 
-client = LixingerClient()
+    # 使用示例
+    df = await client.company.your_api.get_data("000001")
+    print(df)
 
-# 使用示例
-df = client.company.your_api.get_data("000001")
-print(df)
+asyncio.run(main())
 ```""",
         "doc_url": "https://www.lixinger.com/open/api/doc?api-key=cn/company/your-api",
     },

{lixinger_python-0.1.2 → lixinger_python-0.2.0}/CHANGELOG.md

@@ -10,7 +10,54 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Planned
 - Add support for US stock market APIs
 - Add caching mechanism for API responses
-- Add async support
+
+## [0.2.0] - 2026-02-26
+
+### ⚠️ BREAKING CHANGES
+
+This release completely migrates the SDK to async/await. All existing code must be updated.
+
+**Migration Guide:**
+
+```python
+# v0.1.x (old - blocking)
+from lixinger import LixingerClient
+
+with LixingerClient() as client:
+    df = client.company.company.get_company(["000001"])
+
+# v0.2.0 (new - async)
+import asyncio
+from lixinger import AsyncLixingerClient
+
+async def main():
+    async with AsyncLixingerClient() as client:
+        df = await client.company.company.get_company(["000001"])
+
+asyncio.run(main())
+```
+
+### Changed
+- **BREAKING**: `LixingerClient` renamed to `AsyncLixingerClient`
+- **BREAKING**: All API methods now return coroutines and must be awaited
+- **BREAKING**: Context manager now requires `async with` instead of `with`
+- **BREAKING**: `client.close()` is now async and must be awaited
+- **BREAKING**: All functional APIs (e.g., `get_company()`) are now async
+- Replaced `httpx.Client` with `httpx.AsyncClient`
+- Replaced `time.sleep` with `asyncio.sleep` in rate limiter and retry logic
+
+### Added
+- ✨ Full async/await support throughout the SDK
+- ✨ Concurrent request capability - query multiple stocks in parallel
+- ✨ Native Jupyter Notebook support (top-level await)
+- ✨ Perfect integration with AI Agent frameworks (LangChain, LlamaIndex)
+- ✨ Compatible with async web frameworks (FastAPI, Sanic, Quart)
+
+### Benefits
+- Non-blocking I/O for better performance in async contexts
+- Ability to query multiple stocks concurrently using `asyncio.gather()`
+- Seamless integration with modern Python async ecosystem
+- Ideal for AI agents that need to fetch financial data without blocking
 
 ## [0.1.0] - 2026-02-24