lixinger-python 0.3.8__tar.gz → 0.3.10__tar.gz

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

@@ -0,0 +1,13 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(uv run *)",
+      "Bash(git add *)",
+      "Bash(git commit -m ' *)",
+      "Bash(git commit *)",
+      "Bash(python -c ' *)",
+      "Bash(git stash *)",
+      "Bash(gh run *)"
+    ]
+  }
+}

{lixinger_python-0.3.8 → lixinger_python-0.3.10}/.ruff.toml

@@ -10,15 +10,19 @@ preview = false
 select = [
     # Pyflakes (F) - catch common errors
     "F",
-    # Pycodestyle (E, W) - PEP 8 style guide
+    # Pycodestyle (E, W) - PEP 8 style guide (E722 = bare except)
     "E",
     "W",
     # isort (I) - import sorting
     "I",
-    # pep8-naming (N) - naming conventions
+    # pep8-naming (N) - PEP 8 naming conventions
     "N",
-    # pydocstyle (D) - docstring conventions
+    # pydocstyle (D) - docstring conventions (Google style enforced below)
     "D",
+    # flake8-annotations (ANN) - require type hints on function signatures
+    "ANN",
+    # flake8-blind-except (BLE) - forbid bare / overly broad except
+    "BLE",
     # pyupgrade (UP) - upgrade syntax for newer Python versions
     "UP",
     # flake8-bugbear (B) - find bugs and design problems
@@ -43,7 +47,7 @@ select = [
     "PGH",
     # Pylint (PL) - additional checks
     "PL",
-    # tryceratops (TRY) - exception handling
+    # tryceratops (TRY) - exception handling (TRY002 forbids `raise Exception`)
     "TRY",
     # flake8-type-checking (TCH) - type checking imports
     "TCH",
@@ -64,6 +68,10 @@ ignore = [
     "D104",  # Missing docstring in public package
     "D105",  # Missing docstring in magic method
     "D107",  # Missing docstring in __init__
+    # Type-hint relaxations: `self`/`cls` and **kwargs need not be annotated
+    "ANN101",  # Missing type annotation for self
+    "ANN102",  # Missing type annotation for cls
+    "ANN401",  # Allow `typing.Any` (SDK returns generic API payloads)
     # Allow relative imports
     "TID252",
     # Allow print statements (useful for debugging)
@@ -99,6 +107,8 @@ ignore = [
     "S101",  # Use of assert
     "ARG",   # Unused arguments
     "PLR2004",  # Magic numbers
+    "ANN",   # Type annotations not required in tests
+    "D",     # Docstrings not required in tests
 ]
 "data_provider/**/*.py" = [
     "ERA001", # Remove commented-out code
@@ -111,6 +121,13 @@ ignore = [
 "app.py" = [
     "F401",  # Unused imports (Flask decorators)
 ]
+# Examples & scripts: relaxed docstring / annotation requirements
+"examples/**/*.py" = ["ANN", "D"]
+"scripts/**/*.py"  = ["ANN", "D"]
+
+[lint.pydocstyle]
+# Enforce Google-style docstrings (required for MkDocs / mkdocstrings)
+convention = "google"
 
 [lint.isort]
 known-first-party = ["analyzer", "core", "data_provider"]

{lixinger_python-0.3.8 → lixinger_python-0.3.10}/ADD_NEW_API_QUICK.md

@@ -6,7 +6,11 @@
 
 ## 🎯 三步添加新 API
 
-### 1️⃣ 写代码 + Docstrings
+### 1️⃣ 读文档
+
+所有API文档都放在了 [lixinger-api](./lixinger-api/)下, 首先阅读 [REMINDER.md](./lixinger-api/REMINDER.md) 了解注意事项, 然后阅读具体的 API 文档, 例如 [lixinger-api/cn/company/financials.md](./lixinger-api/cn/company/financials.md) 了解具体的参数和返回值。
+
+### 2️⃣ 写代码 + Docstrings
 
 ```python
 # lixinger/api/cn/company/your_api.py
@@ -49,7 +53,7 @@ class YourAPI(BaseAPI):
 
 ---
 
-### 2️⃣ 生成文档
+### 3️⃣ 生成文档
 
 **方式 A: 自动生成（推荐）**
 
@@ -79,7 +83,7 @@ EOF
 
 ---
 
-### 3️⃣ 预览 & 部署
+### 4️⃣ 预览 & 部署
 
 ```bash
 # 本地预览
@@ -167,6 +171,8 @@ async def method_name(param: type) -> return_type:
     return data
 ```
 
+参考@DOCUMENTATION.md了解项目的文档规范和 Docstring 规范。
+
 ---
 
 ## 🧪 测试模板
@@ -191,13 +197,3 @@ async def test_your_api(monkeypatch):
 
     assert not df.empty
 ```
-
----
-
-## 🔗 完整文档
-
-详细指南请查看：[ADD_NEW_API.md](ADD_NEW_API.md)
-
----
-
-**重点**：只要写好 docstrings，文档会自动生成！✨

lixinger_python-0.3.10/ARCHITECTURE.md

@@ -0,0 +1,60 @@
+# 🏛️ ARCHITECTURE
+
+> Lixinger Python SDK 架构简述
+
+---
+
+## 1. 设计原则
+
+| 原则 | 说明 |
+| --- | --- |
+| **完全异步** | 所有 API 方法为 `async def`，底层 `httpx.AsyncClient` |
+| **端点驱动目录** | 目录严格镜像 REST 路径：`/cn/company/fs/bank` → `lixinger/api/cn/company/fs/bank.py` |
+| **类型安全** | 全量类型注解 + Pandera DataFrame Schema，`mypy` 严格 |
+| **两种调用形态** | `AsyncLixingerClient`（OO）与 `get_xxx()`（函数式）共享同一底层 |
+| **单一 HTTP 出口** | 端点模块**只能**通过 `BaseAPI._request` 发起请求，重试/限速/鉴权/异常映射集中在一处 |
+| **DataFrame 一体化** | 所有 API 返回 `pandas.DataFrame`，字段自动 `camelCase → snake_case`，经 Pandera 校验 |
+| **API Key 只来自环境变量** | 强制 `LIXINGER_API_KEY`，不可通过参数传入 |
+| **文档即代码** | MkDocs + mkdocstrings 从 docstring 自动生成 API 参考 |
+
+---
+
+## 2. 分层结构
+
+```
+Layer 4  Public Surface       lixinger/__init__.py
+                              └── AsyncLixingerClient / get_xxx() / 异常类
+Layer 3  Endpoint Modules     lixinger/api/cn/**/*.py
+                              └── XxxAPI 类 + get_xxx() 函数 + Namespace 聚合
+Layer 2  BaseAPI              lixinger/api/base.py
+                              └── _request()：唯一网络出口（重试 + 限速 + 鉴权 + 解包）
+Layer 1  Infrastructure       lixinger/utils/*
+                              └── httpx / RateLimiter / Retry / Config / Pandera
+```
+
+---
+
+## 3. 目录结构
+
+```text
+lixinger-python/
+├── lixinger/              # SDK 主包（client / config / exceptions / __init__）
+│   ├── api/               # Layer 2+3：base.py + 按 REST 路径组织的端点模块
+│   │   └── cn/            # 中国大陆市场
+│   │       ├── company/   # /cn/company/*（含 fs/ 与 fundamental/ 按公司类型细分）
+│   │       ├── index/     # /cn/index/*（含 fs/ 按指数类型细分）
+│   │       └── fund/      # /cn/fund/*
+│   ├── models/            # Pandera DataFrame Schema（结构镜像 api/）
+│   └── utils/             # rate_limiter / retry / dataframe / dict / api 装饰器
+│
+├── tests/                 # pytest（含 integration 标记）
+├── examples/              # 各模块使用示例
+├── scripts/               # explore_api / generate_docs / publish
+├── docs/                  # MkDocs 源文件
+├── lixinger-api/          # 官方 API 文档镜像（cn/hk/us/macro）
+├── mkdocs.yml
+├── pyproject.toml         # uv / ruff / mypy / pytest 配置
+└── .env(.example)         # 环境变量
+```
+
+**核心约束**：目录路径必须与 REST 端点一一对应。端点 `/cn/index/fs/hybrid` → `lixinger/api/cn/index/fs/hybrid.py` → `lixinger/models/cn/index/fs/hybrid.py`。

lixinger_python-0.3.10/CLAUDE.md

@@ -0,0 +1,116 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+This is a Python SDK for the Lixinger API, which provides financial data services. The project is in early development stages.
+
+- **API Documentation**: https://www.lixinger.com/open/api/doc?api-key=cn/company/fundamental/non_financial
+- **API Endpoint**: `https://open.lixinger.com/api`
+- **Python Version**: 3.13+
+- **Package Manager**: uv (fast Python package installer)
+- **Main Dependencies**: httpx (with SOCKS proxy support), python-dotenv, pydantic
+
+## Configuration
+
+**IMPORTANT**: The SDK uses environment variables for configuration via dotenv. The API key is ALWAYS loaded from the `.env` file and CANNOT be passed as a parameter.
+
+1. **Setup**: Copy `.env.example` to `.env` and configure:
+   ```bash
+   cp .env.example .env
+   ```
+
+2. **Required Environment Variables**:
+   - `LIXINGER_API_KEY` - Your Lixinger API key (REQUIRED - cannot be passed as parameter)
+
+3. **Optional Environment Variables**:
+   - `LIXINGER_BASE_URL` - Custom API base URL (default: https://open.lixinger.com/api)
+   - `LIXINGER_TIMEOUT` - Request timeout in seconds (default: 30.0)
+   - `LIXINGER_MAX_RETRIES` - Maximum retry attempts (default: 3)
+   - `LIXINGER_PROXY` - Proxy URL, supports SOCKS (default: None)
+   - `LIXINGER_MAX_REQUESTS_PER_MINUTE` - Rate limit (default: 1000)
+
+## Development Commands
+
+### Setup
+
+```bash
+# Install dependencies using uv
+uv sync --dev
+
+# Install pre-commit hooks (IMPORTANT!)
+uv run pre-commit install
+```
+
+### Running
+
+```bash
+# Run the main script
+uv run python main.py
+
+# Run examples (make sure .env is configured first)
+uv run python examples/company_example.py
+```
+
+### Linting
+
+```bash
+# Run Ruff linter
+uv run ruff check .
+
+# Auto-fix linting issues
+uv run ruff check . --fix
+
+# Format code
+uv run ruff format .
+
+# Check formatting (used in CI)
+uv run ruff format --check .
+
+# Run Mypy type checker
+uv run mypy lixinger/
+```
+
+### Testing
+
+```bash
+# Run all tests
+uv run pytest
+
+# Run only unit tests (fast, no API key needed)
+uv run pytest -m "not integration"
+
+# Run integration tests (requires valid API key in .env)
+uv run pytest -m integration
+
+# Run specific test file
+uv run pytest tests/test_client.py
+
+# Run with coverage
+uv run pytest --cov=lixinger
+
+# Explore API and record real responses
+uv run python scripts/explore_api.py
+```
+
+
+## Hard Constraints
+
+- Always using the python via `uv run python`
+- Always using `~=` in `pyproject.toml` for dependencies and always use `uv` for package management.
+- Update [ARCHITECTURE.md](/.ARCHITECTURE.md) if you add / change project structure.
+- Work on one feature at a time
+- Only start the next feature after the current one passes end-to-end verification
+- Don't "also refactor" feature B while implementing feature A
+- All code must pass lint check
+- Run `load_dotenv()` to load environment variables from `.env` file if not already done when running python code.
+
+
+# References
+
+Read @ADD_NEW_API_QUICK.md to quickly add new API endpoints and models.
+Read @PUBLISHING.md to learn how to publish the SDK to PyPI.
+Read @ARCHITECTURE.md to understand the SDK's architecture and design principles.
+Read @.github/workflows/README.md to understand the CI/CD workflow.
+Read @DOCUMENTATION.md to understand how to write docstrings and generate documentation.

lixinger_python-0.3.10/DOCUMENTATION.md

@@ -0,0 +1,22 @@
+
+## Documentation
+
+This project uses **MkDocs + mkdocstrings** to automatically generate API documentation from docstrings.
+
+**Requirements when adding new APIs**:
+- ✅ Write complete Google-style docstrings
+- ✅ Include `Args`, `Returns`, and `Example` sections
+- ✅ Use full type annotations
+
+**Quick workflow**:
+```bash
+# 1. Write code with docstrings
+# 2. Generate docs
+uv run python scripts/generate_docs.py
+# 3. Preview
+uv run mkdocs serve
+```
+
+**Important**:
+- ✅ DO commit: `docs/` (source files), `mkdocs.yml`
+- ❌ DON'T commit: `site/` (auto-generated)

{lixinger_python-0.3.8 → lixinger_python-0.3.10}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lixinger-python
-Version: 0.3.8
+Version: 0.3.10
 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.8 → lixinger_python-0.3.10}/PUBLISHING.md

@@ -142,6 +142,10 @@ git tag -a v0.1.0 -m "Release version 0.1.0"
 git push origin v0.1.0
 ```
 
+### Step 10: Update CHANGELOG.md
+
+Update `CHANGELOG.md` with the changes in this release.
+
 ## Using in Another Project
 
 After publishing, you can use it in your other project:
@@ -168,65 +172,6 @@ with LixingerClient() as client:
     print(df)
 ```
 
-## Automation with GitHub Actions (Optional)
-
-You can automate releases with GitHub Actions. Create `.github/workflows/publish.yml`:
-
-```yaml
-name: Publish to PyPI
-
-on:
-  release:
-    types: [published]
-
-jobs:
-  publish:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-
-      - name: Set up Python
-        uses: actions/setup-python@v5
-        with:
-          python-version: '3.13'
-
-      - name: Install dependencies
-        run: |
-          pip install build twine
-
-      - name: Build package
-        run: python -m build
-
-      - name: Publish to PyPI
-        env:
-          TWINE_USERNAME: __token__
-          TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}
-        run: twine upload dist/*
-```
-
-Then add `PYPI_API_TOKEN` to your GitHub repository secrets.
-
-## Troubleshooting
-
-### Error: Package already exists
-
-- You cannot re-upload the same version
-- Increment the version number in `pyproject.toml`
-
-### Error: Invalid credentials
-
-- Check your `~/.pypirc` file
-- Ensure API token is correct and has upload permissions
-
-### Error: Package name already taken
-
-- Choose a different name in `pyproject.toml`
-- Try variations like `lixinger-sdk`, `pylixinger`, etc.
-
-### Import errors after installation
-
-- Ensure `lixinger/__init__.py` properly exports all public APIs
-- Check that all required files are included in MANIFEST.in
 
 ## Best Practices
 
@@ -236,11 +181,4 @@ Then add `PYPI_API_TOKEN` to your GitHub repository secrets.
 4. **Write a CHANGELOG.md** to document changes between versions
 5. **Never commit sensitive files** like `.pypirc` or `.env`
 6. **Follow semantic versioning** for version numbers
-7. **Run all tests** before publishing
-
-## Additional Resources
-
-- [Python Packaging User Guide](https://packaging.python.org/)
-- [PyPI Help](https://pypi.org/help/)
-- [Semantic Versioning](https://semver.org/)
-- [uv Documentation](https://docs.astral.sh/uv/)
+7. **Run all tests** before publishing

{lixinger_python-0.3.8 → lixinger_python-0.3.10}/examples/company_profile_example.py

@@ -15,7 +15,7 @@ async def main():
         try:
             df = await client.company.get_profile(stock_codes=["600036"])
             print(df)
-        except Exception as e:
+        except Exception as e:  # noqa: BLE001
             print(f"Error fetching profile: {e}")
             print("Note: This example requires a valid LIXINGER_API_KEY in .env")
     finally:
@@ -26,7 +26,7 @@ async def main():
     try:
         df = await get_profile(stock_codes=["000001"])
         print(df)
-    except Exception as e:
+    except Exception as e:  # noqa: BLE001
         print(f"Error fetching profile: {e}")
 
 

lixinger_python-0.3.10/examples/index_margin_trading_example.py

@@ -0,0 +1,54 @@
+"""Index margin trading and securities lending API example.
+
+This example demonstrates how to use the index margin trading API to retrieve
+daily margin trading (融资) and securities lending (融券) metrics for an index.
+"""
+
+import asyncio
+
+from lixinger import AsyncLixingerClient, get_index_margin_trading
+
+
+async def main():
+    """Demonstrate usage of index margin trading API."""
+    # Method 1: Using the async client with context manager (recommended)
+    print("Method 1: Using async client...")
+    async with AsyncLixingerClient() as client:
+        # Get margin trading data for SSE 50 index
+        print("\nFetching margin trading data for SSE 50 (000016)...")
+        df = await client.cn_index.margin_trading.get_margin_trading(
+            stock_code="000016",
+            start_date="2025-06-13",
+            end_date="2026-06-13",
+        )
+        print(f"Total records: {len(df)}")
+        print("\nLatest 5 records:")
+        print(
+            df.head(5)[
+                [
+                    "date",
+                    "financing_balance",
+                    "financing_net_purchase_amount",
+                    "securities_balance",
+                    "securities_net_sell_amount",
+                ]
+            ]
+        )
+
+        # Analyze balance distribution
+        print("\nFinancing balance statistics:")
+        print(df["financing_balance"].describe())
+
+    # Method 2: Using functional API with limit parameter
+    print("\nMethod 2: Using functional API (last 10 days)...")
+    df = await get_index_margin_trading(
+        stock_code="000300",  # CSI 300
+        start_date="2025-06-01",
+        limit=10,
+    )
+    print(f"Total records: {len(df)}")
+    print(df.head(10))
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

{lixinger_python-0.3.8 → lixinger_python-0.3.10}/lixinger/__init__.py

@@ -34,6 +34,7 @@ from lixinger.api.cn.index import (
     get_index_bank_statements,
     get_index_fundamental,
     get_index_hybrid_statements,
+    get_index_margin_trading,
     get_index_non_financial_statements,
     get_index_security_statements,
     get_tracking_fund,
@@ -75,6 +76,7 @@ __all__ = [
     "get_constituent_weightings",
     "get_index_fundamental",
     "get_tracking_fund",
+    "get_index_margin_trading",
     "get_candlestick",
     "get_index_candlestick",
     "get_index_drawdown",

{lixinger_python-0.3.8 → lixinger_python-0.3.10}/lixinger/api/base.py

@@ -37,7 +37,7 @@ class BaseAPI:
         client: httpx.AsyncClient | None = None,
         config: Config | None = None,
         rate_limiter: AsyncRateLimiter | None = None,
-    ):
+    ) -> None:
         self._client = client
         self._config = config or settings
         self._rate_limiter = rate_limiter or _global_rate_limiter

{lixinger_python-0.3.8 → lixinger_python-0.3.10}/lixinger/api/cn/company/namespace.py

@@ -37,7 +37,7 @@ class FundamentalNamespace:
         insurance: InsuranceFundamentalAPI,
         security: SecurityFundamentalAPI,
         other_financial: OtherFinancialFundamentalAPI,
-    ):
+    ) -> None:
         """Initialize the fundamental namespace."""
         self.non_financial = non_financial
         self.bank = bank
@@ -65,7 +65,7 @@ class FSNamespace:
         insurance: InsuranceStatementAPI,
         security: SecurityStatementAPI,
         other_financial: OtherFinancialStatementAPI,
-    ):
+    ) -> None:
         """Initialize the financial statement namespace."""
         self.non_financial = non_financial
         self.bank = bank
@@ -121,7 +121,7 @@ class CompanyNamespace:
         indices: IndicesAPI,
         dividend: DividendAPI,
         announcement: AnnouncementAPI,
-    ):
+    ) -> None:
         """Initialize the company namespace.
 
         Args:

{lixinger_python-0.3.8 → lixinger_python-0.3.10}/lixinger/api/cn/index/__init__.py

@@ -22,6 +22,10 @@ from lixinger.api.cn.index.fundamental import (
     get_index_fundamental,
 )
 from lixinger.api.cn.index.index import IndexAPI, get_index
+from lixinger.api.cn.index.margin_trading import (
+    IndexMarginTradingAPI,
+    get_index_margin_trading,
+)
 from lixinger.api.cn.index.tracking_fund import TrackingFundAPI, get_tracking_fund
 
 __all__ = [
@@ -37,6 +41,8 @@ __all__ = [
     "get_drawdown",
     "IndexFundamentalAPI",
     "get_index_fundamental",
+    "IndexMarginTradingAPI",
+    "get_index_margin_trading",
     "TrackingFundAPI",
     "get_tracking_fund",
     # Index financial statements