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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lixinger-python
-Version: 0.3.8
+Version: 0.3.9
 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.9/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.9}/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.9}/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

lixinger_python-0.3.9/lixinger/api/cn/index/margin_trading.py

@@ -0,0 +1,117 @@
+"""Index margin trading and securities lending APIs."""
+
+from typing import Any
+
+import pandas as pd
+
+from lixinger.api.base import BaseAPI
+from lixinger.models.cn.index.margin_trading import IndexMarginTrading
+from lixinger.utils.api import api
+from lixinger.utils.dataframe import get_response_df
+
+
+class IndexMarginTradingAPI(BaseAPI):
+    """Index margin trading and securities lending APIs."""
+
+    async def get_margin_trading(
+        self,
+        stock_code: str,
+        start_date: str,
+        end_date: str | None = None,
+        limit: int | None = None,
+    ) -> pd.DataFrame:
+        """获取指数融资融券数据.
+
+        获取大陆指数每日的融资融券数据. 可按指数代码批量查询返回每日指数融资买入金额、
+        融资偿还金额、融资净买入金额、融资余额、融券卖出金额、融券偿还金额、
+        融券净卖出金额、融券余额等数据. 当用户想了解某指数每日的融资融券余额以及变动情况、
+        观察杠杆资金进出节奏或分析做空力量时, 调用此接口.
+
+        API Endpoint: /cn/index/margin-trading-and-securities-lending
+        API Method: POST
+        API Doc: https://www.lixinger.com/open/api/doc?api-key=cn/index/margin-trading-and-securities-lending
+
+        Args:
+            stock_code: 指数代码, 请参考指数信息API获取合法的stockCode
+            start_date: 信息起始时间 (YYYY-MM-DD, 北京时间), 开始和结束的时间间隔不超过10年
+            end_date: 结束信息日期 (YYYY-MM-DD, 北京时间), 默认为今天结束
+            limit: 返回最近数据的数量
+
+        Returns:
+            DataFrame containing margin trading data with columns:
+
+            - date: 数据时间
+            - stock_code: 指数代码
+            - financing_purchase_amount: 融资买入金额
+            - financing_repayment_amount: 融资偿还金额
+            - financing_net_purchase_amount: 融资净买入金额
+            - financing_balance: 融资余额
+            - securities_sell_amount: 融券卖出金额
+            - securities_repayment_amount: 融券偿还金额
+            - securities_net_sell_amount: 融券净卖出金额
+            - securities_balance: 融券余额
+            - financing_balance_to_market_cap: 融资余额占流通市值比例
+            - securities_balance_to_market_cap: 融券余额占流通市值比例
+
+        Example:
+            获取上证50指数融资融券数据::
+
+                from lixinger import AsyncLixingerClient
+
+                async with AsyncLixingerClient() as client:
+                    df = await client.cn_index.margin_trading.get_margin_trading(
+                        stock_code="000016",
+                        start_date="2025-06-13",
+                        end_date="2026-06-13",
+                    )
+                    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/index/margin-trading-and-securities-lending",
+            json=payload,
+        )
+        for item in data:
+            item["stockCode"] = stock_code
+        return get_response_df(data, IndexMarginTrading)
+
+
+# Functional API instance
+_api_instance = IndexMarginTradingAPI()
+
+
+@api
+async def get_index_margin_trading(
+    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)
+        end_date: 结束信息日期 (YYYY-MM-DD)
+        limit: 返回最近数据的数量
+
+    Returns:
+        DataFrame containing index margin trading data
+
+    """
+    return await _api_instance.get_margin_trading(
+        stock_code=stock_code,
+        start_date=start_date,
+        end_date=end_date,
+        limit=limit,
+    )

{lixinger_python-0.3.8 → lixinger_python-0.3.9}/lixinger/api/cn/index/namespace.py

@@ -10,6 +10,7 @@ from lixinger.api.cn.index.fs.non_financial import IndexNonFinancialStatementAPI
 from lixinger.api.cn.index.fs.security import IndexSecurityStatementAPI
 from lixinger.api.cn.index.fundamental import IndexFundamentalAPI
 from lixinger.api.cn.index.index import IndexAPI
+from lixinger.api.cn.index.margin_trading import IndexMarginTradingAPI
 from lixinger.api.cn.index.tracking_fund import TrackingFundAPI
 
 
@@ -60,6 +61,7 @@ class IndexNamespace:
     - candlestick: Index candlestick data API (get_candlestick)
     - drawdown: Index drawdown data API (get_drawdown)
     - tracking_fund: Index tracking fund API (get_tracking_fund)
+    - margin_trading: Index margin trading API (get_margin_trading)
     - fs: Index financial statement APIs (sub-APIs for different index types)
       - fs.non_financial: Non-financial index statements
       - fs.bank: Bank index statements
@@ -77,6 +79,7 @@ class IndexNamespace:
         candlestick: IndexCandlestickAPI,
         drawdown: DrawdownAPI,
         tracking_fund: TrackingFundAPI,
+        margin_trading: IndexMarginTradingAPI,
         fs_non_financial: IndexNonFinancialStatementAPI,
         fs_bank: IndexBankStatementAPI,
         fs_security: IndexSecurityStatementAPI,
@@ -92,6 +95,7 @@ class IndexNamespace:
             candlestick: Index candlestick data API
             drawdown: Index drawdown data API
             tracking_fund: Index tracking fund API
+            margin_trading: Index margin trading and securities lending API
             fs_non_financial: Non-financial index statement API
             fs_bank: Bank index statement API
             fs_security: Security index statement API
@@ -105,6 +109,7 @@ class IndexNamespace:
         self.candlestick = candlestick
         self.drawdown = drawdown
         self.tracking_fund = tracking_fund
+        self.margin_trading = margin_trading
         self.fs = IndexFSNamespace(
             non_financial=fs_non_financial,
             bank=fs_bank,
@@ -140,3 +145,7 @@ class IndexNamespace:
     def get_tracking_fund(self, *args, **kwargs):
         """Alias for tracking_fund.get_tracking_fund."""
         return self.tracking_fund.get_tracking_fund(*args, **kwargs)
+
+    def get_margin_trading(self, *args, **kwargs):
+        """Alias for margin_trading.get_margin_trading."""
+        return self.margin_trading.get_margin_trading(*args, **kwargs)

{lixinger_python-0.3.8 → lixinger_python-0.3.9}/lixinger/client.py

@@ -36,6 +36,7 @@ from lixinger.api.cn.index import (
     IndexCandlestickAPI,
     IndexFundamentalAPI,
     IndexHybridStatementAPI,
+    IndexMarginTradingAPI,
     IndexNonFinancialStatementAPI,
     IndexSecurityStatementAPI,
     TrackingFundAPI,
@@ -186,6 +187,7 @@ class AsyncLixingerClient:
         cn_index_drawdown = DrawdownAPI(self._http_client, self.config, self._rate_limiter)
         cn_index_fundamental = IndexFundamentalAPI(self._http_client, self.config, self._rate_limiter)
         cn_index_tracking_fund = TrackingFundAPI(self._http_client, self.config, self._rate_limiter)
+        cn_index_margin_trading = IndexMarginTradingAPI(self._http_client, self.config, self._rate_limiter)
         cn_index_fs_non_financial = IndexNonFinancialStatementAPI(self._http_client, self.config, self._rate_limiter)
         cn_index_fs_bank = IndexBankStatementAPI(self._http_client, self.config, self._rate_limiter)
         cn_index_fs_security = IndexSecurityStatementAPI(self._http_client, self.config, self._rate_limiter)
@@ -200,6 +202,7 @@ class AsyncLixingerClient:
             candlestick=cn_index_candlestick,
             drawdown=cn_index_drawdown,
             tracking_fund=cn_index_tracking_fund,
+            margin_trading=cn_index_margin_trading,
             fs_non_financial=cn_index_fs_non_financial,
             fs_bank=cn_index_fs_bank,
             fs_security=cn_index_fs_security,
@@ -213,6 +216,7 @@ class AsyncLixingerClient:
         self.cn_index_drawdown = cn_index_drawdown
         self.cn_index_fundamental = cn_index_fundamental
         self.cn_index_tracking_fund = cn_index_tracking_fund
+        self.cn_index_margin_trading = cn_index_margin_trading
         self.cn_index_fs_non_financial = cn_index_fs_non_financial
         self.cn_index_fs_bank = cn_index_fs_bank
         self.cn_index_fs_security = cn_index_fs_security

{lixinger_python-0.3.8 → lixinger_python-0.3.9}/lixinger/models/cn/index/__init__.py

@@ -12,6 +12,7 @@ from lixinger.models.cn.index.fs import (
 )
 from lixinger.models.cn.index.fundamental import IndexFundamentalData
 from lixinger.models.cn.index.index import Index
+from lixinger.models.cn.index.margin_trading import IndexMarginTrading
 from lixinger.models.cn.index.tracking_fund import TrackingFund
 
 __all__ = [
@@ -21,6 +22,7 @@ __all__ = [
     "IndexCandlestick",
     "IndexDrawdown",
     "IndexFundamentalData",
+    "IndexMarginTrading",
     "TrackingFund",
     # Index financial statements
     "IndexBankStatementSchema",

lixinger_python-0.3.9/lixinger/models/cn/index/margin_trading.py

@@ -0,0 +1,30 @@
+"""Index margin trading and securities lending models."""
+
+import pandera.pandas as pa
+
+
+class IndexMarginTrading(pa.DataFrameModel):
+    """Index margin trading and securities lending model.
+
+    Represents the daily margin trading (融资) and securities lending (融券)
+    metrics for an index.
+    """
+
+    class Config:
+        """Pandera configuration."""
+
+        coerce = True
+        strict = False
+
+    date: pa.typing.Series[pa.typing.DateTime]
+    stock_code: pa.typing.Series[str]
+    financing_purchase_amount: pa.typing.Series[float] | None = pa.Field(nullable=True)
+    financing_repayment_amount: pa.typing.Series[float] | None = pa.Field(nullable=True)
+    financing_net_purchase_amount: pa.typing.Series[float] | None = pa.Field(nullable=True)
+    financing_balance: pa.typing.Series[float] | None = pa.Field(nullable=True)
+    securities_sell_amount: pa.typing.Series[float] | None = pa.Field(nullable=True)
+    securities_repayment_amount: pa.typing.Series[float] | None = pa.Field(nullable=True)
+    securities_net_sell_amount: pa.typing.Series[float] | None = pa.Field(nullable=True)
+    securities_balance: pa.typing.Series[float] | None = pa.Field(nullable=True)
+    financing_balance_to_market_cap: pa.typing.Series[float] | None = pa.Field(nullable=True)
+    securities_balance_to_market_cap: pa.typing.Series[float] | None = pa.Field(nullable=True)

{lixinger_python-0.3.8 → lixinger_python-0.3.9}/pyproject.toml

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

lixinger_python-0.3.9/tests/test_index_margin_trading.py

@@ -0,0 +1,125 @@
+from unittest.mock import Mock, patch
+
+import pandas as pd
+import pytest
+
+from lixinger import AsyncLixingerClient, get_index_margin_trading
+
+
+@pytest.fixture
+def client():
+    return AsyncLixingerClient()
+
+
+@pytest.mark.asyncio
+async def test_get_index_margin_trading(client):
+    mock_response = {
+        "code": 1,
+        "message": "success",
+        "data": [
+            {
+                "date": "2026-06-12T00:00:00+08:00",
+                "financingBalanceToMarketCap": None,
+                "securitiesBalanceToMarketCap": None,
+            },
+            {
+                "date": "2026-06-11T00:00:00+08:00",
+                "financingPurchaseAmount": 13388615589,
+                "financingRepaymentAmount": 14204571820,
+                "financingNetPurchaseAmount": -815956231,
+                "financingBalance": 317740762545,
+                "securitiesSellAmount": 95630381.56,
+                "securitiesRepaymentAmount": 142159882.89,
+                "securitiesNetSellAmount": -46529501.33,
+                "securitiesBalance": 1335088430.51,
+                "financingBalanceToMarketCap": 0.011534898947671552,
+                "securitiesBalanceToMarketCap": 0.00004846753060195487,
+            },
+        ],
+    }
+
+    with patch.object(client._http_client, "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 client.cn_index.margin_trading.get_margin_trading(
+            stock_code="000016",
+            start_date="2025-06-13",
+            end_date="2026-06-13",
+        )
+
+        assert isinstance(df, pd.DataFrame)
+        assert len(df) == 2
+        assert "date" in df.columns
+        assert "stock_code" in df.columns
+        assert "financing_purchase_amount" in df.columns
+        assert "securities_balance" in df.columns
+        assert df.iloc[0]["stock_code"] == "000016"
+        assert df.iloc[1]["stock_code"] == "000016"
+        assert df.iloc[1]["financing_balance"] == 317740762545
+        assert df.iloc[1]["securities_net_sell_amount"] == -46529501.33
+        assert pd.api.types.is_datetime64_any_dtype(df["date"])
+
+
+@pytest.mark.asyncio
+async def test_get_index_margin_trading_with_limit(client):
+    mock_response = {
+        "code": 1,
+        "message": "success",
+        "data": [
+            {
+                "date": "2026-06-11T00:00:00+08:00",
+                "financingBalance": 317740762545,
+            }
+        ],
+    }
+
+    with patch.object(client._http_client, "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
+
+        await client.cn_index.margin_trading.get_margin_trading(
+            stock_code="000016",
+            start_date="2025-06-13",
+            limit=1,
+        )
+
+        _, kwargs = mock_request.call_args
+        assert kwargs["json"]["stockCode"] == "000016"
+        assert kwargs["json"]["startDate"] == "2025-06-13"
+        assert kwargs["json"]["limit"] == 1
+        assert "endDate" not in kwargs["json"]
+
+
+@pytest.mark.asyncio
+async def test_functional_get_index_margin_trading():
+    mock_response = {
+        "code": 1,
+        "message": "success",
+        "data": [
+            {
+                "date": "2026-06-11T00:00:00+08:00",
+                "financingPurchaseAmount": 13388615589,
+                "financingBalance": 317740762545,
+                "securitiesBalance": 1335088430.51,
+            }
+        ],
+    }
+
+    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_index_margin_trading(
+            stock_code="000016",
+            start_date="2025-06-13",
+            end_date="2026-06-13",
+        )
+
+        assert isinstance(df, pd.DataFrame)
+        assert len(df) == 1
+        assert df.iloc[0]["stock_code"] == "000016"
+        assert df.iloc[0]["financing_balance"] == 317740762545

{lixinger_python-0.3.8 → lixinger_python-0.3.9}/uv.lock

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