lixinger-python 0.1.2__py3-none-any.whl

lixinger/__init__.py

@@ -0,0 +1,79 @@
+from lixinger.api.cn.company import get_company, get_equity_change, get_profile
+from lixinger.api.cn.company.candlestick import get_candlestick
+from lixinger.api.cn.company.fs.non_financial import get_non_financial_statements
+from lixinger.api.cn.company.fundamental import (
+    get_bank,
+    get_fundamental,
+    get_insurance,
+    get_non_financial,
+    get_other_financial,
+    get_security,
+)
+from lixinger.api.cn.company.indices import get_indices
+from lixinger.api.cn.fund import (
+    get_fund,
+    get_fund_announcement,
+    get_fund_asset_combination,
+    get_fund_asset_industry_combination,
+    get_fund_candlestick,
+    get_fund_profile,
+    get_fund_shareholdings,
+)
+from lixinger.api.cn.index import (
+    get_candlestick as get_index_candlestick,
+)
+from lixinger.api.cn.index import (
+    get_constituent_weightings,
+    get_constituents,
+    get_index,
+    get_index_fundamental,
+    get_tracking_fund,
+)
+from lixinger.api.cn.index import (
+    get_drawdown as get_index_drawdown,
+)
+from lixinger.client import LixingerClient
+from lixinger.config import set_token
+from lixinger.exceptions import (
+    APIError,
+    AuthenticationError,
+    LixingerError,
+    RateLimitError,
+    ValidationError,
+)
+
+__all__ = [
+    "LixingerClient",
+    "LixingerError",
+    "APIError",
+    "RateLimitError",
+    "AuthenticationError",
+    "ValidationError",
+    "set_token",
+    "get_company",
+    "get_fund",
+    "get_fund_announcement",
+    "get_fund_profile",
+    "get_fund_candlestick",
+    "get_fund_shareholdings",
+    "get_fund_asset_combination",
+    "get_fund_asset_industry_combination",
+    "get_profile",
+    "get_equity_change",
+    "get_indices",
+    "get_index",
+    "get_constituents",
+    "get_constituent_weightings",
+    "get_index_fundamental",
+    "get_tracking_fund",
+    "get_candlestick",
+    "get_index_candlestick",
+    "get_index_drawdown",
+    "get_non_financial_statements",
+    "get_fundamental",
+    "get_non_financial",
+    "get_bank",
+    "get_insurance",
+    "get_security",
+    "get_other_financial",
+]

lixinger/api/base.py

@@ -0,0 +1,94 @@
+from typing import Any
+
+import httpx
+
+from lixinger.config import Config, settings
+from lixinger.exceptions import APIError, AuthenticationError, RateLimitError
+from lixinger.utils.rate_limiter import RateLimiter
+from lixinger.utils.retry import retry_on_failure
+
+# Global rate limiter for functional API
+_global_rate_limiter = RateLimiter(max_requests=1000)
+
+# Lazy initialization of global http client to avoid issues with proxy/config changes
+_global_http_client: httpx.Client | None = None
+
+
+def get_global_client() -> httpx.Client:
+    """Get or create the global HTTP client."""
+    global _global_http_client  # noqa: PLW0603
+    if _global_http_client is None:
+        _global_http_client = httpx.Client(
+            headers={
+                "Content-Type": "application/json",
+                "Accept-Encoding": "gzip, deflate, br",
+            },
+            timeout=30.0,
+            follow_redirects=True,
+        )
+    return _global_http_client
+
+
+class BaseAPI:
+    """Base class for API endpoint groups."""
+
+    def __init__(
+        self,
+        client: httpx.Client | None = None,
+        config: Config | None = None,
+        rate_limiter: RateLimiter | None = None,
+    ):
+        self._client = client
+        self._config = config or settings
+        self._rate_limiter = rate_limiter or _global_rate_limiter
+
+    @retry_on_failure(max_retries=3, backoff=1.0)
+    def _request(
+        self,
+        method: str,
+        endpoint: str,
+        *,
+        params: dict[str, Any] | None = None,
+        json: dict[str, Any] | None = None,
+    ) -> Any:
+        """Make an API request with retry logic and rate limiting."""
+        self._rate_limiter.acquire()
+
+        # Use the provided client or the global one
+        client = self._client or get_global_client()
+        api_key = self._config.api_key
+
+        # Ensure token is in the payload
+        if method.upper() == "POST" and json is not None and "token" not in json:
+            json["token"] = api_key
+        elif params is not None and "token" not in params:
+            params["token"] = api_key
+
+        response = client.request(
+            method,
+            f"{self._config.base_url.rstrip('/')}/{endpoint.lstrip('/')}",
+            params=params,
+            json=json,
+        )
+
+        if response.status_code == 429:
+            raise RateLimitError("Rate limit exceeded", status_code=429)
+        if response.status_code == 401:
+            raise AuthenticationError("Authentication failed", status_code=401)
+        if response.status_code != 200:
+            raise APIError(
+                f"API request failed with status {response.status_code}: {response.text}",
+                status_code=response.status_code,
+            )
+
+        data = response.json()
+        if not isinstance(data, dict):
+            raise APIError(f"API returned unexpected response type: {type(data)}")
+
+        code = data.get("code")
+        message = data.get("message")
+
+        if code != 1 or message != "success":
+            raise APIError(f"API returned error code {code}: {message}")
+
+        return data.get("data")

lixinger/api/cn/company/__init__.py

@@ -0,0 +1,34 @@
+"""Company-related APIs."""
+
+from lixinger.api.cn.company.announcement import AnnouncementAPI, get_announcement
+from lixinger.api.cn.company.candlestick import CandlestickAPI, get_candlestick
+from lixinger.api.cn.company.company import CompanyAPI, get_company
+from lixinger.api.cn.company.dividend import DividendAPI, get_dividend
+from lixinger.api.cn.company.equity_change import EquityChangeAPI, get_equity_change
+from lixinger.api.cn.company.fundamental import FundamentalAPI
+from lixinger.api.cn.company.indices import IndicesAPI, get_indices
+from lixinger.api.cn.company.profile import CompanyProfileAPI, get_profile
+
+__all__ = [
+    # Company info
+    "CompanyAPI",
+    "get_company",
+    "CompanyProfileAPI",
+    "get_profile",
+    # Equity
+    "EquityChangeAPI",
+    "get_equity_change",
+    # Fundamental
+    "FundamentalAPI",
+    # Market data
+    "CandlestickAPI",
+    "get_candlestick",
+    # Corporate actions
+    "AnnouncementAPI",
+    "get_announcement",
+    "DividendAPI",
+    "get_dividend",
+    # Relations
+    "IndicesAPI",
+    "get_indices",
+]

lixinger/api/cn/company/announcement.py

@@ -0,0 +1,74 @@
+from typing import Any
+
+import pandas as pd
+
+from lixinger.api.base import BaseAPI
+from lixinger.models.cn.company import Announcement
+from lixinger.utils.api import api
+from lixinger.utils.dataframe import get_response_df
+
+
+class AnnouncementAPI(BaseAPI):
+    """Company announcement APIs."""
+
+    def get_announcement(
+        self,
+        stock_code: str,
+        start_date: str | None = None,
+        end_date: str | None = None,
+        limit: int | None = None,
+    ) -> pd.DataFrame:
+        """获取公告数据.
+
+        API Endpoint: /cn/company/announcement
+        API Method: POST
+
+        Args:
+            stock_code: 股票代码
+            start_date: 开始日期 (YYYY-MM-DD)
+            end_date: 结束日期 (YYYY-MM-DD)
+            limit: 限制返回数量
+
+        """
+        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
+        if limit is not None:
+            payload["limit"] = limit
+
+        data = self._request("POST", "/cn/company/announcement", json=payload)
+        for item in data:
+            item["stockCode"] = stock_code
+        return get_response_df(data, Announcement)
+
+
+# Functional API instance
+_api_instance = AnnouncementAPI()
+
+
+@api
+def get_announcement(
+    stock_code: str,
+    start_date: str | None = None,
+    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: 限制返回数量
+
+    """
+    return _api_instance.get_announcement(
+        stock_code=stock_code,
+        start_date=start_date,
+        end_date=end_date,
+        limit=limit,
+    )

lixinger/api/cn/company/candlestick.py

@@ -0,0 +1,76 @@
+from typing import Any, Literal
+
+import pandas as pd
+
+from lixinger.api.base import BaseAPI
+from lixinger.models.cn.company import Candlestick
+from lixinger.utils.api import api
+from lixinger.utils.dataframe import get_response_df
+
+
+class CandlestickAPI(BaseAPI):
+    """Candlestick (K-line) data APIs."""
+
+    def get_candlestick(
+        self,
+        type: Literal["1d", "1w", "1m", "5m", "15m", "30m", "60m"],
+        stock_code: str,
+        start_date: str,
+        end_date: str,
+        adjust_type: Literal["none", "qxw", "hxw"] | None = None,
+    ) -> pd.DataFrame:
+        """获取K线数据.
+
+        API Endpoint: /cn/company/candlestick
+        API Method: POST
+
+        Args:
+            type: K线类型 (1d, 1w, 1m, 5m, 15m, 30m, 60m)
+            stock_code: 股票代码
+            start_date: 开始日期 (YYYY-MM-DD)
+            end_date: 结束日期 (YYYY-MM-DD)
+            adjust_type: 复权类型 (none, qxw, hxw)
+
+        """
+        payload: dict[str, Any] = {
+            "type": type,
+            "stockCode": stock_code,
+            "startDate": start_date,
+            "endDate": end_date,
+        }
+        if adjust_type is not None:
+            payload["adjustType"] = adjust_type
+
+        data = self._request("POST", "/cn/company/candlestick", json=payload)
+        return get_response_df(data, Candlestick)
+
+
+# Functional API instance
+_api_instance = CandlestickAPI()
+
+
+@api
+def get_candlestick(
+    type: Literal["1d", "1w", "1m", "5m", "15m", "30m", "60m"],
+    stock_code: str,
+    start_date: str,
+    end_date: str,
+    adjust_type: Literal["none", "qxw", "hxw"] | None = None,
+) -> pd.DataFrame:
+    """获取K线数据.
+
+    Args:
+        type: K线类型 (1d, 1w, 1m, 5m, 15m, 30m, 60m)
+        stock_code: 股票代码
+        start_date: 开始日期 (YYYY-MM-DD)
+        end_date: 结束日期 (YYYY-MM-DD)
+        adjust_type: 复权类型 (none, qxw, hxw)
+
+    """
+    return _api_instance.get_candlestick(
+        type=type,
+        stock_code=stock_code,
+        start_date=start_date,
+        end_date=end_date,
+        adjust_type=adjust_type,
+    )

lixinger/api/cn/company/company.py

@@ -0,0 +1,88 @@
+"""Company information API."""
+
+from typing import Any, Literal
+
+import pandas as pd
+
+from lixinger.api.base import BaseAPI
+from lixinger.models.cn.company import Company
+from lixinger.utils.api import api
+from lixinger.utils.dataframe import get_response_df
+
+
+class CompanyAPI(BaseAPI):
+    """Company information API."""
+
+    def get_company(
+        self,
+        fs_type: Literal["non_financial", "bank", "insurance", "security", "other_financial"] | None = None,
+        mutual_markets: Literal["ha"] | None = None,
+        stock_codes: list[str] | None = None,
+        include_delisted: bool | None = None,
+    ) -> pd.DataFrame:
+        """获取股票详细信息.
+
+        API Endpoint: /cn/company
+        API Method: POST
+        Documentation: https://www.lixinger.com/open/api/doc?api-key=cn/company
+
+        Args:
+            fs_type: 财务报表类型 (non_financial, bank, insurance, security, other_financial)
+            mutual_markets: 互联互通市场 (ha)
+            stock_codes: 股票代码列表
+            include_delisted: 是否包含已退市股票
+
+        Returns:
+            包含股票详细信息的 DataFrame
+
+        Example:
+            >>> client = LixingerClient()
+            >>> df = client.company.company.get_company(
+            ...     stock_codes=["000001", "600036"]
+            ... )
+            >>> print(df.head())
+
+        """
+        payload: dict[str, Any] = {}
+        if fs_type is not None:
+            payload["fsType"] = fs_type
+        if mutual_markets is not None:
+            payload["mutualMarkets"] = mutual_markets
+        if stock_codes is not None:
+            payload["stockCodes"] = stock_codes
+        if include_delisted is not None:
+            payload["includeDelisted"] = include_delisted
+
+        data = self._request("POST", "/cn/company", json=payload)
+        return get_response_df(data, Company)
+
+
+# Functional API instance
+_api_instance = CompanyAPI()
+
+
+@api
+def get_company(
+    fs_type: Literal["non_financial", "bank", "insurance", "security", "other_financial"] | None = None,
+    mutual_markets: Literal["ha"] | None = None,
+    stock_codes: list[str] | None = None,
+    include_delisted: bool | None = None,
+) -> pd.DataFrame:
+    """获取股票详细信息.
+
+    Args:
+        fs_type: 财务报表类型 (non_financial, bank, insurance, security, other_financial)
+        mutual_markets: 互联互通市场 (ha)
+        stock_codes: 股票代码列表
+        include_delisted: 是否包含已退市股票
+
+    Returns:
+        包含股票详细信息的 DataFrame
+
+    """
+    return _api_instance.get_company(
+        fs_type=fs_type,
+        mutual_markets=mutual_markets,
+        stock_codes=stock_codes,
+        include_delisted=include_delisted,
+    )

lixinger/api/cn/company/dividend.py

@@ -0,0 +1,67 @@
+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."""
+
+    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 = 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
+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 _api_instance.get_dividend(
+        stock_code=stock_code,
+        start_date=start_date,
+        end_date=end_date,
+    )

lixinger/api/cn/company/equity_change.py

@@ -0,0 +1,84 @@
+"""Company equity change API."""
+
+from typing import Any
+
+import pandas as pd
+
+from lixinger.api.base import BaseAPI
+from lixinger.models.cn.company import EquityChangeData
+from lixinger.utils.api import api
+from lixinger.utils.dataframe import get_response_df
+
+
+class EquityChangeAPI(BaseAPI):
+    """Company equity change API."""
+
+    def get_equity_change(
+        self,
+        stock_code: str,
+        start_date: str,
+        end_date: str | None = None,
+    ) -> pd.DataFrame:
+        """获取股本变动.
+
+        API Endpoint: /cn/company/equity-change
+        API Method: POST
+        Documentation: https://www.lixinger.com/open/api/doc?api-key=cn/company/equity-change
+
+        Args:
+            stock_code: 股票代码
+            start_date: 开始日期 (YYYY-MM-DD)
+            end_date: 结束日期 (YYYY-MM-DD), 可选
+
+        Returns:
+            包含股本变动信息的 DataFrame
+
+        Example:
+            >>> client = LixingerClient()
+            >>> df = client.company.equity_change.get_equity_change(
+            ...     stock_code="000001",
+            ...     start_date="2023-01-01",
+            ...     end_date="2023-12-31"
+            ... )
+            >>> print(df.head())
+
+        """
+        payload: dict[str, Any] = {
+            "stockCode": stock_code,
+            "startDate": start_date,
+        }
+        if end_date is not None:
+            payload["endDate"] = end_date
+
+        data = self._request("POST", "/cn/company/equity-change", json=payload)
+        for item in data:
+            item["stockCode"] = stock_code
+        return get_response_df(data, EquityChangeData)
+
+
+# Functional API instance
+_api_instance = EquityChangeAPI()
+
+
+@api
+def get_equity_change(
+    stock_code: str,
+    start_date: str,
+    end_date: str | None = None,
+) -> pd.DataFrame:
+    """获取股本变动.
+
+    Args:
+        stock_code: 股票代码
+        start_date: 开始日期 (YYYY-MM-DD)
+        end_date: 结束日期 (YYYY-MM-DD), 可选
+
+    Returns:
+        包含股本变动信息的 DataFrame
+
+    """
+    return _api_instance.get_equity_change(
+        stock_code=stock_code,
+        start_date=start_date,
+        end_date=end_date,
+    )

lixinger/api/cn/company/fs/__init__.py

@@ -0,0 +1,5 @@
+"""Financial statement APIs."""
+
+from lixinger.api.cn.company.fs.non_financial import get_non_financial_statements
+
+__all__ = ["get_non_financial_statements"]

lixinger/api/cn/company/fs/non_financial.py

@@ -0,0 +1,77 @@
+"""Non-financial statement APIs."""
+
+from typing import Any
+
+import pandas as pd
+
+from lixinger.api.base import BaseAPI
+from lixinger.models.cn.company.fs.non_financial import NonFinancialStatementSchema
+from lixinger.utils.api import api
+from lixinger.utils.dataframe import get_response_df
+from lixinger.utils.dict import flatten_dict
+
+
+class NonFinancialStatementAPI(BaseAPI):
+    """Non-financial statement APIs."""
+
+    def get_non_financial_statements(
+        self,
+        stock_codes: list[str],
+        metrics: list[str],
+        date: str | None = None,
+        start_date: str | None = None,
+        end_date: str | None = None,
+    ) -> pd.DataFrame:
+        """获取非金融企业财务报表数据.
+
+        API Endpoint: /cn/company/fs/non_financial
+        API Method: POST
+        API Doc: https://www.lixinger.com/open/api/doc?api-key=cn/company/fs/non_financial
+
+        Args:
+            stock_codes: 股票代码列表
+            metrics: 指标列表
+            date: 日期 (YYYY-MM-DD), 与 startDate 二选一
+            start_date: 开始日期 (YYYY-MM-DD), 与 date 二选一
+            end_date: 结束日期 (YYYY-MM-DD), 可选
+
+        """
+        payload: dict[str, Any] = {
+            "stockCodes": stock_codes,
+            "metricsList": metrics,
+        }
+        if date is not None:
+            payload["date"] = date
+        if start_date is not None:
+            payload["startDate"] = start_date
+        if end_date is not None:
+            payload["endDate"] = end_date
+
+        data = self._request("POST", "/cn/company/fs/non_financial", json=payload)
+
+        # Flatten nested metrics
+        flattened_data = [flatten_dict(item) for item in data]
+
+        return get_response_df(flattened_data, NonFinancialStatementSchema)
+
+
+# Functional API instance
+_api_instance = NonFinancialStatementAPI()
+
+
+@api
+def get_non_financial_statements(
+    stock_codes: list[str],
+    metrics: list[str],
+    date: str | None = None,
+    start_date: str | None = None,
+    end_date: str | None = None,
+) -> pd.DataFrame:
+    """获取非金融企业财务报表数据."""
+    return _api_instance.get_non_financial_statements(
+        stock_codes=stock_codes,
+        metrics=metrics,
+        date=date,
+        start_date=start_date,
+        end_date=end_date,
+    )