tea-bond 0.3.1__cp310-abi3-macosx_11_0_arm64.whl → 0.3.2__cp310-abi3-macosx_11_0_arm64.whl

pybond/__init__.py

@@ -1,7 +1,6 @@
 from __future__ import annotations
 
 from .bond import Bond
-
 from .pybond import Future, Ib, Sse
 from .pybond import TfEvaluator as _TfEvaluatorRS
 
@@ -9,7 +8,9 @@ from .pybond import TfEvaluator as _TfEvaluatorRS
 class TfEvaluator(_TfEvaluatorRS):
     def __new__(cls, future, bond, *args, **kwargs):
         if not isinstance(bond, Bond):
+            # 便于直接从Wind下载债券基础数据
             bond = Bond(bond)
         return super().__new__(cls, future, bond, *args, **kwargs)
 
+
 __all__ = ["Bond", "Future", "Ib", "Sse", "TfEvaluator"]

pybond/pd.py

@@ -0,0 +1,394 @@
+from __future__ import annotations
+
+import pandas as pd
+import polars as pl
+
+from .pl import Bonds as PlBonds
+from .pl import TfEvaluators as PlTfEvaluators
+
+
+class TfEvaluators:
+    """
+    Treasury Futures Evaluators for pandas DataFrames.
+
+    A pandas-compatible wrapper around the Polars-based TfEvaluators that provides
+    various financial calculations for treasury futures and bonds analysis.
+
+    This class converts pandas inputs to Polars for computation and returns
+    pandas Series results for seamless integration with pandas workflows.
+    """
+
+    def __init__(
+        self,
+        future: str | pd.Series,
+        bond: str | pd.Series,
+        date: str | pd.Series,
+        future_price: pd.Series,
+        bond_ytm: pd.Series,
+        capital_rate: float | pd.Series,
+        reinvest_rate: float | None = None,
+    ):
+        """
+        Initialize TfEvaluators with market data.
+
+        Args:
+            future: Future contract code(s)
+            bond: Bond code(s)
+            date: Evaluation date(s)
+            future_price: Future price(s)
+            bond_ytm: Bond yield to maturity
+            capital_rate: Capital cost rate for carry calculations
+            reinvest_rate: Reinvestment rate for coupon payments (optional)
+        """
+        self.pl_df = pl.DataFrame(
+            {
+                "future": future,
+                "bond": bond,
+                "date": date,
+                "future_price": future_price,
+                "bond_ytm": bond_ytm,
+                "capital_rate": capital_rate,
+            }
+        )
+        self._evaluators = PlTfEvaluators(reinvest_rate=reinvest_rate)
+        # self.reinvest_rate = reinvest_rate
+
+    @property
+    def net_basis_spread(self):
+        """
+        Calculate net basis spread (净基差).
+
+        Net basis spread = basis spread - carry return
+
+        Returns:
+            pd.Series: Net basis spread values
+        """
+        return self.pl_df.select(net_basis_spread=self._evaluators.net_basis_spread)[
+            "net_basis_spread"
+        ].to_pandas()
+
+    @property
+    def accrued_interest(self):
+        """
+        Calculate accrued interest (应计利息).
+
+        Returns:
+            pd.Series: Accrued interest values
+        """
+        return self.pl_df.select(accrued_interest=self._evaluators.accrued_interest)[
+            "accrued_interest"
+        ].to_pandas()
+
+    @property
+    def deliver_accrued_interest(self):
+        """
+        Calculate delivery accrued interest (国债期货交割应计利息).
+
+        Returns:
+            pd.Series: Delivery accrued interest values
+        """
+        return self.pl_df.select(
+            deliver_accrued_interest=self._evaluators.deliver_accrued_interest
+        )["deliver_accrued_interest"].to_pandas()
+
+    @property
+    def cf(self):
+        """
+        Calculate conversion factor (转换因子).
+
+        Returns:
+            pd.Series: Conversion factor values
+        """
+        return self.pl_df.select(cf=self._evaluators.cf)["cf"].to_pandas()
+
+    @property
+    def dirty_price(self):
+        """
+        Calculate bond dirty price (债券全价).
+
+        Returns:
+            pd.Series: Bond dirty price values
+        """
+        return self.pl_df.select(dirty_price=self._evaluators.dirty_price)[
+            "dirty_price"
+        ].to_pandas()
+
+    @property
+    def clean_price(self):
+        """
+        Calculate bond clean price (债券净价).
+
+        Returns:
+            pd.Series: Bond clean price values
+        """
+        return self.pl_df.select(clean_price=self._evaluators.clean_price)[
+            "clean_price"
+        ].to_pandas()
+
+    @property
+    def future_dirty_price(self):
+        """
+        Calculate future dirty price (期货全价/发票价格).
+
+        Returns:
+            pd.Series: Future dirty price values
+        """
+        return self.pl_df.select(
+            future_dirty_price=self._evaluators.future_dirty_price
+        )["future_dirty_price"].to_pandas()
+
+    @property
+    def deliver_cost(self):
+        """
+        Calculate delivery cost (交割成本).
+
+        Delivery cost = bond dirty price - interim coupon payments
+
+        Returns:
+            pd.Series: Delivery cost values
+        """
+        return self.pl_df.select(deliver_cost=self._evaluators.deliver_cost)[
+            "deliver_cost"
+        ].to_pandas()
+
+    @property
+    def basis_spread(self):
+        """
+        Calculate basis spread (基差).
+
+        Returns:
+            pd.Series: Basis spread values
+        """
+        return self.pl_df.select(basis_spread=self._evaluators.basis_spread)[
+            "basis_spread"
+        ].to_pandas()
+
+    @property
+    def f_b_spread(self):
+        """
+        Calculate futures-bond spread (期现价差).
+
+        Returns:
+            pd.Series: Futures-bond spread values
+        """
+        return self.pl_df.select(f_b_spread=self._evaluators.f_b_spread)[
+            "f_b_spread"
+        ].to_pandas()
+
+    @property
+    def carry(self):
+        """
+        Calculate carry return (持有收益).
+
+        Carry return = (delivery accrued - trading accrued + interim coupons) +
+                      capital cost rate * (weighted average interim coupons - bond dirty price * remaining days / 365)
+
+        Returns:
+            pd.Series: Carry return values
+        """
+        return self.pl_df.select(carry=self._evaluators.carry)["carry"].to_pandas()
+
+    @property
+    def duration(self):
+        """
+        Calculate modified duration (修正久期).
+
+        Returns:
+            pd.Series: Modified duration values
+        """
+        return self.pl_df.select(duration=self._evaluators.duration)[
+            "duration"
+        ].to_pandas()
+
+    @property
+    def irr(self):
+        """
+        Calculate internal rate of return (内部收益率).
+
+        Returns:
+            pd.Series: Internal rate of return values
+        """
+        return self.pl_df.select(irr=self._evaluators.irr)["irr"].to_pandas()
+
+    @property
+    def future_ytm(self):
+        """
+        Calculate futures implied yield to maturity (期货隐含收益率).
+
+        Returns:
+            pd.Series: Futures implied yield to maturity values
+        """
+        return self.pl_df.select(future_ytm=self._evaluators.future_ytm)[
+            "future_ytm"
+        ].to_pandas()
+
+    @property
+    def remain_cp_to_deliver(self):
+        """
+        Calculate remaining coupon payments to delivery (到交割的期间付息).
+
+        Returns:
+            pd.Series: Remaining coupon payments to delivery values
+        """
+        return self.pl_df.select(
+            remain_cp_to_deliver=self._evaluators.remain_cp_to_deliver
+        )["remain_cp_to_deliver"].to_pandas()
+
+    @property
+    def remain_cp_to_deliver_wm(self):
+        """
+        Calculate weighted average remaining coupon payments to delivery (加权平均到交割的期间付息).
+
+        Returns:
+            pd.Series: Weighted average remaining coupon payments to delivery values
+        """
+        return self.pl_df.select(
+            remain_cp_to_deliver_wm=self._evaluators.remain_cp_to_deliver_wm
+        )["remain_cp_to_deliver_wm"].to_pandas()
+
+    @property
+    def remain_cp_num(self):
+        """
+        Calculate remaining number of coupon payments (债券剩余付息次数).
+
+        Returns:
+            pd.Series: Remaining number of coupon payments values
+        """
+        return self.pl_df.select(remain_cp_num=self._evaluators.remain_cp_num)[
+            "remain_cp_num"
+        ].to_pandas()
+
+
+class Bonds:
+    """
+    Bond calculations for pandas DataFrames.
+
+    A pandas-compatible wrapper around the Polars-based Bonds class that provides
+    bond-specific financial calculations without requiring futures contract information.
+    """
+
+    def __init__(self, bond: str | pd.Series):
+        """
+        Initialize Bonds with bond identifier.
+
+        Args:
+            bond: Bond code(s)
+        """
+        self.bond = bond
+
+    def accrued_interest(self, date: str | pd.Series):
+        """
+        Calculate accrued interest for the bond (应计利息).
+
+        Args:
+            date: Evaluation date(s)
+
+        Returns:
+            pd.Series: Accrued interest values
+        """
+        df = pl.DataFrame({"bond": self.bond, "date": date})
+        return df.select(accrued_interest=PlBonds("bond").accrued_interest("date"))[
+            "accrued_interest"
+        ].to_pandas()
+
+    def clean_price(self, ytm: float | pd.Series, date: str | pd.Series):
+        """
+        Calculate bond clean price (债券净价).
+
+        Args:
+            ytm: Yield to maturity
+            date: Evaluation date(s)
+
+        Returns:
+            pd.Series: Bond clean price values
+        """
+        df = pl.DataFrame({"bond": self.bond, "ytm": ytm, "date": date})
+        return df.select(clean_price=PlBonds("bond").clean_price("ytm", "date"))[
+            "clean_price"
+        ].to_pandas()
+
+    def dirty_price(self, ytm: float | pd.Series, date: str | pd.Series):
+        """
+        Calculate bond dirty price (债券全价).
+
+        Args:
+            ytm: Yield to maturity
+            date: Evaluation date(s)
+
+        Returns:
+            pd.Series: Bond dirty price values
+        """
+        df = pl.DataFrame({"bond": self.bond, "ytm": ytm, "date": date})
+        return df.select(dirty_price=PlBonds("bond").dirty_price("ytm", "date"))[
+            "dirty_price"
+        ].to_pandas()
+
+    def duration(self, ytm: float | pd.Series, date: str | pd.Series):
+        """
+        Calculate modified duration (修正久期).
+
+        Args:
+            ytm: Yield to maturity
+            date: Evaluation date(s)
+
+        Returns:
+            pd.Series: Modified duration values
+        """
+        df = pl.DataFrame({"bond": self.bond, "ytm": ytm, "date": date})
+        return df.select(duration=PlBonds("bond").duration("ytm", "date"))[
+            "duration"
+        ].to_pandas()
+
+    def remain_cp_num(self, date: str | pd.Series):
+        """
+        Calculate remaining number of coupon payments (债券剩余付息次数).
+
+        Args:
+            date: Evaluation date(s)
+
+        Returns:
+            pd.Series: Remaining number of coupon payments values
+        """
+        df = pl.DataFrame({"bond": self.bond, "date": date})
+        return df.select(remain_cp_num=PlBonds("bond").remain_cp_num("date"))[
+            "remain_cp_num"
+        ].to_pandas()
+
+
+def find_workday(date: str | pd.Series, market: str, offset: int = 0):
+    """
+    Find the workday based on the given date and market calendar.
+
+    Args:
+        date: Input date(s)
+        market: Market identifier ("IB" or "SSE")
+        offset: Number of workdays to offset (default: 0)
+
+    Returns:
+        pd.Series: Adjusted workday values
+    """
+    from .pl import find_workday as pl_find_workday
+
+    df = pl.DataFrame({"date": date}).select(pl.col("date").dt.date())
+    return df.select(workday=pl_find_workday("date", market, offset))[
+        "workday"
+    ].to_pandas()
+
+
+def is_business_day(date: str | pd.Series, market: str):
+    """
+    Check if the given date is a business day for the specified market.
+
+    Args:
+        date: Input date(s)
+        market: Market identifier ("IB" or "SSE")
+
+    Returns:
+        pd.Series: Boolean values indicating if dates are business days
+    """
+    from .pl import is_business_day as pl_is_business_day
+
+    df = pl.DataFrame({"date": date}).select(pl.col("date").dt.date())
+    return df.select(is_business=pl_is_business_day("date", market))[
+        "is_business"
+    ].to_pandas()

pybond/pl.py

@@ -2,6 +2,8 @@ from __future__ import annotations
 
 from typing import TYPE_CHECKING
 
+from .pybond import Ib, Sse
+
 if TYPE_CHECKING:
     from polars.type_aliases import IntoExpr
 import polars as pl
@@ -239,10 +241,35 @@ class TfEvaluators:
 
 
 class Bonds:
+    """
+    A class for bond-specific calculations using Polars expressions.
+
+    This class provides methods for calculating various bond metrics
+    without requiring futures contract information.
+    """
+
     def __init__(self, bond: IntoExpr = "symbol"):
+        """
+        Initialize Bonds with bond identifier.
+
+        Args:
+            bond: Bond code column expression (default: "symbol")
+        """
         self.bond = bond
 
-    def _evaluator(self, date=None, ytm=None) -> TfEvaluators:
+    def _evaluator(
+        self, date: IntoExpr | None = None, ytm: IntoExpr | None = None
+    ) -> TfEvaluators:
+        """
+        Create a TfEvaluators instance for bond-only calculations.
+
+        Args:
+            date: Evaluation date column expression
+            ytm: Yield to maturity column expression
+
+        Returns:
+            TfEvaluators: Configured evaluator instance
+        """
         return TfEvaluators(
             future=None,
             bond=self.bond,
@@ -253,19 +280,116 @@ class Bonds:
             reinvest_rate=None,
         )
 
-    def accrued_interest(self, date="date"):
+    def accrued_interest(self, date: IntoExpr = "date"):
+        """
+        Calculate accrued interest for the bond (应计利息).
+
+        Args:
+            date: Evaluation date column expression
+
+        Returns:
+            Polars expression for accrued interest
+        """
         return self._evaluator(date=date).accrued_interest
 
-    def clean_price(self, ytm="ytm", date="date"):
+    def clean_price(self, ytm: IntoExpr = "ytm", date: IntoExpr = "date"):
+        """
+        Calculate bond clean price (债券净价).
+
+        Args:
+            ytm: Yield to maturity column expression
+            date: Evaluation date column expression
+
+        Returns:
+            Polars expression for bond clean price
+        """
         return self._evaluator(date=date, ytm=ytm).clean_price
 
-    def dirty_price(self, ytm="ytm", date="date"):
+    def dirty_price(self, ytm: IntoExpr = "ytm", date: IntoExpr = "date"):
+        """
+        Calculate bond dirty price (债券全价).
+
+        Args:
+            ytm: Yield to maturity column expression
+            date: Evaluation date column expression
+
+        Returns:
+            Polars expression for bond dirty price
+        """
         return self._evaluator(date=date, ytm=ytm).dirty_price
 
-    def duration(self, ytm="ytm", date="date"):
+    def duration(self, ytm: IntoExpr = "ytm", date: IntoExpr = "date"):
+        """
+        Calculate modified duration (修正久期).
+
+        Args:
+            ytm: Yield to maturity column expression
+            date: Evaluation date column expression
+
+        Returns:
+            Polars expression for modified duration
+        """
         return self._evaluator(date=date, ytm=ytm).duration
 
-    def remain_cp_num(self, date="date"):
+    def remain_cp_num(self, date: IntoExpr = "date"):
+        """
+        Calculate remaining number of coupon payments (债券剩余付息次数).
+
+        Args:
+            date: Evaluation date column expression
+
+        Returns:
+            Polars expression for remaining number of coupon payments
+        """
         return self._evaluator(date=date).remain_cp_num
 
     # TODO(Teamon): 实现向量化根据净价反推ytm的函数
+
+
+def find_workday(date: IntoExpr, market: str | Ib | Sse, offset: int = 0):
+    """
+    Find the workday based on the given date and market calendar.
+
+    Args:
+        date: Input date column expression
+        market: Market identifier (IB, SSE, or string)
+        offset: Number of workdays to offset (default: 0)
+
+    Returns:
+        Polars expression for the adjusted workday
+    """
+    if market == Ib:
+        market = "IB"
+    elif market == Sse:
+        market = "SSE"
+    date = parse_into_expr(date)
+    return register_plugin(
+        args=[date],
+        kwargs={"market": market, "offset": offset},
+        symbol="calendar_find_workday",
+        is_elementwise=True,
+    )
+
+
+def is_business_day(date: IntoExpr, market: str | Ib | Sse):
+    """
+    Check if the given date is a business day for the specified market.
+
+    Args:
+        date: Input date column expression
+        market: Market identifier (IB, SSE, or string)
+
+    Returns:
+        Polars expression returning boolean values for business day check
+    """
+    if market == Ib:
+        market = "IB"
+    elif market == Sse:
+        market = "SSE"
+    date = parse_into_expr(date)
+    return register_plugin(
+        args=[date],
+        kwargs={"market": market},
+        symbol="calendar_is_business_day",
+        is_elementwise=True,
+    )

{tea_bond-0.3.1.dist-info → tea_bond-0.3.2.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tea-bond
-Version: 0.3.1
+Version: 0.3.2
 Classifier: Programming Language :: Rust
 Classifier: Programming Language :: Python :: Implementation :: CPython
 Classifier: Programming Language :: Python :: Implementation :: PyPy

{tea_bond-0.3.1.dist-info → tea_bond-0.3.2.dist-info}/RECORD

@@ -1,4 +1,4 @@
-pybond/__init__.py,sha256=7x1hBQtlQRhvgxfe6Z0wtQ5tWpTfUPMnaKyjddRyk9Y,430
+pybond/__init__.py,sha256=k0LZ2gzo0mln4AFUnFMClgDorRWfUGUlt7T_UESYS7A,488
 pybond/bond.py,sha256=_bpG2MZkFobGS8kkem3z7eNvCR7GqWJHMH4WJCfB5EQ,6568
 pybond/download.py,sha256=ehl_LfcfjCB5dtVvqD0P9PJzK1UYlqhzpDcBq5BycDI,4222
 pybond/ffi/__init__.py,sha256=x4FSqdM-SZPir9DL_XSMjoO9c4CWsyE5XfQr4GraGsg,94
@@ -15,11 +15,12 @@ pybond/nb/nb_datetime.py,sha256=9fLD9rnfpHQ-cvX4H6PoFh_O3jgk475ZKrG8q_UxT34,1026
 pybond/nb/nb_duration.py,sha256=FSX1y2JbHB_SJn-hcVe-7Zf2v0xpQKKZ1MfWBY7d7IQ,1639
 pybond/nb/nb_evaluators.py,sha256=fCYxcvW717_1E4qY9AV8R5Pv8eTvWqKk3Zj-zMU1kiw,14987
 pybond/nb/nb_time.py,sha256=LaqXfcNvmYD_lZ2u108MwrxCXoVCBX3cr3oOnPp3c1g,8649
-pybond/pl.py,sha256=CakQvQPjvWu8XykDfkBznFmFkIB8m-lVllF-8_BrUsw,7860
+pybond/pd.py,sha256=QmkADhIu0T7w1pbhYZB9dFDaPSO9aZ3kdFxktZf5Kro,11591
+pybond/pl.py,sha256=fk5AGXym02gCkJIZmOpQRPf1qnqYUa1V_PawbeYm7WE,11285
 pybond/pnl.py,sha256=P3KXc-gz6_TA2QxDQR9NHJIJPCvLOGT_v4qN4gzdcRY,1568
 pybond/polars_utils.py,sha256=A8D5T0x08oMCndWiQ5DPhLsuWp8s4OPgqvAnK36d8yY,2567
-pybond/pybond.abi3.so,sha256=hWQdqKMPT9KZU6fPD8z7dLy7b0q5J6HBJi2O0hrikNU,23186096
+pybond/pybond.abi3.so,sha256=xgxcMNOinn1BMAsOhzwxWI_PfZBSmNFE1lPyfKeIll4,23265984
 pybond/pybond.pyi,sha256=xME119HJzVNqNCJ9FapVaQg1amxbNHlbd-qfFyiuhL4,11230
-tea_bond-0.3.1.dist-info/METADATA,sha256=9zA8uD2lRgPAeN66HKlZYrvs1CHs2ZyM6IeJRhWveC4,258
-tea_bond-0.3.1.dist-info/WHEEL,sha256=Mdosfxua6Dx1zYgObRH97e3wyiELqBbLtoRJj4RUSQE,103
-tea_bond-0.3.1.dist-info/RECORD,,
+tea_bond-0.3.2.dist-info/METADATA,sha256=gZqfIfy4fjk1QBHtuRogb71fM-6cyltEf1lw-rsNo44,258
+tea_bond-0.3.2.dist-info/WHEEL,sha256=Mdosfxua6Dx1zYgObRH97e3wyiELqBbLtoRJj4RUSQE,103
+tea_bond-0.3.2.dist-info/RECORD,,