PYield 0.32.4__tar.gz → 0.32.6__tar.gz

{pyield-0.32.4 → pyield-0.32.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: PYield
-Version: 0.32.4
+Version: 0.32.6
 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.32.6/pyield/__about__.py

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

{pyield-0.32.4 → pyield-0.32.6}/pyield/b3/futures/__init__.py

@@ -1,4 +1,5 @@
 import datetime as dt
+import logging
 from typing import Literal
 from zoneinfo import ZoneInfo
 
@@ -7,10 +8,12 @@ import pandas as pd
 from pyield import date_converter as dc
 from pyield.b3.futures.historical import fetch_historical_df
 from pyield.b3.futures.intraday import fetch_intraday_df
+from pyield.b3.futures.xml import fetch_xml_report
 from pyield.date_converter import DateScalar
 
 TIMEZONE_BZ = ZoneInfo("America/Sao_Paulo")
 ContractOptions = Literal["DI1", "DDI", "FRC", "DAP", "DOL", "WDO", "IND", "WIN"]
+logger = logging.getLogger(__name__)
 
 
 def futures(
@@ -60,13 +63,25 @@ def futures(
     selected_contract = str(contract_code).upper()
     converted_date = dc.convert_input_dates(date)
 
-    # First, try to fetch historical data for the specified date
+    # First, try to fetch historical data from BMF site
     df = fetch_historical_df(selected_contract, converted_date)
+    if df.empty:
+        # If historical data is not available, try to fetch the full XML report
+        # from the B3 site
+        try:
+            df = fetch_xml_report(converted_date, selected_contract, "PR")
+            logger.info(f"Using B3 XML report data for {selected_contract}")
+        except ValueError as e:
+            logger.error(f"Failed to fetch data for {selected_contract}: {e}")
+            raise
+    else:
+        logger.info(f"Using BMF historical data for {selected_contract}")
 
     bz_today = dt.datetime.now(TIMEZONE_BZ).date()
     # If there is no historical data available, try to fetch intraday data
     if converted_date.date() == bz_today and df.empty:
         df = fetch_intraday_df(selected_contract)
+        logger.info(f"Using B3 intraday data for {selected_contract}")
 
     return df
 

{pyield-0.32.4 → pyield-0.32.6}/pyield/b3/futures/historical.py

@@ -245,7 +245,6 @@ def process_df(
         duration = df["BDaysToExp"] / 252
         modified_duration = duration / (1 + df["SettlementRate"])
         df["DV01"] = 0.0001 * modified_duration * df["SettlementPrice"]
-        df["DV01"] = df["DV01"].astype("Float64")
 
     return df
 

{pyield-0.32.4 → pyield-0.32.6}/pyield/b3/futures/intraday.py

@@ -129,7 +129,6 @@ def _process_df(raw_df: pd.DataFrame) -> pd.DataFrame:
         duration = df["BDaysToExp"] / 252
         modified_duration = duration / (1 + df["LastRate"])
         df["DV01"] = 0.0001 * modified_duration * df["LastPrice"]
-        df["DV01"] = df["DV01"].astype("Float64")
 
     return df
 

{pyield-0.32.4 → pyield-0.32.6}/pyield/b3/futures/xml.py

@@ -1,4 +1,5 @@
 import io
+import logging
 import zipfile
 from pathlib import Path
 from typing import Literal
@@ -10,6 +11,8 @@ from lxml import etree
 from pyield import bday
 from pyield.b3.futures import common
 
+logger = logging.getLogger(__name__)
+
 
 def _get_file_from_path(file_path: Path) -> io.BytesIO:
     # Check if a file path was not provided
@@ -47,9 +50,13 @@ def _get_file_from_url(date: pd.Timestamp, source_type: str) -> io.BytesIO:
     response = requests.get(url, timeout=10)
 
     # File will be considered invalid if it is too small
-    if response.status_code != 200 or len(response.content) < 1024:
+    if response.status_code != 200 or len(response.content) < 1024:  # noqa
         date_str = date.strftime("%Y-%m-%d")
-        raise ValueError(f"There is no data available for {date_str}.")
+        logger.warning(
+            f"File not found or too small ({len(response.content)} bytes) "
+            f"for {source_type} on {date_str}. Returning empty file."
+        )
+        return io.BytesIO()
 
     return io.BytesIO(response.content)
 
@@ -102,7 +109,7 @@ def _extract_data_from_xml(xml_file: io.BytesIO, asset_code: str) -> list[dict]:
             continue
 
         # A future contract ticker must have 6 characters
-        if ticker.text is None or len(ticker.text) != 6:
+        if ticker.text is None or len(ticker.text) != 6:  # noqa
             continue
 
         # Extract the price report element
@@ -246,6 +253,10 @@ def _select_and_reorder_columns(df: pd.DataFrame) -> pd.DataFrame:
 
 
 def process_zip_file(zip_file: io.BytesIO, asset_code: str) -> pd.DataFrame:
+    if zip_file is None or zip_file.getbuffer().nbytes == 0:
+        logger.warning("Empty XML zip file. Returning empty DataFrame.")
+        return pd.DataFrame()
+
     xml_file = _extract_xml_from_zip(zip_file)
 
     di_data = _extract_data_from_xml(xml_file, asset_code)
@@ -258,18 +269,61 @@ def process_zip_file(zip_file: io.BytesIO, asset_code: str) -> pd.DataFrame:
 
     df = _select_and_reorder_columns(df)
 
+    if asset_code == "DI1":
+        duration = df["BDaysToExp"] / 252
+        modified_duration = duration / (1 + df["SettlementRate"])
+        df["DV01"] = 0.0001 * modified_duration * df["SettlementPrice"]
+
     return df
 
 
-def fetch_df(
+def fetch_xml_report(
     date: pd.Timestamp, asset_code: str, source_type: Literal["PR", "SPR"]
 ) -> pd.DataFrame:
+    """Fetches and processes an XML report from B3's website.
+
+    Downloads a zipped XML report for a specific date and asset code
+    from B3's website, extracts the relevant data, and returns it as a
+    Pandas DataFrame.
+
+    Args:
+        date: The date of the report to fetch.
+        asset_code: The asset code to filter the report for (e.g., 'DI1').
+        source_type: The type of report to fetch, either 'PR' (Full Price
+            Report) or 'SPR' (Simplified Price Report).
+
+    Returns:
+        A Pandas DataFrame containing the processed data.
+        For 'DI1' asset codes, an additional 'DV01' column is calculated.
+
+    Raises:
+        ValueError: If the `source_type` is invalid or if no data is
+            available for the given date.
+    """
     zip_file = _get_file_from_url(date, source_type)
     df = process_zip_file(zip_file, asset_code)
+
     return df
 
 
-def read_df(file_path: Path, asset_code: str) -> pd.DataFrame:
+def read_xml_report(file_path: Path, asset_code: str) -> pd.DataFrame:
+    """Reads and processes an XML report from a local file.
+
+    Reads a zipped XML report from the specified file path, extracts the
+    relevant data, and returns it as a Pandas DataFrame.
+
+    Args:
+        file_path: The path to the zipped XML report file.
+        asset_code: The asset code to filter the report for (e.g., 'DI1').
+
+    Returns:
+        A Pandas DataFrame containing the processed data.
+        For 'DI1' asset codes, an additional 'DV01' column is calculated.
+
+    Raises:
+        ValueError: If the provided `file_path` is not a Path object.
+        FileNotFoundError: If no file is found at the specified `file_path`.
+    """
     zip_file = _get_file_from_path(file_path)
     df = process_zip_file(zip_file, asset_code)
     return df

{pyield-0.32.4 → pyield-0.32.6}/pyield/bc/trade.py

@@ -101,4 +101,7 @@ def tpf_trades(target_date: DateScalar) -> pd.DataFrame:
     url = _build_download_url(target_date)
     df = _fetch_data_from_url(url)
     df = df.rename(columns=COLUMN_MAPPING)
+
+    # TradeValue are empty in the original BCB file, so we calculate it
+    df["TradeValue"] = (df["TradeQuantity"] * df["AvgPrice"]).round(2)
     return df

{pyield-0.32.4 → pyield-0.32.6}/pyield/fwd.py

@@ -6,34 +6,43 @@ def forwards(
     rates: pd.Series,
     groupby_dates: pd.Series | None = None,
 ) -> pd.Series:
-    """
+    r"""
     Calcula taxas a termo (forward rates) a partir de taxas zero (spot rates).
 
-    Utiliza a fórmula:
-        f₁→₂ = ((1 + r₂)^(du₂/252) / (1 + r₁)^(du₁/252))^(252/(du₂ - du₁)) - 1
+    A taxa a termo no vértice 'n' é definida como:
+        fwdₙ = fwdₙ₋₁→ₙ (a taxa a termo de n-1 para n)
+
+    A fórmula utilizada é:
+        fwdₙ = ((1 + rₙ)^(duₙ/252) / (1 + rₙ₋₁)^(duₙ₋₁/252))^(252/(duₙ - duₙ₋₁)) - 1
 
     Como du/252 = t (tempo em anos úteis), a fórmula pode ser simplificada para:
-        f₁→₂ = ((1 + r₂)^t₂ / (1 + r₁)^t₁)^(1/(t₂ - t₁)) - 1
+
+        fwdₙ = ((1 + rₙ)^tₙ / (1 + rₙ₋₁)^tₙ₋₁)^(1/(tₙ - tₙ₋₁)) - 1
+
+    Em LaTeX, a fórmula é representada como:
+    $$
+    fwd_{n} = \left( \frac{(1 + r_n)^{t_n}}{(1 + r_{n-1})^{t_{n-1}}} \right)^{\frac{1}{t_n - t_{n-1}}} - 1
+    $$
 
     Onde:
-        - r₁ é a taxa zero para o vértice anterior.
-        - r₂ é a taxa zero para o vértice atual.
-        - t₁ é o prazo em anos para o vértice anterior (calculado como du₁/252).
-        - t₂ é o prazo em anos para o vértice atual (calculado como du₂/252).
+        - rₙ₋₁ é a taxa zero para o vértice anterior.
+        - rₙ é a taxa zero para o vértice atual.
+        - tₙ₋₁ é o prazo em anos para o vértice anterior (calculado como duₙ₋₁/252).
+        - tₙ é o prazo em anos para o vértice atual (calculado como duₙ/252).
         - A constante 252 representa o número de dias úteis no ano.
 
-    A primeira taxa a termo de cada sequência (ou grupo) é definida como a
-    taxa zero desse primeiro vértice (f₁→₂ = r₂), dado que não existe um vértice
-    anterior (r₁) para se calcular a taxa a termo do primeiro ponto.
-
-    A função lida internamente com o alinhamento dos índices das Séries de
-    entrada através de `reset_index`. Os cálculos são realizados após ordenar
-    os dados pelos prazos (`bdays`) dentro de cada grupo definido por
-    `groupby_dates` (ou como um único grupo se `groupby_dates` não for
-    fornecido), garantindo a ordem cronológica correta para a fórmula.
+    A primeira taxa a termo de cada grupo é definida como a
+    taxa zero desse primeiro vértice (fwd₁ = r₁), dado que não existe um vértice
+    anterior a r₁ para se calcular a taxa a termo no primeiro ponto.
 
-    Valores NaN nas taxas ou prazos de entrada resultarão em NaN na saída,
-    exceto para o primeiro ponto de cada grupo, que é tratado separadamente.
+    Valores nulos nas taxas ou prazos de entrada resultarão em valores nulos
+    nas taxas a termo calculadas. A função também lida com agrupamentos
+    opcionais, permitindo calcular taxas a termo para diferentes grupos de
+    datas. O agrupamento é feito com base na coluna `groupby_dates`, que
+    deve ser fornecida como uma série de pandas. Se `groupby_dates` for None,
+    todos os dados serão tratados como um único grupo.
+    A função calcula as taxas a termo para todos os pontos, exceto o primeiro
+    de cada grupo, que é tratado separadamente.
 
     Args:
         bdays (pd.Series): Número de dias úteis para cada taxa zero.
@@ -47,7 +56,7 @@ def forwards(
         pd.Series: Série contendo as taxas a termo calculadas (tipo Float64).
             A primeira taxa de cada grupo corresponde à taxa zero inicial.
 
-    Example:
+    Examples:
         >>> bdays = pd.Series([10, 20, 30])
         >>> rates = pd.Series([0.05, 0.06, 0.07])
         >>> yd.forwards(bdays, rates)
@@ -55,7 +64,7 @@ def forwards(
         1    0.070095
         2    0.090284
         dtype: Float64
-    """
+    """  # noqa: E501
     # Reset Series indexes to avoid misalignment issues during calculations
     bdays = bdays.reset_index(drop=True).astype("Int64")
     rates = rates.reset_index(drop=True).astype("Float64")
@@ -104,7 +113,7 @@ def forward(
     rate1: float,
     rate2: float,
 ) -> float:
-    """
+    r"""
     Calcula a taxa a termo (forward rate) entre dois prazos (dias úteis).
 
     Utiliza a fórmula:
@@ -118,6 +127,7 @@ def forward(
         - A constante 252 representa o número de dias úteis no ano.
 
     Como du/252 = t (tempo em anos úteis), a fórmula pode ser simplificada para:
+
         f₁→₂ = ((1 + r₂)^t₂ / (1 + r₁)^t₁)^(1/(t₂ - t₁)) - 1
 
     Args:
@@ -131,8 +141,8 @@ def forward(
             `float('nan')` se `bday2 <= bday1` ou se qualquer um dos
             argumentos de entrada for NaN.
 
-    Example:
-        >>> # Exemplo correto: bday2 > bday1
+    Examples:
+        >>> # Exemplo válido: bday2 > bday1
         >>> yd.forward(10, 20, 0.05, 0.06)
         0.0700952380952371
         >>> # Exemplo inválido: bday2 <= bday1
@@ -147,7 +157,12 @@ def forward(
     Note:
         É fundamental que `bday2` seja estritamente maior que `bday1` para que
         o cálculo da taxa a termo seja matematicamente válido.
-    """
+
+    A fórmula utilizada é derivada da relação entre taxas zero (spot rates) é:
+    $$
+    f_{1 \rightarrow 2} = \left( \frac{(1 + r_2)^{t_2}}{(1 + r_1)^{t_1}} \right)^{\frac{1}{t_2 - t_1}} - 1
+    $$
+    """  # noqa: E501
     if pd.isna(rate1) or pd.isna(rate2) or pd.isna(bday1) or pd.isna(bday2):
         # If any of the inputs are NaN, return NaN
         return float("nan")

{pyield-0.32.4 → pyield-0.32.6}/pyield/tpf/ntnf.py

@@ -20,7 +20,7 @@ FINAL_PMT = FACE_VALUE + COUPON_PMT
 COUPON_DAY = 1
 COUPON_MONTHS = {1, 7}
 COUPON_PMT = 48.80885
-FINAL_PMT = 1048.80885
+FINAL_PMT = 1048.80885  # 1000 + 48.80885
 
 
 def data(date: DateScalar) -> pd.DataFrame:
@@ -364,8 +364,8 @@ def di_spreads(date: DateScalar) -> pd.DataFrame:
     return df[["MaturityDate", "DISpread"]]
 
 
-# Bisection method to find the root
 def _bisection_method(func, a, b, tol=1e-8, maxiter=100):
+    """Bisection method for root finding."""
     fa, fb = func(a), func(b)
     if fa * fb > 0:
         raise ValueError("Function does not change sign in the interval.")

pyield-0.32.4/pyield/__about__.py

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