PYield 0.7.2__tar.gz → 0.7.4__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: PYield
-Version: 0.7.2
+Version: 0.7.4
 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>
@@ -38,6 +38,7 @@ Requires-Dist: numpy
 Requires-Dist: beautifulsoup4
 Requires-Dist: html5lib
 Requires-Dist: lxml
+Requires-Dist: python-calamine>=0.2.0
 Description-Content-Type: text/markdown
 
 [![PyPI version](https://img.shields.io/pypi/v/pyield.svg)](https://pypi.python.org/pypi/pyield)
@@ -101,14 +102,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 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
+TradeDate  TickerSymbol ExpirationDate BDaysToExp ... LastRate LastAskRate LastBidRate SettlementRate
+2024-03-08 DI1J24            2024-04-01     15                ... 10.952   10.952      10.956      10.956
+2024-03-08 DI1K24            2024-05-02     37                ... 10.776   10.774      10.780      10.777
+2024-03-08 DI1M24            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
+2024-03-08 DI1F37            2037-01-02     3213              ... <NA>     <NA>        <NA>        10.859
+2024-03-08 DI1F38            2038-01-04     3462              ... <NA>     <NA>        <NA>        10.859
+2024-03-08 DI1F39            2039-01-03     3713              ... <NA>     <NA>        <NA>        10.85
 ```
 
 ### Treasury Bonds Data

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

@@ -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 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
+TradeDate  TickerSymbol ExpirationDate BDaysToExp ... LastRate LastAskRate LastBidRate SettlementRate
+2024-03-08 DI1J24            2024-04-01     15                ... 10.952   10.952      10.956      10.956
+2024-03-08 DI1K24            2024-05-02     37                ... 10.776   10.774      10.780      10.777
+2024-03-08 DI1M24            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
+2024-03-08 DI1F37            2037-01-02     3213              ... <NA>     <NA>        <NA>        10.859
+2024-03-08 DI1F38            2038-01-04     3462              ... <NA>     <NA>        <NA>        10.859
+2024-03-08 DI1F39            2039-01-03     3713              ... <NA>     <NA>        <NA>        10.85
 ```
 
 ### Treasury Bonds Data

pyield-0.7.4/pyield/__about__.py

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

{pyield-0.7.2 → pyield-0.7.4}/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 fetch_asset, fetch_indicator
+from .data_access import fetch_asset, fetch_indicator, fetch_projection
 from .data_analysis import calculate_spreads
 
 __all__ = [
@@ -11,5 +11,6 @@ __all__ = [
     "count_bdays",
     "fetch_asset",
     "fetch_indicator",
+    "fetch_projection",
     "calculate_spreads",
 ]

pyield-0.7.4/pyield/data_access.py

@@ -0,0 +1,148 @@
+import pandas as pd
+
+from . import futures as ft
+from . import indicators as it
+from . import projections as pr
+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.
+            - "FRC": Forward Rate Agreement (FRA) from B3.
+        reference_date (str | pd.Timestamp | None): The reference date for which data is
+            fetched. Defaults to the last 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":
+        today = pd.Timestamp.today().normalize()
+        if normalized_date == today:
+            return ft.fetch_last_di()
+        else:
+            return ft.fetch_past_di(trade_date=normalized_date, return_raw=return_raw)
+    elif asset_code.lower() == "ddi":
+        return ft.fetch_past_ddi(trade_date=normalized_date, return_raw=return_raw)
+    elif asset_code.lower() == "frc":
+        return ft.fetch_past_frc(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, expressed as
+              an annual rate (p.a.).
+            - "DI": Interbank Deposit rate (DI) from B3 expressed as a daily rate,
+              calculated on a daily basis and expressed per diem (p.d.).
+            - "IPCA": IPCA monthly inflation rate from IBGE, expressed per month (p.m.).
+            - "VNA_LFT": VNA (Valor Nominal Atualizado) of LFT (Letra Financeira do
+              Tesouro), which reflects updated nominal values for these bonds.
+        - reference_date (str | pd.Timestamp | None): The reference date for which data
+          is fetched. Defaults to the last business day if None.
+
+    Returns:
+        float | None: The value of the specified economic indicator for the reference
+        date. Returns None if data is not found.
+
+    Raises:
+        ValueError: If the indicator code is not recognized or supported.
+
+    Examples:
+        >>> fetch_indicator('SELIC', '2023-04-01')
+        0.1075  # Indicates a SELIC target rate of 10.75% p.a.
+        >>> fetch_indicator('IPCA', '2023-03-10')
+        0.0016  # Indicates an IPCA monthly rate of 0.16% p.m.
+        >>> fetch_indicator('DI', '2023-04-17')
+        0.00040168  # Indicates a DI daily rate of 0.02% p.d.
+    """
+    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)
+    elif indicator_code.lower() == "di":
+        return it.fetch_di(reference_date=normalized_date)
+    elif indicator_code.lower() == "vna_lft":
+        return it.fetch_vna_selic(reference_date=normalized_date)
+    else:
+        raise ValueError("Indicator type not supported.")
+
+
+def fetch_projection(projection_code: str) -> dict:
+    """
+    Fetches a financial projection for a specified code and reference date.
+
+    Args:
+        projection_code (str): The code for the financial projection. Supported options:
+            - "IPCA_CM": IPCA projection for the current month from ANBIMA.
+
+    Returns:
+        IndicatorProjection: An instance of IndicatorProjection containing:
+            - last_updated (pd.Timestamp): The datetime when the projection was last
+              updated.
+            - reference_month_ts (pd.Timestamp): The month to which the projection
+              applies.
+            - reference_month_br (str): The formatted month as a string formatted using
+              the pt_BR locale.
+            - projected_value (float): The projected indicator value.
+
+    Raises:
+        ValueError: If the projection code is not recognized or supported.
+
+    Examples:
+        >>> fetch_projection('IPCA_CM')
+        IndicatorProjection(
+            last_updated=pd.Timestamp('2024-04-19 18:55:00'),
+            reference_month_ts=pd.Timestamp('2024-04-01 00:00:00'),
+            reference_month_br='ABR/2024',
+            projected_value=0.35
+        )
+    """
+
+    if projection_code.lower() == "ipca_cm":
+        return pr.fetch_current_month_ipca_projection()
+    else:
+        raise ValueError("Projection type not supported.")

pyield-0.7.4/pyield/futures/__init__.py

@@ -0,0 +1,13 @@
+from .common import get_expiration_date, get_old_expiration_date
+from .ddi import fetch_past_ddi
+from .di import fetch_last_di, fetch_past_di
+from .frc import fetch_past_frc
+
+__all__ = [
+    "fetch_past_di",
+    "fetch_last_di",
+    "fetch_past_ddi",
+    "fetch_past_frc",
+    "get_expiration_date",
+    "get_old_expiration_date",
+]

{pyield-0.7.2 → pyield-0.7.4}/pyield/futures/common.py

@@ -131,12 +131,12 @@ def get_old_expiration_date(
         return pd.NaT  # type: ignore
 
 
-def _fetch_raw_df(asset_code: str, trade_date: pd.Timestamp) -> pd.DataFrame:
+def fetch_past_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.
+    Fetch the historical futures data from B3 for a specific trade date.
 
     Args:
-        trade_date: a datetime-like object representing the trade date.
+        trade_date (pd.Timestamp): The trade date for which the data should be fetched.
 
     Returns:
         pd.DataFrame: Raw DI data as a Pandas pd.DataFrame.
@@ -170,6 +170,60 @@ def _fetch_raw_df(asset_code: str, trade_date: pd.Timestamp) -> pd.DataFrame:
     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())
+    if "AJUSTE CORRIG. (4)" in df.columns:
+        df["AJUSTE CORRIG. (4)"] = df["AJUSTE CORRIG. (4)"].astype(pd.Float64Dtype())
+
+    return df
+
+
+def fetch_last_raw_df(future_code: str) -> pd.DataFrame:
+    """
+    Fetch the latest data for a given future code from B3 derivatives quotation API.
+
+    Args:
+    future_code (str): The future code to fetch data for.
+
+    Returns:
+    pd.DataFrame: A DataFrame containing the normalized and cleaned data from the API.
+
+    Raises:
+    Exception: An exception is raised if the data fetch operation fails.
+    """
+
+    url = f"https://cotacao.b3.com.br/mds/api/v1/DerivativeQuotation/{future_code}"
+
+    try:
+        r = requests.get(url)
+        r.raise_for_status()  # Check for HTTP request errors
+    except requests.exceptions.RequestException:
+        raise Exception(f"Failed to fetch data for {future_code}.") from None
+
+    r.encoding = "utf-8"  # Explicitly set response encoding to utf-8 for consistency
+
+    # Normalize JSON response into a flat table
+    df = pd.json_normalize(r.json()["Scty"])
+
+    # Clean and reformat the DataFrame columns
+    df.columns = (df.columns
+        .str.replace("SctyQtn.", "")
+        .str.replace("asset.AsstSummry.", "")
+    )  # fmt: skip
+    df.drop(columns=["desc", "asset.code", "mkt.cd"], inplace=True)
+
+    # Convert maturity codes to datetime and drop rows with missing values
+    df["mtrtyCode"] = pd.to_datetime(df["mtrtyCode"], errors="coerce")
+    df.dropna(subset=["mtrtyCode"], inplace=True)
+
+    # Sort the DataFrame by maturity code and reset the index
+    df.sort_values("mtrtyCode", inplace=True, ignore_index=True)
+
+    # Get current date and time
+    now = pd.Timestamp.now().round("s")
+    # Subtract 15 minutes from the current time to account for API delay
+    trade_ts = now - pd.Timedelta(minutes=15)
+    df["TradeTimestamp"] = trade_ts
+
+    # Convert DataFrame to use nullable data types for better type consistency
+    df = df.convert_dtypes(dtype_backend="numpy_nullable")
 
     return df

{pyield-0.7.2 → pyield-0.7.4}/pyield/futures/ddi.py

@@ -59,8 +59,8 @@ def _process_raw_df(df: pd.DataFrame, trade_date: pd.Timestamp) -> pd.DataFrame:
         "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",
+        "NÚM. NEGOC.": "TradeCount",
+        "CONTR. NEGOC.": "TradeVolume",
         "VOL.": "FinancialVolume",
         "AJUSTE": "SettlementPrice",
         "AJUSTE ANTER. (3)": "PrevSettlementRate",
@@ -133,8 +133,8 @@ def _process_raw_df(df: pd.DataFrame, trade_date: pd.Timestamp) -> pd.DataFrame:
         "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",
+        "TradeCount",
+        "TradeVolume",
         "FinancialVolume",
         "SettlementPrice",
         "MinRate",
@@ -149,7 +149,7 @@ def _process_raw_df(df: pd.DataFrame, trade_date: pd.Timestamp) -> pd.DataFrame:
     return df[ordered_cols]
 
 
-def fetch_ddi(trade_date: pd.Timestamp, return_raw: bool = False) -> pd.DataFrame:
+def fetch_past_ddi(trade_date: pd.Timestamp, return_raw: bool = False) -> pd.DataFrame:
     """
     Fetchs the DDI futures data for a given date from B3.
 
@@ -172,7 +172,7 @@ def fetch_ddi(trade_date: pd.Timestamp, return_raw: bool = False) -> pd.DataFram
         - 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)
+    df_raw = common.fetch_past_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.2 → pyield-0.7.4}/pyield/futures/di.py

@@ -28,12 +28,12 @@ def _convert_prices_in_older_contracts(df: pd.DataFrame) -> pd.DataFrame:
         "MinRate",
         "MaxRate",
         "AvgRate",
-        "LastRate",
-        "LastBidRate",
-        "LastAskRate",
+        "CloseRate",
+        "CloseBidRate",
+        "CloseAskRate",
     ]
     for col in convert_cols:
-        df[col] = _convert_prices_to_rates(df[col], df["BDaysToExpiration"])
+        df[col] = _convert_prices_to_rates(df[col], df["BDaysToExp"])
 
     # Invert low and high prices
     df["MinRate"], df["MaxRate"] = df["MaxRate"], df["MinRate"]
@@ -41,7 +41,7 @@ def _convert_prices_in_older_contracts(df: pd.DataFrame) -> pd.DataFrame:
     return df
 
 
-def _process_raw_df(df: pd.DataFrame, trade_date: pd.Timestamp) -> pd.DataFrame:
+def _process_past_raw_df(df: pd.DataFrame, trade_date: pd.Timestamp) -> pd.DataFrame:
     """
     Internal function to process and transform raw DI futures data.
 
@@ -60,8 +60,8 @@ def _process_raw_df(df: pd.DataFrame, trade_date: pd.Timestamp) -> pd.DataFrame:
         "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",
+        "NÚM. NEGOC.": "TradeCount",
+        "CONTR. NEGOC.": "TradeVolume",
         "VOL.": "FinancialVolume",
         "AJUSTE": "SettlementPrice",
         "AJUSTE ANTER. (3)": "PrevSettlementRate",
@@ -70,11 +70,11 @@ def _process_raw_df(df: pd.DataFrame, trade_date: pd.Timestamp) -> pd.DataFrame:
         "PREÇO MÉD.": "AvgRate",
         "PREÇO MÁX.": "MaxRate",
         "PREÇO ABERTU.": "FirstRate",
-        "ÚLT. PREÇO": "LastRate",
+        "ÚLT. PREÇO": "CloseRate",
         "VAR. PTOS.": "PointsVariation",
         # Attention: bid/ask rates are inverted
-        "ÚLT.OF. COMPRA": "LastAskRate",
-        "ÚLT.OF. VENDA": "LastBidRate",
+        "ÚLT.OF. COMPRA": "CloseAskRate",
+        "ÚLT.OF. VENDA": "CloseBidRate",
     }
 
     df = df.rename(columns=rename_dict)
@@ -91,11 +91,9 @@ def _process_raw_df(df: pd.DataFrame, trade_date: pd.Timestamp) -> pd.DataFrame:
     else:
         df["ExpirationDate"] = df["ExpirationCode"].apply(common.get_expiration_date)
 
-    df["BDaysToExpiration"] = bday.count_bdays(trade_date, df["ExpirationDate"])
-    # Convert to nullable integer, since other columns use this data type
-    df["BDaysToExpiration"] = df["BDaysToExpiration"].astype(pd.Int64Dtype())
+    df["BDaysToExp"] = bday.count_bdays(trade_date, df["ExpirationDate"])
     # Remove expired contracts
-    df.query("BDaysToExpiration > 0", inplace=True)
+    df.query("BDaysToExp > 0", inplace=True)
 
     # Columns where 0 means NaN
     cols_with_nan = [
@@ -104,9 +102,9 @@ def _process_raw_df(df: pd.DataFrame, trade_date: pd.Timestamp) -> pd.DataFrame:
         "MinRate",
         "MaxRate",
         "AvgRate",
-        "LastRate",
-        "LastBidRate",
-        "LastAskRate",
+        "CloseRate",
+        "CloseBidRate",
+        "CloseAskRate",
     ]
     for col in cols_with_nan:
         df[col] = df[col].replace(0, pd.NA)
@@ -116,7 +114,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["BDaysToExpiration"]
+        df["SettlementPrice"], df["BDaysToExp"]
     )
 
     # Remove percentage in all rate columns and round to 5 decimal places since it's the
@@ -125,32 +123,83 @@ def _process_raw_df(df: pd.DataFrame, trade_date: pd.Timestamp) -> pd.DataFrame:
     for col in rate_cols:
         df[col] = (df[col] / 100).round(5)
 
+    df["TickerSymbol"] = "DI1" + df["ExpirationCode"]
+
     # Filter and order columns
     ordered_cols = [
         "TradeDate",
-        "ExpirationCode",
+        "TickerSymbol",
+        # "ExpirationCode",
         "ExpirationDate",
-        "BDaysToExpiration",
+        "BDaysToExp",
         "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",
+        "TradeCount",
+        "TradeVolume",
         "FinancialVolume",
         "SettlementPrice",
+        "SettlementRate",
+        "FirstRate",
         "MinRate",
         "AvgRate",
         "MaxRate",
-        "FirstRate",
-        "LastRate",
-        "LastAskRate",
-        "LastBidRate",
-        "SettlementRate",
+        "CloseAskRate",
+        "CloseBidRate",
+        "CloseRate",
     ]
     return df[ordered_cols]
 
 
-def fetch_di(trade_date: pd.Timestamp, return_raw: bool = False) -> pd.DataFrame:
+def _process_last_raw_di_df(raw_df: pd.DataFrame) -> pd.DataFrame:
+    df = raw_df.copy()
+
+    # Columns to be renamed
+    rename_columns = {
+        "TradeTimestamp": "TradeTimestamp",
+        "symb": "TickerSymbol",
+        "mtrtyCode": "ExpirationDate",
+        "BDaysToExp": "BDaysToExp",
+        "opnCtrcts": "OpenContracts",
+        "tradQty": "TradeCount",
+        "traddCtrctsQty": "TradeVolume",
+        "grssAmt": "FinancialVolume",
+        "prvsDayAdjstmntPric": "PrevSettlementRate",
+        "bottomLmtPric": "MinLimitRate",
+        "topLmtPric": "MaxLimitRate",
+        "opngPric": "OpenRate",
+        "minPric": "MinRate",
+        "avrgPric": "AvgRate",
+        "maxPric": "MaxRate",
+        "buyOffer.price": "LastAskRate",
+        "sellOffer.price": "LastBidRate",
+        "curPrc": "LastRate",
+    }
+    # Rename columns
+    df = df.rename(columns=rename_columns)
+
+    df["BDaysToExp"] = bday.count_bdays(df["TradeTimestamp"], df["ExpirationDate"])
+
+    # Remove percentage in all rate columns
+    rate_cols = [col for col in df.columns if "Rate" in col]
+    df[rate_cols] = df[rate_cols] / 100
+
+    # Reorder columns based on the order of the dictionary
+    return df[rename_columns.values()]
+
+
+def fetch_last_di() -> pd.DataFrame:
+    """
+    Fetch the latest DI futures data from B3.
+
+    Returns:
+        pd.DataFrame: A Pandas pd.DataFrame containing the latest DI futures data.
+    """
+    raw_df = common.fetch_last_raw_df(future_code="DI1")
+    return _process_last_raw_di_df(raw_df)
+
+
+def fetch_past_di(trade_date: pd.Timestamp, return_raw: bool = False) -> pd.DataFrame:
     """
     Fetchs the DI futures data for a given date from B3.
 
@@ -165,15 +214,11 @@ def fetch_di(trade_date: pd.Timestamp, return_raw: bool = False) -> pd.DataFrame
     Returns:
         pd.DataFrame: A Pandas pd.DataFrame containing processed DI futures data.
 
-    Examples:
-        >>> from pyield.futures import di
-        >>> di.fetch_di(pd.Timestamp("2021-01-04"))
-
     Notes:
-        - BDaysToExpiration: number of business days to ExpirationDate.
+        - BDaysToExp: 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="DI1", trade_date=trade_date)
+    df_raw = common.fetch_past_raw_df(asset_code="DI1", trade_date=trade_date)
     if return_raw:
         return df_raw
-    return _process_raw_df(df_raw, trade_date)
+    return _process_past_raw_df(df_raw, trade_date)

{pyield-0.7.2 → pyield-0.7.4}/pyield/futures/di_xml.py

@@ -194,7 +194,7 @@ def _standardize_column_names(df: DataFrame) -> DataFrame:
         # "MktDataStrmId"
         # "IntlFinVol",
         "OpnIntrst": "OpenContracts",
-        "FinInstrmQty": "TradedQuantity",
+        "FinInstrmQty": "TradeVolume",
         "NtlFinVol": "FinancialVolume",
         "AdjstdQt": "SettlementPrice",
         "MinTradLmt": "MinTradeLimitRate",
@@ -233,13 +233,13 @@ def _process_di_df(df_raw: DataFrame) -> DataFrame:
     df.insert(2, "ExpirationDate", expiration)
 
     business_days = bday.count_bdays(df["TradDt"], df["ExpirationDate"])
-    df.insert(3, "BDaysToExpiration", business_days)
+    df.insert(3, "BDaysToExp", business_days)
 
     # Convert to nullable integer, since other columns use this data type
-    df["BDaysToExpiration"] = df["BDaysToExpiration"].astype(pd.Int64Dtype())
+    df["BDaysToExp"] = df["BDaysToExp"].astype(pd.Int64Dtype())
 
     # Remove expired contracts
-    df.query("BDaysToExpiration > 0", inplace=True)
+    df.query("BDaysToExp > 0", inplace=True)
 
     return df.sort_values(by=["ExpirationDate"], ignore_index=True)
 

pyield-0.7.4/pyield/futures/frc.py

@@ -0,0 +1,94 @@
+import pandas as pd
+
+from . import common
+
+
+def _process_past_data(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",
+        "NÚM. NEGOC.": "TradeCount",
+        "CONTR. NEGOC.": "TradeVolume",
+        "VOL.": "FinancialVolume",
+        "AJUSTE  DE REF.": "SettlementRate",
+        "PREÇO ABERTU.": "FirstRate",
+        "PREÇO MÍN.": "MinRate",
+        "PREÇO MÉD.": "AvgRate",
+        "PREÇO MÁX.": "MaxRate",
+        "ÚLT. PREÇO": "CloseRate",
+        "VAR. PTOS.": "PointsVariation",
+        # Attention: bid/ask rates are inverted
+        "ÚLT.OF. COMPRA": "CloseAskRate",
+        "ÚLT.OF. VENDA": "CloseBidRate",
+    }
+
+    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]")
+
+    df["ExpirationDate"] = df["ExpirationCode"].apply(common.get_expiration_date)
+
+    # Replace 0 values in rate columns with pd.NA and remove percentage
+    rate_cols = [col for col in df.columns if "Rate" in col]
+    for col in rate_cols:
+        df[col] = df[col].replace(0, pd.NA)
+        # Round to 5 decimal places (3 in %) since it is the contract's precision
+        df[col] = (df[col] / 100).round(5)
+
+    df["TickerSymbol"] = "FRC" + df["ExpirationCode"]
+
+    # Filter and order columns
+    ordered_cols = [
+        "TradeDate",
+        "TickerSymbol",
+        # "ExpirationCode",
+        "ExpirationDate",
+        "TradeCount",
+        "TradeVolume",
+        "FinancialVolume",
+        "SettlementRate",
+        "FirstRate",
+        "MinRate",
+        "AvgRate",
+        "MaxRate",
+        "CloseAskRate",
+        "CloseBidRate",
+        "CloseRate",
+    ]
+    return df[ordered_cols]
+
+
+def fetch_past_frc(trade_date: pd.Timestamp, return_raw: bool = False) -> pd.DataFrame:
+    """
+    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 (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.
+    """
+    df_raw = common.fetch_past_raw_df(asset_code="FRC", trade_date=trade_date)
+    if return_raw:
+        return df_raw
+    return _process_past_data(df_raw, trade_date)

{pyield-0.7.2 → pyield-0.7.4}/pyield/indicators.py

@@ -41,7 +41,7 @@ def fetch_ipca_mr(reference_date: pd.Timestamp) -> float | None:
     # 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)
+        return round(float(ipca_str) / 100, 4)
     else:
         return None
 
@@ -52,8 +52,62 @@ def fetch_selic_target(reference_date: pd.Timestamp) -> float | None:
     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"])
+
+    if selic_date in response.text:
+        data = response.json()
+        return round(float(data[0]["valor"]) / 100, 4)
     else:
         return None
+
+
+def fetch_di(reference_date: pd.Timestamp) -> float | None:
+    # https://api.bcb.gov.br/dados/serie/bcdata.sgs.11/dados?formato=json&dataInicial=12/04/2024&dataFinal=12/04/2024
+    di_date = reference_date.strftime("%d/%m/%Y")
+    api_url = f"https://api.bcb.gov.br/dados/serie/bcdata.sgs.11/dados?formato=json&dataInicial={di_date}&dataFinal={di_date}"
+    response = requests.get(api_url)
+    response.raise_for_status()
+
+    if di_date in response.text:
+        data = response.json()
+        return round(float(data[0]["valor"]) / 100, 8)
+    else:
+        return None
+
+
+def fetch_vna_selic(reference_date: pd.Timestamp) -> float | None:
+    # url example: https://www3.bcb.gov.br/novoselic/rest/arquivosDiarios/pub/download/3/20240418APC238
+
+    url_base = "https://www3.bcb.gov.br/novoselic/rest/arquivosDiarios/pub/download/3/"
+    url_file = f"{reference_date.strftime("%Y%m%d")}APC238"
+    url_vna = url_base + url_file
+    response = requests.get(url_vna)
+    response.raise_for_status()
+    file_text = response.text
+
+    # Finding the part that contains the table
+    start_of_table = file_text.find("EMISSAO")
+    end_of_table = file_text.find("99999999*")
+
+    # Extracting the table
+    table_text = file_text[start_of_table:end_of_table].strip()
+    table_lines = table_text.splitlines()
+
+    # Remove empty lines
+    table_lines = [line.strip() for line in table_lines if line.strip()]
+
+    # Remove first line
+    body_lines = table_lines[1:]
+
+    vnas = []
+    for line in body_lines:
+        vna_str = line.split()[-1].replace(",", ".")
+        vna_float = float(vna_str)
+        vnas.append(vna_float)
+
+    # Raise error if all values are not the same
+    vna_value = vnas[0]
+    if any(vna_value != vna for vna in vnas):
+        bcb_url = "https://www.bcb.gov.br/estabilidadefinanceira/selicbaixar"
+        raise ValueError(f"VNA values are not the same. Please check data at {bcb_url}")
+
+    return vna_value

pyield-0.7.4/pyield/projections.py

@@ -0,0 +1,87 @@
+import io
+import locale
+from dataclasses import dataclass
+
+import pandas as pd
+import python_calamine as pc
+import requests
+
+
+@dataclass
+class IndicatorProjection:
+    last_updated: pd.Timestamp  # Date and time of the last update
+    reference_month_ts: pd.Timestamp  # Timestamp to which the projection applies
+    reference_month_br: str  # Brazilian formatted month (e.g., "ABR/2024")
+    projected_value: float  # Projected value
+
+
+def fetch_current_month_ipca_projection() -> IndicatorProjection:
+    """
+    Fetches the current month's IPCA projection from the ANBIMA website and returns it
+    as an IndicatorProjection instance.
+
+    This function retrieves and parses the Excel file that contains economic indicators,
+    specifically looking for the IPCA projection. It extracts the date of the last
+    update and the IPCA projection for the reference month.
+
+    Args:
+        None
+
+    Returns:
+        IndicatorProjection: An instance of IndicatorProjection containing:
+            - last_updated (pd.Timestamp): The datetime when the data was last updated.
+            - reference_month_ts (pd.Timestamp): The month to which the IPCA projection
+              applies.
+            - reference_month_br (str): The formatted month as a string
+              (e.g., "ABR/2024") using the pt_BR locale.
+            - projected_value (float): The projected IPCA value.
+
+    Example:
+        >>> projection = fetch_current_month_ipca_projection()
+        >>> print(projection)
+        IndicatorProjection(
+            last_updated=pd.Timestamp('2024-04-19 18:55:00'),
+            reference_month_ts=pd.Timestamp('2024-04-01 00:00:00'),
+            reference_month_br='ABR/2024',
+            projected_value=0.35
+        )
+
+    Data file format example after parsing:
+        - ['Data e Hora da Última Atualização: 19/04/2024 - 18:55 h', '', '']
+        - ...
+        - ['IPCA1', 'Projeção (abr/24)', 0.35]
+        - ...
+    """
+    # Define the URL and get the data
+    url = "https://www.anbima.com.br/informacoes/indicadores/arqs/indicadores.xls"
+    response = requests.get(url)
+    excel_data = io.BytesIO(response.content)
+
+    # Load the workbook and select the first sheet
+    workbook = pc.load_workbook(excel_data)
+    first_sheet = workbook.sheet_names[0]
+    data = workbook.get_sheet_by_name(first_sheet).to_python(skip_empty_area=True)
+
+    # Extract projection update date and time from the first row
+    last_update_str = data[0][0].split("Atualização:")[-1].strip()
+    last_updated = pd.to_datetime(last_update_str, format="%d/%m/%Y - %H:%M h")
+
+    # Find the row containing the IPCA projection and extract its data
+    ipca_data = next(line for line in data if "IPCA1" in line)
+
+    # Convert the last element of the IPCA data row to float for the projection value
+    ipca_value = round(float(ipca_data[-1]) / 100, 4)
+
+    # Extract and format the reference month
+    month_text = ipca_data[1].split("(")[-1].split(")")[0]
+    locale.setlocale(locale.LC_TIME, "pt_BR.UTF-8")
+    ipca_month_ts = pd.to_datetime(month_text, format="%b/%y")
+    ipca_month_br = ipca_month_ts.strftime("%b/%Y").upper()
+    locale.setlocale(locale.LC_TIME, "")  # Reset locale to default
+
+    return IndicatorProjection(
+        last_updated=last_updated,
+        reference_month_ts=ipca_month_ts,
+        reference_month_br=ipca_month_br,
+        projected_value=ipca_value,
+    )

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

@@ -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 = ft.fetch_di(reference_date)[["ExpirationDate", "SettlementRate"]]
+    df_di = ft.fetch_past_di(reference_date)[["ExpirationDate", "SettlementRate"]]
 
     # Renaming the columns to match the ANBIMA structure
     df_di.rename(columns={"ExpirationDate": "MaturityDate"}, inplace=True)

{pyield-0.7.2 → pyield-0.7.4}/pyield/utils.py

@@ -3,10 +3,10 @@ import pandas as pd
 from . import bday
 
 
-def _normalize_date(reference_date: str | pd.Timestamp | None = None) -> pd.Timestamp:
+def _normalize_date(input_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.
+    date is provided, it defaults to the last business day.
 
     Args:
         reference_date (str | pd.Timestamp | None): The date to normalize. Can be a
@@ -31,25 +31,25 @@ def _normalize_date(reference_date: str | pd.Timestamp | None = None) -> pd.Time
         >>> _normalize_date(pd.Timestamp('2023-04-01 15:30'))
         >>> _normalize_date()
     """
-    if isinstance(reference_date, str):
+    if isinstance(input_date, str):
         # Convert string date to Timestamp and normalize to midnight
-        normalized_date = pd.Timestamp(reference_date).normalize()
-    elif isinstance(reference_date, pd.Timestamp):
+        normalized_date = pd.Timestamp(input_date).normalize()
+    elif isinstance(input_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
+        normalized_date = input_date.normalize()
+    elif input_date is None:
+        # If no date is provided, use the last available business day
         today = pd.Timestamp.today().normalize()
-        normalized_date = bday.offset_bdays(today, -1)
+        normalized_date = bday.offset_bdays(dates=today, offset=0, roll="backward")
     else:
-        raise ValueError("Invalid date format.")
+        raise ValueError(f"Date format not recognized: {input_date}")
 
+    error_date = normalized_date.strftime("%d-%m-%Y")
     # 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.")
-
+        raise ValueError(f"Date {error_date} is 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.")
+        raise ValueError(f"Date {error_date} is not a business day")
 
     return normalized_date

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

@@ -29,9 +29,10 @@ dependencies = [
     "beautifulsoup4",
     "html5lib",
     "lxml",
+    "python-calamine>=0.2.0",
 ]
 dynamic = []
-version = "0.7.2"
+version = "0.7.4"
 
 [project.license]
 file = "LICENSE"

{pyield-0.7.2 → pyield-0.7.4}/tests/test_futures.py

@@ -37,46 +37,44 @@ def test_new_contract_code():
 
 def test_settlement_rate_with_old_holiday_list():
     settlement_rates = {
-        "N27": 0.09809,
-        "F33": 0.10368,
+        "DI1N27": 0.09809,
+        "DI1F33": 0.10368,
     }
 
     # 22-12-2023 is before the new holiday calendar
     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()
+    df = ft.fetch_past_di(trade_date=test_date)
+    tickers = list(settlement_rates.keys())  # noqa: F841
+    result = df.query("TickerSymbol in @tickers")["SettlementRate"].to_list()
     assert result == list(settlement_rates.values())
 
 
 def test_settlement_rates_with_current_holiday_list():
     settlement_rates = {
-        "F24": 0.11644,
-        "J24": 0.11300,
-        "N24": 0.10786,
-        "V24": 0.10321,
-        "F25": 0.10031,
-        "J25": 0.09852,
-        "N25": 0.09715,
-        "V25": 0.09651,
-        "F26": 0.09583,
-        "N26": 0.09631,
-        "F27": 0.09683,
-        "N27": 0.09794,
-        "F29": 0.10042,
-        "F31": 0.10240,
-        "F33": 0.10331,
+        "DI1F24": 0.11644,
+        "DI1J24": 0.11300,
+        "DI1N24": 0.10786,
+        "DI1V24": 0.10321,
+        "DI1F25": 0.10031,
+        "DI1J25": 0.09852,
+        "DI1N25": 0.09715,
+        "DI1V25": 0.09651,
+        "DI1F26": 0.09583,
+        "DI1N26": 0.09631,
+        "DI1F27": 0.09683,
+        "DI1N27": 0.09794,
+        "DI1F29": 0.10042,
+        "DI1F31": 0.10240,
+        "DI1F33": 0.10331,
     }
     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"
-    ].to_list()
+    df = ft.fetch_past_di(trade_date=test_date)
+    tickers = list(settlement_rates.keys())  # noqa: F841
+    results = df.query("TickerSymbol in @tickers")["SettlementRate"].to_list()
     assert results == list(settlement_rates.values())
 
 
 def test_non_business_day():
     non_business_day = pd.Timestamp("2023-12-24")
     with pytest.raises(ValueError):
-        ft.fetch_di(trade_date=non_business_day)
+        ft.fetch_past_di(trade_date=non_business_day)

pyield-0.7.2/pyield/__about__.py

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

pyield-0.7.2/pyield/data_access.py

@@ -1,89 +0,0 @@
-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.2/pyield/futures/__init__.py

@@ -1,10 +0,0 @@
-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",
-]