PYield 0.46.2__tar.gz → 0.46.3__tar.gz

{pyield-0.46.2 → pyield-0.46.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyield
-Version: 0.46.2
+Version: 0.46.3
 Summary: A Python library for analysis of fixed income instruments in Brazil
 Project-URL: Homepage, https://github.com/crdcj/PYield
 Project-URL: Documentation, https://crdcj.github.io/PYield

pyield-0.46.3/pyield/__about__.py

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

{pyield-0.46.2 → pyield-0.46.3}/pyield/_internal/data_cache.py

@@ -16,7 +16,7 @@ registro = logging.getLogger(__name__)
 
 # Estrutura interna única — usuário não vê isso
 class _Dataset(Enum):
-    TPF = ("anbima_tpf.parquet", "ReferenceDate", "TPF (ANBIMA)")
+    TPF = ("anbima_tpf.parquet", "data_referencia", "TPF (ANBIMA)")
     PR = ("b3_price_report.parquet", "TradeDate", "Price Report (B3)")
 
     def __init__(self, nome_arquivo: str, coluna_data: str, descricao: str):

pyield-0.46.3/pyield/anbima/tpf.py

@@ -0,0 +1,293 @@
+"""Dados do mercado secundário de Títulos Públicos Federais (TPF) da ANBIMA.
+
+Exemplo de URL:
+    https://www.anbima.com.br/informacoes/merc-sec/arqs/ms240614.txt
+
+Exemplo de dado bruto (CSV separado por @, encoding latin1):
+    ANBIMA - Associação Brasileira das Entidades dos Mercados Financeiro e de Capitais
+
+    Titulo@Data Referencia@Codigo SELIC@Data Base/Emissao@Data Vencimento@Tx. Compra@Tx. Venda@Tx. Indicativas@PU@Desvio padrao@Interv. Ind. Inf. (D0)@Interv. Ind. Sup. (D0)@Interv. Ind. Inf. (D+1)@Interv. Ind. Sup. (D+1)@Criterio
+    LTN@20250924@100000@20230707@20251001@14,9483@14,9263@14,9375@997,241543@0,00433039162894@14,7341@15,2612@14,7316@15,2689@Calculado
+    LTN@20250924@100000@20200206@20260101@14,7741@14,7485@14,7616@963,001853@0,00729826731971@14,7008@14,9986@14,7021@14,9975@Calculado
+"""  # noqa: E501
+
+import datetime as dt
+import logging
+import socket
+from typing import Literal
+
+import polars as pl
+import requests
+
+from pyield import bday
+from pyield._internal.br_numbers import float_br, taxa_br
+from pyield._internal.converters import converter_datas, data_referencia_valida
+from pyield._internal.data_cache import obter_dataset_cacheado
+from pyield._internal.retry import retry_padrao
+from pyield._internal.types import DateLike
+
+BOND_TYPES = Literal["LFT", "NTN-B", "NTN-C", "LTN", "NTN-F", "PRE"]
+
+ANBIMA_URL = "https://www.anbima.com.br/informacoes/merc-sec/arqs"
+ANBIMA_RTM_HOSTNAME = "www.anbima.associados.rtm"
+ANBIMA_RTM_URL = f"http://{ANBIMA_RTM_HOSTNAME}/merc_sec/arqs"
+
+# Antes de 13/05/2014 o arquivo era zipado e o endpoint terminava com ".exe"
+DATA_MUDANCA_FORMATO = dt.date(2014, 5, 13)
+
+DIAS_RETENCAO_PUBLICA = 5
+
+# Colunas selecionadas pela função pública tpf()
+COLUNAS_TPF = (
+    "titulo",
+    "data_referencia",
+    "codigo_selic",
+    "data_base",
+    "data_vencimento",
+    "pu",
+    "taxa_compra",
+    "taxa_venda",
+    "taxa_indicativa",
+)
+
+logger = logging.getLogger(__name__)
+
+
+def _mapear_tipo_titulo(tipo_titulo: str) -> list[str]:
+    tipo_titulo = tipo_titulo.upper()
+    mapa_titulos = {
+        "PRE": ["LTN", "NTN-F"],
+        "NTNB": ["NTN-B"],
+        "NTNC": ["NTN-C"],
+        "NTNF": ["NTN-F"],
+    }
+    return mapa_titulos.get(tipo_titulo, [tipo_titulo])
+
+
+def _montar_nome_arquivo(data: dt.date) -> str:
+    data_url = data.strftime("%y%m%d")
+    if data < DATA_MUDANCA_FORMATO:
+        nome_arquivo = f"ms{data_url}.exe"
+    else:
+        nome_arquivo = f"ms{data_url}.txt"
+    return nome_arquivo
+
+
+def _montar_url_arquivo(data: dt.date) -> str:
+    ultimo_dia_util = bday.last_business_day()
+    qtd_dias_uteis = bday.count(data, ultimo_dia_util)
+    if qtd_dias_uteis > DIAS_RETENCAO_PUBLICA:
+        # Para datas com mais de 5 dias úteis, apenas os dados da RTM estão disponíveis
+        logger.info("Tentando buscar dados RTM para %s", data.strftime("%d/%m/%Y"))
+        url_arquivo = f"{ANBIMA_RTM_URL}/{_montar_nome_arquivo(data)}"
+    else:
+        url_arquivo = f"{ANBIMA_URL}/{_montar_nome_arquivo(data)}"
+    return url_arquivo
+
+
+@retry_padrao
+def _obter_csv(data: dt.date) -> bytes:
+    url_arquivo = _montar_url_arquivo(data)
+    resposta = requests.get(url_arquivo, timeout=10)
+    resposta.raise_for_status()
+    return resposta.content
+
+
+def _parsear_df(csv_bytes: bytes) -> pl.DataFrame:
+    """Converte bytes brutos do CSV da ANBIMA em DataFrame (tudo string)."""
+    return pl.read_csv(
+        source=csv_bytes,
+        skip_lines=2,
+        separator="@",
+        null_values=["--"],
+        infer_schema=False,
+        encoding="latin1",
+    )
+
+
+def _processar_df(df: pl.DataFrame) -> pl.DataFrame:
+    """Renomeia, converte tipos e define a ordem das colunas."""
+    return df.select(
+        titulo=pl.col("Titulo"),
+        data_referencia=pl.col("Data Referencia").str.to_date("%Y%m%d"),
+        codigo_selic=pl.col("Codigo SELIC").cast(pl.Int64),
+        data_base=pl.col("Data Base/Emissao").str.to_date("%Y%m%d"),
+        data_vencimento=pl.col("Data Vencimento").str.to_date("%Y%m%d"),
+        taxa_compra=taxa_br("Tx. Compra"),
+        taxa_venda=taxa_br("Tx. Venda"),
+        taxa_indicativa=taxa_br("Tx. Indicativas"),
+        pu=float_br("PU"),
+        desvio_padrao=float_br("Desvio padrao"),
+        taxa_intervalo_inf_d0=taxa_br("Interv. Ind. Inf. (D0)"),
+        taxa_intervalo_sup_d0=taxa_br("Interv. Ind. Sup. (D0)"),
+        taxa_intervalo_inf_d1=taxa_br("Interv. Ind. Inf. (D+1)"),
+        taxa_intervalo_sup_d1=taxa_br("Interv. Ind. Sup. (D+1)"),
+        criterio=pl.col("Criterio"),
+    )
+
+
+def _buscar_dados_tpf(data: dt.date) -> pl.DataFrame:
+    """Busca e processa dados do mercado secundário de TPF na fonte ANBIMA.
+
+    Args:
+        data: Data de referência.
+
+    Returns:
+        DataFrame processado ou DataFrame vazio se indisponível.
+    """
+    url_arquivo = _montar_url_arquivo(data)
+
+    # Fail-fast: se a URL é RTM e o host não resolve, não adianta tentar
+    if ANBIMA_RTM_URL in url_arquivo:
+        try:
+            socket.gethostbyname(ANBIMA_RTM_HOSTNAME)
+        except socket.gaierror:
+            data_str = data.strftime("%d/%m/%Y")
+            logger.warning(
+                f"Não foi possível resolver o host da RTM para {data_str}. "
+                "Dados históricos exigem acesso à rede RTM."
+            )
+            return pl.DataFrame()
+
+    csv_bytes = _obter_csv(data)
+    if not csv_bytes.strip():
+        return pl.DataFrame()
+
+    df = _parsear_df(csv_bytes)
+    return _processar_df(df)
+
+
+def tpf(
+    date: DateLike,
+    bond_type: BOND_TYPES | None = None,
+) -> pl.DataFrame:
+    """Recupera os dados do mercado secundário de TPF da ANBIMA.
+
+    Esta função busca taxas indicativas e outros dados de títulos públicos
+    brasileiros. Primeiro consulta o cache local; se não houver dados,
+    busca diretamente na fonte (ANBIMA).
+
+    Args:
+        date (DateLike): A data de referência para os dados (ex: '2024-06-14').
+        bond_type (str, optional): Filtra por tipo de título. Aceita os tipos
+            individuais ('LTN', 'NTN-F', 'NTN-B', 'NTN-C', 'LFT') ou 'PRE'
+            como atalho para prefixados ('LTN' e 'NTN-F').
+
+    Returns:
+        pl.DataFrame: Um DataFrame contendo os dados solicitados.
+            Retorna um DataFrame vazio se não houver dados para a data especificada (ex:
+            finais de semana, feriados ou datas futuras).
+
+    Examples:
+        >>> from pyield import anbima
+        >>> df = anbima.tpf(date="06-02-2026")
+
+    Output Columns:
+        * titulo (String): tipo do título público (ex: 'LTN', 'NTN-B').
+        * data_referencia (Date): data de referência dos dados.
+        * codigo_selic (Int64): código do título no SELIC.
+        * data_base (Date): data base ou de emissão do título.
+        * data_vencimento (Date): data de vencimento do título.
+        * pu (Float64): preço unitário (PU) para liquidação em D0.
+        * taxa_compra (Float64): taxa de compra em D0 (decimal).
+        * taxa_venda (Float64): taxa de venda em D0 (decimal).
+        * taxa_indicativa (Float64): taxa indicativa em D0 (decimal).
+
+    Notes:
+        A fonte dos dados segue a seguinte hierarquia:
+
+        1.  **Cache Local:** Fornece acesso rápido a dados históricos
+            desde 01/01/2020.
+        2.  **Fonte ANBIMA (fallback):** Se a data não estiver no cache,
+            busca automaticamente na fonte. Para datas recentes (até 5 dias
+            úteis), usa o site público. Para datas mais antigas, requer
+            acesso à rede RTM.
+
+        Para obter o dado completo direto da fonte (todas as colunas),
+        use :func:`fetch_tpf`.
+    """
+    date = converter_datas(date)
+
+    if not data_referencia_valida(date):
+        return pl.DataFrame()
+
+    # Cache primeiro; se não tiver, busca na fonte
+    df = obter_dataset_cacheado("tpf")
+    if not df.is_empty():
+        df = df.filter(pl.col("data_referencia") == date)
+    if df.is_empty():
+        df = _buscar_dados_tpf(date)
+    if df.is_empty():
+        return pl.DataFrame()
+
+    df = df.select(col for col in COLUNAS_TPF if col in df.columns)
+
+    if bond_type:
+        tipos_titulo = _mapear_tipo_titulo(bond_type)
+        df = df.filter(pl.col("titulo").is_in(tipos_titulo))
+
+    return df.sort("data_referencia", "titulo", "data_vencimento")
+
+
+def fetch_tpf(
+    date: DateLike,
+) -> pl.DataFrame:
+    """Busca os dados do mercado secundário de TPF direto da fonte ANBIMA.
+
+    Retorna todas as colunas publicadas pela ANBIMA, sem cache e sem
+    filtro de colunas. Indicado para uso em jobs e pipelines de dados.
+
+    Args:
+        date (DateLike): Data de referência (ex: '2024-06-14').
+
+    Returns:
+        pl.DataFrame: DataFrame com todas as colunas da ANBIMA.
+            Retorna DataFrame vazio se não houver dados.
+    """
+    date = converter_datas(date)
+
+    if not data_referencia_valida(date):
+        return pl.DataFrame()
+
+    df = _buscar_dados_tpf(date)
+    if df.is_empty():
+        return pl.DataFrame()
+
+    return df.sort("data_referencia", "titulo", "data_vencimento")
+
+
+def tpf_maturities(
+    date: DateLike,
+    bond_type: BOND_TYPES,
+) -> pl.Series:
+    """Recupera os vencimentos existentes para um tipo de título na data especificada.
+
+    Args:
+        date (DateLike): A data de referência para os vencimentos.
+        bond_type (BOND_TYPES): O tipo de título para filtrar (ex: 'PRE' para 'LTN'
+            e 'NTN-F', ou especifique 'LTN' ou 'NTN-F' diretamente).
+
+    Returns:
+        pl.Series: Uma Series contendo as datas de vencimento únicas para o(s)
+            tipo(s) de título especificado(s).
+
+    Examples:
+        >>> from pyield import anbima
+        >>> anbima.tpf_maturities(date="22-08-2025", bond_type="PRE")
+        shape: (18,)
+        Series: 'data_vencimento' [date]
+        [
+            2025-10-01
+            2026-01-01
+            2026-04-01
+            2026-07-01
+            2026-10-01
+            …
+            2030-01-01
+            2031-01-01
+            2032-01-01
+            2033-01-01
+            2035-01-01
+        ]
+    """
+    return tpf(date, bond_type)["data_vencimento"].unique().sort()

{pyield-0.46.2 → pyield-0.46.3}/pyield/b3/di1.py

@@ -62,11 +62,11 @@ def data(
     if pre_filter:
         df_tpf = (
             obter_dataset_cacheado("tpf")
-            .filter(pl.col("BondType").is_in(["LTN", "NTN-F"]))
-            .unique(subset=["MaturityDate", "ReferenceDate"])
+            .filter(pl.col("titulo").is_in(["LTN", "NTN-F"]))
+            .unique(subset=["data_vencimento", "data_referencia"])
             .select(
-                TradeDate_tpf=pl.col("ReferenceDate"),
-                ExpirationDate=bday.offset_expr("MaturityDate", 0),
+                TradeDate_tpf=pl.col("data_referencia"),
+                ExpirationDate=bday.offset_expr("data_vencimento", 0),
             )
             .sort("TradeDate_tpf", "ExpirationDate")
         )

{pyield-0.46.2 → pyield-0.46.3}/pyield/tn/lft.py

@@ -20,7 +20,7 @@ def data(date: DateLike) -> pl.DataFrame:
         - data_referencia (Date): Data de referência dos dados.
         - titulo (String): Tipo do título (ex.: "LFT").
         - codigo_selic (Int64): Código do título no SELIC.
-        - data_base (Date): Data base/emissão do título.
+        - data_base (Date): Data base de emissão do título.
         - data_vencimento (Date): Data de vencimento do título.
         - dias_uteis (Int64): Dias úteis entre referência e vencimento.
         - prazo_medio (Float64): Prazo médio do título em anos.
@@ -28,7 +28,8 @@ def data(date: DateLike) -> pl.DataFrame:
         - taxa_compra (Float64): Taxa de compra (decimal).
         - taxa_venda (Float64): Taxa de venda (decimal).
         - taxa_indicativa (Float64): Taxa indicativa (decimal).
-        - taxa_di (Float64): Taxa DI interpolada pelo método flat forward.
+        - taxa_di (Float64): Taxa de ajuste do DI Futuro interpolada pelo
+            método flat forward.
         - rentabilidade (Float64): Rentabilidade da LFT sobre o DI.
 
     Examples:

{pyield-0.46.2 → pyield-0.46.3}/pyield/tn/ltn.py

@@ -23,7 +23,7 @@ def data(date: DateLike) -> pl.DataFrame:
         - data_referencia (Date): Data de referência dos dados.
         - titulo (String): Tipo do título (ex.: "LTN").
         - codigo_selic (Int64): Código do título no SELIC.
-        - data_base (Date): Data base/emissão do título.
+        - data_base (Date): Data base de emissão do título.
         - data_vencimento (Date): Data de vencimento do título.
         - dias_uteis (Int64): Dias úteis entre referência e vencimento.
         - duration (Float64): Macaulay Duration do título (anos).
@@ -34,7 +34,8 @@ def data(date: DateLike) -> pl.DataFrame:
         - taxa_compra (Float64): Taxa de compra (decimal).
         - taxa_venda (Float64): Taxa de venda (decimal).
         - taxa_indicativa (Float64): Taxa indicativa (decimal).
-        - taxa_di (Float64): Taxa DI interpolada pelo método flat forward.
+        - taxa_di (Float64): Taxa de ajuste do DI Futuro interpolada pelo
+            método flat forward.
         - spread_di (Float64): Spread sobre o DI (também conhecido como
             prêmio).
         - rentabilidade (Float64): Rentabilidade diária da LTN sobre o DI.

{pyield-0.46.2 → pyield-0.46.3}/pyield/tn/ntnb.py

@@ -37,7 +37,7 @@ def data(date: DateLike) -> pl.DataFrame:
         - data_referencia (Date): Data de referência dos dados.
         - titulo (String): Tipo do título (ex.: "NTN-B").
         - codigo_selic (Int64): Código do título no SELIC.
-        - data_base (Date): Data base/emissão do título.
+        - data_base (Date): Data base de emissão do título.
         - data_vencimento (Date): Data de vencimento do título.
         - dias_uteis (Int64): Dias úteis entre referência e vencimento.
         - duration (Float64): Macaulay Duration do título (anos).
@@ -48,7 +48,8 @@ def data(date: DateLike) -> pl.DataFrame:
         - taxa_compra (Float64): Taxa de compra (decimal).
         - taxa_venda (Float64): Taxa de venda (decimal).
         - taxa_indicativa (Float64): Taxa indicativa (decimal).
-        - taxa_di (Float64): Taxa DI interpolada pelo método flat forward.
+        - taxa_di (Float64): Taxa de ajuste do DI Futuro interpolada pelo
+            método flat forward.
         - taxa_zero (Float64): Taxa zero real (via bootstrap das taxas indicativas).
         - taxa_forward (Float64): Taxa forward real (a partir das taxas zero).
         - inflacao_implicita (Float64): Inflação implícita (breakeven) calculada

{pyield-0.46.2 → pyield-0.46.3}/pyield/tn/ntnc.py

@@ -53,7 +53,7 @@ def data(date: DateLike) -> pl.DataFrame:
         - data_referencia (Date): Data de referência dos dados.
         - titulo (String): Tipo do título (ex.: "NTN-C").
         - codigo_selic (Int64): Código do título no SELIC.
-        - data_base (Date): Data base/emissão do título.
+        - data_base (Date): Data base de emissão do título.
         - data_vencimento (Date): Data de vencimento do título.
         - dias_uteis (Int64): Dias úteis entre referência e vencimento.
         - duration (Float64): Macaulay Duration do título (anos).
@@ -64,7 +64,8 @@ def data(date: DateLike) -> pl.DataFrame:
         - taxa_compra (Float64): Taxa de compra (decimal).
         - taxa_venda (Float64): Taxa de venda (decimal).
         - taxa_indicativa (Float64): Taxa indicativa (decimal).
-        - taxa_di (Float64): Taxa DI interpolada pelo método flat forward.
+        - taxa_di (Float64): Taxa de ajuste do DI Futuro interpolada pelo
+            método flat forward.
 
     Examples:
         >>> from pyield import ntnc

{pyield-0.46.2 → pyield-0.46.3}/pyield/tn/ntnf.py

@@ -43,7 +43,7 @@ def data(date: DateLike) -> pl.DataFrame:
         - data_referencia (Date): Data de referência dos dados.
         - titulo (String): Tipo do título (ex.: "NTN-F").
         - codigo_selic (Int64): Código do título no SELIC.
-        - data_base (Date): Data base/emissão do título.
+        - data_base (Date): Data base de emissão do título.
         - data_vencimento (Date): Data de vencimento do título.
         - dias_uteis (Int64): Dias úteis entre referência e vencimento.
         - prazo_medio (Float64): Prazo médio do título em dias corridos.
@@ -54,11 +54,11 @@ def data(date: DateLike) -> pl.DataFrame:
         - taxa_compra (Float64): Taxa de compra (decimal).
         - taxa_venda (Float64): Taxa de venda (decimal).
         - taxa_indicativa (Float64): Taxa indicativa (decimal).
-        - taxa_di (Float64): Taxa DI interpolada pelo método flat forward.
+        - taxa_di (Float64): Taxa de ajuste do DI Futuro interpolada pelo
+            método flat forward.
         - taxa_zero (Float64): Taxa zero (zero cupom via bootstrap).
-        - spread_di (Float64): Spread sobre o DI (também conhecido como
-            prêmio).
-        - spread_di_liquido (Float64): Spread líquido sobre a curva DI.
+        - spread_di (Float64): Spread sobre o DI (conhecido como prêmio).
+        - spread_di_limpo (Float64): Spread limpo sobre a curva DI (conhecido como prêmio limpo).
         - rentabilidade (Float64): Rentabilidade da NTN-F sobre a curva DI.
 
     Examples:
@@ -98,7 +98,7 @@ def data(date: DateLike) -> pl.DataFrame:
     # Calcula spreads e rentabilidade para cada vencimento
     df = df.with_columns(
         spread_di=pl.col("taxa_indicativa") - pl.col("taxa_di"),
-        spread_di_liquido=pl.struct("data_vencimento", "taxa_indicativa").map_elements(
+        spread_di_limpo=pl.struct("data_vencimento", "taxa_indicativa").map_elements(
             lambda row: di_net_spread(
                 settlement=date,  # Usa a variável externa explicitamente aqui
                 ntnf_maturity=row["data_vencimento"],
@@ -138,7 +138,7 @@ def data(date: DateLike) -> pl.DataFrame:
         "taxa_di",
         "taxa_zero",
         "spread_di",
-        "spread_di_liquido",
+        "spread_di_limpo",
         "rentabilidade",
     )
 
@@ -293,9 +293,7 @@ def cash_flows(
     )
 
     if adj_payment_dates:
-        df = df.with_columns(
-            data_pagamento=bday.offset_expr("data_pagamento", 0)
-        )
+        df = df.with_columns(data_pagamento=bday.offset_expr("data_pagamento", 0))
     return df
 
 

{pyield-0.46.2 → pyield-0.46.3}/pyield/tn/utils.py

@@ -11,18 +11,6 @@ from pyield.anbima.tpf import BOND_TYPES
 
 logger = logging.getLogger(__name__)
 
-MAPA_COLUNAS_TPF = {
-    "ReferenceDate": "data_referencia",
-    "BondType": "titulo",
-    "SelicCode": "codigo_selic",
-    "IssueBaseDate": "data_base",
-    "MaturityDate": "data_vencimento",
-    "Price": "pu",
-    "BidRate": "taxa_compra",
-    "AskRate": "taxa_venda",
-    "IndicativeRate": "taxa_indicativa",
-}
-
 COLUNAS_DADOS_TPF = (
     "data_referencia",
     "titulo",
@@ -51,9 +39,7 @@ def obter_tpf(
     """Busca dados de ``anbima.tpf()`` no padrão de colunas usado por ``tn``."""
     from pyield import anbima  # noqa: PLC0415
 
-    return anbima.tpf(date, tipo_titulo).select(tuple(MAPA_COLUNAS_TPF)).rename(
-        MAPA_COLUNAS_TPF
-    )
+    return anbima.tpf(date, tipo_titulo).select(COLUNAS_DADOS_TPF)
 
 
 def adicionar_taxa_di(df: pl.DataFrame, data_ref: dt.date) -> pl.DataFrame:

pyield-0.46.2/pyield/__about__.py

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

pyield-0.46.2/pyield/anbima/tpf.py

@@ -1,356 +0,0 @@
-import datetime as dt
-import logging
-import socket
-from typing import Literal
-
-import polars as pl
-import polars.selectors as cs
-import requests
-from requests.exceptions import HTTPError, RequestException
-
-from pyield import bday
-from pyield._internal.converters import converter_datas, data_referencia_valida
-from pyield._internal.data_cache import obter_dataset_cacheado
-from pyield._internal.retry import retry_padrao
-from pyield._internal.types import DateLike
-
-BOND_TYPES = Literal["LFT", "NTN-B", "NTN-C", "LTN", "NTN-F", "PRE"]
-
-ANBIMA_URL = "https://www.anbima.com.br/informacoes/merc-sec/arqs"
-ANBIMA_RTM_HOSTNAME = "www.anbima.associados.rtm"
-ANBIMA_RTM_URL = f"http://{ANBIMA_RTM_HOSTNAME}/merc_sec/arqs"
-# Exemplo de URL: https://www.anbima.com.br/informacoes/merc-sec/arqs/ms240614.txt
-
-# Antes de 13/05/2014 o arquivo era zipado e o endpoint terminava com ".exe"
-DATA_MUDANCA_FORMATO = dt.date(2014, 5, 13)
-
-DIAS_RETENCAO_PUBLICA = 5
-
-# Única fonte de verdade para colunas do CSV: (nome_csv, nome_novo, tipo)
-# Colunas de data são lidas como String e convertidas em _processar_df_bruto
-TPF_COLUNAS = [
-    ("Titulo", "BondType", pl.String),
-    ("Data Referencia", "ReferenceDate", pl.String),
-    ("Codigo SELIC", "SelicCode", pl.Int64),
-    ("Data Base/Emissao", "IssueBaseDate", pl.String),
-    ("Data Vencimento", "MaturityDate", pl.String),
-    ("Tx. Compra", "BidRate", pl.Float64),
-    ("Tx. Venda", "AskRate", pl.Float64),
-    ("Tx. Indicativas", "IndicativeRate", pl.Float64),
-    ("PU", "Price", pl.Float64),
-    ("Desvio padrao", "StdDev", pl.Float64),
-    ("Interv. Ind. Inf. (D0)", "LowerBoundRateD0", pl.Float64),
-    ("Interv. Ind. Sup. (D0)", "UpperBoundRateD0", pl.Float64),
-    ("Interv. Ind. Inf. (D+1)", "LowerBoundRateD1", pl.Float64),
-    ("Interv. Ind. Sup. (D+1)", "UpperBoundRateD1", pl.Float64),
-    ("Criterio", "Criteria", pl.String),
-]
-
-# Derivados automaticamente
-ESQUEMA_TPF = {csv: tipo for csv, _, tipo in TPF_COLUNAS}
-MAPA_NOMES_COLUNAS = {csv: novo for csv, novo, _ in TPF_COLUNAS}
-
-logger = logging.getLogger(__name__)
-
-
-def _mapear_tipo_titulo(tipo_titulo: str) -> list[str]:
-    tipo_titulo = tipo_titulo.upper()
-    mapa_titulos = {
-        "PRE": ["LTN", "NTN-F"],
-        "NTNB": ["NTN-B"],
-        "NTNC": ["NTN-C"],
-        "NTNF": ["NTN-F"],
-    }
-    return mapa_titulos.get(tipo_titulo, [tipo_titulo])
-
-
-def _montar_nome_arquivo(data: dt.date) -> str:
-    data_url = data.strftime("%y%m%d")
-    if data < DATA_MUDANCA_FORMATO:
-        nome_arquivo = f"ms{data_url}.exe"
-    else:
-        nome_arquivo = f"ms{data_url}.txt"
-    return nome_arquivo
-
-
-def _montar_url_arquivo(data: dt.date) -> str:
-    ultimo_dia_util = bday.last_business_day()
-    qtd_dias_uteis = bday.count(data, ultimo_dia_util)
-    if qtd_dias_uteis > DIAS_RETENCAO_PUBLICA:
-        # Para datas com mais de 5 dias úteis, apenas os dados da RTM estão disponíveis
-        logger.info("Tentando buscar dados RTM para %s", data.strftime("%d/%m/%Y"))
-        url_arquivo = f"{ANBIMA_RTM_URL}/{_montar_nome_arquivo(data)}"
-    else:
-        url_arquivo = f"{ANBIMA_URL}/{_montar_nome_arquivo(data)}"
-    return url_arquivo
-
-
-@retry_padrao
-def _obter_csv(data: dt.date) -> bytes:
-    url_arquivo = _montar_url_arquivo(data)
-    resposta = requests.get(url_arquivo, timeout=10)
-    resposta.raise_for_status()
-    return resposta.content
-
-
-def _ler_csv(csv_texto: bytes) -> pl.DataFrame:
-    """
-    Exemplo de arquivo bruto da ANBIMA:
-        ANBIMA - Associação Brasileira das Entidades dos Mercados Financeiro e de Capitais
-
-        Titulo@Data Referencia@Codigo SELIC@Data Base/Emissao@Data Vencimento@Tx. Compra@Tx. Venda@Tx. Indicativas@PU@Desvio padrao@Interv. Ind. Inf. (D0)@Interv. Ind. Sup. (D0)@Interv. Ind. Inf. (D+1)@Interv. Ind. Sup. (D+1)@Criterio
-        LTN@20250924@100000@20230707@20251001@14,9483@14,9263@14,9375@997,241543@0,00433039162894@14,7341@15,2612@14,7316@15,2689@Calculado
-        LTN@20250924@100000@20200206@20260101@14,7741@14,7485@14,7616@963,001853@0,00729826731971@14,7008@14,9986@14,7021@14,9975@Calculado
-        LTN@20250924@100000@20240105@20260401@14,7357@14,707@14,7205@931,607124@0,00317937979329@14,5525@14,9847@14,5669@14,9959@Calculado
-        ...
-    """  # noqa
-    df = pl.read_csv(
-        source=csv_texto,
-        skip_lines=2,
-        separator="@",
-        null_values=["--"],
-        decimal_comma=True,
-        schema_overrides=ESQUEMA_TPF,
-        encoding="latin1",
-    )
-    return df
-
-
-def _processar_df_bruto(df: pl.DataFrame) -> pl.DataFrame:
-    df = (
-        df.rename(MAPA_NOMES_COLUNAS)
-        .with_columns(
-            # Remove o percentual das taxas
-            # Colunas de taxa têm valores percentuais com 4 casas decimais
-            # Arredonda para 6 casas decimais para minimizar erros de ponto flutuante
-            cs.contains("Rate").truediv(100).round(6),
-            cs.ends_with("Date").str.to_date(format="%Y%m%d"),
-        )
-        # Substituir eventuais NaNs por None para compatibilidade com bancos de dados
-        .with_columns(cs.float().fill_nan(None))
-    )
-    return df
-
-
-def _selecionar_e_ordenar_colunas(df: pl.DataFrame) -> pl.DataFrame:
-    """Reordena as colunas do DataFrame de acordo com a ordem especificada."""
-    ordem_colunas = [
-        "BondType",
-        "ReferenceDate",
-        "SelicCode",
-        "IssueBaseDate",
-        "MaturityDate",
-        "Price",
-        "BidRate",
-        "AskRate",
-        "IndicativeRate",
-    ]
-    ordem_colunas = [col for col in ordem_colunas if col in df.columns]
-    return df.select(ordem_colunas).sort("BondType", "MaturityDate")
-
-
-def _buscar_dados_tpf(date: dt.date) -> pl.DataFrame:
-    """Busca e processa dados do mercado secundário de TPF diretamente da fonte ANBIMA.
-
-    Esta é uma função de baixo nível para uso interno. Ela lida com a lógica
-    de construir a URL correta (pública ou RTM), baixar os dados com novas
-    tentativas e processá-los em um DataFrame estruturado.
-
-    Args:
-        date (dt.date): A data de referência para os dados.
-
-    Returns:
-        pl.DataFrame: Um DataFrame contendo os dados de mercado de títulos
-            processados, ou um DataFrame vazio se os dados não estiverem
-            disponíveis ou ocorrer um erro de conexão.
-    """
-    url_arquivo = _montar_url_arquivo(date)
-    data_str = date.strftime("%d/%m/%Y")
-
-    # --- "FAIL-FAST" PARA EVITAR RETRIES DESNECESSÁRIOS NA RTM ---
-    if ANBIMA_RTM_URL in url_arquivo:
-        try:
-            # Tenta resolver o hostname da RTM. É uma verificação de rede rápida.
-            socket.gethostbyname(ANBIMA_RTM_HOSTNAME)
-        except socket.gaierror:
-            # Se falhar (gaierror = get address info error), não estamos na RTM.
-            # Não adianta prosseguir para a função com retry.
-            logger.warning(
-                f"Não foi possível resolver o host da RTM para {data_str}. "
-                "Isso é esperado fora da rede RTM. Dados históricos exigem acesso "
-                "à RTM. Retornando DataFrame vazio."
-            )
-            return pl.DataFrame()
-
-    try:
-        # Se passamos pela verificação da RTM, agora podemos chamar a função com retry.
-        csv_texto = _obter_csv(date)
-        if not csv_texto.strip():
-            logger.info(
-                f"Dados TPF de mercado secundário para {data_str} não disponíveis. "
-                "Retornando DataFrame vazio."
-            )
-            return pl.DataFrame()
-
-        df = _ler_csv(csv_texto)
-        df = _processar_df_bruto(df)
-
-        return df
-
-    except HTTPError as e:
-        if e.response.status_code == 404:  # noqa
-            logger.info(
-                f"Dados TPF de mercado secundário para {data_str} (HTTP 404). "
-                "Retornando DataFrame vazio."
-            )
-            return pl.DataFrame()
-        logger.error(
-            "Erro HTTP ao buscar dados para %s de %s: %s", data_str, url_arquivo, e
-        )
-        raise
-
-    # Este bloco ainda é útil para outros URLErrors (ex: timeout genuíno na URL pública)
-    except RequestException:
-        logger.exception("RequestException ao buscar dados TPF para %s", data_str)
-        raise
-
-    except Exception:
-        msg = f"Ocorreu um erro inesperado ao buscar dados TPF para {data_str}"
-        logger.exception(msg)
-        raise
-
-
-def tpf(
-    date: DateLike,
-    bond_type: BOND_TYPES | None = None,
-) -> pl.DataFrame:
-    """Recupera os dados do mercado secundário de TPF da ANBIMA.
-
-    Esta função busca taxas indicativas e outros dados de títulos públicos
-    brasileiros. Primeiro consulta o cache local; se não houver dados,
-    busca diretamente na fonte (ANBIMA).
-
-    Args:
-        date (DateLike): A data de referência para os dados (ex: '2024-06-14').
-        bond_type (str, optional): Filtra por tipo de título. Aceita os tipos
-            individuais ('LTN', 'NTN-F', 'NTN-B', 'NTN-C', 'LFT') ou 'PRE'
-            como atalho para prefixados ('LTN' e 'NTN-F').
-
-    Returns:
-        pl.DataFrame: Um DataFrame contendo os dados solicitados.
-            Retorna um DataFrame vazio se não houver dados para a data especificada (ex:
-            finais de semana, feriados ou datas futuras).
-
-    Examples:
-        >>> from pyield import anbima
-        >>> df = anbima.tpf(date="06-02-2026")
-
-    Data columns:
-        - BondType: Tipo do título público (e.g., 'LTN', 'NTN-B').
-        - ReferenceDate: Data de referência dos dados.
-        - SelicCode: Código do título no SELIC.
-        - IssueBaseDate: Data base ou de emissão do título.
-        - MaturityDate: Data de vencimento do título.
-        - Price: Preço Unitário (PU) calculado para liquidação em D0.
-        - BidRate: Taxa de compra para liquidação em D0 (decimal).
-        - AskRate: Taxa de venda para liquidação em D0 (decimal).
-        - IndicativeRate: Taxa indicativa para liquidação em D0 (decimal).
-
-    Notes:
-        A fonte dos dados segue a seguinte hierarquia:
-
-        1.  **Cache Local:** Fornece acesso rápido a dados históricos
-            desde 01/01/2020.
-        2.  **Fonte ANBIMA (fallback):** Se a data não estiver no cache,
-            busca automaticamente na fonte. Para datas recentes (até 5 dias
-            úteis), usa o site público. Para datas mais antigas, requer
-            acesso à rede RTM.
-
-        Para obter o dado completo direto da fonte (todas as colunas),
-        use :func:`fetch_tpf`.
-    """
-    date = converter_datas(date)
-
-    if not data_referencia_valida(date):
-        return pl.DataFrame()
-
-    # Cache primeiro; se não tiver, busca na fonte
-    df = obter_dataset_cacheado("tpf")
-    if not df.is_empty():
-        df = df.filter(pl.col("ReferenceDate") == date)
-    if df.is_empty():
-        df = _buscar_dados_tpf(date)
-    df = _selecionar_e_ordenar_colunas(df)
-
-    if df.is_empty():
-        return pl.DataFrame()
-
-    if bond_type:
-        norm_bond_type = _mapear_tipo_titulo(bond_type)
-        df = df.filter(pl.col("BondType").is_in(norm_bond_type))
-
-    return df.sort("ReferenceDate", "BondType", "MaturityDate")
-
-
-def fetch_tpf(
-    date: DateLike,
-) -> pl.DataFrame:
-    """Busca os dados do mercado secundário de TPF direto da fonte ANBIMA.
-
-    Retorna todas as colunas publicadas pela ANBIMA, sem cache e sem
-    filtro de colunas. Indicado para uso em jobs e pipelines de dados.
-
-    Args:
-        date (DateLike): Data de referência (ex: '2024-06-14').
-
-    Returns:
-        pl.DataFrame: DataFrame com todas as colunas da ANBIMA.
-            Retorna DataFrame vazio se não houver dados.
-    """
-    date = converter_datas(date)
-
-    if not data_referencia_valida(date):
-        return pl.DataFrame()
-
-    df = _buscar_dados_tpf(date)
-    if df.is_empty():
-        return pl.DataFrame()
-
-    return df.sort("ReferenceDate", "BondType", "MaturityDate")
-
-
-def tpf_maturities(
-    date: DateLike,
-    bond_type: BOND_TYPES,
-) -> pl.Series:
-    """Recupera os vencimentos existentes para um tipo de título na data especificada.
-
-    Args:
-        date (DateLike): A data de referência para os vencimentos.
-        bond_type (BOND_TYPES): O tipo de título para filtrar (ex: 'PRE' para 'LTN'
-            e 'NTN-F', ou especifique 'LTN' ou 'NTN-F' diretamente).
-
-    Returns:
-        pl.Series: Uma Series contendo as datas de vencimento únicas para o(s)
-            tipo(s) de título especificado(s).
-
-    Examples:
-        >>> from pyield import anbima
-        >>> anbima.tpf_maturities(date="22-08-2025", bond_type="PRE")
-        shape: (18,)
-        Series: 'MaturityDate' [date]
-        [
-            2025-10-01
-            2026-01-01
-            2026-04-01
-            2026-07-01
-            2026-10-01
-            …
-            2030-01-01
-            2031-01-01
-            2032-01-01
-            2033-01-01
-            2035-01-01
-        ]
-    """
-    return tpf(date, bond_type)["MaturityDate"].unique().sort()