PYield 0.37.2__tar.gz → 0.37.3__tar.gz

{pyield-0.37.2 → pyield-0.37.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: PYield
-Version: 0.37.2
+Version: 0.37.3
 Summary: A Python library for analysis of fixed income instruments in Brazil
 Project-URL: Source, https://github.com/crdcj/PYield
 Author-email: Carlos Carvalho <cr.cj@outlook.com>

pyield-0.37.3/pyield/__about__.py

@@ -0,0 +1 @@
+__version__ = "0.37.3"

{pyield-0.37.2 → pyield-0.37.3}/pyield/anbima/__init__.py

@@ -2,13 +2,13 @@ from pyield.anbima.ettj import intraday_ettj, last_ettj
 from pyield.anbima.ima import last_ima
 from pyield.anbima.imaq import imaq
 from pyield.anbima.ipca import ipca_projection
-from pyield.anbima.tpf import fetch_tpf_data, tpf_data, tpf_fixed_rate_maturities
+from pyield.anbima.tpf import _fetch_tpf_data, tpf_data, tpf_fixed_rate_maturities
 
 __all__ = [
     "last_ima",
     "imaq",
     "ipca_projection",
-    "fetch_tpf_data",
+    "_fetch_tpf_data",
     "tpf_data",
     "tpf_fixed_rate_maturities",
     "last_ettj",

{pyield-0.37.2 → pyield-0.37.3}/pyield/anbima/tpf.py

@@ -8,6 +8,7 @@ from zoneinfo import ZoneInfo
 import pandas as pd
 
 from pyield import bday
+from pyield.b3 import di1
 from pyield.bc.ptax_api import ptax
 from pyield.data_cache import get_cached_dataset
 from pyield.date_converter import DateScalar, convert_input_dates
@@ -106,7 +107,7 @@ def _process_raw_df(df_raw: pd.DataFrame) -> pd.DataFrame:
     return df
 
 
-def _process_dv01(df: pd.DataFrame) -> pd.DataFrame:
+def _add_dv01(df: pd.DataFrame) -> pd.DataFrame:
     df["BDToMat"] = bday.count(start=df["ReferenceDate"], end=df["MaturityDate"])
 
     df["Duration"] = 0.0
@@ -167,6 +168,17 @@ def _add_usd_dv01(df: pd.DataFrame) -> pd.DataFrame:
     return df
 
 
+def _add_di_rate(df: pd.DataFrame, target_date: pd.Timestamp) -> pd.DataFrame:
+    """Add the DI rate column to the DataFrame."""
+    # INSERIR OS DADOS DO DI INTERPOLADO ###
+    df["DIRate"] = di1.interpolate_rates(
+        dates=target_date,
+        expirations=df["MaturityDate"],
+        extrapolate=True,
+    )
+    return df
+
+
 def _reorder_columns(df: pd.DataFrame) -> pd.DataFrame:
     """Reorder the columns of the DataFrame according to the specified order."""
     column_order = [
@@ -183,6 +195,7 @@ def _reorder_columns(df: pd.DataFrame) -> pd.DataFrame:
         "BidRate",
         "AskRate",
         "IndicativeRate",
+        "DIRate",
         "StdDev",
         "LowerBoundRateD0",
         "UpperBoundRateD0",
@@ -194,65 +207,22 @@ def _reorder_columns(df: pd.DataFrame) -> pd.DataFrame:
     return df[column_order].copy()
 
 
-def _select_main_columns(df: pd.DataFrame) -> pd.DataFrame:
-    """Select only the main columns from the DataFrame."""
-    main_columns = [
-        "BondType",
-        "ReferenceDate",
-        "MaturityDate",
-        "BDToMat",
-        "Duration",
-        "DV01",
-        "DV01USD",
-        "Price",
-        "BidRate",
-        "AskRate",
-        "IndicativeRate",
-    ]
-    main_columns = [col for col in main_columns if col in df.columns]
-    return df[main_columns].copy()
-
-
-def fetch_tpf_data(
-    date: DateScalar,
-    bond_type: str | BOND_TYPES | None = None,
-    all_columns: bool = True,
-) -> pd.DataFrame:
-    """Fetch and process TPF secondary market data directly from the ANBIMA website.
-    This is a low-level function intended for internal use or specific backend
-    jobs. For general use, prefer `tpf_data` which includes caching logic.
-
-    Only the last 5 days of data are available in the ANBIMA website. Data older
-    than 5 business days is only available through the RTM network.
+def _fetch_tpf_data(date: pd.Timestamp) -> pd.DataFrame:
+    """Fetch and process TPF secondary market data directly from the ANBIMA source.
 
-    This function retrieves bond market data from the ANBIMA website for a
-    specified reference date. It handles different file formats based on the date
-    and attempts to download the data from both member and non-member URLs.
+    This is a low-level function intended for internal use. It handles the logic
+    of building the correct URL (public or RTM), downloading the data with retries,
+    and processing it into a structured DataFrame.
 
     Args:
-        date (DateScalar): The reference date for the data.
-        bond_type (str, optional):  Filter data by bond type.
-            Defaults to None, which returns data for all bond types.
-        all_columns (bool, optional):  If True, all columns are returned.
-            Defaults to True. If False, only the main columns are returned.
+        date (pd.Timestamp): The reference date for the data.
 
     Returns:
-        pd.DataFrame: A DataFrame containing bond market data.
-            Returns an empty DataFrame if data is not available for the
-            specified date (weekends, holidays, unavailable data, or lack of
-            RTM access for older data).
+        pd.DataFrame: A DataFrame containing processed bond market data, or an
+            empty DataFrame if data is unavailable or a connection error occurs.
     """
-    date = convert_input_dates(date)
-    date_log = date.strftime("%d/%m/%Y")
-    today = dt.datetime.now(BZ_TIMEZONE).date()
-    if date.date() > today:
-        logger.info(
-            f"Cannot fetch data for a future date ({date_log}). "
-            "Returning empty DataFrame."
-        )
-        return pd.DataFrame()
-
     file_url = _build_file_url(date)
+    date_str = date.strftime("%d/%m/%Y")
 
     # --- "FAIL-FAST" PARA EVITAR RETRIES DESNECESSÁRIOS NA RTM ---
     if ANBIMA_RTM_URL in file_url:
@@ -263,7 +233,7 @@ def fetch_tpf_data(
             # Se falhar (gaierror = get address info error), não estamos na RTM.
             # Não adianta prosseguir para a função com retry.
             logger.warning(
-                f"Could not resolve RTM host for {date_log}. This is expected if "
+                f"Could not resolve RTM host for {date_str}. This is expected if "
                 "you are not on the RTM network. Historical data requires RTM access. "
                 "Returning empty DataFrame."
             )
@@ -274,40 +244,35 @@ def fetch_tpf_data(
         df = _read_raw_df(file_url)
         if df.empty:
             logger.info(
-                f"Anbima TPF secondary market data for {date_log} not available. "
+                f"Anbima TPF secondary market data for {date_str} not available. "
                 "Returning empty DataFrame."
             )
             return df
         df = _process_raw_df(df)
-        df = _process_dv01(df)
+        df = _add_dv01(df)
         df = _add_usd_dv01(df)
+        df = _add_di_rate(df, target_date=date)
         df = _reorder_columns(df)
 
-        if not all_columns:
-            df = _select_main_columns(df)
-
-        if bond_type:
-            norm_bond_type = _bond_type_mapping(bond_type)  # noqa
-            df = df.query("BondType == @norm_bond_type").reset_index(drop=True)
         return df.sort_values(["BondType", "MaturityDate"]).reset_index(drop=True)
 
     except HTTPError as e:
         if e.code == 404:  # noqa
             logger.info(
-                f"No Anbima TPF secondary market data for {date_log} (HTTP 404). "
+                f"No Anbima TPF secondary market data for {date_str} (HTTP 404). "
                 "Returning empty DataFrame."
             )
             return pd.DataFrame()
-        logger.error(f"HTTP Error fetching data for {date_log} from {file_url}: {e}")
+        logger.error(f"HTTP Error fetching data for {date_str} from {file_url}: {e}")
         raise
 
     # Este bloco ainda é útil para outros URLErrors (ex: timeout genuíno na URL pública)
     except URLError:
-        logger.exception(f"Network error (URLError) fetching TPF data for {date_log}")
+        logger.exception(f"Network error (URLError) fetching TPF data for {date_str}")
         raise
 
     except Exception:
-        msg = f"An unexpected error occurred fetching TPF data for {date_log}"
+        msg = f"An unexpected error occurred fetching TPF data for {date_str}"
         logger.exception(msg)
         raise
 
@@ -315,27 +280,27 @@ def fetch_tpf_data(
 def tpf_data(
     date: DateScalar,
     bond_type: str | None = None,
-    adj_maturities: bool = False,
+    fetch_from_source: bool = False,
 ) -> pd.DataFrame:
-    """Retrieve indicative rates for bonds from ANBIMA data.
+    """Retrieve TPF secondary market data from ANBIMA.
 
-    This function fetches indicative rates for bonds from ANBIMA,
-    initially attempting to retrieve data from a cached dataset. If the data
-    is not available in the cache, it fetches it directly from the ANBIMA website.
+    This function fetches indicative rates and other data for Brazilian government
+    bonds from ANBIMA. By default, it attempts to retrieve data from a local
+    cache for performance. If `fetch_from_source` is True, it tries to fetch the data
+    directly from the ANBIMA website.
 
     Args:
-        date (DateScalar): The reference date for the rates.
-        bond_type (str, optional): Filter rates by bond type.
-            Defaults to None, which returns rates for all bond types.
-        adj_maturities (bool, optional): Adjust maturity dates to the next
-            business day. Defaults to False.
+        date (DateScalar): The reference date for the data (e.g., '2024-06-14').
+        bond_type (str, optional): Filters results by a specific bond type
+            (e.g., 'LTN', 'NTN-B'). Defaults to None, returning all bond types.
+        fetch_from_source (bool, optional): If True, forces the function to
+            bypass the cache and fetch data directly from the source.
+            Defaults to False.
 
     Returns:
-        pd.DataFrame: A DataFrame with the following columns:
-            - BondType: The type of bond.
-            - MaturityDate: The maturity date of the bond.
-            - IndicativeRate: The indicative rate of the bond.
-            - Price: The price (PU) of the bond.
+        pd.DataFrame: A DataFrame containing the requested bond data. An empty
+        DataFrame is returned if no data is available for the specified date
+        (e.g., weekends, holidays, or future dates).
 
     Examples:
         >>> from pyield import anbima
@@ -347,30 +312,67 @@ def tpf_data(
         3     2025-08-22      LFT   2027-03-01        0.000302  17193.200289
         4     2025-08-22      LFT   2027-09-01        0.000411  17186.767105
         ...
+
+    DataFrame columns:
+        - BondType: Tipo do título público (e.g., 'LTN', 'NTN-B').
+        - ReferenceDate: Data de referência dos dados.
+        - SelicCode: Código do título no SELIC.
+        - IssueBaseDate: Data base ou de emissão do título.
+        - MaturityDate: Data de vencimento do título.
+        - BDToMat: Número de dias úteis entre a data de referência e o vencimento.
+        - Duration: Macaulay Duration do título em anos.
+        - DV01: Variação financeira no preço do título (em BRL) para uma
+            mudança de 1 basis point (0,01%) na taxa de juros.
+        - DV01USD: O mesmo que DV01, mas convertido para USD pela PTAX do dia.
+        - Price: Preço Unitário (PU) do título na data de referência.
+        - BidRate: Taxa de compra em formato decimal (e.g., 0.10 para 10%).
+        - AskRate: Taxa de venda em formato decimal.
+        - IndicativeRate: Taxa indicativa em formato decimal.
+        - DIRate: Taxa DI interpolada para o vencimento do título.
+        - StdDev: Desvio padrão da taxa indicativa.
+        - LowerBoundRateD0: Limite inferior do intervalo indicativo para D+0.
+        - UpperBoundRateD0: Limite superior do intervalo indicativo para D+0.
+        - LowerBoundRateD1: Limite inferior do intervalo indicativo para D+1.
+        - UpperBoundRateD1: Limite superior do intervalo indicativo para D+1.
+        - Criteria: Critério utilizado pela ANBIMA para o cálculo.
+
+    Notes:
+        - Data for the last 5 business days is available on the public ANBIMA
+          website.
+        - Historical data (older than 5 business days) is only available via
+          the RTM network. If you are not connected to RTM, requests for
+          older dates will return an empty DataFrame.
     """
-    df = get_cached_dataset("tpf")
     date = convert_input_dates(date)
-    df = df.query("ReferenceDate == @date").reset_index(drop=True)
 
-    if df.empty:
+    date_log = date.strftime("%d/%m/%Y")
+    today = dt.datetime.now(BZ_TIMEZONE).date()
+    if date.date() > today:
+        logger.info(
+            f"Cannot fetch data for a future date ({date_log}). "
+            "Returning empty DataFrame."
+        )
+        return pd.DataFrame()
+
+    if fetch_from_source:
         # Try to fetch the data from the Anbima website
-        df = fetch_tpf_data(date)
+        df = _fetch_tpf_data(date)
+    else:
+        df = (
+            get_cached_dataset("tpf")
+            .query("ReferenceDate == @date")
+            .reset_index(drop=True)
+        )
 
     if df.empty:
         # If the data is still empty, return an empty DataFrame
         return pd.DataFrame()
 
     if bond_type:
-        df = df.query("BondType == @bond_type").reset_index(drop=True)
+        norm_bond_type = _bond_type_mapping(bond_type)  # noqa
+        df = df.query("BondType == @norm_bond_type").reset_index(drop=True)
 
-    if adj_maturities:
-        df["MaturityDate"] = bday.offset(df["MaturityDate"], 0)
-
-    return (
-        df[["ReferenceDate", "BondType", "MaturityDate", "IndicativeRate", "Price"]]
-        .sort_values(["BondType", "MaturityDate"])
-        .reset_index(drop=True)
-    )
+    return df.sort_values(["BondType", "MaturityDate"]).reset_index(drop=True)
 
 
 def tpf_fixed_rate_maturities(date: DateScalar) -> pd.Series:

pyield-0.37.2/pyield/__about__.py

@@ -1 +0,0 @@
-__version__ = "0.37.2"