PYield 0.6.0__tar.gz → 0.7.1__tar.gz

{pyield-0.6.0 → pyield-0.7.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: PYield
-Version: 0.6.0
+Version: 0.7.1
 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
 
@@ -67,29 +67,56 @@ pip install pyield
 
 ## How to use PYield
 
+### Business Days Tools (Brazilian holidays are automatically considered)
+```python
+>>> import pyield as yd
+
+# Count the number of business days between two dates
+# Start date is included, end date is excluded
+>>> yd.count_bdays(start='2023-12-29', end='2024-01-02')
+1
+
+# Get the next business day after a given date (offset=1)
+>>> yd.offset_bdays(dates="2023-12-29", offset=1)
+Timestamp('2024-01-02 00:00:00')
+
+# Get the next business day if it is not a business day (offset=0)
+>>> yd.offset_bdays(dates="2023-12-30", offset=0)
+Timestamp('2024-01-02 00:00:00')
+
+# Since 2023-12-29 is a business day, it returns the same date (offset=0)
+>>> yd.offset_bdays(dates="2023-12-29", offset=0)
+Timestamp('2023-12-29 00:00:00')
+
+# Generate a pandas series with the business days between two dates
+>>> yd.generate_bdays(start='2023-12-29', end='2024-01-03')
+0   2023-12-29
+1   2024-01-02
+2   2024-01-03
+dtype: datetime64[ns]
+```
+
 ### Futures Data
 ```python
-import pyield as yd
-
-# Get a DataFrame with the DI Futures data from B3
->>> yd.get_data(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
+# Fetch a DataFrame with the DI Futures data from B3
+>>> yd.fetch_asset(asset_code="DI1", reference_date='2024-03-08')
+
+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
 ```python
-# Get a DataFrame with the NTN-B data from ANBIMA
+# Fetch a DataFrame with the NTN-B data from ANBIMA
 # Anbima data is available for the last 5 working days
 # Obs: Anbima members have access to the full history
->>> yd.get_data(asset_code="NTN-B", reference_date='2024-04-12')
+>>> yd.fetch_asset(asset_code="NTN-B", reference_date='2024-04-12')
 
 BondType ReferenceDate MaturityDate BidRate AskRate IndicativeRate Price
 NTN-B    2024-04-12    2024-08-15   0.07540 0.07504 0.07523        4,271.43565
@@ -116,29 +143,17 @@ NTN-F    2024-04-11    2033-01-01    -5.69000
 NTN-F    2024-04-11    2035-01-01    -1.27000
 ```
 
-### Business Days Tools (Brazilian holidays are automatically considered)
+### Indicators Data
 ```python
-# Count the number of business days between two dates
-# Start date is included, end date is excluded
->>> yd.count_bdays(start='2023-12-29', end='2024-01-02')
-1
+# Fetch the SELIC target rate from the Central Bank of Brazil
+>>> yd.fetch_indicator(indicator_code="SELIC", reference_date='2024-04-12')
+10.75
 
-# Get the next business day after a given date (offset=1)
->>> yd.offset_bdays(dates="2023-12-29", offset=1)
-Timestamp('2024-01-02 00:00:00')
+# Fetch the IPCA monthly inflation rate from IBGE
+>>> yd.fetch_indicator(indicator_code="IPCA", reference_date='2024-03-18')
+0.16
 
-# Get the next business day if it is not a business day (offset=0)
->>> yd.offset_bdays(dates="2023-12-30", offset=0)
-Timestamp('2024-01-02 00:00:00')
-
-# Since 2023-12-29 is a business day, it returns the same date (offset=0)
->>> yd.offset_bdays(dates="2023-12-29", offset=0)
-Timestamp('2023-12-29 00:00:00')
-
-# Generate a pandas series with the business days between two dates
->>> yd.generate_bdays(start='2023-12-29', end='2024-01-03')
-0   2023-12-29
-1   2024-01-02
-2   2024-01-03
-dtype: datetime64[ns]
+# If no data is yet available for the indicator, the function returns None
+>>> yd.fetch_indicator(indicator_code="IPCA", reference_date='2024-04-10')
+None
 ```

{pyield-0.6.0 → pyield-0.7.1}/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
 
@@ -25,29 +25,56 @@ pip install pyield
 
 ## How to use PYield
 
+### Business Days Tools (Brazilian holidays are automatically considered)
+```python
+>>> import pyield as yd
+
+# Count the number of business days between two dates
+# Start date is included, end date is excluded
+>>> yd.count_bdays(start='2023-12-29', end='2024-01-02')
+1
+
+# Get the next business day after a given date (offset=1)
+>>> yd.offset_bdays(dates="2023-12-29", offset=1)
+Timestamp('2024-01-02 00:00:00')
+
+# Get the next business day if it is not a business day (offset=0)
+>>> yd.offset_bdays(dates="2023-12-30", offset=0)
+Timestamp('2024-01-02 00:00:00')
+
+# Since 2023-12-29 is a business day, it returns the same date (offset=0)
+>>> yd.offset_bdays(dates="2023-12-29", offset=0)
+Timestamp('2023-12-29 00:00:00')
+
+# Generate a pandas series with the business days between two dates
+>>> yd.generate_bdays(start='2023-12-29', end='2024-01-03')
+0   2023-12-29
+1   2024-01-02
+2   2024-01-03
+dtype: datetime64[ns]
+```
+
 ### Futures Data
 ```python
-import pyield as yd
-
-# Get a DataFrame with the DI Futures data from B3
->>> yd.get_data(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
+# Fetch a DataFrame with the DI Futures data from B3
+>>> yd.fetch_asset(asset_code="DI1", reference_date='2024-03-08')
+
+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
 ```python
-# Get a DataFrame with the NTN-B data from ANBIMA
+# Fetch a DataFrame with the NTN-B data from ANBIMA
 # Anbima data is available for the last 5 working days
 # Obs: Anbima members have access to the full history
->>> yd.get_data(asset_code="NTN-B", reference_date='2024-04-12')
+>>> yd.fetch_asset(asset_code="NTN-B", reference_date='2024-04-12')
 
 BondType ReferenceDate MaturityDate BidRate AskRate IndicativeRate Price
 NTN-B    2024-04-12    2024-08-15   0.07540 0.07504 0.07523        4,271.43565
@@ -74,29 +101,17 @@ NTN-F    2024-04-11    2033-01-01    -5.69000
 NTN-F    2024-04-11    2035-01-01    -1.27000
 ```
 
-### Business Days Tools (Brazilian holidays are automatically considered)
+### Indicators Data
 ```python
-# Count the number of business days between two dates
-# Start date is included, end date is excluded
->>> yd.count_bdays(start='2023-12-29', end='2024-01-02')
-1
+# Fetch the SELIC target rate from the Central Bank of Brazil
+>>> yd.fetch_indicator(indicator_code="SELIC", reference_date='2024-04-12')
+10.75
 
-# Get the next business day after a given date (offset=1)
->>> yd.offset_bdays(dates="2023-12-29", offset=1)
-Timestamp('2024-01-02 00:00:00')
+# Fetch the IPCA monthly inflation rate from IBGE
+>>> yd.fetch_indicator(indicator_code="IPCA", reference_date='2024-03-18')
+0.16
 
-# Get the next business day if it is not a business day (offset=0)
->>> yd.offset_bdays(dates="2023-12-30", offset=0)
-Timestamp('2024-01-02 00:00:00')
-
-# Since 2023-12-29 is a business day, it returns the same date (offset=0)
->>> yd.offset_bdays(dates="2023-12-29", offset=0)
-Timestamp('2023-12-29 00:00:00')
-
-# Generate a pandas series with the business days between two dates
->>> yd.generate_bdays(start='2023-12-29', end='2024-01-03')
-0   2023-12-29
-1   2024-01-02
-2   2024-01-03
-dtype: datetime64[ns]
+# If no data is yet available for the indicator, the function returns None
+>>> yd.fetch_indicator(indicator_code="IPCA", reference_date='2024-04-10')
+None
 ```

pyield-0.7.1/pyield/__about__.py

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

{pyield-0.6.0 → pyield-0.7.1}/pyield/__init__.py

@@ -1,6 +1,6 @@
 from .__about__ import __version__
 from .bday import count_bdays, generate_bdays, is_bday, offset_bdays
-from .data_access import get_data
+from .data_access import fetch_asset, fetch_indicator
 from .data_analysis import calculate_spreads
 
 __all__ = [
@@ -9,6 +9,7 @@ __all__ = [
     "generate_bdays",
     "offset_bdays",
     "count_bdays",
-    "get_data",
+    "fetch_asset",
+    "fetch_indicator",
     "calculate_spreads",
 ]

pyield-0.7.1/pyield/data_access.py

@@ -0,0 +1,89 @@
+import pandas as pd
+
+from . import futures as ft
+from . import indicators as it
+from . import treasuries as tr
+from .utils import _normalize_date
+
+
+def fetch_asset(
+    asset_code: str,
+    reference_date: str | pd.Timestamp | None = None,
+    **kwargs,
+) -> pd.DataFrame:
+    """
+    Fetches data for a specified asset based on type and reference date.
+
+    Args:
+        asset_code (str): The asset code identifying the type of financial asset.
+        Supported options:
+            - "TRB": Treasury bonds (indicative rates from ANBIMA).
+            - "LTN", "LFT", "NTN-F", "NTN-B": Specific types of Brazilian treasury bonds
+                  (indicative rates from ANBIMA).
+            - "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:
+            - return_raw (bool): Whether to return raw data without processing. Defaults
+              to False.
+
+    Returns:
+        pd.DataFrame: A DataFrame containing the fetched data for the specified asset.
+
+    Raises:
+        ValueError: If the asset code is not recognized or supported.
+
+    Examples:
+        >>> fetch_asset('TRB', '2023-04-01')
+        >>> fetch_asset('DI1', '2023-04-01', return_raw=True)
+    """
+    return_raw = kwargs.get("return_raw", False)
+    normalized_date = _normalize_date(reference_date)
+
+    if asset_code.lower() == "trb":
+        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_bonds(reference_date=normalized_date)
+        return df.query(f"BondType == '{asset_code.upper()}'")
+
+    elif asset_code.lower() == "di1":
+        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.")
+
+
+def fetch_indicator(
+    indicator_code: str,
+    reference_date: str | pd.Timestamp | None = None,
+) -> float | None:
+    """
+    Fetches data for a specified economic indicator and reference date.
+
+    Args:
+        indicator_code (str): The code for the economic indicator. Supported options:
+            - "SELIC": SELIC target rate from the Central Bank of Brazil.
+            - "IPCA": IPCA monthly inflation rate from IBGE.
+        reference_date (str | pd.Timestamp | None): The reference date for which data is
+            fetched. Defaults to the previous business day if None.
+
+    Returns:
+        pd.Series: A Series containing the fetched data for the specified indicator.
+
+    Raises:
+        ValueError: If the indicator code is not recognized or supported.
+
+    Examples:
+        >>> fetch_indicator('SELIC', '2023-04-01')
+        >>> fetch_indicator('IPCA', '2023-04-01')
+    """
+    normalized_date = _normalize_date(reference_date)
+
+    if indicator_code.lower() == "selic":
+        return it.fetch_selic_target(reference_date=normalized_date)
+    elif indicator_code.lower() == "ipca":
+        return it.fetch_ipca_mr(reference_date=normalized_date)
+    else:
+        raise ValueError("Indicator type not supported.")

pyield-0.7.1/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.1/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