Metadata-Version: 2.3
Name: pyield
Version: 0.50.0
Summary: A Python library for analysis of fixed income instruments in Brazil
Keywords: fixed-income,brazil,finance,analysis,bonds
Author: Carlos Carvalho
Author-email: Carlos Carvalho <cr.cj@outlook.com>
License: MIT License
         
         Copyright (c) 2023 Carlos Carvalho
         
         Permission is hereby granted, free of charge, to any person obtaining a copy
         of this software and associated documentation files (the "Software"), to deal
         in the Software without restriction, including without limitation the rights
         to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
         copies of the Software, and to permit persons to whom the Software is
         furnished to do so, subject to the following conditions:
         
         The above copyright notice and this permission notice shall be included in all
         copies or substantial portions of the Software.
         
         THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
         IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
         FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
         AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
         LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
         OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
         SOFTWARE.
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Topic :: Office/Business :: Financial :: Investment
Requires-Dist: polars>=1.39.0
Requires-Dist: lxml>=6.0.0
Requires-Dist: requests>=2.31.0
Requires-Dist: fastexcel>=0.19.0
Requires-Dist: tzdata>=2024.1 ; sys_platform == 'win32'
Requires-Python: >=3.12
Project-URL: Homepage, https://github.com/crdcj/PYield
Project-URL: Documentation, https://crdcj.github.io/PYield
Project-URL: Source, https://github.com/crdcj/PYield
Project-URL: Bug Tracker, https://github.com/crdcj/PYield/issues
Description-Content-Type: text/markdown

[![PyPI version](https://img.shields.io/pypi/v/pyield.svg)](https://pypi.python.org/pypi/pyield)
[![Made with Python](https://img.shields.io/badge/Python->=3.12-blue?logo=python&logoColor=white)](https://python.org "Go to Python homepage")
[![License](https://img.shields.io/badge/License-MIT-blue)](https://github.com/crdcj/PYield/blob/main/LICENSE)
[![Docs](https://img.shields.io/badge/docs-GitHub%20Pages-blue?logo=readthedocs&logoColor=white)](https://crdcj.github.io/PYield/)
[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/crdcj/PYield/blob/main/examples/pyield_quickstart.ipynb)

# PYield: Toolkit de Renda Fixa Brasileira

Português | [English](https://github.com/crdcj/PYield/blob/main/README.en.md)

PYield é uma biblioteca Python voltada para análise de títulos públicos brasileiros. Ela busca e processa dados da ANBIMA, BCB, IBGE, B3 e **Tesouro Nacional**, retornando DataFrames do Polars para pipelines rápidos e com tipagem consistente.

Embora inclua dados e ferramentas de outros mercados (como DI1, DAP e PTAX), esses recursos são auxiliares para o objetivo central: análise, precificação e acompanhamento de títulos públicos.

## Instalação

```sh
pip install pyield
```

## Início Rápido

```python
import pyield as yd

# Dias úteis (base de todos os cálculos)
yd.du.contar("02-01-2025", "15-01-2025")  # -> 9
yd.du.deslocar("29-12-2023", 1)           # -> datetime.date(2024, 1, 2)

# Curva de DI Futuro
df = yd.futuro.historico("31-05-2024", "DI1")
# Colunas: data_referencia, codigo_negociacao, data_vencimento, dias_uteis, taxa_ajuste, ...

# Interpolação de taxas (flat forward, convenção 252 dias úteis/ano)
interp = yd.Interpolador(df["dias_uteis"], df["taxa_ajuste"], metodo="flat_forward")
interp(45)       # -> 0.04833...
interp([30, 60]) # -> Series do Polars com taxas interpoladas

# Precificação de títulos públicos
yd.ntnb.cotacao("31-05-2024", "15-05-2035", 0.061490)  # -> 99.3651

# Indicadores do BCB
yd.selic.over("31-05-2024")  # -> 0.000414...
```

Um notebook no Colab com mais exemplos:

[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/crdcj/PYield/blob/main/examples/pyield_quickstart.ipynb)

## Blocos Principais

### Dias Úteis (`du`)

O módulo `du` é a base do PYield. Todos os cálculos com datas (preço, duration, taxas a termo) dependem da contagem correta de dias úteis com feriados brasileiros.

```python
from pyield import du

# Conta dias úteis (início inclusivo, fim exclusivo)
du.contar("29-12-2023", "02-01-2024")  # -> 1

# Avança N dias úteis
du.deslocar("29-12-2023", 1)  # -> datetime.date(2024, 1, 2)

# Ajusta dia não útil para o próximo dia útil
du.deslocar("30-12-2023", 0)  # -> datetime.date(2024, 1, 2)

# Gera intervalo de dias úteis
du.gerar("22-12-2023", "02-01-2024")
# -> Series: [2023-12-22, 2023-12-26, 2023-12-27, 2023-12-28, 2023-12-29, 2024-01-02]

# Verifica se a data é dia útil
du.eh_dia_util("25-12-2023")  # -> False (Natal)
```

Todas as funções suportam operações vetorizadas com listas, Series ou arrays.

### Interpolação de Taxas (`Interpolador`)

A classe `Interpolador` interpola taxas usando a convenção de 252 dias úteis/ano, padrão no mercado brasileiro.

```python
from pyield import Interpolador

dias_uteis = [30, 60, 90]
taxas = [0.045, 0.05, 0.055]

# Interpolação flat forward (padrão de mercado)
interp = Interpolador(dias_uteis, taxas, metodo="flat_forward")
interp(45)  # -> 0.04833...

# Interpolação linear
linear = Interpolador(dias_uteis, taxas, metodo="linear")
linear(45)  # -> 0.0475

# Vetorizado
interp([15, 45, 75])  # -> pl.Series com 3 taxas

# Extrapolação (desabilitada por padrão, retorna NaN)
interp(100)  # -> nan
Interpolador(dias_uteis, taxas, metodo="flat_forward", extrapolar=True)(100)  # -> 0.055
```

### Taxas a Termo (`forward`, `forwards`)

Calcula taxas a termo a partir de curvas spot:

Convenção utilizada:

- `fwd_k = fwd_{j->k}` (forward do vértice `j` para `k`)
- `f_k = 1 + tx_k` (fator de capitalização no vértice `k`)
- `fwd_k = (f_k^au_k / f_j^au_j)^(1 / (au_k - au_j)) - 1`, com `au = du / 252`

```python
from pyield import forward, forwards

# Taxa a termo única entre dois pontos
forward(10, 20, 0.05, 0.06)  # -> 0.0700952...

# Curva a termo vetorizada a partir de taxas spot
dias_uteis = [10, 20, 30]
taxas = [0.05, 0.06, 0.07]
forwards(dias_uteis, taxas)  # -> Series: [0.05, 0.070095, 0.090284]
```

## Visão Geral dos Módulos

| Módulo | Finalidade |
|--------|---------|
| `du` | Cálculos com dias úteis considerando feriados brasileiros |
| `futuro` | Dados de futuros (DI1, DDI, DAP, DOL, WDO, IND, WIN e outros) |
| `tpf` | Taxas, vencimentos, estoque, leilões, benchmarks, RMD e negociações de TPFs |
| `di1` | Curva DI1 interpolada e datas de negociação disponíveis |
| `Interpolador` | Interpolação de taxas (flat_forward, linear) |
| `forward` / `forwards` | Cálculo de taxas a termo |
| `ltn`, `ntnb`, `ntnf`, `lft`, `ntnc` | Precificação e análise dos títulos públicos principais |
| `ntnb1`, `ntnbprinc` | Títulos adicionais (NTN-B1, NTN-B Principal) |
| `selic` | Dados da taxa Selic, COPOM, compromissadas do BCB, CPM e probabilidades implícitas |
| `ipca` | Dados de inflação (histórico e projeções) |
| `hoje` / `agora` | Data/hora atual no Brasil (America/Sao_Paulo) |

## Títulos Públicos

```python
from pyield import ltn, ntnb, ntnf

# Busca taxas indicativas da ANBIMA
ltn.dados("23-08-2024")  # -> DataFrame com títulos LTN
ntnb.dados("23-08-2024")  # -> DataFrame com títulos NTN-B

# Calcula cotação do título (base 100)
ntnb.cotacao("31-05-2024", "15-05-2035", 0.061490)  # -> 99.3651
ntnb.cotacao("31-05-2024", "15-08-2060", 0.061878)  # -> 99.5341

# Prêmio sobre o DI (pontos_base=True multiplica por 10.000)
ntnf.premio("30-05-2025", pontos_base=True)
# -> DataFrame: titulo, data_vencimento, premio
```

## Dados de Futuros

```python
import pyield as yd

# DI1 (Futuro de Depósito Interfinanceiro)
yd.futuro.historico("31-05-2024", "DI1")

# Outros contratos disponíveis no cache histórico:
# - Juros: DI1, DDI, FRC, FRO, DAP
# - Moedas: DOL, WDO
# - Índices: IND, WIN
yd.futuro.historico("31-05-2024", "DAP")

# Múltiplas datas de uma vez
yd.futuro.historico(["29-05-2024", "31-05-2024"], "DI1")

# Dados intradia (quando o mercado estiver aberto)
yd.futuro.intradia("DI1")  # Retorna dados ao vivo durante o pregão
```

## Tratamento de Datas

PYield aceita entradas de data flexíveis (`DateLike`):
- Strings: `"31-05-2024"`, `"31/05/2024"`, `"2024-05-31"`
- `datetime.date`, `datetime.datetime`

Funções escalares retornam `datetime.date`. Funções vetorizadas retornam `polars.Series`.

O parsing de strings é elemento a elemento entre os formatos aceitos. Strings
inválidas são convertidas para valores nulos (`None` em saídas escalares e `null`
em saídas vetorizadas).

Tratamento de nulos: funções escalares retornam `float('nan')` para entradas ausentes
(propaga nos cálculos). Funções vetorizadas propagam `null` elemento a elemento.

```python
from pyield import ntnb, du

ntnb.cotacao(None, "15-05-2035", 0.06149)  # -> nan
du.contar(["01-01-2024", None], "01-02-2024")  # -> Series: [22, null]
```

Consultas sem dados disponíveis (data futura, feriado, fim de semana ou
fonte indisponível) retornam DataFrame vazio ou `nan`, sem lançar exceção:

```python
import pyield as yd

yd.futuro.historico("01-01-2030", "DI1").is_empty()  # -> True
yd.tpf.secundario_mensal("01-01-2030").is_empty()    # -> True
yd.ptax("25-12-2025")                                # -> nan
```

## Quebra de API em leilões de TPF (v0.50.0)

`yd.tpf.leilao(data)` foi substituída por `yd.tpf.leiloes(...)`.
A nova função usa parâmetros nomeados e permite consultar uma data específica,
uma lista de datas ou um período:

```python
yd.tpf.leiloes(data="19-05-2026")
yd.tpf.leiloes(data=["14-05-2026", "19-05-2026"])
yd.tpf.leiloes(inicio="01-05-2026")
yd.tpf.leiloes(inicio="01-05-2026", fim="19-05-2026")
```

## Mapa da API

Veja o [mapa completo da API](https://crdcj.github.io/PYield/api-map/) na
documentação.

| Componente | Tipo | Finalidade |
|---|---|---|
| `yd.du` | módulo | Dias úteis e calendário brasileiro |
| `yd.futuro` | módulo | Contratos futuros da B3 |
| `yd.di1` | módulo | Curva DI1 e interpolação |
| `yd.tpf` | módulo | Títulos públicos federais |
| `yd.selic` | módulo | Selic, COPOM e política monetária |
| `yd.ipca` | módulo | IPCA histórico e projetado |
| `yd.lft` | módulo | LFT |
| `yd.ltn` | módulo | LTN |
| `yd.ntnb` | módulo | NTN-B |
| `yd.ntnb1` | módulo | NTN-B1 |
| `yd.ntnbprinc` | módulo | NTN-B Principal |
| `yd.ntnc` | módulo | NTN-C |
| `yd.ntnf` | módulo | NTN-F |
| `yd.ptax(data)` | função | PTAX para uma data |
| `yd.ptax_serie(inicio, fim)` | função | Série histórica da PTAX |
| `yd.di_over(data)` | função | Taxa DI Over |
| `yd.forward(...)` | função | Taxa a termo entre dois vértices |
| `yd.forwards(...)` | função | Curva de taxas a termo |
| `yd.Interpolador` | classe | Interpolação de curvas |
| `yd.hoje()` | função | Data atual no Brasil |
| `yd.agora()` | função | Data e hora atual no Brasil |

## Documentação

Documentação completa: [crdcj.github.io/PYield](https://crdcj.github.io/PYield/)

## Testes

```sh
pytest
```
