kabukit 0.5.2__py3-none-any.whl → 0.5.3__py3-none-any.whl

kabukit/core/prices.py

@@ -17,6 +17,26 @@ if TYPE_CHECKING:
 
 class Prices(Base):
     def truncate(self, every: str | timedelta | Expr) -> Self:
+        """時系列データを指定された頻度で集計し、切り詰める。
+
+        このメソッドは、日次などの時系列データを指定された頻度（例: 月次、週次）で
+        集計し、新しい時間軸に切り詰めます。集計方法は以下の通りです。
+
+        *   `Open`: 各期間の最初の`Open`値
+        *   `High`: 各期間の最大`High`値
+        *   `Low`: 各期間の最小`Low`値
+        *   `Close`: 各期間の最後の`Close`値
+        *   `Volume`: 各期間の`Volume`の合計
+        *   `TurnoverValue`: 各期間の`TurnoverValue`の合計
+
+        Args:
+            every (str | timedelta | Expr): 切り詰める頻度を指定します。
+                例: "1d" (日次), "1mo" (月次), `timedelta`オブジェクト,
+                または Polars の `Expr` オブジェクト。
+
+        Returns:
+            Self: 指定された頻度で切り詰められた新しいPricesオブジェクト。
+        """
         data = (
             self.data.group_by(pl.col("Date").dt.truncate(every), "Code")
             .agg(
@@ -29,6 +49,7 @@ class Prices(Base):
             )
             .sort("Code", "Date")
         )
+
         return self.__class__(data)
 
     def with_adjusted_shares(self, statements: Statements) -> Self:
@@ -47,19 +68,22 @@ class Prices(Base):
         新しい列（`AdjustedIssuedShares`, `AdjustedTreasuryShares`）として
         追加されます。
 
-        .. note::
-            この計算は、決算発表間の株式数の変動が、株式分割・併合
-            （`AdjustmentFactor`）にのみ起因すると仮定しています。
-            期中に行われる増資や自己株式取得など、`AdjustmentFactor`に
-            反映されないイベントによる株式数の変動は考慮されません。
-
         Args:
             statements (Statements): 財務データを提供する`Statements`オブジェクト。
 
         Returns:
             Self: `AdjustedIssuedShares`および`AdjustedTreasuryShares`列が
             追加された、新しいPricesオブジェクト。
+
+        Note:
+            この計算は、決算発表間の株式数の変動が、株式分割・併合
+            （`AdjustmentFactor`）にのみ起因すると仮定しています。
+            期中に行われる増資や自己株式取得など、`AdjustmentFactor`に
+            反映されないイベントによる株式数の変動は考慮されません。
         """
+        if "AdjustedIssuedShares" in self.data.columns:
+            return self
+
         shares = statements.shares().rename({"Date": "ReportDate"})
 
         adjusted = (
@@ -89,6 +113,23 @@ class Prices(Base):
 
         return self.__class__(data)
 
+    @property
+    def _outstanding_shares_expr(self) -> pl.Expr:
+        """調整済み発行済株式数を計算する Polars 式を返す。
+
+        Raises:
+            KeyError: 必要な列が存在しない場合は KeyError を送出する。
+        """
+        required_cols = {"AdjustedIssuedShares", "AdjustedTreasuryShares"}
+
+        if not required_cols.issubset(self.data.columns):
+            missing = required_cols - set(self.data.columns)
+            msg = f"必要な列が存在しません: {missing}。"
+            msg += "事前に .with_adjusted_shares() を呼び出してください。"
+            raise KeyError(msg)
+
+        return pl.col("AdjustedIssuedShares") - pl.col("AdjustedTreasuryShares")
+
     def with_market_cap(self) -> Self:
         """時価総額を計算し、列として追加する。
 
@@ -99,17 +140,18 @@ class Prices(Base):
         計算式:
             時価総額 = 調整前終値 * (調整済み発行済株式数 - 調整済み自己株式数)
 
-        Note:
-            このメソッドを呼び出す前に、`with_adjusted_shares()` を
-            実行して、調整済みの株式数列を事前に計算しておく必要があります。
-
         Returns:
             Self: `MarketCap` 列が追加された、新しいPricesオブジェクト。
+
+        Note:
+            このメソッドを呼び出す前に、`with_adjusted_shares()` あるいは
+            `with_yields()` を実行して、調整済みの株式数列を事前に計算して
+            おく必要があります。
         """
-        shares = pl.col("AdjustedIssuedShares") - pl.col("AdjustedTreasuryShares")
         data = self.data.with_columns(
-            (pl.col("RawClose") * shares).round(0).alias("MarketCap"),
+            (pl.col("RawClose") * self._outstanding_shares_expr).alias("MarketCap"),
         )
+
         return self.__class__(data)
 
     def with_equity(self, statements: Statements) -> Self:
@@ -121,12 +163,44 @@ class Prices(Base):
         Returns:
             Self: `Equity` 列が追加された、新しいPricesオブジェクト。
         """
+        if "Equity" in self.data.columns:
+            return self
+
         data = self.data.join_asof(
             statements.equity(),
             on="Date",
             by="Code",
             check_sortedness=False,
         )
+
+        return self.__class__(data)
+
+    def with_book_value_yield(self) -> Self:
+        """時系列の一株あたり純資産と純資産利回りを列として追加する。
+
+        計算式:
+            一株あたり純資産 = 純資産 / (調整済み発行済株式数 - 調整済み自己株式数)
+            純資産利回り = 一株あたり純資産 / 調整前終値
+
+        Returns:
+            Self: `BookValuePerShare`, `BookValueYield` 列が追加された、
+            新しいPricesオブジェクト。
+
+        Note:
+            このメソッドを呼び出す前に、`with_equity()` および
+            `with_adjusted_shares()` を実行して、純資産および調整済み株式数
+            列を事前に計算しておく必要があります。
+        """
+        data = self.data.with_columns(
+            (pl.col("Equity") / self._outstanding_shares_expr).alias(
+                "BookValuePerShare",
+            ),
+        ).with_columns(
+            (pl.col("BookValuePerShare") / pl.col("RawClose")).alias(
+                "BookValueYield",
+            ),
+        )
+
         return self.__class__(data)
 
     def with_forecast_profit(self, statements: Statements) -> Self:
@@ -138,12 +212,42 @@ class Prices(Base):
         Returns:
             Self: `ForecastProfit` 列が追加された、新しいPricesオブジェクト。
         """
+        if "ForecastProfit" in self.data.columns:
+            return self
+
         data = self.data.join_asof(
             statements.forecast_profit(),
             on="Date",
             by="Code",
             check_sortedness=False,
         )
+
+        return self.__class__(data)
+
+    def with_earnings_yield(self) -> Self:
+        """時系列の一株あたり純利益と収益利回り(純利益利回り)を列として追加する。
+
+        計算式:
+            一株あたり純利益 = 予想純利益 / (調整済み発行済株式数 - 調整済み自己株式数)
+            収益利回り = 一株あたり純利益 / 調整前終値
+
+        Returns:
+            Self: `EarningsPerShare`, `EarningsYield` 列が追加された、
+            新しいPricesオブジェクト。
+
+        Note:
+            このメソッドを呼び出す前に、`with_forecast_profit()` および
+            `with_adjusted_shares()` を実行して、予想純利益および調整済み株式数
+            列を事前に計算しておく必要があります。
+        """
+        data = self.data.with_columns(
+            (pl.col("ForecastProfit") / self._outstanding_shares_expr).alias(
+                "EarningsPerShare",
+            ),
+        ).with_columns(
+            (pl.col("EarningsPerShare") / pl.col("RawClose")).alias("EarningsYield"),
+        )
+
         return self.__class__(data)
 
     def with_forecast_dividend(self, statements: Statements) -> Self:
@@ -155,10 +259,75 @@ class Prices(Base):
         Returns:
             Self: `ForecastDividend` 列が追加された、新しいPricesオブジェクト。
         """
+        if "ForecastDividend" in self.data.columns:
+            return self
+
         data = self.data.join_asof(
             statements.forecast_dividend(),
             on="Date",
             by="Code",
             check_sortedness=False,
         )
+
         return self.__class__(data)
+
+    def with_dividend_yield(self) -> Self:
+        """時系列の一株あたり配当金と配当利回りを列として追加する。
+
+        計算式:
+            一株あたり配当金 = 予想年間配当総額 / (調整済み発行済株式数 - 調整済み自己株式数)
+            配当利回り = 一株あたり配当金 / 調整前終値
+
+        Returns:
+            Self: `DividendPerShare`, `DividendYield` 列が追加された、
+            新しいPricesオブジェクト。
+
+        Note:
+            このメソッドを呼び出す前に、`with_forecast_dividend()` および
+            `with_adjusted_shares()` を実行して、予想年間配当総額および調整済み株式数
+            列を事前に計算しておく必要があります。
+        """  # noqa: E501
+        data = self.data.with_columns(
+            (pl.col("ForecastDividend") / self._outstanding_shares_expr).alias(
+                "DividendPerShare",
+            ),
+        ).with_columns(
+            (pl.col("DividendPerShare") / pl.col("RawClose")).alias("DividendYield"),
+        )
+
+        return self.__class__(data)
+
+    def with_yields(self, statements: Statements) -> Self:
+        """すべての利回り関連指標を計算し、列として追加する。
+
+        このメソッドは、以下の利回り関連指標をまとめて計算し、DataFrameに
+        追加するコンビニエンスメソッドです。
+
+        *   純資産利回り (`BookValueYield`)
+        *   収益利回り (`EarningsYield`)
+        *   配当利回り (`DividendYield`)
+
+        内部で `with_adjusted_shares()`, `with_equity()`,
+        `with_book_value_yield()`, `with_forecast_profit()`,
+        `with_earnings_yield()`, `with_forecast_dividend()`,
+        `with_dividend_yield()` を呼び出します。
+        これらのメソッドはべき等であるため、重複して呼び出されても
+        無駄な計算は行われません。
+
+        Args:
+            statements (Statements): 財務データを提供する`Statements`オブジェクト。
+
+        Returns:
+            Self: `BookValuePerShare`, `BookValueYield`, `EarningsPerShare`,
+            `EarningsYield`, `DividendPerShare`, `DividendYield` 列が追加された、
+            新しいPricesオブジェクト。
+        """
+        return (
+            self.with_adjusted_shares(statements)
+            .with_equity(statements)
+            .with_book_value_yield()
+            .with_forecast_profit(statements)
+            .with_earnings_yield()
+            .with_forecast_dividend(statements)
+            .with_dividend_yield()
+        )

kabukit/core/statements.py

@@ -12,7 +12,7 @@ if TYPE_CHECKING:
 
 class Statements(Base):
     def shares(self) -> DataFrame:
-        """発行済株式数を取得する。"""
+        """発行済株式数および自己株式数を取得する。"""
         return self.data.filter(
             pl.col("IssuedShares").is_not_null(),
         ).select(
@@ -20,7 +20,6 @@ class Statements(Base):
             "Code",
             "IssuedShares",
             "TreasuryShares",
-            "AverageOutstandingShares",
         )
 
     def equity(self) -> DataFrame:

{kabukit-0.5.2.dist-info → kabukit-0.5.3.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: kabukit
-Version: 0.5.2
+Version: 0.5.3
 Summary: A Python toolkit for Japanese financial market data, supporting J-Quants and EDINET APIs.
 Author: daizutabi
 Author-email: daizutabi <daizutabi@gmail.com>

{kabukit-0.5.2.dist-info → kabukit-0.5.3.dist-info}/RECORD

@@ -13,9 +13,9 @@ kabukit/core/base.py,sha256=YQfGw3P2QshRdut3KhtrAleVvnFsIPOw5oGA9azypAA,1695
 kabukit/core/client.py,sha256=tVq1r3zpOfjmOtnRI1KPZHgTgBZYIpJzfw15i2kAM48,676
 kabukit/core/info.py,sha256=5BX7mDavF6g-b0KzHgKIFHUS5701BoaHtw1JcHSsy94,174
 kabukit/core/list.py,sha256=AjnXzC9XIu21l6IBEHHAS5VAnfxTfkAA9m1WAOZJNa8,174
-kabukit/core/prices.py,sha256=4jL6ItbyVov-G-JuZhvZTzqTDeisHJ9rEPH9wpf3pUg,6382
+kabukit/core/prices.py,sha256=YGhz6ZjfC86aZ0pM4NFxceXTs2gTmO2hVdPd5DawV14,13316
 kabukit/core/reports.py,sha256=ch_xe84GbB17JTfmY3ArQqneQ2XOuvrAykBTAyNmWuM,177
-kabukit/core/statements.py,sha256=BNVmzTF_GvckRj3TfZT5ZoSBfnK32RzJM8YHpkz-h6Y,2806
+kabukit/core/statements.py,sha256=_n4-8G284e6y_MwhvUq4xBK4bapQHk-Zmwu09C_r7wU,2790
 kabukit/edinet/__init__.py,sha256=PKa4D-jVpeoOkdVp9NwwpgAiGEBjqvmJLmpzF-9SlVk,101
 kabukit/edinet/client.py,sha256=BlM7pjXpKweOo-ses41JiKinqRn4qerMN5NF7hgYKgg,3275
 kabukit/edinet/concurrent.py,sha256=2YPzIFuuOB8-gL3CnHIlP486QH5d21qjKNKGCFK7Hzk,4707
@@ -33,7 +33,7 @@ kabukit/utils/concurrent.py,sha256=m2zVqJUz4xFVpNbEc9YEaj3Jmbl82njupdm4_rBOoYQ,4
 kabukit/utils/config.py,sha256=Jp-2TCnIj_QqA71FzYCkHXbvXvhw_1JVl4PR0foA1vM,618
 kabukit/utils/date.py,sha256=DEC6Ac5LS8eiW6JtrmcD3U1pX4qzXtx4ale0swpO4Ag,937
 kabukit/utils/params.py,sha256=qcaJbf6CWPUoZAZsYDTaZSnBUWeAersbWnR_iiYW9GM,1108
-kabukit-0.5.2.dist-info/WHEEL,sha256=n2u5OFBbdZvCiUKAmfnY1Po2j3FB_NWfuUlt5WiAjrk,79
-kabukit-0.5.2.dist-info/entry_points.txt,sha256=vvX771TemoM-35vVizW3JJ70HvRXnd2tX4P1Btzyoxs,46
-kabukit-0.5.2.dist-info/METADATA,sha256=HCAafrEHVXPOwUFGWhmBK2Q0UFhMcpbMAZk8ZxAWHpo,3207
-kabukit-0.5.2.dist-info/RECORD,,
+kabukit-0.5.3.dist-info/WHEEL,sha256=n2u5OFBbdZvCiUKAmfnY1Po2j3FB_NWfuUlt5WiAjrk,79
+kabukit-0.5.3.dist-info/entry_points.txt,sha256=vvX771TemoM-35vVizW3JJ70HvRXnd2tX4P1Btzyoxs,46
+kabukit-0.5.3.dist-info/METADATA,sha256=B1p6W0ztcfnlZ2i1x6IpAjobxlffOATdoSngUxu6ztc,3207
+kabukit-0.5.3.dist-info/RECORD,,