PYield 0.7.0__tar.gz → 0.7.2__tar.gz

{pyield-0.7.0 → pyield-0.7.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: PYield
-Version: 0.7.0
+Version: 0.7.2
 Summary: A Python library for analysis of fixed income instruments in Brazil
 Keywords: fixed-income, brazil, finance, analysis, bonds
 Author-Email: Carlos Carvalho <cr.cj@outlook.com>
@@ -48,7 +48,7 @@ Description-Content-Type: text/markdown
 
 ## Introduction
 
-Welcome to PYield, a Python library designed for the analysis of fixed income instruments in Brazil. This library is tailored for financial analysts, researchers, and enthusiasts interested in the Brazilian fixed income market. Leveraging the power of popular Python libraries like Pandas and Requests, PYield simplifies the process of obtaining and processing data from key sources such as ANBIMA and B3.
+Welcome to PYield, a Python library designed for the analysis of fixed income instruments in Brazil. This library is tailored for financial analysts, researchers, and enthusiasts interested in the Brazilian fixed income market. Leveraging the power of popular Python libraries like Pandas and Requests, PYield simplifies the process of obtaining and processing data from key sources such as ANBIMA, BCB, IBGE and B3.
 
 ## Features
 
@@ -101,14 +101,14 @@ dtype: datetime64[ns]
 # Fetch a DataFrame with the DI Futures data from B3
 >>> yd.fetch_asset(asset_code="DI1", reference_date='2024-03-08')
 
-TradeDate  ExpirationCode ExpirationDate BDToExpiration  ... LastRate LastAskRate LastBidRate SettlementRate
-2024-03-08 J24            2024-04-01     15              ... 10.952   10.952      10.956      10.956
-2024-03-08 K24            2024-05-02     37              ... 10.776   10.774      10.780      10.777
-2024-03-08 M24            2024-06-03     58              ... 10.604   10.602      10.604      10.608
-...        ...            ...            ...             ... ...      ...         ...         ...
-2024-03-08 F37            2037-01-02     3213            ... <NA>     <NA>        <NA>        10.859
-2024-03-08 F38            2038-01-04     3462            ... <NA>     <NA>        <NA>        10.859
-2024-03-08 F39            2039-01-03     3713            ... <NA>     <NA>        <NA>        10.85
+TradeDate  ExpirationCode ExpirationDate BDaysToExpiration ... LastRate LastAskRate LastBidRate SettlementRate
+2024-03-08 J24            2024-04-01     15                ... 10.952   10.952      10.956      10.956
+2024-03-08 K24            2024-05-02     37                ... 10.776   10.774      10.780      10.777
+2024-03-08 M24            2024-06-03     58                ... 10.604   10.602      10.604      10.608
+...        ...            ...            ...               ... ...      ...         ...         ...
+2024-03-08 F37            2037-01-02     3213              ... <NA>     <NA>        <NA>        10.859
+2024-03-08 F38            2038-01-04     3462              ... <NA>     <NA>        <NA>        10.859
+2024-03-08 F39            2039-01-03     3713              ... <NA>     <NA>        <NA>        10.85
 ```
 
 ### Treasury Bonds Data

{pyield-0.7.0 → pyield-0.7.2}/README.md

@@ -6,7 +6,7 @@
 
 ## Introduction
 
-Welcome to PYield, a Python library designed for the analysis of fixed income instruments in Brazil. This library is tailored for financial analysts, researchers, and enthusiasts interested in the Brazilian fixed income market. Leveraging the power of popular Python libraries like Pandas and Requests, PYield simplifies the process of obtaining and processing data from key sources such as ANBIMA and B3.
+Welcome to PYield, a Python library designed for the analysis of fixed income instruments in Brazil. This library is tailored for financial analysts, researchers, and enthusiasts interested in the Brazilian fixed income market. Leveraging the power of popular Python libraries like Pandas and Requests, PYield simplifies the process of obtaining and processing data from key sources such as ANBIMA, BCB, IBGE and B3.
 
 ## Features
 
@@ -59,14 +59,14 @@ dtype: datetime64[ns]
 # Fetch a DataFrame with the DI Futures data from B3
 >>> yd.fetch_asset(asset_code="DI1", reference_date='2024-03-08')
 
-TradeDate  ExpirationCode ExpirationDate BDToExpiration  ... LastRate LastAskRate LastBidRate SettlementRate
-2024-03-08 J24            2024-04-01     15              ... 10.952   10.952      10.956      10.956
-2024-03-08 K24            2024-05-02     37              ... 10.776   10.774      10.780      10.777
-2024-03-08 M24            2024-06-03     58              ... 10.604   10.602      10.604      10.608
-...        ...            ...            ...             ... ...      ...         ...         ...
-2024-03-08 F37            2037-01-02     3213            ... <NA>     <NA>        <NA>        10.859
-2024-03-08 F38            2038-01-04     3462            ... <NA>     <NA>        <NA>        10.859
-2024-03-08 F39            2039-01-03     3713            ... <NA>     <NA>        <NA>        10.85
+TradeDate  ExpirationCode ExpirationDate BDaysToExpiration ... LastRate LastAskRate LastBidRate SettlementRate
+2024-03-08 J24            2024-04-01     15                ... 10.952   10.952      10.956      10.956
+2024-03-08 K24            2024-05-02     37                ... 10.776   10.774      10.780      10.777
+2024-03-08 M24            2024-06-03     58                ... 10.604   10.602      10.604      10.608
+...        ...            ...            ...               ... ...      ...         ...         ...
+2024-03-08 F37            2037-01-02     3213              ... <NA>     <NA>        <NA>        10.859
+2024-03-08 F38            2038-01-04     3462              ... <NA>     <NA>        <NA>        10.859
+2024-03-08 F39            2039-01-03     3713              ... <NA>     <NA>        <NA>        10.85
 ```
 
 ### Treasury Bonds Data

pyield-0.7.2/pyield/__about__.py

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

{pyield-0.7.0 → pyield-0.7.2}/pyield/data_access.py

@@ -1,7 +1,7 @@
 import pandas as pd
 
-from . import di
-from . import indicators as ir
+from . import futures as ft
+from . import indicators as it
 from . import treasuries as tr
 from .utils import _normalize_date
 
@@ -20,7 +20,8 @@ def fetch_asset(
             - "TRB": Treasury bonds (indicative rates from ANBIMA).
             - "LTN", "LFT", "NTN-F", "NTN-B": Specific types of Brazilian treasury bonds
                   (indicative rates from ANBIMA).
-            - "DI1": DI Futures rates from B3.
+            - "DI1": One-day Interbank Deposit Futures (Futuro de DI) from B3.
+            - "DDI": DI x U.S. Dollar Spread Futures (Futuro de Cupom Cambial) from B3.
         reference_date (str | pd.Timestamp | None): The reference date for which data is
             fetched. Defaults to the previous business day if None.
         **kwargs: Additional keyword arguments, specifically:
@@ -41,15 +42,15 @@ def fetch_asset(
     normalized_date = _normalize_date(reference_date)
 
     if asset_code.lower() == "trb":
-        return tr.fetch_data(reference_date=normalized_date, return_raw=return_raw)
+        return tr.fetch_bonds(reference_date=normalized_date, return_raw=return_raw)
     elif asset_code.lower() in ["ltn", "lft", "ntn-f", "ntn-b"]:
-        df = tr.fetch_data(reference_date=normalized_date)
+        df = tr.fetch_bonds(reference_date=normalized_date)
         return df.query(f"BondType == '{asset_code.upper()}'")
 
     elif asset_code.lower() == "di1":
-        return di.fetch_data(
-            trade_date=normalized_date, source_type="bmf", return_raw=return_raw
-        )
+        return ft.fetch_di(trade_date=normalized_date, return_raw=return_raw)
+    elif asset_code.lower() == "ddi":
+        return ft.fetch_ddi(trade_date=normalized_date, return_raw=return_raw)
     else:
         raise ValueError("Asset type not supported.")
 
@@ -81,8 +82,8 @@ def fetch_indicator(
     normalized_date = _normalize_date(reference_date)
 
     if indicator_code.lower() == "selic":
-        return ir.fetch_selic_target(reference_date=normalized_date)
+        return it.fetch_selic_target(reference_date=normalized_date)
     elif indicator_code.lower() == "ipca":
-        return ir.fetch_ipca_mr(reference_date=normalized_date)
+        return it.fetch_ipca_mr(reference_date=normalized_date)
     else:
         raise ValueError("Indicator type not supported.")

{pyield-0.7.0 → pyield-0.7.2}/pyield/data_analysis.py

@@ -4,7 +4,9 @@ from . import treasuries as tr
 from .utils import _normalize_date
 
 
-def calculate_spreads(spread_type: str, reference_date: pd.Timestamp) -> pd.DataFrame:
+def calculate_spreads(
+    spread_type: str, reference_date: str | pd.Timestamp | None = None
+) -> pd.DataFrame:
     """
     Calculates spreads between assets based on the specified spread type.
     If no reference date is provided, the function uses the previous business day.

pyield-0.7.2/pyield/futures/__init__.py

@@ -0,0 +1,10 @@
+from .common import get_expiration_date, get_old_expiration_date
+from .ddi import fetch_ddi
+from .di import fetch_di
+
+__all__ = [
+    "fetch_di",
+    "fetch_ddi",
+    "get_expiration_date",
+    "get_old_expiration_date",
+]

pyield-0.7.2/pyield/futures/common.py

@@ -0,0 +1,175 @@
+import io
+
+import pandas as pd
+import requests
+
+from .. import bday
+
+
+def get_expiration_date(expiration_code: str) -> pd.Timestamp:
+    """
+    Converts an expiration code into its corresponding expiration date.
+
+    This function translates an expiration code into a specific expiration date based on
+    a given mapping. The expiration code consists of a letter representing the month and
+    two digits for the year. The function ensures the date returned is a valid business
+    day by adjusting weekends and holidays as necessary.
+
+    Args:
+        expiration_code (str): The expiration code to be converted, where the first
+            letter represents the month and the last two digits represent the year
+            (e.g., "F23" for January 2023).
+
+    Returns:
+        pd.Timestamp: The expiration date corresponding to the code, adjusted to a valid
+            business day. Returns pd.NaT if the code is invalid.
+
+    Examples:
+        >>> get_expiration_date("F23")
+        pd.Timestamp('2023-01-01')
+
+        >>> get_expiration_date("Z33")
+        pd.Timestamp('2033-12-01')
+
+        >>> get_expiration_date("A99")
+        pd.NaT
+
+    Notes:
+        The expiration date is calculated based on the format change introduced by B3 on
+        22-05-2006, where the first letter represents the month and the last two digits
+        represent the year.
+    """
+    month_codes = {
+        "F": 1,
+        "G": 2,
+        "H": 3,
+        "J": 4,
+        "K": 5,
+        "M": 6,
+        "N": 7,
+        "Q": 8,
+        "U": 9,
+        "V": 10,
+        "X": 11,
+        "Z": 12,
+    }
+
+    try:
+        month_code = expiration_code[0]
+        month = month_codes[month_code]
+        year = int("20" + expiration_code[-2:])
+        # The expiration date is always the first business day of the month
+        expiration = pd.Timestamp(year, month, 1)
+
+        # Adjust to the next business day when expiration date is a weekend or a holiday
+        adj_expiration = bday.offset_bdays(expiration, offset=0)
+
+        return adj_expiration
+
+    except (KeyError, ValueError):
+        return pd.NaT  # type: ignore
+
+
+def get_old_expiration_date(
+    expiration_code: str, trade_date: pd.Timestamp
+) -> pd.Timestamp:
+    """
+    Internal function to convert an old DI contract code into its ExpirationDate date.
+    Valid for contract codes up to 21-05-2006.
+
+    Args:
+        expiration_code (str): An old DI Expiration Code from B3, where the first three
+            letters represent the month and the last digit represents the year.
+            Example: "JAN3".
+        trade_date (pd.Timestamp): The trade date for which the contract code is valid.
+
+    Returns:
+        pd.Timestamp
+            The contract's ExpirationDate date. Returns pd.NaT if the input is invalid.
+
+    Examples:
+        >>> get_old_expiration_date("JAN3", pd.Timestamp("2001-05-21"))
+        pd.Timestamp('2003-01-01')
+
+    Notes:
+        - In 22-05-2006, B3 changed the format of the DI contract codes. Before that
+        date, the first three letters represented the month and the last digit
+        represented the year.
+    """
+
+    month_codes = {
+        "JAN": 1,
+        "FEV": 2,
+        "MAR": 3,
+        "ABR": 4,
+        "MAI": 5,
+        "JUN": 6,
+        "JUL": 7,
+        "AGO": 8,
+        "SET": 9,
+        "OUT": 10,
+        "NOV": 11,
+        "DEZ": 12,
+    }
+    try:
+        month_code = expiration_code[:3]
+        month = month_codes[month_code]
+
+        # Year codes must generated dynamically, since it depends on the trade date.
+        reference_year = trade_date.year
+        year_codes = {}
+        for year in range(reference_year, reference_year + 10):
+            year_codes[str(year)[-1:]] = year
+        year = year_codes[expiration_code[-1:]]
+
+        expiration_date = pd.Timestamp(year, month, 1)
+        # Adjust to the next business day when the date is a weekend or a holiday.
+        # Must use old holiday list, since this contract code was used until 2006.
+        return bday.offset_bdays(expiration_date, offset=0, holiday_list="old")
+
+    except (KeyError, ValueError):
+        return pd.NaT  # type: ignore
+
+
+def _fetch_raw_df(asset_code: str, trade_date: pd.Timestamp) -> pd.DataFrame:
+    """
+    Internal function to fetch raw DI futures data from B3 for a specific trade date.
+
+    Args:
+        trade_date: a datetime-like object representing the trade date.
+
+    Returns:
+        pd.DataFrame: Raw DI data as a Pandas pd.DataFrame.
+    """
+    url_date = trade_date.strftime("%d/%m/%Y")
+    # url example: https://www2.bmf.com.br/pages/portal/bmfbovespa/boletim1/SistemaPregao_excel1.asp?Data=05/10/2023&Mercadoria=DI1
+    url = f"https://www2.bmf.com.br/pages/portal/bmfbovespa/boletim1/SistemaPregao_excel1.asp?Data={url_date}&Mercadoria={asset_code}&XLS=false"
+    r = requests.get(url)
+
+    text = r.text
+    if "AJUSTE" not in text:
+        raise ValueError(f"Could not fetch data for {url_date}.")
+
+    df = pd.read_html(
+        io.StringIO(text),
+        match="AJUSTE",
+        header=1,
+        thousands=".",
+        decimal=",",
+        na_values=["-"],
+        dtype_backend="numpy_nullable",
+    )[0]
+
+    # Remove rows with all NaN values
+    df = df.dropna(how="all")
+
+    # Remove columns with all NaN values
+    df = df.dropna(axis=1, how="all")
+
+    # Force "VAR. PTOS." to be string, since it can also be read as float
+    df["VAR. PTOS."] = df["VAR. PTOS."].astype(pd.StringDtype())
+
+    # Force "AJUSTE CORRIG. (4)" to be float, since it can be also read as int
+    df["AJUSTE CORRIG. (4)"] = df["AJUSTE CORRIG. (4)"].astype(pd.Float64Dtype())
+
+    return df

pyield-0.7.2/pyield/futures/ddi.py

@@ -0,0 +1,178 @@
+import pandas as pd
+
+from . import common
+
+
+def _convert_prices_to_rates(prices: pd.Series, n_days: pd.Series) -> pd.Series:
+    """
+    Internal function to convert DDI futures prices to rates.
+
+    Args:
+        prices (pd.Series): A pd.Series containing DDI futures prices.
+        bd (pd.Series): A serie containing the number of days to expiration.
+
+    Returns:
+        pd.Series: A pd.Series containing DDI futures rates.
+    """
+    rates = (100_000 / prices - 1) * (360 / n_days)
+
+    # Return rates as percentage
+    return 100 * rates
+
+
+def _convert_prices_in_older_contracts(df: pd.DataFrame) -> pd.DataFrame:
+    # Prior to 01/01/2002, prices were not converted to rates
+    convert_cols = [
+        "FirstRate",
+        "MinRate",
+        "MaxRate",
+        "AvgRate",
+        "LastRate",
+        "LastBidRate",
+        "LastAskRate",
+    ]
+    for col in convert_cols:
+        df[col] = _convert_prices_to_rates(df[col], df["DaysToExpiration"])
+
+    # Invert low and high prices
+    df["MinRate"], df["MaxRate"] = df["MaxRate"], df["MinRate"]
+
+    return df
+
+
+def _process_raw_df(df: pd.DataFrame, trade_date: pd.Timestamp) -> pd.DataFrame:
+    """
+    Internal function to process and transform raw DI futures data.
+
+    Args:
+        df (pd.DataFrame): the raw DI DataFrame.
+        trade_date: a datetime-like object representing the trade date.
+
+    Returns:
+        pd.DataFrame: Processed and transformed data as a Pandas pd.DataFrame.
+    """
+    # Check if the pd.DataFrame is empty
+    if df.empty:
+        return df
+
+    rename_dict = {
+        "VENCTO": "ExpirationCode",
+        "CONTR. ABERT.(1)": "OpenContracts",  # At the start of the day
+        "CONTR. FECH.(2)": "OpenContractsEndSession",  # At the end of the day
+        "NÚM. NEGOC.": "NumOfTrades",
+        "CONTR. NEGOC.": "TradedQuantity",
+        "VOL.": "FinancialVolume",
+        "AJUSTE": "SettlementPrice",
+        "AJUSTE ANTER. (3)": "PrevSettlementRate",
+        "AJUSTE CORRIG. (4)": "AdjSettlementRate",
+        "PREÇO MÍN.": "MinRate",
+        "PREÇO MÉD.": "AvgRate",
+        "PREÇO MÁX.": "MaxRate",
+        "PREÇO ABERTU.": "FirstRate",
+        "ÚLT. PREÇO": "LastRate",
+        "VAR. PTOS.": "PointsVariation",
+        # Attention: bid/ask rates are inverted
+        "ÚLT.OF. COMPRA": "LastAskRate",
+        "ÚLT.OF. VENDA": "LastBidRate",
+    }
+
+    df = df.rename(columns=rename_dict)
+
+    df["TradeDate"] = trade_date
+    # Convert to datetime64[ns] since it is pandas default type for timestamps
+    df["TradeDate"] = df["TradeDate"].astype("datetime64[ns]")
+
+    # Contract code format was changed in 22/05/2006
+    if trade_date < pd.Timestamp("2006-05-22"):
+        df["ExpirationDate"] = df["ExpirationCode"].apply(
+            common.get_old_expiration_date, args=(trade_date,)
+        )
+    else:
+        df["ExpirationDate"] = df["ExpirationCode"].apply(common.get_expiration_date)
+
+    df["DaysToExpiration"] = (df["ExpirationDate"] - trade_date).dt.days
+    # Convert to nullable integer, since other columns use this data type
+    df["DaysToExpiration"] = df["DaysToExpiration"].astype(pd.Int64Dtype())
+    # Remove expired contracts
+    df.query("DaysToExpiration > 0", inplace=True)
+
+    # Columns where 0 means NaN
+    cols_with_nan = [
+        "SettlementPrice",
+        "FirstRate",
+        "MinRate",
+        "MaxRate",
+        "AvgRate",
+        "LastRate",
+        "LastBidRate",
+        "LastAskRate",
+    ]
+    for col in cols_with_nan:
+        df[col] = df[col].replace(0, pd.NA)
+
+    # Prior to 17/01/2002 (incluive), prices were not converted to rates
+    if trade_date <= pd.Timestamp("2002-01-17"):
+        df = _convert_prices_in_older_contracts(df)
+
+    df["SettlementRate"] = _convert_prices_to_rates(
+        df["SettlementPrice"], df["DaysToExpiration"]
+    )
+
+    # Remove percentage in all rate columns and round to 5 decimal places since it's the
+    # precision used by B3. Obs: 5 decimal places = 3 decimal places in percentage
+    rate_cols = [col for col in df.columns if "Rate" in col]
+    for col in rate_cols:
+        df[col] = (df[col] / 100).round(5)
+
+    # Filter and order columns
+    ordered_cols = [
+        "TradeDate",
+        "ExpirationCode",
+        "ExpirationDate",
+        "DaysToExpiration",
+        "OpenContracts",
+        # "OpenContractsEndSession" since there is no OpenContracts at the end of the
+        # day in XML data, it will be removed to avoid confusion with XML data
+        "NumOfTrades",
+        "TradedQuantity",
+        "FinancialVolume",
+        "SettlementPrice",
+        "MinRate",
+        "AvgRate",
+        "MaxRate",
+        "FirstRate",
+        "LastRate",
+        "LastAskRate",
+        "LastBidRate",
+        "SettlementRate",
+    ]
+    return df[ordered_cols]
+
+
+def fetch_ddi(trade_date: pd.Timestamp, return_raw: bool = False) -> pd.DataFrame:
+    """
+    Fetchs the DDI futures data for a given date from B3.
+
+    This function fetches and processes the DI futures data from B3 for a specific
+    trade date. It's the primary external interface for accessing DI data.
+
+    Args:
+        trade_date (pd.Timestamp): The trade date to fetch the DI futures data.
+        raw (bool): If True, returns the raw data as a Pandas pd.DataFrame.
+            Defaults to False.
+
+    Returns:
+        pd.DataFrame: A Pandas pd.DataFrame containing processed DI futures data.
+
+    Examples:
+        >>> from pyield.futures import di
+        >>> di.fetch_ddi(pd.Timestamp("2021-01-04"))
+
+    Notes:
+        - DaysToExpiration: number of business days to ExpirationDate.
+        - OpenContracts: number of open contracts at the start of the trading day.
+    """
+    df_raw = common._fetch_raw_df(asset_code="DDI", trade_date=trade_date)
+    if return_raw:
+        return df_raw
+    return _process_raw_df(df_raw, trade_date)

pyield-0.7.0/pyield/di/web.py → pyield-0.7.2/pyield/futures/di.py

@@ -1,121 +1,7 @@
-import io
-import warnings
-
 import pandas as pd
-import requests
 
 from .. import bday
-from . import core as cr
-
-
-def get_old_expiration_date(
-    expiration_code: str, trade_date: pd.Timestamp
-) -> pd.Timestamp:
-    """
-    Internal function to convert an old DI contract code into its ExpirationDate date.
-    Valid for contract codes up to 21-05-2006.
-
-    Args:
-        expiration_code (str): An old DI Expiration Code from B3, where the first three
-            letters represent the month and the last digit represents the year.
-            Example: "JAN3".
-        trade_date (pd.Timestamp): The trade date for which the contract code is valid.
-
-    Returns:
-        pd.Timestamp
-            The contract's ExpirationDate date. Returns pd.NaT if the input is invalid.
-
-    Examples:
-        >>> get_old_expiration_date("JAN3", pd.Timestamp("2001-05-21"))
-        pd.Timestamp('2003-01-01')
-
-    Notes:
-        - In 22-05-2006, B3 changed the format of the DI contract codes. Before that
-        date, the first three letters represented the month and the last digit
-        represented the year.
-    """
-
-    month_codes = {
-        "JAN": 1,
-        "FEV": 2,
-        "MAR": 3,
-        "ABR": 4,
-        "MAI": 5,
-        "JUN": 6,
-        "JUL": 7,
-        "AGO": 8,
-        "SET": 9,
-        "OUT": 10,
-        "NOV": 11,
-        "DEZ": 12,
-    }
-    try:
-        month_code = expiration_code[:3]
-        month = month_codes[month_code]
-
-        # Year codes must generated dynamically, since it depends on the trade date.
-        reference_year = trade_date.year
-        year_codes = {}
-        for year in range(reference_year, reference_year + 10):
-            year_codes[str(year)[-1:]] = year
-        year = year_codes[expiration_code[-1:]]
-
-        expiration_date = pd.Timestamp(year, month, 1)
-        # Adjust to the next business day when the date is a weekend or a holiday.
-        # Must use old holiday list, since this contract code was used until 2006.
-        return bday.offset_bdays(expiration_date, offset=0, holiday_list="old")
-
-    except (KeyError, ValueError):
-        return pd.NaT  # type: ignore
-
-
-def _get_raw_df(trade_date: pd.Timestamp) -> pd.DataFrame:
-    """
-    Internal function to fetch raw DI futures data from B3 for a specific trade date.
-
-    Args:
-        trade_date: a datetime-like object representing the trade date.
-
-    Returns:
-        pd.DataFrame: Raw DI data as a Pandas pd.DataFrame.
-    """
-    # url example: https://www2.bmf.com.br/pages/portal/bmfbovespa/boletim1/SistemaPregao_excel1.asp?Data=05/10/2023&Mercadoria=DI1
-    url = f"https://www2.bmf.com.br/pages/portal/bmfbovespa/boletim1/SistemaPregao_excel1.asp?Data={trade_date.strftime('%d/%m/%Y')}&Mercadoria=DI1&XLS=false"
-    r = requests.get(url)
-    f = io.StringIO(r.text)
-
-    try:
-        # Attempt to get the first table with the header "AJUSTE"
-        df = pd.read_html(
-            f,
-            match="AJUSTE",
-            header=1,
-            thousands=".",
-            decimal=",",
-            na_values=["-"],
-            dtype_backend="numpy_nullable",
-        )[0]
-
-        # Remove rows with all NaN values
-        df = df.dropna(how="all")
-
-        # Remove columns with all NaN values
-        df = df.dropna(axis=1, how="all")
-
-        # Force "VAR. PTOS." to be string, since it can also be read as float
-        df["VAR. PTOS."] = df["VAR. PTOS."].astype(pd.StringDtype())
-
-        # Force "AJUSTE CORRIG. (4)" to be float, since it can be also read as int
-        df["AJUSTE CORRIG. (4)"] = df["AJUSTE CORRIG. (4)"].astype(pd.Float64Dtype())
-
-        return df
-
-    except Exception as e:
-        trade_date_str = trade_date.strftime("%d/%m/%Y")
-        message = f"""A {type(e).__name__} occurred while reading the DI futures data
-        for {trade_date_str}. Returning an empty pd.DataFrame."""
-        warnings.warn(message, stacklevel=2)
-        return pd.DataFrame()
+from . import common
 
 
 def _convert_prices_to_rates(prices: pd.Series, bd: pd.Series) -> pd.Series:
@@ -147,7 +33,7 @@ def _convert_prices_in_older_contracts(df: pd.DataFrame) -> pd.DataFrame:
         "LastAskRate",
     ]
     for col in convert_cols:
-        df[col] = _convert_prices_to_rates(df[col], df["BDToExpiration"])
+        df[col] = _convert_prices_to_rates(df[col], df["BDaysToExpiration"])
 
     # Invert low and high prices
     df["MinRate"], df["MaxRate"] = df["MaxRate"], df["MinRate"]
@@ -200,16 +86,16 @@ def _process_raw_df(df: pd.DataFrame, trade_date: pd.Timestamp) -> pd.DataFrame:
     # Contract code format was changed in 22/05/2006
     if trade_date < pd.Timestamp("2006-05-22"):
         df["ExpirationDate"] = df["ExpirationCode"].apply(
-            get_old_expiration_date, args=(trade_date,)
+            common.get_old_expiration_date, args=(trade_date,)
         )
     else:
-        df["ExpirationDate"] = df["ExpirationCode"].apply(cr.get_expiration_date)
+        df["ExpirationDate"] = df["ExpirationCode"].apply(common.get_expiration_date)
 
-    df["BDToExpiration"] = bday.count_bdays(trade_date, df["ExpirationDate"])
+    df["BDaysToExpiration"] = bday.count_bdays(trade_date, df["ExpirationDate"])
     # Convert to nullable integer, since other columns use this data type
-    df["BDToExpiration"] = df["BDToExpiration"].astype(pd.Int64Dtype())
+    df["BDaysToExpiration"] = df["BDaysToExpiration"].astype(pd.Int64Dtype())
     # Remove expired contracts
-    df.query("BDToExpiration > 0", inplace=True)
+    df.query("BDaysToExpiration > 0", inplace=True)
 
     # Columns where 0 means NaN
     cols_with_nan = [
@@ -230,7 +116,7 @@ def _process_raw_df(df: pd.DataFrame, trade_date: pd.Timestamp) -> pd.DataFrame:
         df = _convert_prices_in_older_contracts(df)
 
     df["SettlementRate"] = _convert_prices_to_rates(
-        df["SettlementPrice"], df["BDToExpiration"]
+        df["SettlementPrice"], df["BDaysToExpiration"]
     )
 
     # Remove percentage in all rate columns and round to 5 decimal places since it's the
@@ -244,7 +130,7 @@ def _process_raw_df(df: pd.DataFrame, trade_date: pd.Timestamp) -> pd.DataFrame:
         "TradeDate",
         "ExpirationCode",
         "ExpirationDate",
-        "BDToExpiration",
+        "BDaysToExpiration",
         "OpenContracts",
         # "OpenContractsEndSession" since there is no OpenContracts at the end of the
         # day in XML data, it will be removed to avoid confusion with XML data
@@ -264,15 +150,15 @@ def _process_raw_df(df: pd.DataFrame, trade_date: pd.Timestamp) -> pd.DataFrame:
     return df[ordered_cols]
 
 
-def get_di(trade_date: pd.Timestamp, return_raw: bool = False) -> pd.DataFrame:
+def fetch_di(trade_date: pd.Timestamp, return_raw: bool = False) -> pd.DataFrame:
     """
-    Gets the DI futures data for a given date from B3.
+    Fetchs the DI futures data for a given date from B3.
 
     This function fetches and processes the DI futures data from B3 for a specific
     trade date. It's the primary external interface for accessing DI data.
 
     Args:
-        trade_date: a datetime-like object representing the trade date.
+        trade_date (pd.Timestamp): The trade date to fetch the DI futures data.
         raw (bool): If True, returns the raw data as a Pandas pd.DataFrame.
             Defaults to False.
 
@@ -280,14 +166,14 @@ def get_di(trade_date: pd.Timestamp, return_raw: bool = False) -> pd.DataFrame:
         pd.DataFrame: A Pandas pd.DataFrame containing processed DI futures data.
 
     Examples:
-        >>> get_di("2023-12-28")
+        >>> from pyield.futures import di
+        >>> di.fetch_di(pd.Timestamp("2021-01-04"))
 
     Notes:
-        - BDToExpiration: number of business days to ExpirationDate.
+        - BDaysToExpiration: number of business days to ExpirationDate.
         - OpenContracts: number of open contracts at the start of the trading day.
-        - closed_contracts: number of closed contracts at the end of the trading day.
     """
-    df_raw = _get_raw_df(trade_date)
+    df_raw = common._fetch_raw_df(asset_code="DI1", trade_date=trade_date)
     if return_raw:
         return df_raw
     return _process_raw_df(df_raw, trade_date)

pyield-0.7.0/pyield/di/xml.py → pyield-0.7.2/pyield/futures/di_xml.py

@@ -8,7 +8,7 @@ from lxml import etree
 from pandas import DataFrame, Timestamp
 
 from .. import bday
-from . import core as cr
+from . import common as cm
 
 
 def _get_file_from_url(trade_date: Timestamp, source_type: str) -> io.BytesIO:
@@ -97,12 +97,12 @@ def _extract_di_data_from_xml(xml_file: io.BytesIO) -> list[dict]:
         # Extrair a data de negociação
         if price_report is None:
             continue
-        trade_date = price_report.find(".//ns:TradDt/ns:Dt", namespaces)
+        trade_date = price_report.find(".//ns:TradeDate/ns:Dt", namespaces)
 
         # Preparar o dicionário de dados do ticker com a data de negociação
         if trade_date is None:
             continue
-        ticker_data = {"TradDt": trade_date.text, "TckrSymb": tckr_symb.text}
+        ticker_data = {"TradeDate": trade_date.text, "TckrSymb": tckr_symb.text}
 
         # Acessar o elemento FinInstrmAttrbts que contém o TckrSymb
         fin_instrm_attrbts = price_report.find(".//ns:FinInstrmAttrbts", namespaces)
@@ -229,17 +229,17 @@ def _process_di_df(df_raw: DataFrame) -> DataFrame:
     # Convert to datetime64[ns] since it is pandas default type for timestamps
     df["TradDt"] = df["TradDt"].astype("datetime64[ns]")
 
-    expiration = df["TckrSymb"].str[3:].apply(cr.get_expiration_date)
+    expiration = df["TckrSymb"].str[3:].apply(cm.get_expiration_date)
     df.insert(2, "ExpirationDate", expiration)
 
     business_days = bday.count_bdays(df["TradDt"], df["ExpirationDate"])
-    df.insert(3, "BDToExpiration", business_days)
+    df.insert(3, "BDaysToExpiration", business_days)
 
     # Convert to nullable integer, since other columns use this data type
-    df["BDToExpiration"] = df["BDToExpiration"].astype(pd.Int64Dtype())
+    df["BDaysToExpiration"] = df["BDaysToExpiration"].astype(pd.Int64Dtype())
 
     # Remove expired contracts
-    df.query("BDToExpiration > 0", inplace=True)
+    df.query("BDaysToExpiration > 0", inplace=True)
 
     return df.sort_values(by=["ExpirationDate"], ignore_index=True)
 
@@ -307,3 +307,43 @@ def read_di(file_path: Path, return_raw: bool = False) -> DataFrame:
 
     else:
         raise ValueError("A file path must be provided.")
+
+
+def read_file(file_path: Path, return_raw: bool = False) -> pd.DataFrame:
+    """
+    Reads DI futures data from a file and returns it as a pandas DataFrame.
+
+    This function opens and reads a DI futures data file, returning the contents as a
+    pandas DataFrame. It supports reading from both XML files provided by B3, wich
+    are the simplified and complete Price Reports.
+
+    Args:
+        file_path (Path): The file path to the DI data file. This should be a valid
+            Path object pointing to the location of the file.
+        return_raw (bool, optional): If set to True, the function returns the raw data
+            without applying any transformation or processing. Useful for cases where
+            raw data inspection or custom processing is needed. Defaults to False.
+        source_type (Literal["bmf", "b3", "b3s"], optional): Indicates the source of
+            the data. Defaults to "bmf". Options include:
+                - "bmf": Fetches data from the old BM&FBOVESPA website. Fastest option.
+                - "b3": Fetches data from the complete Price Report (XML file) provided
+                    by B3.
+                - "b3s": Fetches data from the simplified Price Report (XML file)
+                    provided by B3. Faster than "b3" but less detailed.
+
+    Returns:
+        pd.DataFrame: A DataFrame containing the processed or raw DI futures data,
+            depending on the `return_raw` flag.
+
+    Examples:
+        >>> read_di(Path("path/to/di_data_file.xml"))
+        # returns a DataFrame with the DI futures data
+
+        >>> read_di(Path("path/to/di_data_file.xml"), return_raw=True)
+        # returns a DataFrame with the raw DI futures data, without processing
+
+    Note:
+        The ability to process and return raw data is primarily intended for advanced
+        users who require access to the data in its original form for custom analyses.
+    """
+    return read_di(file_path, return_raw=return_raw)

{pyield-0.7.0 → pyield-0.7.2}/pyield/treasuries.py

@@ -3,7 +3,7 @@ import io
 import pandas as pd
 import requests
 
-from . import di
+from . import futures as ft
 
 # URL Constants
 ANBIMA_NON_MEMBER_URL = "https://www.anbima.com.br/informacoes/merc-sec/arqs/"
@@ -100,7 +100,7 @@ def _process_raw_df(df_raw: pd.DataFrame) -> pd.DataFrame:
     return df.sort_values(["BondType", "MaturityDate"], ignore_index=True)
 
 
-def fetch_data(reference_date: pd.Timestamp, return_raw=False) -> pd.DataFrame:
+def fetch_bonds(reference_date: pd.Timestamp, return_raw=False) -> pd.DataFrame:
     """
     Fetches indicative treasury rates from ANBIMA for a specified reference date.
 
@@ -150,7 +150,7 @@ def calculate_di_spreads(reference_date: pd.Timestamp) -> pd.DataFrame:
             bond type and maturity date.
     """
     # Fetch DI rates and adjust the maturity date format for compatibility
-    df_di = di.fetch_data(reference_date)[["ExpirationDate", "SettlementRate"]]
+    df_di = ft.fetch_di(reference_date)[["ExpirationDate", "SettlementRate"]]
 
     # Renaming the columns to match the ANBIMA structure
     df_di.rename(columns={"ExpirationDate": "MaturityDate"}, inplace=True)
@@ -159,7 +159,7 @@ def calculate_di_spreads(reference_date: pd.Timestamp) -> pd.DataFrame:
     df_di["MaturityDate"] = df_di["MaturityDate"].dt.to_period("M").dt.to_timestamp()
 
     # Fetch bond rates, filtering for LTN and NTN-F types
-    df_anbima = fetch_data(reference_date, False)
+    df_anbima = fetch_bonds(reference_date, False)
     df_anbima.query("BondType in ['LTN', 'NTN-F']", inplace=True)
 
     # Merge bond and DI rates by maturity date to calculate spreads

{pyield-0.7.0 → pyield-0.7.2}/pyproject.toml

@@ -31,7 +31,7 @@ dependencies = [
     "lxml",
 ]
 dynamic = []
-version = "0.7.0"
+version = "0.7.2"
 
 [project.license]
 file = "LICENSE"

pyield-0.7.0/tests/test_di.py → pyield-0.7.2/tests/test_futures.py

@@ -1,14 +1,13 @@
 import pandas as pd
 import pytest
 
-from pyield.di import core as cr
-from pyield.di import web as web
+from pyield import futures as ft
 
 
 def test_valid_old_contract_code1():
     expiration_code = "JAN3"  # Valid contract code
     trade_date = pd.Timestamp("2001-05-21")
-    result = web.get_old_expiration_date(expiration_code, trade_date)
+    result = ft.get_old_expiration_date(expiration_code, trade_date)
     contract_expiration = pd.Timestamp("2003-01-02")
     assert result == contract_expiration
 
@@ -16,7 +15,7 @@ def test_valid_old_contract_code1():
 def test_valid_old_contract_code2():
     expiration_code = "JAN3"  # Valid contract code
     trade_date = pd.Timestamp("1990-01-01")
-    result = web.get_old_expiration_date(expiration_code, trade_date)
+    result = ft.get_old_expiration_date(expiration_code, trade_date)
     contract_expiration = pd.Timestamp("1993-01-04")
     assert result == contract_expiration
 
@@ -25,13 +24,13 @@ def test_invalid_old_contract_code():
     expiration_code = "J3"  # Invalid contract code
     trade_date = pd.Timestamp("2001-01-02")
     # Must return NaT
-    result = web.get_old_expiration_date(expiration_code, trade_date)
+    result = ft.get_old_expiration_date(expiration_code, trade_date)
     assert pd.isnull(result)
 
 
 def test_new_contract_code():
     expiration_code = "F23"  # Valid contract code
-    result = cr.get_expiration_date(expiration_code)
+    result = ft.get_expiration_date(expiration_code)
     contract_expiration = pd.Timestamp("2023-01-02")
     assert result == contract_expiration
 
@@ -43,7 +42,8 @@ def test_settlement_rate_with_old_holiday_list():
     }
 
     # 22-12-2023 is before the new holiday calendar
-    df = cr.fetch_data(trade_date="2023-12-22")
+    test_date = pd.Timestamp("2023-12-22")
+    df = ft.fetch_di(trade_date=test_date)
     expiration_codes = list(settlement_rates.keys())  # noqa: F841
     result = df.query("ExpirationCode in @expiration_codes")["SettlementRate"].to_list()
     assert result == list(settlement_rates.values())
@@ -67,8 +67,8 @@ def test_settlement_rates_with_current_holiday_list():
         "F31": 0.10240,
         "F33": 0.10331,
     }
-
-    df = cr.fetch_data(trade_date="2023-12-26")
+    test_date = pd.Timestamp("2023-12-26")
+    df = ft.fetch_di(trade_date=test_date)
     expiration_codes = list(settlement_rates.keys())  # noqa: F841
     results = df.query("ExpirationCode in @expiration_codes")[
         "SettlementRate"
@@ -77,6 +77,6 @@ def test_settlement_rates_with_current_holiday_list():
 
 
 def test_non_business_day():
-    non_business_day = "2023-12-24"
+    non_business_day = pd.Timestamp("2023-12-24")
     with pytest.raises(ValueError):
-        cr.fetch_data(trade_date=non_business_day)
+        ft.fetch_di(trade_date=non_business_day)

pyield-0.7.0/pyield/__about__.py

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

pyield-0.7.0/pyield/di/__init__.py

@@ -1,6 +0,0 @@
-from .core import fetch_data, read_data
-
-__all__ = [
-    "fetch_data",
-    "read_data",
-]

pyield-0.7.0/pyield/di/core.py

@@ -1,180 +0,0 @@
-from pathlib import Path
-from typing import Literal
-
-import pandas as pd
-
-from .. import bday
-from . import web, xml
-
-
-def _normalize_date(trade_date: str | pd.Timestamp | None = None) -> pd.Timestamp:
-    if isinstance(trade_date, str):
-        normalized_date = pd.Timestamp(trade_date).normalize()
-    elif isinstance(trade_date, pd.Timestamp):
-        normalized_date = trade_date.normalize()
-    elif trade_date is None:
-        today = pd.Timestamp.today().normalize()
-        # Get last business day before today
-        normalized_date = bday.offset_bdays(today, -1)
-    else:
-        raise ValueError("Invalid date format.")
-
-    # Raise an error if the trade date is in the future
-    if normalized_date > pd.Timestamp.today().normalize():
-        raise ValueError("Trade date cannot be in the future.")
-
-    # Raise error if the reference date is not a business day
-    if not bday.is_bday(normalized_date):
-        raise ValueError("Trade date must be a business day.")
-
-    return normalized_date
-
-
-def get_expiration_date(expiration_code: str) -> pd.Timestamp:
-    """
-    Converts an expiration code into its corresponding expiration date.
-
-    This function translates an expiration code into a specific expiration date based on
-    a given mapping. The expiration code consists of a letter representing the month and
-    two digits for the year. The function ensures the date returned is a valid business
-    day by adjusting weekends and holidays as necessary.
-
-    Args:
-        expiration_code (str): The expiration code to be converted, where the first
-            letter represents the month and the last two digits represent the year
-            (e.g., "F23" for January 2023).
-
-    Returns:
-        pd.Timestamp: The expiration date corresponding to the code, adjusted to a valid
-            business day. Returns pd.NaT if the code is invalid.
-
-    Examples:
-        >>> get_expiration_date("F23")
-        pd.Timestamp('2023-01-01')
-
-        >>> get_expiration_date("Z33")
-        pd.Timestamp('2033-12-01')
-
-        >>> get_expiration_date("A99")
-        pd.NaT
-
-    Notes:
-        The expiration date is calculated based on the format change introduced by B3 on
-        22-05-2006, where the first letter represents the month and the last two digits
-        represent the year.
-    """
-    month_codes = {
-        "F": 1,
-        "G": 2,
-        "H": 3,
-        "J": 4,
-        "K": 5,
-        "M": 6,
-        "N": 7,
-        "Q": 8,
-        "U": 9,
-        "V": 10,
-        "X": 11,
-        "Z": 12,
-    }
-
-    try:
-        month_code = expiration_code[0]
-        month = month_codes[month_code]
-        year = int("20" + expiration_code[-2:])
-        # The expiration date is always the first business day of the month
-        expiration = pd.Timestamp(year, month, 1)
-
-        # Adjust to the next business day when expiration date is a weekend or a holiday
-        adj_expiration = bday.offset_bdays(expiration, offset=0)
-
-        return adj_expiration
-
-    except (KeyError, ValueError):
-        return pd.NaT  # type: ignore
-
-
-def fetch_data(
-    trade_date: str | pd.Timestamp | None = None,
-    source_type: Literal["bmf", "b3", "b3s"] = "bmf",
-    return_raw: bool = False,
-) -> pd.DataFrame:
-    """
-    Fetches DI futures data for a specified trade date from B3.
-
-     Retrieves and processes DI futures data from B3 for a given trade date. This
-     function serves as the primary method for accessing DI data, with options to
-     specify the source of the data and whether to return raw data.
-
-     Args:
-        trade_date (str | pd.Timestamp | None, optional): The trade date for which to
-            fetch DI data. If None or not provided, uses the previous business day.
-        source_type (Literal["bmf", "b3", "b3s"], optional): Indicates the source of
-            the data. Defaults to "bmf". Options include:
-                - "bmf": Fetches data from the old BM&FBOVESPA website. Fastest option.
-                - "b3": Fetches data from the complete Price Report (XML file) provided
-                    by B3.
-                - "b3s": Fetches data from the simplified Price Report (XML file)
-                    provided by B3. Faster than "b3" but less detailed.
-        return_raw (bool, optional): If True, returns the raw DI data without
-            processing.
-
-     Returns:
-         pd.DataFrame: A DataFrame containing the DI futures data for the specified
-         trade
-             date. Format and content depend on the source_type and return_raw flag.
-
-     Examples:
-         # Fetch DI data for the previous business day using default settings
-         >>> get_di()
-
-         # Fetch DI data for a specific trade date from the simplified B3 Price Report
-         >>> get_di("2023-12-28", source_type="b3s")
-
-     Notes:
-         - Complete Price Report XML files are about 5 MB in size.
-         - Simplified Price Report XML files are significantly smaller, around 50 kB.
-         - For file specifications, refer to the B3 documentation: [B3 File Specs](https://www.b3.com.br/data/files/16/70/29/9C/6219D710C8F297D7AC094EA8/Catalogo_precos_v1.3.pdf)
-    """
-    # Force trade_date to be a pandas pd.Timestamp
-    normalized_trade_date = _normalize_date(trade_date)
-
-    if source_type == "bmf":
-        return web.get_di(normalized_trade_date, return_raw)
-    elif source_type in ["b3", "b3s"]:
-        return xml.read_xml(normalized_trade_date, source_type, return_raw)
-    else:
-        raise ValueError("source_type must be either 'bmf', 'b3' or 'b3s'.")
-
-
-def read_data(file_path: Path, return_raw: bool = False) -> pd.DataFrame:
-    """
-    Reads DI futures data from a file and returns it as a pandas DataFrame.
-
-    This function opens and reads a DI futures data file, returning the contents as a
-    pandas DataFrame. It supports reading from both XML files provided by B3, wich
-    are the simplified and complete Price Reports.
-
-    Args:
-        file_path (Path): The file path to the DI data file. This should be a valid
-            Path object pointing to the location of the file.
-        return_raw (bool, optional): If set to True, the function returns the raw data
-            without applying any transformation or processing. Useful for cases where
-            raw data inspection or custom processing is needed. Defaults to False.
-
-    Returns:
-        pd.DataFrame: A DataFrame containing the processed or raw DI futures data,
-            depending on the `return_raw` flag.
-
-    Examples:
-        >>> read_di(Path("path/to/di_data_file.xml"))
-        # returns a DataFrame with the DI futures data
-
-        >>> read_di(Path("path/to/di_data_file.xml"), return_raw=True)
-        # returns a DataFrame with the raw DI futures data, without processing
-
-    Note:
-        The ability to process and return raw data is primarily intended for advanced
-        users who require access to the data in its original form for custom analyses.
-    """
-    return xml.read_di(file_path, return_raw=return_raw)

pyield-0.7.0/tests/test_br_calendar.py → pyield-0.7.2/tests/test_bday.py

@@ -1,5 +1,5 @@
-import pandas as pd
 import numpy as np
+import pandas as pd
 
 import pyield as yd