PYield 0.46.0__tar.gz → 0.46.1__tar.gz

{pyield-0.46.0 → pyield-0.46.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyield
-Version: 0.46.0
+Version: 0.46.1
 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.1/pyield/__about__.py

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

{pyield-0.46.0 → pyield-0.46.1}/pyield/anbima/difusao.py

@@ -109,7 +109,7 @@ def _processar_csv(data_ref: dt.date, df: pl.DataFrame) -> pl.DataFrame:
             provedor=pl.col("Provedor"),
             titulo=pl.col("Título"),
             data_vencimento=pl.col("data_vencimento"),
-            codigo_isin=pl.col("Código ISIN"),
+            isin=pl.col("Código ISIN"),
             dias_uteis=bday.count_expr(data_ref, "data_vencimento"),
             taxa_indicativa_anterior=taxa_br("Fech D-1"),
             taxa_indicativa_superior=taxa_br("Indicativo Superior"),
@@ -142,7 +142,7 @@ def tpf_difusao(data_referencia: DateLike) -> pl.DataFrame:
         - provedor (string): Provedor dos dados.
         - titulo (string): Nome do título (ex: LFT, LTN).
         - data_vencimento (date): Data de vencimento do título.
-        - codigo_isin (string): Código ISIN do título.
+        - isin (string): código ISIN do título.
         - dias_uteis (int): Dias úteis entre a data de referência e o vencimento.
         - taxa_indicativa_anterior (float): Taxa indicativa de fechamento D-1 (decimal).
         - taxa_indicativa_superior (float): Limite superior da banda indicativa (decimal).

{pyield-0.46.0 → pyield-0.46.1}/pyield/anbima/ima.py

@@ -59,7 +59,7 @@ def _processar_df(df: pl.DataFrame) -> pl.DataFrame:
             titulo=pl.col("Títulos"),
             data_vencimento=pl.col("Data de Vencimento").str.to_date("%d/%m/%Y"),
             codigo_selic=pl.col("Código SELIC").cast(pl.Int64),
-            codigo_isin=pl.col("Código ISIN"),
+            isin=pl.col("Código ISIN"),
             dias_uteis=pl.col("Prazo (d.u.)").cast(pl.Int64),
             duration=pl.col("duration"),
             taxa_indicativa=pl.col("taxa_indicativa"),
@@ -100,7 +100,7 @@ def last_ima(ima_type: TiposIMA | None = None) -> pl.DataFrame:
         - titulo (String): título (ex: 'LTN', 'NTN-B').
         - data_vencimento (Date): data de vencimento do título.
         - codigo_selic (Int64): código do título no sistema SELIC.
-        - codigo_isin (String): código ISIN.
+        - isin (String): código ISIN.
         - dias_uteis (Int64): dias úteis até o vencimento.
         - duration (Float64): duration do título em anos úteis (252 d.u./ano).
         - taxa_indicativa (Float64): taxa indicativa em decimal (ex: 0.10 para 10%).

{pyield-0.46.0 → pyield-0.46.1}/pyield/anbima/imaq.py

@@ -102,7 +102,7 @@ def _processar_df(df: pl.DataFrame, data_referencia: dt.date) -> pl.DataFrame:
             titulo=pl.col("Título"),
             data_vencimento=pl.col("Data de Vencimento").str.to_date(format="%d/%m/%Y"),
             codigo_selic=pl.col("Codigo Selic").cast(pl.Int64),
-            codigo_isin=pl.col("Código ISIN"),
+            isin=pl.col("Código ISIN"),
             pu=float_br("PU (R$)"),
             quantidade_mercado=inteiro_m("Quantidade em Mercado (1.000 Títulos)"),
             valor_mercado=inteiro_m("Valor de Mercado (R$ Mil)"),
@@ -129,7 +129,7 @@ def imaq(date: DateLike) -> pl.DataFrame:
         - titulo (String): tipo do título (LTN, NTN-B, NTN-F, LFT, …).
         - data_vencimento (Date): data de vencimento do título.
         - codigo_selic (Int64): código SELIC do título.
-        - codigo_isin (String): código ISIN (International Securities Id Number).
+        - isin (String): código ISIN.
         - pu (Float64): PU do título em R$.
         - quantidade_mercado (Int64): quantidade em mercado (unidades).
         - valor_mercado (Int64): valor de mercado em R$.

{pyield-0.46.0 → pyield-0.46.1}/pyield/bc/auction.py

@@ -280,54 +280,62 @@ def auctions(
     end: DateLike | None = None,
     auction_type: Literal["sell", "buy"] | None = None,
 ) -> pl.DataFrame:
-    """
-    Recupera dados de leilões para um determinado período e tipo de leilão da API do BC.
-
-    **Consultas de período:**
-    - Para consultar dados de um intervalo, forneça as datas de `start` e `end`.
-      Exemplo: `auctions(start='2024-10-20', end='2024-10-27')`
-    - Se apenas `start` for fornecido, a API do BC retornará dados de leilão a partir
-      da data de `start` **até a data mais recente disponível**.
-      Exemplo: `auctions(start='2024-10-20')`
-    - Se apenas `end` for fornecido, a API do BC retornará dados de leilão **desde a
-      data mais antiga disponível até a data de `end`**.
-      Exemplo: `auctions(end='2024-10-27')`
-
-    **Série histórica completa:**
-    - Para recuperar a série histórica completa de leilões (desde 12/11/2012 até o
-      último dia útil), chame a função sem fornecer os parâmetros `start` e `end`.
-      Exemplo: `auctions()`
-
-    Busca dados de leilões da API do BC para as datas de início e fim especificadas,
-    filtrando os resultados diretamente na API pelo tipo de leilão, se especificado.
-    O comportamento da função em relação aos parâmetros `start` e `end` segue o padrão
-    da API do Banco Central:
-    - Se `start` for fornecido e `end` não, a função retorna dados de `start` até o fim.
-    - Se `end` for fornecido e `start` não, a API retorna dados do início até `end`.
-    - Se ambos `start` e `end` forem omitidos, a API retorna a série histórica completa.
-
-    Os dados podem ser filtrados pelo tipo de leilão especificado ("Sell" ou "Buy").
-    Leilões de "Sell" são aqueles em que o Tesouro Nacional vende títulos ao mercado.
-    Leilões de "Buy" são aqueles em que o Tesouro Nacional compra títulos do mercado.
+    """Dados de leilões de títulos públicos federais do BCB.
+
+    Fonte: Banco Central do Brasil. Disponível desde 12/11/2012.
+
+    Se ambos `start` e `end` forem omitidos, retorna a série
+    histórica completa. Se apenas um for informado, a API do BCB
+    usa o início ou fim do histórico como limite.
 
     Args:
-        start (DateLike, opcional): A data de início para a consulta dos leilões.
-            Se `start` for fornecido e `end` for `None`, a API retornará dados de
-            leilão a partir de `start` até a data mais recente disponível.
-            Se `start` e `end` forem `None`, a série histórica completa será retornada.
-            Padrão é `None`.
-        end (DateLike, opcional): A data de fim para a consulta de dados de leilão.
-            Se `end` for fornecido e `start` for `None`, a API retornará dados de
-            leilão desde a data mais antiga disponível até a data de `end`.
-            Se `start` e `end` forem `None`, a série histórica completa será retornada.
-            Padrão é `None`.
-        auction_type (Literal["sell", "buy"], opcional): O tipo de leilão para filtrar
-            diretamente na API. Padrão é `None` (retorna todos os tipos de leilão).
+        start: Data de início. Padrão é ``None``.
+        end: Data de fim. Padrão é ``None``.
+        auction_type: Tipo de leilão (``"sell"`` = venda,
+            ``"buy"`` = compra). Padrão é ``None`` (todos).
 
     Returns:
-        pl.DataFrame: Um DataFrame contendo dados de leilões para o período e tipo
-            especificados. Em caso de erro ao buscar os dados, um DataFrame vazio
-            é retornado e uma mensagem de erro é registrada no log.
+        DataFrame com dados de leilões, ou DataFrame vazio
+        se não houver dados.
+
+    Output Columns:
+        * data_leilao (Date): data do leilão.
+        * data_liquidacao (Date): data de liquidação.
+        * tipo_leilao (String): "Venda" ou "Compra".
+        * numero_edital (Int64): edital normativo.
+        * tipo_publico (String): categoria do comprador.
+        * titulo (String): sigla do título (LTN, LFT, NTN-B, NTN-F).
+        * codigo_selic (Int64): código no sistema Selic.
+        * data_vencimento (Date): data de vencimento.
+        * dias_uteis (Int32): dias úteis até o vencimento.
+        * duration (Float64): duração de Macaulay em anos.
+        * prazo_medio (Float64): prazo médio em anos.
+        * pu_medio (Float64): PU médio no leilão.
+        * pu_corte (Float64): PU de corte.
+        * taxa_media (Float64): taxa média (decimal).
+        * taxa_corte (Float64): taxa de corte (decimal).
+        * dv01_1v (Float64): DV01 da 1ª volta em R$.
+        * dv01_2v (Float64): DV01 da 2ª volta em R$.
+        * dv01_total (Float64): DV01 total em R$.
+        * ptax (Float64): PTAX (venda) para conversão USD.
+        * dv01_1v_usd (Float64): DV01 da 1ª volta em USD.
+        * dv01_2v_usd (Float64): DV01 da 2ª volta em USD.
+        * dv01_total_usd (Float64): DV01 total em USD.
+        * quantidade_liquidada_1v (Int64): qtd liquidada 1ª volta.
+        * quantidade_liquidada_2v (Int64): qtd liquidada 2ª volta.
+        * quantidade_liquidada_total (Int64): qtd total liquidada.
+        * quantidade_ofertada_1v (Int64): qtd ofertada 1ª volta.
+        * quantidade_ofertada_2v (Int64): qtd ofertada 2ª volta.
+        * quantidade_ofertada_total (Int64): qtd total ofertada.
+        * quantidade_aceita_1v (Int64): qtd aceita 1ª volta.
+        * quantidade_aceita_2v (Int64): qtd aceita 2ª volta.
+        * quantidade_aceita_total (Int64): qtd total aceita.
+        * financeiro_1v (Int64): financeiro 1ª volta em R$.
+        * financeiro_2v (Int64): financeiro 2ª volta em R$.
+        * financeiro_total (Int64): financeiro total em R$.
+
+    Notes:
+        1v = primeira volta (rodada), 2v = segunda volta.
 
     Examples:
         >>> from pyield import bc
@@ -344,46 +352,6 @@ def auctions(
         │ 2025-08-19  ┆ 2025-08-20      ┆ Venda       ┆ 194           ┆ … ┆ 500542                  ┆ 2071654327    ┆ 2245673       ┆ 2073900000       │
         │ 2025-08-19  ┆ 2025-08-20      ┆ Venda       ┆ 194           ┆ … ┆ 500000                  ┆ 2010700000    ┆ 0             ┆ 2010700000       │
         └─────────────┴─────────────────┴─────────────┴───────────────┴───┴─────────────────────────┴───────────────┴───────────────┴──────────────────┘
-
-    Notes:
-        1v = Primeira Volta (Rodada)
-        2v = Segunda Volta (Rodada)
-
-    Colunas do DataFrame:
-        - data_leilao (Date): data do leilão.
-        - data_liquidacao (Date): data de liquidação do leilão.
-        - tipo_leilao (String): tipo de leilão (ex: "Venda" ou "Compra").
-        - numero_edital (Int64): edital normativo associado ao leilão.
-        - tipo_publico (String): categoria do comprador.
-        - titulo (String): tipo do título (ex: "LTN", "LFT", "NTN-B", "NTN-F").
-        - codigo_selic (Int64): código do título no sistema Selic.
-        - data_vencimento (Date): data de vencimento do título.
-        - dias_uteis (Int32): dias úteis entre a liquidação e o vencimento.
-        - duration (Float64): duração de Macaulay em anos.
-        - prazo_medio (Float64): prazo médio do título em anos.
-        - pu_medio (Float64): preço unitário médio no leilão.
-        - pu_corte (Float64): preço unitário de corte.
-        - taxa_media (Float64): taxa de juros média (formato decimal).
-        - taxa_corte (Float64): taxa de corte (formato decimal).
-        - dv01_1v (Float64): DV01 da 1ª volta em R$.
-        - dv01_2v (Float64): DV01 da 2ª volta em R$.
-        - dv01_total (Float64): DV01 total do leilão em R$.
-        - ptax (Float64): taxa PTAX utilizada na conversão para USD.
-        - dv01_1v_usd (Float64): DV01 da 1ª volta em USD.
-        - dv01_2v_usd (Float64): DV01 da 2ª volta em USD.
-        - dv01_total_usd (Float64): DV01 total em USD.
-        - quantidade_liquidada_1v (Int64): quantidade liquidada na 1ª volta.
-        - quantidade_liquidada_2v (Int64): quantidade liquidada na 2ª volta.
-        - quantidade_liquidada_total (Int64): quantidade total liquidada.
-        - quantidade_ofertada_1v (Int64): quantidade ofertada na 1ª volta.
-        - quantidade_ofertada_2v (Int64): quantidade ofertada na 2ª volta.
-        - quantidade_ofertada_total (Int64): quantidade total ofertada.
-        - quantidade_aceita_1v (Int64): quantidade aceita na 1ª volta.
-        - quantidade_aceita_2v (Int64): quantidade aceita na 2ª volta.
-        - quantidade_aceita_total (Int64): quantidade total aceita.
-        - financeiro_1v (Int64): valor financeiro da 1ª volta em R$.
-        - financeiro_2v (Int64): valor financeiro da 2ª volta em R$.
-        - financeiro_total (Int64): valor financeiro total em R$.
     """
     url = _montar_url(inicio=start, fim=end, tipo_leilao=auction_type)
     dados = _buscar_csv(url)

{pyield-0.46.0 → pyield-0.46.1}/pyield/bc/ptax_api.py

@@ -9,10 +9,14 @@ cotacaoCompra, cotacaoVenda, dataHoraCotacao
 2814         , 2828        , 1984-12-03 11:29:00.0
 2814         , 2828        , 1984-12-03 16:38:00.0
 2867         , 2881        , 1984-12-04 11:17:00.0
+"0,843"      , "0,845"     , 1995-01-02 18:20:00.0
 ...
 "5,4272"     , "5,4278"    , 2025-09-08 13:09:40.608
 "5,4272"     , "5,4278"    , 2025-09-09 13:07:27.786
 "5,4117"     , "5,4123"    , 2025-09-10 13:06:29.196
+
+ATENÇÃO: a fração de segundo varia entre .0 (datas antigas) e .608
+(datas recentes). Usar %.f (variável) no parsing, nunca %.3f (fixo).
 """
 
 import datetime as dt
@@ -60,7 +64,7 @@ def _processar_df(df: pl.DataFrame) -> pl.DataFrame:
             cotacao_compra=float_br("cotacaoCompra"),
             cotacao_venda=float_br("cotacaoVenda"),
             data_hora=pl.col("dataHoraCotacao").str.to_datetime(
-                format="%Y-%m-%d %H:%M:%S%.3f", strict=False
+                format="%Y-%m-%d %H:%M:%S%.f", strict=False
             ),
         )
         .with_columns(
@@ -121,13 +125,27 @@ def ptax_series(
         ┌────────────┬─────────────────────────┬────────────────┬───────────────┬───────────────┐
         │ data       ┆ data_hora               ┆ cotacao_compra ┆ cotacao_venda ┆ cotacao_media │
         │ ---        ┆ ---                     ┆ ---            ┆ ---           ┆ ---           │
-        │ date       ┆ datetime[ms]            ┆ f64            ┆ f64           ┆ f64           │
+        │ date       ┆ datetime[μs]            ┆ f64            ┆ f64           ┆ f64           │
         ╞════════════╪═════════════════════════╪════════════════╪═══════════════╪═══════════════╡
         │ 2025-04-22 ┆ 2025-04-22 13:09:35.629 ┆ 5.749          ┆ 5.7496        ┆ 5.7493        │
         │ 2025-04-23 ┆ 2025-04-23 13:06:30.443 ┆ 5.6874         ┆ 5.688         ┆ 5.6877        │
         │ 2025-04-24 ┆ 2025-04-24 13:04:29.639 ┆ 5.6732         ┆ 5.6738        ┆ 5.6735        │
         │ 2025-04-25 ┆ 2025-04-25 13:09:26.592 ┆ 5.684          ┆ 5.6846        ┆ 5.6843        │
         └────────────┴─────────────────────────┴────────────────┴───────────────┴───────────────┘
+
+        >>> bc.ptax_series(start="02-01-1995", end="06-01-1995")
+        shape: (5, 5)
+        ┌────────────┬─────────────────────┬────────────────┬───────────────┬───────────────┐
+        │ data       ┆ data_hora           ┆ cotacao_compra ┆ cotacao_venda ┆ cotacao_media │
+        │ ---        ┆ ---                 ┆ ---            ┆ ---           ┆ ---           │
+        │ date       ┆ datetime[μs]        ┆ f64            ┆ f64           ┆ f64           │
+        ╞════════════╪═════════════════════╪════════════════╪═══════════════╪═══════════════╡
+        │ 1995-01-02 ┆ 1995-01-02 18:20:00 ┆ 0.843          ┆ 0.845         ┆ 0.844         │
+        │ 1995-01-03 ┆ 1995-01-03 18:25:00 ┆ 0.844          ┆ 0.846         ┆ 0.845         │
+        │ 1995-01-04 ┆ 1995-01-04 18:12:00 ┆ 0.844          ┆ 0.846         ┆ 0.845         │
+        │ 1995-01-05 ┆ 1995-01-05 18:07:00 ┆ 0.842          ┆ 0.844         ┆ 0.843         │
+        │ 1995-01-06 ┆ 1995-01-06 18:12:00 ┆ 0.839          ┆ 0.841         ┆ 0.84          │
+        └────────────┴─────────────────────┴────────────────┴───────────────┴───────────────┘
     """
     if start:
         start = cv.converter_datas(start)

{pyield-0.46.0 → pyield-0.46.1}/pyield/bc/trades_intraday.py

@@ -49,7 +49,7 @@ def _processar_df(df: pl.DataFrame) -> pl.DataFrame:
     """Filtra registros, converte tipos e reordena colunas."""
     agora = clock.now()
     return df.filter(pl.col("//1") == "1").select(
-        coletado_em=agora,
+        data_hora_consulta=agora,
         data_liquidacao=agora.date(),
         titulo=pl.col("sigla").str.strip_chars(),
         codigo_selic=inteiro_br("código título"),
@@ -106,7 +106,7 @@ def tpf_intraday_trades() -> pl.DataFrame:
             estiver fechado ou ocorrer erro.
 
     Output Columns:
-        - coletado_em (Datetime): timestamp da coleta (BRT).
+        - data_hora_consulta (Datetime): data e hora da consulta (BRT).
         - data_liquidacao (Date): data de liquidação à vista.
         - titulo (String): sigla do título (ex.: LFT, LTN, NTN-B).
         - codigo_selic (Int64): código SELIC do título.

{pyield-0.46.0 → pyield-0.46.1}/pyield/bc/trades_monthly.py

@@ -72,7 +72,7 @@ def _processar_df(df: pl.DataFrame) -> pl.DataFrame:
             data_liquidacao=pl.col("DATA MOV").str.to_date("%d/%m/%Y", strict=False),
             titulo=pl.col("SIGLA"),
             codigo_selic=pl.col("CODIGO").cast(pl.Int64),
-            codigo_isin=pl.col("CODIGO ISIN"),
+            isin=pl.col("CODIGO ISIN"),
             data_emissao=pl.col("EMISSAO").str.to_date("%d/%m/%Y", strict=False),
             data_vencimento=pl.col("VENCIMENTO").str.to_date("%d/%m/%Y", strict=False),
             operacoes=pl.col("NUM DE OPER").cast(pl.Int64),
@@ -120,7 +120,7 @@ def tpf_monthly_trades(target_date: DateLike, extragroup: bool = False) -> pl.Da
         - data_liquidacao (Date): data de liquidação da negociação.
         - titulo (str): sigla do título (ex: LFT, LTN, NTN-B, NTN-F).
         - codigo_selic (Int64): código único no sistema Selic.
-        - codigo_isin (str): código ISIN (International Securities Id Number).
+        - isin (str): código ISIN.
         - data_emissao (Date): data de emissão do título.
         - data_vencimento (Date): data de vencimento do título.
         - operacoes (Int64): número total de operações realizadas.
@@ -130,11 +130,11 @@ def tpf_monthly_trades(target_date: DateLike, extragroup: bool = False) -> pl.Da
         - pu_medio (Float64): preço unitário médio.
         - pu_maximo (Float64): preço unitário máximo.
         - pu_lastro (Float64): PU lastro.
-        - valor_par (Float64): valor nominal atualizado (VNA) do título.
+        - valor_par (Float64): valor par do título.
         - taxa_minima (Float64): taxa mínima.
         - taxa_media (Float64): taxa média.
         - taxa_maxima (Float64): taxa máxima.
-        - operacoes_corretagem (Int64): subconjunto de operacoes com corretagem.
+        - operacoes_corretagem (Int64): subconjunto de operações com corretagem.
         - quantidade_corretagem (Int64): subconjunto de quantidade com corretagem.
 
     Notes:

pyield-0.46.0/pyield/__about__.py

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