PYield 0.34.2__tar.gz → 0.35.1__tar.gz

{pyield-0.34.2 → pyield-0.35.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: PYield
-Version: 0.34.2
+Version: 0.35.1
 Summary: A Python library for analysis of fixed income instruments in Brazil
 Project-URL: Source, https://github.com/crdcj/PYield
 Author-email: Carlos Carvalho <cr.cj@outlook.com>

pyield-0.35.1/pyield/__about__.py

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

{pyield-0.34.2 → pyield-0.35.1}/pyield/__init__.py

@@ -2,7 +2,7 @@ import logging
 
 from pyield import anbima, b3, bc, bday, ibge
 from pyield.__about__ import __version__
-from pyield.b3 import dif, futures
+from pyield.b3 import di1, futures
 from pyield.fwd import forward, forwards
 from pyield.interpolator import Interpolator
 from pyield.tpf import lft, ltn, ntnb, ntnc, ntnf
@@ -11,7 +11,7 @@ __all__ = [
     "__version__",
     "anbima",
     "bday",
-    "dif",
+    "di1",
     "forwards",
     "forward",
     "futures",

{pyield-0.34.2 → pyield-0.35.1}/pyield/b3/__init__.py

@@ -1,9 +1,9 @@
-from pyield.b3 import dif
+from pyield.b3 import di1
 from pyield.b3.di_over import di_over
 from pyield.b3.futures import futures
 
 __all__ = [
     "di_over",
     "futures",
-    "dif",
+    "di1",
 ]

pyield-0.34.2/pyield/b3/dif.py → pyield-0.35.1/pyield/b3/di1.py

@@ -15,7 +15,7 @@ TIMEZONE_BZ = ZoneInfo("America/Sao_Paulo")
 
 
 def data(
-    date: DateScalar,
+    dates: DateScalar | DateArray,
     month_start: bool = False,
     pre_filter: bool = False,
     all_columns: bool = True,
@@ -27,9 +27,7 @@ def data(
     (to month start) and optional filtering based on LTN and NTN-F bond maturities.
 
     Args:
-        date (DateScalar): The trade date for which to retrieve DI contract data.
-            If the date is invalid, a holiday, in the future, or None, an empty
-            DataFrame is returned with appropriate logging.
+        dates (DateScalar): The trade dates for which to retrieve DI contract data.
         month_start (bool, optional): If True, adjusts all expiration dates to the
             first day of their respective month (e.g., 2025-02-01 becomes
             2025-01-01). Defaults to False.
@@ -43,12 +41,12 @@ def data(
 
     Returns:
         pd.DataFrame: A DataFrame containing the DI futures contract data for the
-            specified date, sorted by expiration date. Returns an empty DataFrame
-            if no data is found, the date is invalid, a holiday, or in the future.
+            specified dates, sorted by trade dates and expiration dates.
+            Returns an empty DataFrame if no data is found
 
     Examples:
-        >>> from pyield import dif
-        >>> df = dif.data(date="16-10-2024", month_start=True)
+        >>> from pyield import di1
+        >>> df = di1.data(dates="16-10-2024", month_start=True)
         >>> df.iloc[:5, :5]  # Show the first five rows and columns
            TradeDate ExpirationDate TickerSymbol  BDaysToExp  OpenContracts
         0 2024-10-16     2024-11-01       DI1X24          12        1744269
@@ -57,31 +55,25 @@ def data(
         3 2024-10-16     2025-02-01       DI1G25          74         279491
         4 2024-10-16     2025-03-01       DI1H25          94         344056
     """
-    if date:
-        date = dc.convert_input_dates(date)
-        bz_today = dt.now(TIMEZONE_BZ).date()
-        if date.date() > bz_today:
-            logger.warning(f"DI date ({date}) after current date {bz_today}")
-            logger.warning("Returning empty DataFrame.")
-            return pd.DataFrame()
-    else:
-        logger.info("No date specified. Returning empty DataFrame.")
-        return pd.DataFrame()
-    # Return an empty DataFrame if the trade date is a holiday
-    if not bday.is_business_day(date):
-        logger.warning("Specified date is not a business day.")
-        logger.warning("Returning empty DataFrame.")
-        return pd.DataFrame()
 
-    # Get historical data
-    df = get_cached_dataset("DI").query("TradeDate == @date").reset_index(drop=True)
+    dates = dc.convert_input_dates(dates)
+    # Force dates to be a Series for consistency
+    dates = pd.Series(dates) if isinstance(dates, pd.Timestamp) else dates
+    # Remove duplicates and sort dates
+    dates = dates.drop_duplicates().sort_values().reset_index(drop=True)
 
-    if df.empty:
-        logger.info("No historical data found. Trying real-time data.")
-        df = b3.futures(contract_code="DI1", date=date)
+    df = get_cached_dataset("DI").query("TradeDate in @dates").reset_index(drop=True)
+
+    today = dt.now(TIMEZONE_BZ)
+    last_bday = bday.last_business_day()
+    is_trading_day = today.date() == last_bday.date()
+    if is_trading_day and last_bday in df["TradeDate"]:
+        logger.info("Trying to get DI Futures data for today.")
+        df_intraday = b3.futures(contract_code="DI1", date=last_bday)
+        df = pd.concat([df, df_intraday]).reset_index(drop=True)
 
     if df.empty:
-        logger.warning("No DI Futures data found for the specified date.")
+        logger.warning("No DI Futures data found for the specified dates.")
         logger.warning("Returning empty DataFrame.")
         return pd.DataFrame()
 
@@ -92,24 +84,35 @@ def data(
         df_pre = (
             get_cached_dataset("TPF")
             .query("BondType in ['LTN', 'NTN-F']")
-            .reset_index(drop=True)[["ReferenceDate", "MaturityDate"]]
+            .drop_duplicates(subset=["ReferenceDate", "MaturityDate"])
+            .sort_values(["ReferenceDate", "MaturityDate"])
+            .reset_index(drop=True)[["ReferenceDate", "MaturityDate", "BondType"]]
         )
+        # Assure that the MaturityDate is a business day
+        df_pre["MaturityDate"] = bday.offset(df_pre["MaturityDate"], 0)
 
-        nearest_date = _find_nearest_date(date, df_pre["ReferenceDate"])
-        if nearest_date is pd.NaT:
-            logger.warning("No matching reference date found in TPF dataset.")
-            return pd.DataFrame()
+        # Rename columns for merging
+        df_pre = df_pre.rename(
+            columns={"ReferenceDate": "TradeDate", "MaturityDate": "ExpirationDate"}
+        )
+
+        df = pd.merge_asof(
+            df, df_pre, on="TradeDate", by="ExpirationDate", direction="backward"
+        )
 
-        # Filter the TPF dataset for the nearest reference date
-        pre_maturities = (
-            df_pre.query("ReferenceDate == @nearest_date")["MaturityDate"]
-            .drop_duplicates()
+        # BondType was used as flag to filter the maturities
+        df = (
+            df.query("BondType.notna()")
+            .drop(columns=["BondType"])
             .reset_index(drop=True)
         )
 
-        # Force the expirations to be a business day as DI contracts
-        pre_maturities = bday.offset(pre_maturities, 0)
-        df = df.query("ExpirationDate in @pre_maturities").reset_index(drop=True)
+        if df.empty:
+            logger.warning(
+                "No DI Futures data found for the specified dates after pre-filtering."
+                "Returning empty DataFrame."
+            )
+            return pd.DataFrame()
 
     if month_start:
         df["ExpirationDate"] = df["ExpirationDate"].dt.to_period("M").dt.to_timestamp()
@@ -139,33 +142,6 @@ def data(
     return df.sort_values(by=["TradeDate", "ExpirationDate"]).reset_index(drop=True)
 
 
-def _find_nearest_date(
-    target_date: pd.Timestamp, date_series: pd.Series
-) -> pd.Timestamp:
-    """Finds the date in a Series closest to the target date.
-
-    Args:
-        target_date (pd.Timestamp): The reference date.
-        date_series (pd.Series): A Series of dates to search within.
-
-    Returns:
-        pd.Timestamp: The date from `date_series` that is closest in time
-            to `target_date`. Returns pd.NaT if the series is empty or
-            target_date is None.
-    """
-    if date_series.empty or target_date is None:
-        return pd.NaT
-    # The result will be a Series of positive Timedeltas (durations)
-    abs_differences = (date_series - target_date).abs()
-
-    # Find the index of the minimum difference in the differences Series
-    # idxmin() returns the index label where the minimum value occurs
-    closest_index = abs_differences.idxmin()
-
-    # Use the found index to get the corresponding date from the original Series
-    return date_series.loc[closest_index]  # or date_series[closest_index]
-
-
 def interpolate_rates(
     dates: DateScalar | DateArray,
     expirations: DateScalar | DateArray,
@@ -230,11 +206,7 @@ def interpolate_rates(
     dfi["irate"] = dfi["irate"].astype("Float64")
 
     # Load DI rates dataset filtered by the provided reference dates
-    dfr = (
-        get_cached_dataset("DI")
-        .query("TradeDate in @dfi['tdate'].unique()")
-        .reset_index(drop=True)
-    )
+    dfr = data(dates=dates)
 
     # Return an empty DataFrame if no rates are found
     if dfr.empty:
@@ -295,17 +267,17 @@ def interpolate_rate(
                 - An interpolation calculation fails.
 
     Examples:
-        >>> from pyield import dif
+        >>> from pyield import di1
         >>> # Get rate for an existing contract expiration
-        >>> dif.interpolate_rate("25-04-2025", "01-01-2027")
+        >>> di1.interpolate_rate("25-04-2025", "01-01-2027")
         0.13901
 
         >>> # Get rate for a non-existing contract expiration
-        >>> dif.interpolate_rate("25-04-2025", "01-11-2027")
+        >>> di1.interpolate_rate("25-04-2025", "01-11-2027")
         0.13576348733268917
 
         >>> # Extrapolate rate for a future expiration date
-        >>> dif.interpolate_rate("25-04-2025", "01-01-2050", extrapolate=True)
+        >>> di1.interpolate_rate("25-04-2025", "01-01-2050", extrapolate=True)
         0.13881
     """
 
@@ -314,7 +286,7 @@ def interpolate_rate(
         return float("NaN")
 
     # Get the DI contract DataFrame
-    df = data(date=date)
+    df = data(dates=date)
 
     if df.empty:
         return float("NaN")
@@ -354,9 +326,9 @@ def eod_dates() -> pd.Series:
                    for which DI data is available.
 
     Examples:
-        >>> from pyield import dif
+        >>> from pyield import di1
         >>> # DI Futures series starts from 1995-01-02
-        >>> dif.eod_dates().head(5)
+        >>> di1.eod_dates().head(5)
         0   1995-01-02
         1   1995-01-03
         2   1995-01-04

{pyield-0.34.2 → pyield-0.35.1}/pyield/data_cache.py

@@ -5,6 +5,8 @@ from zoneinfo import ZoneInfo
 
 import pandas as pd
 
+from pyield.retry import default_retry
+
 # --- Configurações Centralizadas ---
 TIMEZONE_BZ = ZoneInfo("America/Sao_Paulo")
 
@@ -40,6 +42,12 @@ def _get_today_date_key():
     return datetime.now(TIMEZONE_BZ).strftime("%Y-%m-%d")
 
 
+@default_retry
+def _load_github_file(file_url: str) -> pd.DataFrame:
+    """Carrega um arquivo do GitHub e retorna um DataFrame."""
+    return pd.read_parquet(file_url)
+
+
 @functools.lru_cache(maxsize=len(DATASET_CONFIGS))
 def _get_dataset_with_ttl(dataset_id: str, date_key: str) -> pd.DataFrame:
     """Carrega o dataset a partir do ID e da chave de data. Cache expira diariamente."""
@@ -55,7 +63,7 @@ def _get_dataset_with_ttl(dataset_id: str, date_key: str) -> pd.DataFrame:
     full_url = f"{BASE_DATA_URL}/{filename}"
 
     try:
-        df = pd.read_parquet(full_url)
+        df = _load_github_file(full_url)
         last_date = df[date_column].max().date()
         logger.info(f"Dataset {dataset_name} carregado. Última data: {last_date}")
         return df.copy()

{pyield-0.34.2 → pyield-0.35.1}/pyield/retry.py

@@ -19,66 +19,65 @@ from tenacity import RetryCallState
 # --- Configuração do Logger ---
 logger = logging.getLogger(__name__)
 
-# --- Constantes ---
-DEFAULT_TIMEOUT = (2, 10)
-RETRYABLE_NETWORK_ERRORS = (URLError,)
-RETRYABLE_PARSING_ERRORS = (pd.errors.EmptyDataError, pd.errors.ParserError)
-
 
 # --- Funções Auxiliares para Tenacity ---
-
-
 def _log_before_sleep(retry_state: RetryCallState):
     """
     Loga uma mensagem ANTES de o Tenacity entrar em espera (sleep) entre tentativas.
-
-    Simplificada para confiar no contrato do Tenacity e usar asserções
-    para verificar o estado esperado.
     """
-    # 1. Verificar o resultado (outcome)
     outcome = retry_state.outcome
-    assert outcome is not None, "before_sleep chamada sem 'outcome'"
-    # Adicionado: Garantir que realmente falhou antes de logar como falha
-    assert outcome.failed, "before_sleep chamada para 'outcome' bem-sucedido"
+    if not outcome or not outcome.failed:
+        logger.debug(
+            "before_sleep chamada sem 'outcome' ou para 'outcome' bem-sucedido."
+        )
+        return
 
-    exception = outcome.exception
-    # Adicionado: Garantir que a exceção existe quando falhou
-    assert exception is not None, "before_sleep chamada sem 'exception' no outcome"
+    exception = outcome.exception()
+    if not exception:
+        logger.debug("before_sleep chamada sem 'exception' real no outcome.")
+        return
 
-    # 2. Verificar a próxima ação (next_action)
     next_action = retry_state.next_action
-    assert next_action is not None, "before_sleep chamada sem 'next_action'"
+    if not next_action or not hasattr(next_action, "sleep"):
+        logger.debug(
+            "before_sleep chamada sem 'next_action' ou 'sleep' em next_action."
+        )
+        return
 
-    # 3. Acessar a duração do sono (sleep)
-    # Confiamos que 'next_action' terá '.sleep' neste contexto, pois é antes de dormir.
     sleep_duration = next_action.sleep
 
-    # Log principal
     logger.warning(
         f"Tentativa {retry_state.attempt_number} falhou com "
-        f"{type(exception).__name__}: {exception}. Tentando novamente em "
+        f"{type(exception).__name__}: {str(exception)[:150]}. Tentando novamente em "
         f"{sleep_duration:.2f} segundos..."
     )
 
 
 def should_retry_exception(retry_state: RetryCallState) -> bool:
-    """Determina se uma exceção capturada justifica uma nova tentativa."""
+    """Determina se uma exceção capturada justifica uma nova tentativa"""
     if not retry_state.outcome or not retry_state.outcome.failed:
         return False
 
-    # Usar o atributo .exception
-    exception = retry_state.outcome.exception
-    assert exception is not None, (
-        "should_retry_exception processando um outcome sem exceção?"
-    )
+    exception = retry_state.outcome.exception()
+
+    if exception is None:
+        # Isso não deveria acontecer se outcome.failed é True.
+        logger.error(
+            "should_retry_exception: outcome.failed é True,"
+            "mas exception() retornou None."
+        )
+        return False
 
     attempt_number = retry_state.attempt_number
+    # getattr é mais seguro caso a exceção não tenha 'url'
     url = getattr(exception, "url", "N/A")
 
     retry_decision = False
-    log_message = ""
-    log_level = logging.ERROR
+    # Inicializar como None para evitar log default se nenhum case corresponder
+    log_message = None
+    log_level = logging.ERROR  # Default para não retentativa
 
+    # Usando match/case como originalmente preferido
     match exception:
         case HTTPError(code=404):
             log_message = (
@@ -88,6 +87,15 @@ def should_retry_exception(retry_state: RetryCallState) -> bool:
             retry_decision = False
             log_level = logging.INFO
 
+        case HTTPError(code=429):  # ADICIONADO: Tratamento para Too Many Requests
+            log_message = (
+                f"Tentativa {attempt_number}: Too Many Requests (429) da API em {url}. "
+                f"API pediu para aguardar. Tentando novamente."
+            )
+            retry_decision = True
+            log_level = logging.WARNING
+
+        # Gateway Timeout, primeira tentativa
         case HTTPError(code=504) if attempt_number == 1:
             log_message = (
                 f"Tentativa {attempt_number}: Gateway Timeout (504) da API em {url}. "
@@ -96,7 +104,7 @@ def should_retry_exception(retry_state: RetryCallState) -> bool:
             retry_decision = True
             log_level = logging.WARNING
 
-        case HTTPError(code=504):
+        case HTTPError(code=504):  # Gateway Timeout, tentativas subsequentes
             log_message = (
                 f"Tentativa {attempt_number}: Gateway Timeout (504) persistiu em {url}."
                 f"API parece indisponível. Desistindo."
@@ -104,41 +112,52 @@ def should_retry_exception(retry_state: RetryCallState) -> bool:
             retry_decision = False
             log_level = logging.ERROR
 
-        case HTTPError() as http_err:
+        case HTTPError() as http_err:  # Outros erros HTTP
+            # Esta regra genérica para HTTPError retentará outros códigos HTTP.
+            # Por exemplo, 500, 502, 503 (geralmente bom para retry)
+            # mas também 400, 401, 403 (geralmente não bom para retry).
+            # Se precisar de mais granularidade, adicione cases específicos acima deste.
             log_message = (
-                f"Tentativa {attempt_number}: Erro HTTP {http_err.code} encontrado "
-                f"para {url}. Pode ser transitório. Tentando novamente."
+                f"Tentativa {attempt_number}: Erro HTTP {http_err.code} "
+                f"({http_err.reason}) encontrado para {url}. "
+                "Pode ser transitório. Tentando novamente."
             )
             retry_decision = True
             log_level = logging.WARNING
 
+        # Erros de rede mais genéricos (e.g., DNS falhou, conexão recusada)
         case URLError():
             log_message = (
                 f"Tentativa {attempt_number}: Erro de rede recuperável "
-                f"({type(exception).__name__}). Tentando novamente."
+                f"({type(exception).__name__}: {str(exception)[:100]}) para {url}. "
+                f"Tentando novamente."
             )
             retry_decision = True
             log_level = logging.WARNING
 
+        # Usando o operador | para combinar tipos de exceção no case
         case pd.errors.EmptyDataError() | pd.errors.ParserError():
             log_message = (
-                f"Tentativa {attempt_number}: Erro de parsing "
+                f"Tentativa {attempt_number}: Erro de parsing de dados "
                 f"({type(exception).__name__}). Tentando novamente."
             )
             retry_decision = True
             log_level = logging.WARNING
 
-        case _:
+        case _:  # Exceção não mapeada/inesperada
+            # Mensagem para o log de exceção
             log_message_exc = (
                 f"Tentativa {attempt_number}: Erro não recuperável/inesperado "
-                f"({type(exception).__name__}). Desistindo."
+                f"({type(exception).__name__}: {str(exception)[:100]}) "
+                f"ao processar {url}. Desistindo."
             )
-            retry_decision = False
-            log_level = logging.ERROR
+            # Sempre incluir traceback para erros inesperados
             logger.exception(log_message_exc)
-            log_message = None
+            log_message = None  # Evita log duplicado pela seção logger.log abaixo
+            retry_decision = False
+            log_level = logging.ERROR  # Já é o default, mas explícito aqui
 
-    if log_message:
+    if log_message:  # Loga a mensagem formatada se uma foi definida
         logger.log(log_level, log_message)
 
     return retry_decision
@@ -147,8 +166,9 @@ def should_retry_exception(retry_state: RetryCallState) -> bool:
 # --- Decorador Tenacity Principal ---
 default_retry = tenacity.retry(
     retry=should_retry_exception,
+    # Backoff exponencial é bom para 429
     wait=tenacity.wait_exponential(multiplier=1, min=1, max=10),
     stop=(tenacity.stop_after_attempt(3) | tenacity.stop_after_delay(15)),
     before_sleep=_log_before_sleep,
-    reraise=True,
+    reraise=True,  # Importante para propagar o erro final se as tentativas falharem
 )

{pyield-0.34.2 → pyield-0.35.1}/pyield/tpf/ltn.py

@@ -2,7 +2,7 @@ import pandas as pd
 
 from pyield import anbima, bday
 from pyield import date_converter as dc
-from pyield.b3 import dif
+from pyield.b3 import di1
 from pyield.date_converter import DateScalar
 from pyield.tpf import tools
 
@@ -223,7 +223,7 @@ def historical_premium(
     ltn_rate = float(ltn_rates.iloc[0])
 
     # Retrieve DI rate for the reference date and maturity
-    di_rate = dif.interpolate_rate(date=date, expiration=maturity, extrapolate=True)
+    di_rate = di1.interpolate_rate(date=date, expiration=maturity, extrapolate=True)
     if pd.isnull(di_rate):  # Check if the DI rate is NaN
         return float("NaN")
 

{pyield-0.34.2 → pyield-0.35.1}/pyield/tpf/ntnb.py

@@ -463,7 +463,7 @@ def bei_rates(
 
         Get the DI Futures settlement rates for the same reference date to be used as
         reference for the nominal rates:
-        >>> df_di = yd.dif.data("05-09-2024")
+        >>> df_di = yd.di1.data("05-09-2024")
 
         Calculate the BEI rates considering the settlement at the reference date:
         >>> yd.ntnb.bei_rates(

{pyield-0.34.2 → pyield-0.35.1}/pyield/tpf/ntnf.py

@@ -6,7 +6,7 @@ import pandas as pd
 from pyield import anbima, bday
 from pyield import date_converter as dc
 from pyield import interpolator as ip
-from pyield.b3 import dif
+from pyield.b3 import di1
 from pyield.date_converter import DateScalar
 from pyield.tpf import tools
 
@@ -596,7 +596,7 @@ def historical_premium(
     df["BYears"] = df["BDToMat"] / 252
     df["ReferenceDate"] = date
 
-    df["DIRate"] = dif.interpolate_rates(
+    df["DIRate"] = di1.interpolate_rates(
         dates=df["ReferenceDate"],
         expirations=df["PaymentDate"],
         extrapolate=True,

{pyield-0.34.2 → pyield-0.35.1}/pyield/tpf/tools.py

@@ -5,7 +5,7 @@ import pandas as pd
 
 from pyield import date_converter as dc
 from pyield.anbima import tpf
-from pyield.b3 import dif
+from pyield.b3 import di1
 from pyield.date_converter import DateScalar
 
 
@@ -77,7 +77,7 @@ def pre_spreads(date: DateScalar) -> pd.DataFrame:
     """
     # Fetch DI rates for the reference date
     converted_date = dc.convert_input_dates(date)
-    df_di = dif.data(date=converted_date, month_start=True)
+    df_di = di1.data(dates=converted_date, month_start=True)
     if "SettlementRate" not in df_di.columns or df_di.empty:
         raise ValueError("DI data is missing the 'SettlementRate' column or is empty.")
 

pyield-0.34.2/pyield/__about__.py

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