kabukit 0.1.0__py3-none-any.whl → 0.2.0__py3-none-any.whl

kabukit/jquants/client.py

@@ -1,324 +1,324 @@
-"""This module provides a client for the J-Quants API.
-
-It handles authentication and provides methods to interact with
-the API endpoints.
-"""
-
 from __future__ import annotations
 
 import datetime
 import os
 from enum import StrEnum
-from functools import cached_property
-from pathlib import Path
 from typing import TYPE_CHECKING
 
 import polars as pl
-from dotenv import load_dotenv, set_key
-from httpx import Client
-from platformdirs import user_config_dir
 from polars import DataFrame
 
+from kabukit.core.client import Client
+from kabukit.utils.config import load_dotenv, set_key
+from kabukit.utils.params import get_params
+
+from . import info, prices, statements
+
 if TYPE_CHECKING:
-    from collections.abc import Iterator
-    from typing import Any
+    from collections.abc import AsyncIterator
+    from typing import Any, Self
 
     from httpx import HTTPStatusError  # noqa: F401
     from httpx._types import QueryParamTypes
 
 API_VERSION = "v1"
-
-
-class AuthenticationError(Exception):
-    """Custom exception for authentication failures."""
+BASE_URL = f"https://api.jquants.com/{API_VERSION}"
 
 
 class AuthKey(StrEnum):
-    """Environment variable keys for J-Quants authentication."""
+    """J-Quants認証のための環境変数キー。"""
 
     REFRESH_TOKEN = "JQUANTS_REFRESH_TOKEN"  # noqa: S105
     ID_TOKEN = "JQUANTS_ID_TOKEN"  # noqa: S105
 
 
-class JQuantsClient:
-    """A client for interacting with the J-Quants API.
+class JQuantsClient(Client):
+    """J-Quants APIと対話するためのクライアント。
 
-    This client manages API authentication tokens (refresh and ID)
-    and provides methods to access various J-Quants API
-    endpoints. Tokens are loaded from and saved to a file in the
-    user's standard config directory.
+    API認証トークン（リフレッシュトークンおよびIDトークン）を管理し、
+    各種J-Quants APIエンドポイントへアクセスするメソッドを提供する。
+    トークンは設定ファイルから読み込まれ、またファイルに保存される。
 
     Attributes:
-        client: An httpx.Client instance for making API requests.
-        refresh_token: The refresh token for authentication.
-        id_token: The ID token for API requests.
+        client: APIリクエストを行うための `AsyncClient` インスタンス。
     """
 
-    client: Client
-    refresh_token: str | None
-    id_token: str | None
+    def __init__(self, id_token: str | None = None) -> None:
+        super().__init__(BASE_URL)
+        self.set_id_token(id_token)
 
-    def __init__(self) -> None:
-        """Initializes the JQuantsClient.
+    def set_id_token(self, id_token: str | None = None) -> None:
+        """IDトークンをヘッダーに設定する。
 
-        It sets up the httpx client, determines the config path,
-        loads authentication tokens, and sets the auth header if an
-        ID token is present.
+        Args:
+            id_token (str | None, optional): 設定するIDトークン。
+                Noneの場合、環境変数から読み込む。
         """
-        self.client = Client(base_url=f"https://api.jquants.com/{API_VERSION}")
-        self._setup_config_path()
-        self._load_tokens()
-        self.set_header()
-
-    @cached_property
-    def dotenv_path(self) -> Path:
-        """Returns the path to the .env file in the user config directory."""
-        config_dir = Path(user_config_dir("kabukit"))
-        config_dir.mkdir(parents=True, exist_ok=True)
-        return config_dir / ".env"
-
-    def _setup_config_path(self) -> None:
-        """Determines the config path and creates the directory."""
-        # Accessing dotenv_path property will create the directory if it doesn't exist
-        _ = self.dotenv_path
-
-    def _load_tokens(self) -> None:
-        """Loads tokens from the .env file."""
-        load_dotenv(self.dotenv_path)
-        self.refresh_token = os.environ.get(AuthKey.REFRESH_TOKEN)
-        self.id_token = os.environ.get(AuthKey.ID_TOKEN)
-
-    def set_header(self) -> None:
-        """Sets the Authorization header if an ID token is available."""
-        if self.id_token:
-            self.client.headers["Authorization"] = f"Bearer {self.id_token}"
-        # Clear header if no ID token is available
-        elif "Authorization" in self.client.headers:
-            del self.client.headers["Authorization"]
-
-    def auth(self, mailaddress: str, password: str) -> None:
-        """Authenticates, saves tokens, and sets the auth header.
 
-        Args:
-            mailaddress: The user's email address.
-            password: The user's password.
+        if id_token is None:
+            load_dotenv()
+            id_token = os.environ.get(AuthKey.ID_TOKEN)
 
-        Raises:
-            HTTPStatusError: If any API request fails.
-        """
-        self.refresh_token = self.get_refresh_token(mailaddress, password)
-        self.id_token = self.get_id_token(self.refresh_token)
-        set_key(self.dotenv_path, AuthKey.REFRESH_TOKEN, self.refresh_token)
-        set_key(self.dotenv_path, AuthKey.ID_TOKEN, self.id_token)
-        self.set_header()
+        if id_token:
+            self.client.headers["Authorization"] = f"Bearer {id_token}"
 
-    def post(self, url: str, json: Any | None = None) -> Any:
-        """Sends a POST request to the specified URL.
+    async def post(self, url: str, json: Any | None = None) -> Any:
+        """指定されたURLにPOSTリクエストを送信する。
 
         Args:
-            url: The URL path for the POST request.
-            json: The JSON payload for the request body.
+            url: POSTリクエストのURLパス。
+            json: リクエストボディのJSONペイロード。
 
         Returns:
-            The JSON response from the API.
+            APIからのJSONレスポンス。
 
         Raises:
-            AuthenticationError: If no ID token is available.
-            HTTPStatusError: If the API request fails.
+            HTTPStatusError: APIリクエストが失敗した場合。
         """
-        if not self.id_token:
-            msg = "ID token is not available. Please authenticate first."
-            raise AuthenticationError(msg)
-
-        resp = self.client.post(url, json=json)
+        resp = await self.client.post(url, json=json)
         resp.raise_for_status()
         return resp.json()
 
-    def get_refresh_token(self, mailaddress: str, password: str) -> str:
-        """Gets a new refresh token from the API.
+    async def get(self, url: str, params: QueryParamTypes | None = None) -> Any:
+        """指定されたURLにGETリクエストを送信する。
 
         Args:
-            mailaddress: The user's email address.
-            password: The user's password.
+            url (str): GETリクエストのURLパス。
+            params (QueryParamTypes | None, optional): リクエストのクエリパラメータ。
 
         Returns:
-            The new refresh token.
+            APIからのJSONレスポンス。
 
         Raises:
-            httpx.HTTPStatusError: If the API request fails.
+            HTTPStatusError: APIリクエストが失敗した場合。
         """
-        json_data = {"mailaddress": mailaddress, "password": password}
-        return self.post("/token/auth_user", json=json_data)["refreshToken"]
+        resp = await self.client.get(url, params=params)
+        resp.raise_for_status()
+        return resp.json()
 
-    def get_id_token(self, refresh_token: str) -> str:
-        """Gets a new ID token from the API.
+    async def auth(
+        self,
+        mailaddress: str,
+        password: str,
+        *,
+        save: bool = False,
+    ) -> Self:
+        """認証を行い、トークンを保存する。
 
         Args:
-            refresh_token: The refresh token to use.
-
-        Returns:
-            The new ID token.
+            mailaddress (str): J-Quantsに登録したメールアドレス。
+            password (str): J-Quantsのパスワード。
+            save (bool, optional): トークンを環境変数に保存するかどうか。
 
         Raises:
-            HTTPStatusError: If the API request fails.
+            HTTPStatusError: APIリクエストが失敗した場合。
         """
-        url = f"/token/auth_refresh?refreshtoken={refresh_token}"
-        return self.post(url)["idToken"]
-
-    def get(self, url: str, params: QueryParamTypes | None = None) -> Any:
-        """Sends a GET request to the specified URL.
+        json_data = {"mailaddress": mailaddress, "password": password}
+        data = await self.post("/token/auth_user", json=json_data)
+        refresh_token = data["refreshToken"]
 
-        Args:
-            url: The URL path for the GET request.
-            params: The query parameters for the request.
+        url = f"/token/auth_refresh?refreshtoken={refresh_token}"
+        data = await self.post(url)
+        id_token = data["idToken"]
 
-        Returns:
-            The JSON response from the API.
+        if save:
+            set_key(AuthKey.REFRESH_TOKEN, refresh_token)
+            set_key(AuthKey.ID_TOKEN, id_token)
 
-        Raises:
-            AuthenticationError: If no ID token is available.
-            HTTPStatusError: If the API request fails.
-        """
-        if not self.id_token:
-            msg = "ID token is not available. Please authenticate first."
-            raise AuthenticationError(msg)
-
-        resp = self.client.get(url, params=params)
-        resp.raise_for_status()
-        return resp.json()
+        self.set_id_token(id_token)
+        return self
 
-    def get_listed_info(
+    async def get_info(
         self,
         code: str | None = None,
         date: str | datetime.date | None = None,
     ) -> DataFrame:
-        """Gets listed info (e.g., stock details) from the API.
+        """銘柄情報を取得する。
 
         Args:
-            code: Optional. The stock code to filter by.
-            date: Optional. The date to filter by (YYYY-MM-DD format
-                or datetime.date object).
+            code (str, optional): 情報を取得する銘柄のコード。
+            date (str | datetime.date, optional): 情報を取得する日付。
 
         Returns:
-            A Polars DataFrame containing the listed info.
+            銘柄情報を含むPolars DataFrame。
 
         Raises:
-            AuthenticationError: If no ID token is available.
-            HTTPStatusError: If the API request fails.
+            HTTPStatusError: APIリクエストが失敗した場合。
         """
-        params = params_code_date(code, date)
+        params = get_params(code=code, date=date)
         url = "/listed/info"
-        data = self.get(url, params)
-        df = DataFrame(data["info"])
-        return df.with_columns(pl.col("Date").str.to_date())
+        data = await self.get(url, params)
+        return DataFrame(data["info"]).pipe(info.clean)
 
-    def iter_pagaes(
+    async def iter_pages(
         self,
         url: str,
         params: dict[str, Any] | None,
         name: str,
-    ) -> Iterator[DataFrame]:
-        """Iterates through paginated API responses.
+    ) -> AsyncIterator[DataFrame]:
+        """ページ分割されたAPIレスポンスを反復処理する。
 
         Args:
-            url: The base URL for the API endpoint.
-            params: Optional. Dictionary of query parameters.
-            name: The key in the JSON response containing the list of items.
+            url (str): APIエンドポイントのベースURL。
+            params (dict[str, Any]): クエリパラメータの辞書。
+            name (str): アイテムのリストを含むJSONレスポンスのキー。
 
         Yields:
-            A Polars DataFrame for each page of data.
+            データの各ページに対応するPolars DataFrame。
 
         Raises:
-            AuthenticationError: If no ID token is available.
-            HTTPStatusError: If the API request fails.
+            HTTPStatusError: APIリクエストが失敗した場合。
         """
         params = params or {}
 
         while True:
-            data = self.get(url, params)
+            data = await self.get(url, params)
             yield DataFrame(data[name])
             if "pagination_key" in data:
                 params["pagination_key"] = data["pagination_key"]
             else:
                 break
 
-    def get_prices(
+    async def get_prices(
         self,
         code: str | None = None,
         date: str | datetime.date | None = None,
         from_: str | datetime.date | None = None,
         to: str | datetime.date | None = None,
     ) -> DataFrame:
-        """Gets daily stock prices from the API.
+        """日々の株価四本値を取得する。
+
+        株価は分割・併合を考慮した調整済み株価（小数点第２位四捨五入）と調整前の株価を取得できる。
 
         Args:
-            code: Optional. The stock code to filter by.
-            date: Optional. The specific date for which to retrieve prices.
-                Cannot be used with `from_` or `to`.
-            from_: Optional. The start date for a price range.
-                Requires `to` if `date` is not specified.
-            to: Optional. The end date for a price range.
-                Requires `from_` if `date` is not specified.
+            code (str, optional): 株価を取得する銘柄のコード。
+            date (str | datetime.date, optional): 株価を取得する日付。
+                `from_`または`to`とは併用不可。
+            from_ (str | datetime.date, optional): 取得期間の開始日。
+                `date`とは併用不可。
+            to (str | datetime.date, optional): 取得期間の終了日。
+                `date`とは併用不可。
 
         Returns:
-            A Polars DataFrame containing daily stock prices.
+            日々の株価四本値を含むPolars DataFrame。
 
         Raises:
-            ValueError: If both `date` and `from_`/`to` are specified.
-            AuthenticationError: If no ID token is available.
-            HTTPStatusError: If the API request fails.
+            ValueError: `date`と`from_`/`to`の両方が指定された場合。
+            HTTPStatusError: APIリクエストが失敗した場合。
         """
-        params = params_code_date(code, date)
+        if not date and not code:
+            return await self.get_latest_available_prices()
 
         if date and (from_ or to):
-            msg = "Cannot specify both date and from/to parameters."
+            msg = "dateとfrom/toの両方を指定することはできません。"
             raise ValueError(msg)
 
-        if not date and from_:
-            params["from"] = date_to_str(from_)
-        if not date and to:
-            params["to"] = date_to_str(to)
+        params = get_params(code=code, date=date, from_=from_, to=to)
 
         url = "/prices/daily_quotes"
         name = "daily_quotes"
 
-        df = pl.concat(self.iter_pagaes(url, params, name))
+        dfs = [df async for df in self.iter_pages(url, params, name)]
+        df = pl.concat(dfs)
+
         if df.is_empty():
             return df
 
-        return df.with_columns(pl.col("Date").str.to_date())
+        return prices.clean(df)
 
+    async def get_latest_available_prices(self, num_days: int = 30) -> DataFrame:
+        """直近利用可能な日付の株価を取得する。"""
+        today = datetime.date.today()  # noqa: DTZ011
 
-def params_code_date(
-    code: str | None,
-    date: str | datetime.date | None,
-) -> dict[str, str]:
-    """Constructs a dictionary of parameters for code and date filtering.
+        for days in range(num_days):
+            date = today - datetime.timedelta(days)
+            df = await self.get_prices(date=date)
 
-    Args:
-        code: Optional. The stock code.
-        date: Optional. The date (string or datetime.date object).
+            if not df.is_empty():
+                return df
 
-    Returns:
-        A dictionary containing 'code' and/or 'date' parameters.
-    """
-    params: dict[str, str] = {}
-    if code:
-        params["code"] = code
-    if date:
-        params["date"] = date_to_str(date)
-    return params
+        return DataFrame()
+
+    async def get_statements(
+        self,
+        code: str | None = None,
+        date: str | datetime.date | None = None,
+    ) -> DataFrame:
+        """四半期毎の決算短信サマリーおよび業績・配当の修正に関する開示情報を取得する。
+
+        Args:
+            code (str, optional): 財務情報を取得する銘柄のコード。
+            date (str | datetime.date, optional): 財務情報を取得する日付。
+
+        Returns:
+            財務情報を含むDataFrame。
+
+        Raises:
+            ValueError: `code`と`date`が両方とも指定されない場合。
+            HTTPStatusError: APIリクエストが失敗した場合。
+        """
+        if not code and not date:
+            msg = "codeまたはdateのどちらかを指定する必要があります。"
+            raise ValueError(msg)
 
+        params = get_params(code=code, date=date)
+        url = "/fins/statements"
+        name = "statements"
 
-def date_to_str(date: str | datetime.date) -> str:
-    """Converts a date object or string to a YYYY-MM-DD string.
+        dfs = [df async for df in self.iter_pages(url, params, name)]
+        df = pl.concat(dfs)
 
-    Args:
-        date: The date to convert (string or datetime.date object).
+        if df.is_empty():
+            return df
 
-    Returns:
-        The date as a YYYY-MM-DD string.
-    """
-    if isinstance(date, datetime.date):
-        return date.strftime("%Y-%m-%d")
-    return date
+        return statements.clean(df)
+
+    async def get_announcement(self) -> DataFrame:
+        """翌日発表予定の決算情報を取得する。
+
+        Returns:
+            開示情報を含むPolars DataFrame。
+
+        Raises:
+            HTTPStatusError: APIリクエストが失敗した場合。
+        """
+        url = "fins/announcement"
+        name = "announcement"
+
+        dfs = [df async for df in self.iter_pages(url, {}, name)]
+        df = pl.concat(dfs)
+        if df.is_empty():
+            return df
+
+        return df.with_columns(pl.col("Date").str.to_date("%Y-%m-%d", strict=False))
+
+    async def get_trades_spec(
+        self,
+        section: str | None = None,
+        from_: str | datetime.date | None = None,
+        to: str | datetime.date | None = None,
+    ) -> DataFrame:
+        """投資部門別の情報を取得する。
+
+        Args:
+            section: 絞り込み対象のセクション。
+            from_: 取得期間の開始日。
+            to: 取得期間の終了日。
+
+        Returns:
+            投資部門別の情報を含むPolars DataFrame。
+
+        Raises:
+            HTTPStatusError: APIリクエストが失敗した場合。
+        """
+        params = get_params(section=section, from_=from_, to=to)
+
+        url = "/markets/trades_spec"
+        name = "trades_spec"
+
+        dfs = [df async for df in self.iter_pages(url, params, name)]
+        df = pl.concat(dfs)
+        if df.is_empty():
+            return df
+
+        return df.with_columns(pl.col("^.*Date$").str.to_date("%Y-%m-%d", strict=False))

kabukit/jquants/concurrent.py

@@ -0,0 +1,91 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from kabukit.utils import concurrent
+
+from .client import JQuantsClient
+from .info import get_codes
+
+if TYPE_CHECKING:
+    from collections.abc import Iterable
+
+    from polars import DataFrame
+
+    from kabukit.utils.concurrent import Callback, Progress
+
+
+async def fetch(
+    resource: str,
+    codes: Iterable[str],
+    /,
+    max_concurrency: int | None = None,
+    progress: Progress | None = None,
+    callback: Callback | None = None,
+) -> DataFrame:
+    """全銘柄の各種データを取得し、単一のDataFrameにまとめて返す。
+
+    Args:
+        resource (str): 取得するデータの種類。JQuantsClientのメソッド名から"get_"を
+            除いたものを指定する。
+        codes (Iterable[str]): 取得対象の銘柄コードのリスト。
+        max_concurrency (int | None, optional): 同時に実行するリクエストの最大数。
+            指定しないときはデフォルト値が使用される。
+        progress (Progress | None, optional): 進捗表示のための関数。
+            tqdm, marimoなどのライブラリを使用できる。
+            指定しないときは進捗表示は行われない。
+        callback (Callback | None, optional): 各DataFrameに対して適用する
+            コールバック関数。指定しないときはそのままのDataFrameが使用される。
+
+    Returns:
+        DataFrame:
+            すべての銘柄の財務情報を含む単一のDataFrame。
+    """
+    return await concurrent.fetch(
+        JQuantsClient,
+        resource,
+        codes,
+        max_concurrency=max_concurrency,
+        progress=progress,
+        callback=callback,
+    )
+
+
+async def fetch_all(
+    resource: str,
+    /,
+    limit: int | None = None,
+    max_concurrency: int | None = None,
+    progress: Progress | None = None,
+    callback: Callback | None = None,
+) -> DataFrame:
+    """全銘柄の各種データを取得し、単一のDataFrameにまとめて返す。
+
+    Args:
+        resource (str): 取得するデータの種類。JQuantsClientのメソッド名から"get_"を
+            除いたものを指定する。
+        limit (int | None, optional): 取得する銘柄数の上限。
+            指定しないときはすべての銘柄が対象となる。
+        max_concurrency (int | None, optional): 同時に実行するリクエストの最大数。
+            指定しないときはデフォルト値が使用される。
+        progress (Progress | None, optional): 進捗表示のための関数。
+            tqdm, marimoなどのライブラリを使用できる。
+            指定しないときは進捗表示は行われない。
+        callback (Callback | None, optional): 各DataFrameに対して適用する
+            コールバック関数。指定しないときはそのままのDataFrameが使用される。
+
+    Returns:
+        DataFrame:
+            すべての銘柄の財務情報を含む単一のDataFrame。
+    """
+
+    codes = await get_codes()
+    codes = codes[:limit]
+
+    return await fetch(
+        resource,
+        codes,
+        max_concurrency=max_concurrency,
+        progress=progress,
+        callback=callback,
+    )

kabukit/jquants/info.py

@@ -0,0 +1,31 @@
+from __future__ import annotations
+
+import polars as pl
+from polars import DataFrame
+
+
+def clean(df: DataFrame) -> DataFrame:
+    return df.with_columns(
+        pl.col("Date").str.to_date("%Y-%m-%d"),
+        pl.col("^.*CodeName$", "ScaleCategory").cast(pl.Categorical),
+    ).drop("^.+Code$", "CompanyNameEnglish")
+
+
+async def get_codes() -> list[str]:
+    """銘柄コードのリストを返す。
+
+    市場「TOKYO PRO MARKET」と業種「その他」を除外した銘柄を対象とする。
+    """
+    from .client import JQuantsClient
+
+    async with JQuantsClient() as client:
+        info = await client.get_info()
+
+    return (
+        info.filter(
+            pl.col("MarketCodeName") != "TOKYO PRO MARKET",
+            pl.col("Sector17CodeName") != "その他",
+        )
+        .get_column("Code")
+        .to_list()
+    )