PYield 0.6.0__tar.gz → 0.7.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: PYield
-Version: 0.6.0
+Version: 0.7.0
 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>
@@ -67,12 +67,39 @@ pip install pyield
 
 ## How to use PYield
 
-### Futures Data
+### Business Days Tools (Brazilian holidays are automatically considered)
 ```python
-import pyield as yd
+>>> 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')
 
-# Get a DataFrame with the DI Futures data from B3
->>> yd.get_data(asset_code="DI1", reference_date='2024-03-08')
+# 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
+# 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
@@ -86,10 +113,10 @@ TradeDate  ExpirationCode ExpirationDate BDToExpiration  ... LastRate LastAskRat
 
 ### 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.0}/README.md

@@ -25,12 +25,39 @@ pip install pyield
 
 ## How to use PYield
 
-### Futures Data
+### Business Days Tools (Brazilian holidays are automatically considered)
 ```python
-import pyield as yd
+>>> 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')
 
-# Get a DataFrame with the DI Futures data from B3
->>> yd.get_data(asset_code="DI1", reference_date='2024-03-08')
+# 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
+# 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
@@ -44,10 +71,10 @@ TradeDate  ExpirationCode ExpirationDate BDToExpiration  ... LastRate LastAskRat
 
 ### 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.0/pyield/__about__.py

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

{pyield-0.6.0 → pyield-0.7.0}/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.0/pyield/data_access.py

@@ -0,0 +1,88 @@
+import pandas as pd
+
+from . import di
+from . import indicators as ir
+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": DI Futures rates 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_data(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)
+        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
+        )
+    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 ir.fetch_selic_target(reference_date=normalized_date)
+    elif indicator_code.lower() == "ipca":
+        return ir.fetch_ipca_mr(reference_date=normalized_date)
+    else:
+        raise ValueError("Indicator type not supported.")

pyield-0.7.0/pyield/indicators.py

@@ -0,0 +1,59 @@
+import pandas as pd
+import requests
+
+
+def fetch_ipca_mr(reference_date: pd.Timestamp) -> float | None:
+    """
+    Fetches the IPCA (Índice Nacional de Preços ao Consumidor Amplo) monthly rate
+    from the IBGE (Instituto Brasileiro de Geografia e Estatística) for a given
+    reference date.
+
+    Args:
+        reference_date (pd.Timestamp): Reference date for the data. The function expects
+        a pandas Timestamp object.
+
+    Returns:
+        float | None: The IPCA monthly rate for the specified date as a float.
+        Returns None if data is not found or in case of an error.
+
+    Notes:
+        The function makes an API call to the IBGE's data portal to retrieve the
+        information. An example of the API call:
+        https://servicodados.ibge.gov.br/api/v3/agregados/6691/periodos/202403/variaveis/63?localidades=N1[all]
+        where '202403' is the reference date in 'YYYYMM' format.
+        The API URL is constructed dynamically based on the reference date provided.
+    """
+    # Format the date as 'YYYYMM' for the API endpoint
+    ipca_date = reference_date.strftime("%Y%m")
+
+    # Construct the API URL using the formatted date
+    api_url = f"https://servicodados.ibge.gov.br/api/v3/agregados/6691/periodos/{ipca_date}/variaveis/63?localidades=N1[all]"
+
+    # Send a GET request to the API
+    response = requests.get(api_url)
+
+    # Raises HTTPError, if one occurred
+    response.raise_for_status()
+
+    # Parse the JSON response
+    data = response.json()
+
+    # Extract and return the IPCA monthly growth rate if data is available
+    if data:
+        ipca_str = data[0]["resultados"][0]["series"][0]["serie"][ipca_date]
+        return float(ipca_str)
+    else:
+        return None
+
+
+def fetch_selic_target(reference_date: pd.Timestamp) -> float | None:
+    # https://api.bcb.gov.br/dados/serie/bcdata.sgs.432/dados?formato=json&dataInicial=12/04/2024&dataFinal=12/04/2024
+    selic_date = reference_date.strftime("%d/%m/%Y")
+    api_url = f"https://api.bcb.gov.br/dados/serie/bcdata.sgs.432/dados?formato=json&dataInicial={selic_date}&dataFinal={selic_date}"
+    response = requests.get(api_url)
+    response.raise_for_status()
+    data = response.json()
+    if data:
+        return float(data[0]["valor"])
+    else:
+        return None

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

@@ -105,10 +105,8 @@ def fetch_data(reference_date: pd.Timestamp, return_raw=False) -> pd.DataFrame:
     Fetches indicative treasury rates from ANBIMA for a specified reference date.
 
     This function retrieves the indicative rates for Brazilian treasury securities
-    from ANBIMA, processing them into a structured pandas DataFrame. If no reference
-    date is provided, it defaults to the previous business day according to the
-    Brazilian calendar. There is an option to return raw data directly from the source
-    without processing.
+    from ANBIMA, processing them into a structured pandas DataFrame.
+    There is an option to return raw data directly from the source without processing.
 
     Parameters:
         reference_date (str | pd.Timestamp, optional): The date for which to fetch the
@@ -123,12 +121,6 @@ def fetch_data(reference_date: pd.Timestamp, return_raw=False) -> pd.DataFrame:
             data includes bond type, reference date, maturity date and various rates
             (bid, ask, indicative) among others, depending on the `return_raw` flag.
 
-    Examples:
-        # Fetch processed indicative rates for the previous business day
-        >>> get_treasury_rates()
-
-        # Fetch raw indicative rates for a specific date
-        >>> get_treasury_rates("2023-12-28")
     """
     df = _get_raw_df(reference_date)
 
@@ -150,20 +142,12 @@ def calculate_di_spreads(reference_date: pd.Timestamp) -> pd.DataFrame:
 
     Parameters:
         reference_date (str | pd.Timestamp, optional): The reference date for the DI
-            spread calculation. If None or not provided, defaults to the previous
-            business day according to the Brazilian calendar.
+            spread calculation.
 
     Returns:
         pd.DataFrame: A DataFrame containing the bond type, reference date, maturity
             date, and the calculated DI spread in basis points. The data is sorted by
             bond type and maturity date.
-
-    Examples:
-        # Calculate DI spreads for the previous business day
-        >>> calculate_treasury_di_spreads()
-
-        # Calculate DI spreads for a specific reference date
-        >>> calculate_treasury_di_spreads("2023-12-15")
     """
     # Fetch DI rates and adjust the maturity date format for compatibility
     df_di = di.fetch_data(reference_date)[["ExpirationDate", "SettlementRate"]]

pyield-0.7.0/pyield/utils.py

@@ -0,0 +1,55 @@
+import pandas as pd
+
+from . import bday
+
+
+def _normalize_date(reference_date: str | pd.Timestamp | None = None) -> pd.Timestamp:
+    """
+    Normalizes the given date to ensure it is a past business day at midnight. If no
+    date is provided, it defaults to the previous business day.
+
+    Args:
+        reference_date (str | pd.Timestamp | None): The date to normalize. Can be a
+        string, pandas Timestamp or None. If None, it defaults to the last business day.
+
+    Returns:
+        pd.Timestamp: A normalized pandas Timestamp representing a past business day at
+        midnight.
+
+    Raises:
+        ValueError: If the input date format is invalid, if the date is in the future,
+        or if the date is not a business day.
+
+    Notes:
+        - Normalization means setting the time component of the timestamp to midnight.
+        - The function checks if the normalized date is a business day and adjusts
+          accordingly.
+        - Business day calculations consider local market holidays.
+
+    Examples:
+        >>> _normalize_date('2023-04-01')
+        >>> _normalize_date(pd.Timestamp('2023-04-01 15:30'))
+        >>> _normalize_date()
+    """
+    if isinstance(reference_date, str):
+        # Convert string date to Timestamp and normalize to midnight
+        normalized_date = pd.Timestamp(reference_date).normalize()
+    elif isinstance(reference_date, pd.Timestamp):
+        # Normalize Timestamp to midnight
+        normalized_date = reference_date.normalize()
+    elif reference_date is None:
+        # If no date is provided, use the previous business day
+        today = pd.Timestamp.today().normalize()
+        normalized_date = bday.offset_bdays(today, -1)
+    else:
+        raise ValueError("Invalid date format.")
+
+    # Validate that the date is not in the future
+    if normalized_date > pd.Timestamp.today().normalize():
+        raise ValueError("Reference date cannot be in the future.")
+
+    # Validate that the date is a business day
+    if not bday.is_bday(normalized_date):
+        raise ValueError("Reference date must be a business day.")
+
+    return normalized_date

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

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

pyield-0.6.0/pyield/__about__.py

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

pyield-0.6.0/pyield/data_access.py

@@ -1,51 +0,0 @@
-import pandas as pd
-
-from . import di
-from . import treasuries as tr
-from .utils import _normalize_date
-
-
-def get_data(
-    asset_code: str,
-    reference_date: str | pd.Timestamp | None = None,
-    **kwargs,
-) -> pd.DataFrame:
-    """
-    Fetches data for a specified asset type and reference date.
-
-    Args:
-    asset (str): The asset type. Available options are:
-        - "TRB": Fetches indicative rates for Brazilian treasury bonds from ANBIMA.
-        - "LTN": Fetches indicative rates for Brazilian LTN bonds from ANBIMA.
-        - "LFT": Fetches indicative rates for Brazilian LFT bonds from ANBIMA.
-        - "NTN-F": Fetches indicative rates for Brazilian NTN-F bonds from ANBIMA.
-        - "NTN-B": Fetches indicative rates for Brazilian NTN-B bonds from ANBIMA.
-        - "DI1": Fetches DI Futures rates from B3.
-    reference_date (str): Reference date for the data in YYYY-MM-DD format.
-
-    Returns:
-    pd.DataFrame: A DataFrame containing the fetched data.
-
-    Raises:
-    ValueError: If the specified source or asset type is not supported.
-    """
-    # Extract the internal use parameter with default value
-    return_raw = kwargs.get("return_raw", False)
-
-    # Validate the date, defaulting to the previous business day if not provided
-    normalized_date = _normalize_date(reference_date)
-
-    if asset_code.lower() == "trb":
-        # Fetch all indicative treasury rates from ANBIMA
-        return tr.fetch_data(reference_date=normalized_date, return_raw=return_raw)
-    elif asset_code.lower() in ["ltn", "lft", "ntn-f", "ntn-b"]:
-        # Fetch indicative rates for a specific type of Brazilian treasury bond
-        df = tr.fetch_data(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
-        )
-    else:
-        raise ValueError("Asset type not supported.")

pyield-0.6.0/pyield/utils.py

@@ -1,26 +0,0 @@
-import pandas as pd
-
-from . import bday
-
-
-def _normalize_date(reference_date: str | pd.Timestamp | None = None) -> pd.Timestamp:
-    if isinstance(reference_date, str):
-        normalized_date = pd.Timestamp(reference_date).normalize()
-    elif isinstance(reference_date, pd.Timestamp):
-        normalized_date = reference_date.normalize()
-    elif reference_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 reference date is in the future
-    if normalized_date > pd.Timestamp.today().normalize():
-        raise ValueError("Reference 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("Reference date must be a business day.")
-
-    return normalized_date