PYield 0.7.6__tar.gz → 0.7.8__tar.gz

{pyield-0.7.6 → pyield-0.7.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: PYield
-Version: 0.7.6
+Version: 0.7.8
 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>
@@ -32,13 +32,13 @@ Classifier: Intended Audience :: Financial and Insurance Industry
 Classifier: Topic :: Office/Business :: Financial :: Investment
 Project-URL: Source, https://github.com/crdcj/PYield
 Requires-Python: >=3.11
-Requires-Dist: requests
 Requires-Dist: pandas>=2.0.0
 Requires-Dist: numpy
 Requires-Dist: beautifulsoup4
 Requires-Dist: html5lib
 Requires-Dist: lxml
 Requires-Dist: python-calamine>=0.2.0
+Requires-Dist: requests>=2.31.0
 Description-Content-Type: text/markdown
 
 [![PyPI version](https://img.shields.io/pypi/v/pyield.svg)](https://pypi.python.org/pypi/pyield)
@@ -101,7 +101,7 @@ dtype: datetime64[ns]
 ```python
 # Fetch current DI Futures data from B3 (15 minutes delay)
 >>> yd.fetch_asset(asset_code="DI1")
-TradeTimestamp      TickerSymbol ExpirationDate BDaysToExp ... MaxRate LastAskRate LastBidRate LastRate
+TradeTimestamp      TickerSymbol ExpirationDate BDaysToExp ... MaxRate LastAskRate LastBidRate CurrentRate
 2024-04-21 13:37:39       DI1K24     2024-05-02          7 ... 0.10660     0.10652     0.10660  0.10660
 2024-04-21 13:37:39       DI1M24     2024-06-03         28 ... 0.10518     0.10510     0.10516  0.10518
 2024-04-21 13:37:39       DI1N24     2024-07-01         48 ... 0.10480     0.10456     0.10462  0.10460
@@ -158,11 +158,11 @@ BondType ReferenceDate MaturityDate  DISpread
 ```python
 # Fetch the SELIC target rate from the Central Bank of Brazil
 >>> yd.fetch_indicator(indicator_code="SELIC", reference_date='2024-04-12')
-10.75
+0.1075  # 10.75%
 
 # Fetch the IPCA monthly inflation rate from IBGE
 >>> yd.fetch_indicator(indicator_code="IPCA", reference_date='2024-03-18')
-0.16
+0.16  # 0.16%
 
 # If no data is yet available for the indicator, the function returns None
 >>> yd.fetch_indicator(indicator_code="IPCA", reference_date='2024-04-10')
@@ -178,9 +178,9 @@ IndicatorProjection(
     last_updated=Timestamp('2024-04-19 18:55:00'),
     reference_month_ts=Timestamp('2024-04-01 00:00:00'),
     reference_month_br='ABR/2024',
-    projected_value=0.0035
+    projected_value=0.0035  # 0.35%
 )
 >>> ipca.projected_value
-0.0035
+0.0035  # 0.35%
 ```
 

{pyield-0.7.6 → pyield-0.7.8}/README.md

@@ -58,7 +58,7 @@ dtype: datetime64[ns]
 ```python
 # Fetch current DI Futures data from B3 (15 minutes delay)
 >>> yd.fetch_asset(asset_code="DI1")
-TradeTimestamp      TickerSymbol ExpirationDate BDaysToExp ... MaxRate LastAskRate LastBidRate LastRate
+TradeTimestamp      TickerSymbol ExpirationDate BDaysToExp ... MaxRate LastAskRate LastBidRate CurrentRate
 2024-04-21 13:37:39       DI1K24     2024-05-02          7 ... 0.10660     0.10652     0.10660  0.10660
 2024-04-21 13:37:39       DI1M24     2024-06-03         28 ... 0.10518     0.10510     0.10516  0.10518
 2024-04-21 13:37:39       DI1N24     2024-07-01         48 ... 0.10480     0.10456     0.10462  0.10460
@@ -115,11 +115,11 @@ BondType ReferenceDate MaturityDate  DISpread
 ```python
 # Fetch the SELIC target rate from the Central Bank of Brazil
 >>> yd.fetch_indicator(indicator_code="SELIC", reference_date='2024-04-12')
-10.75
+0.1075  # 10.75%
 
 # Fetch the IPCA monthly inflation rate from IBGE
 >>> yd.fetch_indicator(indicator_code="IPCA", reference_date='2024-03-18')
-0.16
+0.16  # 0.16%
 
 # If no data is yet available for the indicator, the function returns None
 >>> yd.fetch_indicator(indicator_code="IPCA", reference_date='2024-04-10')
@@ -135,9 +135,9 @@ IndicatorProjection(
     last_updated=Timestamp('2024-04-19 18:55:00'),
     reference_month_ts=Timestamp('2024-04-01 00:00:00'),
     reference_month_br='ABR/2024',
-    projected_value=0.0035
+    projected_value=0.0035  # 0.35%
 )
 >>> ipca.projected_value
-0.0035
+0.0035  # 0.35%
 ```
 

pyield-0.7.8/pyield/__about__.py

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

{pyield-0.7.6 → pyield-0.7.8}/pyield/data_access.py

@@ -1,9 +1,10 @@
 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 .futures import historical as fh
+from .futures import intraday as fi
 from .utils import _normalize_date
 
 
@@ -24,6 +25,7 @@ def fetch_asset(
             - "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.
+            - "DAP": DI x IPCA Spread Futures
         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:
@@ -43,24 +45,30 @@ def fetch_asset(
     return_raw = kwargs.get("return_raw", False)
     normalized_date = _normalize_date(reference_date)
 
+    today = pd.Timestamp.today().normalize()
+    if normalized_date == today:
+        return fi.fetch_intraday(future_code=asset_code.upper())
+
     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"]:
+
+    if 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.")
+    if asset_code.lower() == "di1":
+        return fh.fetch_di(trade_date=normalized_date, return_raw=return_raw)
+
+    if asset_code.lower() == "ddi":
+        return fh.fetch_ddi(trade_date=normalized_date, return_raw=return_raw)
+
+    if asset_code.lower() == "frc":
+        return fh.fetch_frc(trade_date=normalized_date, return_raw=return_raw)
+
+    if asset_code.lower() == "dap":
+        return fh.fetch_dap(trade_date=normalized_date, return_raw=return_raw)
+
+    raise ValueError("Asset type not supported.")
 
 
 def fetch_indicator(
@@ -111,7 +119,7 @@ def fetch_indicator(
         raise ValueError("Indicator type not supported.")
 
 
-def fetch_projection(projection_code: str) -> dict:
+def fetch_projection(projection_code: str) -> pr.IndicatorProjection:
     """
     Fetches a financial projection for a specified code and reference date.
 

pyield-0.7.8/pyield/futures/historical/__init__.py

@@ -0,0 +1,6 @@
+from .dap import fetch_dap
+from .ddi import fetch_ddi
+from .di import fetch_di
+from .frc import fetch_frc
+
+__all__ = ["fetch_di", "fetch_ddi", "fetch_frc", "fetch_dap"]

{pyield-0.7.6/pyield/futures → pyield-0.7.8/pyield/futures/historical}/common.py

@@ -3,7 +3,7 @@ import io
 import pandas as pd
 import requests
 
-from .. import bday
+from ... import bday
 
 
 def get_expiration_date(expiration_code: str) -> pd.Timestamp:
@@ -131,7 +131,28 @@ def get_old_expiration_date(
         return pd.NaT  # type: ignore
 
 
-def fetch_past_raw_df(asset_code: str, trade_date: pd.Timestamp) -> pd.DataFrame:
+def convert_prices_to_rates(
+    prices: pd.Series, days_to_expiration: pd.Series, count_convention: int
+) -> pd.Series:
+    """
+    Internal function to convert DI futures prices to rates.
+
+    Args:
+        prices (pd.Series): The futures prices to be converted.
+        days_to_expiration (pd.Series): The number of days to expiration for each price.
+        count_convention (int): The count convention for the DI futures contract.
+            Normally, it is 252 business days or 360 calendar days.
+
+    Returns:
+        pd.Series: A pd.Series containing the futures rates.
+    """
+    rates = (100_000 / prices) ** (count_convention / days_to_expiration) - 1
+
+    # Round to 5 (3 in %) dec. places (contract's current max. precision)
+    return rates.round(5)
+
+
+def fetch_raw_df(asset_code: str, trade_date: pd.Timestamp) -> pd.DataFrame:
     """
     Fetch the historical futures data from B3 for a specific trade date. If the data is
     not available, an empty DataFrame is returned.
@@ -177,54 +198,84 @@ def fetch_past_raw_df(asset_code: str, trade_date: pd.Timestamp) -> pd.DataFrame
     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}"
+def rename_columns(df: pd.DataFrame) -> pd.DataFrame:
+    all_columns = {
+        "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.": "TradeCount",
+        "CONTR. NEGOC.": "TradeVolume",
+        "VOL.": "FinancialVolume",
+        "AJUSTE": "SettlementPrice",
+        "AJUSTE ANTER. (3)": "PrevSettlementRate",
+        "AJUSTE CORRIG. (4)": "AdjSettlementRate",
+        "AJUSTE  DE REF.": "SettlementRate",  # FRC
+        "PREÇO MÍN.": "MinRate",
+        "PREÇO MÉD.": "AvgRate",
+        "PREÇO MÁX.": "MaxRate",
+        "PREÇO ABERTU.": "FirstRate",
+        "ÚLT. PREÇO": "CloseRate",
+        "VAR. PTOS.": "PointsVariation",
+        # Attention: bid/ask rates are inverted
+        "ÚLT.OF. COMPRA": "CloseAskRate",
+        "ÚLT.OF. VENDA": "CloseBidRate",
+    }
+    rename_dict = {c: all_columns[c] for c in all_columns if c in df.columns}
+    return df.rename(columns=rename_dict)
 
-    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
+def process_raw_df(
+    df: pd.DataFrame, trade_date: pd.Timestamp, asset_code: str
+) -> pd.DataFrame:
+    df = rename_columns(df)
 
-    # Normalize JSON response into a flat table
-    df = pd.json_normalize(r.json()["Scty"])
+    df["TradeDate"] = trade_date
+    # Convert to datetime64[ns] since it is pandas default type for timestamps
+    df["TradeDate"] = df["TradeDate"].astype("datetime64[ns]")
 
-    # 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)
+    df["TickerSymbol"] = asset_code + df["ExpirationCode"]
 
-    # 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)
+    # 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,)
+        )
+    else:
+        df["ExpirationDate"] = df["ExpirationCode"].apply(get_expiration_date)
 
-    # Sort the DataFrame by maturity code and reset the index
-    df.sort_values("mtrtyCode", inplace=True, ignore_index=True)
+    # Columns where 0 means NaN
+    cols_with_nan = [col for col in df.columns if "Rate" in col]
+    if "SettlementPrice" in df.columns:
+        cols_with_nan.append("SettlementPrice")
+    # Replace 0 with NaN in these columns
+    df[cols_with_nan] = df[cols_with_nan].replace(0, pd.NA)
 
-    # 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
+    return df
 
-    # Convert DataFrame to use nullable data types for better type consistency
-    df = df.convert_dtypes(dtype_backend="numpy_nullable")
 
-    return df
+def reorder_columns(df: pd.DataFrame):
+    all_columns = [
+        "TradeDate",
+        "TickerSymbol",
+        # "ExpirationCode",
+        "ExpirationDate",
+        "BDaysToExp",
+        "DaysToExp",
+        "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
+        "TradeCount",
+        "TradeVolume",
+        "FinancialVolume",
+        "SettlementPrice",
+        "SettlementRate",
+        "FirstRate",
+        "MinRate",
+        "AvgRate",
+        "MaxRate",
+        "CloseAskRate",
+        "CloseBidRate",
+        "CloseRate",
+    ]
+    reordered_columns = [col for col in all_columns if col in df.columns]
+    return df[reordered_columns]

pyield-0.7.8/pyield/futures/historical/dap.py

@@ -0,0 +1,62 @@
+import pandas as pd
+
+from ... import bday as bd
+from . import common as cm
+
+
+def _process_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.
+    """
+    df["BDaysToExp"] = bd.count_bdays(trade_date, df["ExpirationDate"])
+
+    # Remove expired contracts
+    df.query("BDaysToExp > 0", inplace=True)
+
+    rate_cols = [col for col in df.columns if "Rate" in col]
+    # Remove % and round to 5 (3 in %) dec. places in rate columns
+    df[rate_cols] = df[rate_cols].div(100).round(5)
+
+    # Calculate SettlementRate
+    df["SettlementRate"] = cm.convert_prices_to_rates(
+        prices=df["SettlementPrice"],
+        days_to_expiration=df["BDaysToExp"],
+        count_convention=252,
+    )
+
+    return df
+
+
+def fetch_dap(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. If the data
+    is not available, an empty DataFrame is returned.
+
+    Args:
+        trade_date (pd.Timestamp): The trade date to fetch the DI futures data.
+        return_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.
+
+    Notes:
+        - BDaysToExp: number of business days to ExpirationDate.
+        - OpenContracts: number of open contracts at the start of the trading day.
+    """
+    df_raw = cm.fetch_raw_df(asset_code="DI1", trade_date=trade_date)
+    if return_raw or df_raw.empty:
+        return df_raw
+    df = cm.process_raw_df(df_raw, trade_date, asset_code="DI1")
+    df = _process_df(df, trade_date)
+    return cm.reorder_columns(df)

pyield-0.7.8/pyield/futures/historical/ddi.py

@@ -0,0 +1,80 @@
+import pandas as pd
+
+from . import common as cm
+
+
+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)
+    # Round to 5 (3 in %) dec. places (contract's current max. precision)
+    return rates.round(5)
+
+
+def _process_ddi_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.
+    """
+    df["DaysToExp"] = (df["ExpirationDate"] - trade_date).dt.days
+    # Convert to nullable integer, since it is the default type in the library
+    df["DaysToExp"] = df["DaysToExp"].astype(pd.Int64Dtype())
+
+    # Remove expired contracts
+    df.query("DaysToExp > 0", inplace=True)
+
+    # Columns where 0 means NaN
+    rate_cols = [col for col in df.columns if "Rate" in col]
+    df[rate_cols] = df[rate_cols].div(100).round(5)
+
+    # Calculate SettlementRate
+    df["SettlementRate"] = _convert_prices_to_rates(
+        df["SettlementPrice"], df["DaysToExp"]
+    )
+
+    return df
+
+
+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:
+        - DaysToExp: number of business days to ExpirationDate.
+        - OpenContracts: number of open contracts at the start of the trading day.
+    """
+    df_raw = cm.fetch_raw_df(asset_code="DDI", trade_date=trade_date)
+    if return_raw or df_raw.empty:
+        return df_raw
+    df = cm.process_raw_df(df_raw, trade_date, asset_code="DDI")
+    df = _process_ddi_df(df, trade_date)
+    return cm.reorder_columns(df)

pyield-0.7.8/pyield/futures/historical/di.py

@@ -0,0 +1,91 @@
+import pandas as pd
+
+from ... import bday as bd
+from . import common as cm
+
+
+def _convert_prices_to_rates(prices: pd.Series, bd: pd.Series) -> pd.Series:
+    """
+    Internal function to convert DI futures prices to rates.
+
+    Args:
+        prices (pd.Series): A pd.Series containing DI futures prices.
+        bd (pd.Series): A serie containing the number of business days to expiration.
+
+    Returns:
+        pd.Series: A pd.Series containing DI futures rates.
+    """
+    rates = (100_000 / prices) ** (252 / bd) - 1
+
+    # Round to 5 (3 in %) dec. places (contract's current max. precision)
+    return rates.round(5)
+
+
+def _adjust_older_contracts_rates(df: pd.DataFrame, rate_cols: list) -> pd.DataFrame:
+    for col in rate_cols:
+        df[col] = _convert_prices_to_rates(df[col], df["BDaysToExp"])
+
+    # Invert low and high prices
+    df["MinRate"], df["MaxRate"] = df["MaxRate"], df["MinRate"]
+
+    return df
+
+
+def _process_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.
+    """
+    df["BDaysToExp"] = bd.count_bdays(trade_date, df["ExpirationDate"])
+
+    # Remove expired contracts
+    df.query("BDaysToExp > 0", inplace=True)
+
+    rate_cols = [col for col in df.columns if "Rate" in col]
+    # Prior to 17/01/2002 (inclusive), prices were not converted to rates
+    if trade_date > pd.Timestamp("2002-01-17"):
+        # Remove % and round to 5 (3 in %) dec. places in rate columns
+        df[rate_cols] = df[rate_cols].div(100).round(5)
+    else:
+        df = _adjust_older_contracts_rates(df, rate_cols)
+
+    # Calculate SettlementRate
+    df["SettlementRate"] = _convert_prices_to_rates(
+        df["SettlementPrice"], df["BDaysToExp"]
+    )
+
+    return df
+
+
+def fetch_di(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. If the data
+    is not available, an empty DataFrame is returned.
+
+    Args:
+        trade_date (pd.Timestamp): The trade date to fetch the DI futures data.
+        return_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.
+
+    Notes:
+        - BDaysToExp: number of business days to ExpirationDate.
+        - OpenContracts: number of open contracts at the start of the trading day.
+    """
+    df_raw = cm.fetch_raw_df(asset_code="DI1", trade_date=trade_date)
+    if return_raw or df_raw.empty:
+        return df_raw
+    df = cm.process_raw_df(df_raw, trade_date, asset_code="DI1")
+    df = _process_df(df, trade_date)
+    return cm.reorder_columns(df)

{pyield-0.7.6/pyield/futures → pyield-0.7.8/pyield/futures/historical}/di_xml.py

@@ -7,7 +7,7 @@ import requests
 from lxml import etree
 from pandas import DataFrame, Timestamp
 
-from .. import bday
+from ... import bday
 from . import common as cm
 
 
@@ -206,7 +206,7 @@ def _standardize_column_names(df: DataFrame) -> DataFrame:
         "TradAvrgPric": "AvgRate",
         "MaxPric": "MaxRate",
         "FrstPric": "FirstRate",
-        "LastPric": "LastRate",
+        "LastPric": "CloseRate",
         "AdjstdQtTax": "SettlementRate",
         # "RglrTxsQty"
         # "RglrTraddCtrcts"

pyield-0.7.8/pyield/futures/historical/frc.py

@@ -0,0 +1,60 @@
+import pandas as pd
+
+from . import common as cm
+
+
+def _process_frc_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.
+    """
+    df = cm.rename_columns(df)
+
+    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(
+            cm.get_old_expiration_date, args=(trade_date,)
+        )
+    else:
+        df["ExpirationDate"] = df["ExpirationCode"].apply(cm.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]
+    # Round to 5 decimal places (3 in %) since it is the contract's precision
+    df[rate_cols] = df[rate_cols].replace(0, pd.NA).div(100).round(5)
+
+    return df
+
+
+def fetch_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 = cm.fetch_raw_df(asset_code="FRC", trade_date=trade_date)
+    if return_raw or df_raw.empty:
+        return df_raw
+    # Filter and order columns
+    df = cm.process_raw_df(df_raw, trade_date, asset_code="FRC")
+    df = _process_frc_df(df, trade_date)
+    return cm.reorder_columns(df)

pyield-0.7.8/pyield/futures/intraday/__init__.py

@@ -0,0 +1,3 @@
+from .trading_data import fetch_intraday
+
+__all__ = ["fetch_intraday"]