PYield 0.42.2__tar.gz → 0.42.3__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- pyield-0.42.3/.gitignore +21 -0
- pyield-0.42.3/PKG-INFO +237 -0
- pyield-0.42.3/README.md +195 -0
- pyield-0.42.3/pyield/__about__.py +1 -0
- {pyield-0.42.2 → pyield-0.42.3}/pyield/anbima/ima.py +4 -6
- {pyield-0.42.2 → pyield-0.42.3}/pyield/anbima/imaq.py +10 -12
- {pyield-0.42.2 → pyield-0.42.3}/pyield/anbima/tpf.py +3 -3
- pyield-0.42.3/pyield/b3/di_over.py +76 -0
- {pyield-0.42.2 → pyield-0.42.3}/pyield/b3/futures/core.py +1 -2
- {pyield-0.42.2 → pyield-0.42.3}/pyield/bc/trades_monthly.py +2 -4
- pyield-0.42.3/pyield/ipca/projected.py +117 -0
- {pyield-0.42.2 → pyield-0.42.3}/pyield/tn/ltn.py +6 -12
- {pyield-0.42.2 → pyield-0.42.3}/pyield/tn/ntnb.py +10 -15
- {pyield-0.42.2 → pyield-0.42.3}/pyield/tn/ntnb1.py +11 -14
- {pyield-0.42.2 → pyield-0.42.3}/pyield/tn/ntnbprinc.py +7 -12
- {pyield-0.42.2 → pyield-0.42.3}/pyield/tn/ntnc.py +3 -4
- {pyield-0.42.2 → pyield-0.42.3}/pyield/tn/ntnf.py +5 -9
- {pyield-0.42.2 → pyield-0.42.3}/pyield/types.py +6 -11
- {pyield-0.42.2 → pyield-0.42.3}/pyproject.toml +5 -4
- pyield-0.42.2/.gitignore +0 -40
- pyield-0.42.2/PKG-INFO +0 -309
- pyield-0.42.2/README.md +0 -268
- pyield-0.42.2/pyield/__about__.py +0 -1
- pyield-0.42.2/pyield/b3/di_over.py +0 -75
- pyield-0.42.2/pyield/ipca/projected.py +0 -97
- {pyield-0.42.2 → pyield-0.42.3}/LICENSE +0 -0
- {pyield-0.42.2 → pyield-0.42.3}/pyield/__init__.py +0 -0
- {pyield-0.42.2 → pyield-0.42.3}/pyield/anbima/__init__.py +0 -0
- {pyield-0.42.2 → pyield-0.42.3}/pyield/anbima/difusao.py +0 -0
- {pyield-0.42.2 → pyield-0.42.3}/pyield/anbima/ettj_intraday.py +0 -0
- {pyield-0.42.2 → pyield-0.42.3}/pyield/anbima/ettj_last.py +0 -0
- {pyield-0.42.2 → pyield-0.42.3}/pyield/b3/__init__.py +0 -0
- {pyield-0.42.2 → pyield-0.42.3}/pyield/b3/common.py +0 -0
- {pyield-0.42.2 → pyield-0.42.3}/pyield/b3/di1.py +0 -0
- {pyield-0.42.2 → pyield-0.42.3}/pyield/b3/futures/__init__.py +0 -0
- {pyield-0.42.2 → pyield-0.42.3}/pyield/b3/futures/historical/core.py +0 -0
- {pyield-0.42.2 → pyield-0.42.3}/pyield/b3/futures/historical/historical_new.py +0 -0
- {pyield-0.42.2 → pyield-0.42.3}/pyield/b3/futures/historical/historical_old.py +0 -0
- {pyield-0.42.2 → pyield-0.42.3}/pyield/b3/futures/intraday.py +0 -0
- {pyield-0.42.2 → pyield-0.42.3}/pyield/b3/price_report.py +0 -0
- {pyield-0.42.2 → pyield-0.42.3}/pyield/bc/__init__.py +0 -0
- {pyield-0.42.2 → pyield-0.42.3}/pyield/bc/auction.py +0 -0
- {pyield-0.42.2 → pyield-0.42.3}/pyield/bc/ptax_api.py +0 -0
- {pyield-0.42.2 → pyield-0.42.3}/pyield/bc/rates.py +0 -0
- {pyield-0.42.2 → pyield-0.42.3}/pyield/bc/repo.py +0 -0
- {pyield-0.42.2 → pyield-0.42.3}/pyield/bc/trades_intraday.py +0 -0
- {pyield-0.42.2 → pyield-0.42.3}/pyield/bc/vna.py +0 -0
- {pyield-0.42.2 → pyield-0.42.3}/pyield/bday/__init__.py +0 -0
- {pyield-0.42.2 → pyield-0.42.3}/pyield/bday/core.py +0 -0
- {pyield-0.42.2 → pyield-0.42.3}/pyield/bday/holidays/__init__.py +0 -0
- {pyield-0.42.2 → pyield-0.42.3}/pyield/bday/holidays/br_holidays_new.txt +0 -0
- {pyield-0.42.2 → pyield-0.42.3}/pyield/bday/holidays/br_holidays_old.txt +0 -0
- {pyield-0.42.2 → pyield-0.42.3}/pyield/bday/holidays/brholidays.py +0 -0
- {pyield-0.42.2 → pyield-0.42.3}/pyield/clock.py +0 -0
- {pyield-0.42.2 → pyield-0.42.3}/pyield/conftest.py +0 -0
- {pyield-0.42.2 → pyield-0.42.3}/pyield/converters.py +0 -0
- {pyield-0.42.2 → pyield-0.42.3}/pyield/data_cache.py +0 -0
- {pyield-0.42.2 → pyield-0.42.3}/pyield/fwd.py +0 -0
- {pyield-0.42.2 → pyield-0.42.3}/pyield/interpolator.py +0 -0
- {pyield-0.42.2 → pyield-0.42.3}/pyield/ipca/__init__.py +0 -0
- {pyield-0.42.2 → pyield-0.42.3}/pyield/ipca/historical.py +0 -0
- {pyield-0.42.2 → pyield-0.42.3}/pyield/py.typed +0 -0
- {pyield-0.42.2 → pyield-0.42.3}/pyield/retry.py +0 -0
- {pyield-0.42.2 → pyield-0.42.3}/pyield/tn/__init__.py +0 -0
- {pyield-0.42.2 → pyield-0.42.3}/pyield/tn/auctions.py +0 -0
- {pyield-0.42.2 → pyield-0.42.3}/pyield/tn/benchmark.py +0 -0
- {pyield-0.42.2 → pyield-0.42.3}/pyield/tn/lft.py +0 -0
- {pyield-0.42.2 → pyield-0.42.3}/pyield/tn/pre.py +0 -0
- {pyield-0.42.2 → pyield-0.42.3}/pyield/tn/tools.py +0 -0
pyield-0.42.3/.gitignore
ADDED
pyield-0.42.3/PKG-INFO
ADDED
|
@@ -0,0 +1,237 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: PYield
|
|
3
|
+
Version: 0.42.3
|
|
4
|
+
Summary: A Python library for analysis of fixed income instruments in Brazil
|
|
5
|
+
Project-URL: Source, https://github.com/crdcj/PYield
|
|
6
|
+
Author-email: Carlos Carvalho <cr.cj@outlook.com>
|
|
7
|
+
License: MIT License
|
|
8
|
+
|
|
9
|
+
Copyright (c) 2023 Carlos Carvalho
|
|
10
|
+
|
|
11
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
12
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
13
|
+
in the Software without restriction, including without limitation the rights
|
|
14
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
15
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
16
|
+
furnished to do so, subject to the following conditions:
|
|
17
|
+
|
|
18
|
+
The above copyright notice and this permission notice shall be included in all
|
|
19
|
+
copies or substantial portions of the Software.
|
|
20
|
+
|
|
21
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
22
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
23
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
24
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
25
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
26
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
27
|
+
SOFTWARE.
|
|
28
|
+
License-File: LICENSE
|
|
29
|
+
Keywords: analysis,bonds,brazil,finance,fixed-income
|
|
30
|
+
Classifier: Intended Audience :: Financial and Insurance Industry
|
|
31
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
32
|
+
Classifier: Operating System :: OS Independent
|
|
33
|
+
Classifier: Programming Language :: Python :: 3
|
|
34
|
+
Classifier: Topic :: Office/Business :: Financial :: Investment
|
|
35
|
+
Requires-Python: >=3.12
|
|
36
|
+
Requires-Dist: pandas[html]>=2.0.0
|
|
37
|
+
Requires-Dist: polars[pyarrow]>=1.33.0
|
|
38
|
+
Requires-Dist: python-dateutil>=2.8.0
|
|
39
|
+
Requires-Dist: requests>=2.31.0
|
|
40
|
+
Requires-Dist: tenacity>=9.0.0
|
|
41
|
+
Description-Content-Type: text/markdown
|
|
42
|
+
|
|
43
|
+
[](https://pypi.python.org/pypi/pyield)
|
|
44
|
+
[](https://python.org "Go to Python homepage")
|
|
45
|
+
[](https://github.com/crdcj/PYield/blob/main/LICENSE)
|
|
46
|
+
|
|
47
|
+
# PYield: Brazilian Fixed Income Toolkit
|
|
48
|
+
|
|
49
|
+
PYield is a Python library for analyzing Brazilian fixed income instruments. It fetches and processes data from ANBIMA, BCB, IBGE and B3, returning Polars DataFrames for fast, type-safe data pipelines.
|
|
50
|
+
|
|
51
|
+
## Installation
|
|
52
|
+
|
|
53
|
+
```sh
|
|
54
|
+
pip install pyield
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
## Quick Start
|
|
58
|
+
|
|
59
|
+
```python
|
|
60
|
+
import pyield as yd
|
|
61
|
+
|
|
62
|
+
# Business days (foundation of all calculations)
|
|
63
|
+
yd.bday.count("02-01-2025", "15-01-2025") # -> 9
|
|
64
|
+
yd.bday.offset("29-12-2023", 1) # -> datetime.date(2024, 1, 2)
|
|
65
|
+
|
|
66
|
+
# DI Futures curve
|
|
67
|
+
df = yd.futures("31-05-2024", "DI1")
|
|
68
|
+
# Columns: TradeDate, TickerSymbol, ExpirationDate, BDaysToExp, SettlementRate, ...
|
|
69
|
+
|
|
70
|
+
# Rate interpolation (flat forward, 252 bdays/year convention)
|
|
71
|
+
interp = yd.Interpolator("flat_forward", df["BDaysToExp"], df["SettlementRate"])
|
|
72
|
+
interp(45) # -> 0.04833...
|
|
73
|
+
interp([30, 60]) # -> pl.Series with interpolated rates
|
|
74
|
+
|
|
75
|
+
# Treasury bond pricing
|
|
76
|
+
yd.ntnb.quotation("31-05-2024", "15-05-2035", 0.061490) # -> 99.3651
|
|
77
|
+
|
|
78
|
+
# BCB indicators
|
|
79
|
+
yd.bc.selic_over("31-05-2024") # -> 0.000414...
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
A Colab notebook with more examples is available:
|
|
83
|
+
|
|
84
|
+
[](https://colab.research.google.com/github/crdcj/PYield/blob/main/examples/pyield_quickstart.ipynb)
|
|
85
|
+
|
|
86
|
+
## Core Building Blocks
|
|
87
|
+
|
|
88
|
+
### Business Days (`bday`)
|
|
89
|
+
|
|
90
|
+
The `bday` module is the foundation of PYield. All date calculations (pricing, duration, forward rates) depend on accurate business day counting with Brazilian holidays.
|
|
91
|
+
|
|
92
|
+
```python
|
|
93
|
+
from pyield import bday
|
|
94
|
+
|
|
95
|
+
# Count business days (start inclusive, end exclusive)
|
|
96
|
+
bday.count("29-12-2023", "02-01-2024") # -> 1
|
|
97
|
+
|
|
98
|
+
# Offset by N business days
|
|
99
|
+
bday.offset("29-12-2023", 1) # -> datetime.date(2024, 1, 2)
|
|
100
|
+
|
|
101
|
+
# Adjust non-business day to next business day
|
|
102
|
+
bday.offset("30-12-2023", 0) # -> datetime.date(2024, 1, 2)
|
|
103
|
+
|
|
104
|
+
# Generate business day range
|
|
105
|
+
bday.generate("22-12-2023", "02-01-2024")
|
|
106
|
+
# -> Series: [2023-12-22, 2023-12-26, 2023-12-27, 2023-12-28, 2023-12-29, 2024-01-02]
|
|
107
|
+
|
|
108
|
+
# Check if date is business day
|
|
109
|
+
bday.is_business_day("25-12-2023") # -> False (Christmas)
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
All functions support vectorized operations with lists, Series, or arrays.
|
|
113
|
+
|
|
114
|
+
### Rate Interpolation (`Interpolator`)
|
|
115
|
+
|
|
116
|
+
The `Interpolator` class interpolates interest rates using the 252 business days/year convention standard in Brazil.
|
|
117
|
+
|
|
118
|
+
```python
|
|
119
|
+
from pyield import Interpolator
|
|
120
|
+
|
|
121
|
+
known_bdays = [30, 60, 90]
|
|
122
|
+
known_rates = [0.045, 0.05, 0.055]
|
|
123
|
+
|
|
124
|
+
# Flat forward interpolation (market standard)
|
|
125
|
+
interp = Interpolator("flat_forward", known_bdays, known_rates)
|
|
126
|
+
interp(45) # -> 0.04833...
|
|
127
|
+
|
|
128
|
+
# Linear interpolation
|
|
129
|
+
linear = Interpolator("linear", known_bdays, known_rates)
|
|
130
|
+
linear(45) # -> 0.0475
|
|
131
|
+
|
|
132
|
+
# Vectorized
|
|
133
|
+
interp([15, 45, 75]) # -> pl.Series with 3 rates
|
|
134
|
+
|
|
135
|
+
# Extrapolation (disabled by default, returns NaN)
|
|
136
|
+
interp(100) # -> nan
|
|
137
|
+
Interpolator("flat_forward", known_bdays, known_rates, extrapolate=True)(100) # -> 0.055
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
### Forward Rates (`forward`, `forwards`)
|
|
141
|
+
|
|
142
|
+
Calculate forward rates from spot curves:
|
|
143
|
+
|
|
144
|
+
```python
|
|
145
|
+
from pyield import forward, forwards
|
|
146
|
+
|
|
147
|
+
# Single forward rate between two points
|
|
148
|
+
forward(bday1=10, bday2=20, rate1=0.05, rate2=0.06) # -> 0.0700952...
|
|
149
|
+
|
|
150
|
+
# Vectorized forward curve from spot rates
|
|
151
|
+
bdays = [10, 20, 30]
|
|
152
|
+
rates = [0.05, 0.06, 0.07]
|
|
153
|
+
forwards(bdays, rates) # -> Series: [0.05, 0.070095, 0.090284]
|
|
154
|
+
```
|
|
155
|
+
|
|
156
|
+
## Modules Overview
|
|
157
|
+
|
|
158
|
+
| Module | Purpose |
|
|
159
|
+
|--------|---------|
|
|
160
|
+
| `bday` | Business day calendar with Brazilian holidays |
|
|
161
|
+
| `futures` | B3 futures data (DI1, DDI, FRC, DAP, DOL, WDO, IND, WIN) |
|
|
162
|
+
| `Interpolator` | Rate interpolation (flat_forward, linear) |
|
|
163
|
+
| `forward` / `forwards` | Forward rate calculation |
|
|
164
|
+
| `ltn`, `ntnb`, `ntnf`, `lft`, `ntnc` | Treasury bond pricing and analytics |
|
|
165
|
+
| `anbima` | ANBIMA data (TPF prices, yield curves, IMA indices) |
|
|
166
|
+
| `bc` | BCB indicators (SELIC, PTAX, repo rates, VNA) |
|
|
167
|
+
| `ipca` | Inflation data (historical and projections) |
|
|
168
|
+
| `today` / `now` | Current date/time in Brazil (America/Sao_Paulo) |
|
|
169
|
+
|
|
170
|
+
## Treasury Bonds
|
|
171
|
+
|
|
172
|
+
```python
|
|
173
|
+
from pyield import ltn, ntnb, ntnf
|
|
174
|
+
|
|
175
|
+
# Fetch ANBIMA indicative rates
|
|
176
|
+
ltn.data("23-08-2024") # -> DataFrame with LTN bonds
|
|
177
|
+
ntnb.data("23-08-2024") # -> DataFrame with NTN-B bonds
|
|
178
|
+
|
|
179
|
+
# Calculate bond quotation (base 100)
|
|
180
|
+
ntnb.quotation("31-05-2024", "15-05-2035", 0.061490) # -> 99.3651
|
|
181
|
+
ntnb.quotation("31-05-2024", "15-08-2060", 0.061878) # -> 99.5341
|
|
182
|
+
|
|
183
|
+
# DI spreads (bps=True multiplies by 10,000)
|
|
184
|
+
ntnf.di_spreads("30-05-2025", bps=True)
|
|
185
|
+
# -> DataFrame: BondType, MaturityDate, DISpread
|
|
186
|
+
```
|
|
187
|
+
|
|
188
|
+
## Futures Data
|
|
189
|
+
|
|
190
|
+
```python
|
|
191
|
+
from pyield import futures
|
|
192
|
+
|
|
193
|
+
# DI1 (Interbank Deposit Futures)
|
|
194
|
+
futures("31-05-2024", "DI1")
|
|
195
|
+
|
|
196
|
+
# Other contracts: DDI, FRC, DAP, DOL, WDO, IND, WIN
|
|
197
|
+
futures("31-05-2024", "DAP")
|
|
198
|
+
|
|
199
|
+
# Intraday data (when market is open)
|
|
200
|
+
futures("16-01-2025", "DI1") # Returns live data if called during trading hours
|
|
201
|
+
```
|
|
202
|
+
|
|
203
|
+
## Date Handling
|
|
204
|
+
|
|
205
|
+
PYield accepts flexible date inputs (`DateLike`):
|
|
206
|
+
- Strings: `"31-05-2024"`, `"31/05/2024"`, `"2024-05-31"`
|
|
207
|
+
- `datetime.date`, `datetime.datetime`
|
|
208
|
+
- `pandas.Timestamp`, `numpy.datetime64`
|
|
209
|
+
|
|
210
|
+
Scalar functions return `datetime.date`. Vectorized functions return `polars.Series`.
|
|
211
|
+
|
|
212
|
+
Null handling: scalar functions return `float('nan')` for missing inputs (propagates through calculations). Vectorized functions propagate `null` element-wise.
|
|
213
|
+
|
|
214
|
+
```python
|
|
215
|
+
from pyield import ntnb, bday
|
|
216
|
+
|
|
217
|
+
ntnb.quotation(None, "15-05-2035", 0.06149) # -> nan
|
|
218
|
+
bday.count(["01-01-2024", None], "01-02-2024") # -> Series: [22, null]
|
|
219
|
+
```
|
|
220
|
+
|
|
221
|
+
## Polars Migration (v0.40.0+)
|
|
222
|
+
|
|
223
|
+
All functions return **Polars DataFrames/Series**. To convert to Pandas:
|
|
224
|
+
|
|
225
|
+
```python
|
|
226
|
+
df_pandas = df.to_pandas(use_pyarrow_extension_array=True)
|
|
227
|
+
```
|
|
228
|
+
|
|
229
|
+
## Documentation
|
|
230
|
+
|
|
231
|
+
Full documentation: [crdcj.github.io/PYield](https://crdcj.github.io/PYield/)
|
|
232
|
+
|
|
233
|
+
## Tests
|
|
234
|
+
|
|
235
|
+
```sh
|
|
236
|
+
pytest pyield --doctest-modules
|
|
237
|
+
```
|
pyield-0.42.3/README.md
ADDED
|
@@ -0,0 +1,195 @@
|
|
|
1
|
+
[](https://pypi.python.org/pypi/pyield)
|
|
2
|
+
[](https://python.org "Go to Python homepage")
|
|
3
|
+
[](https://github.com/crdcj/PYield/blob/main/LICENSE)
|
|
4
|
+
|
|
5
|
+
# PYield: Brazilian Fixed Income Toolkit
|
|
6
|
+
|
|
7
|
+
PYield is a Python library for analyzing Brazilian fixed income instruments. It fetches and processes data from ANBIMA, BCB, IBGE and B3, returning Polars DataFrames for fast, type-safe data pipelines.
|
|
8
|
+
|
|
9
|
+
## Installation
|
|
10
|
+
|
|
11
|
+
```sh
|
|
12
|
+
pip install pyield
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
## Quick Start
|
|
16
|
+
|
|
17
|
+
```python
|
|
18
|
+
import pyield as yd
|
|
19
|
+
|
|
20
|
+
# Business days (foundation of all calculations)
|
|
21
|
+
yd.bday.count("02-01-2025", "15-01-2025") # -> 9
|
|
22
|
+
yd.bday.offset("29-12-2023", 1) # -> datetime.date(2024, 1, 2)
|
|
23
|
+
|
|
24
|
+
# DI Futures curve
|
|
25
|
+
df = yd.futures("31-05-2024", "DI1")
|
|
26
|
+
# Columns: TradeDate, TickerSymbol, ExpirationDate, BDaysToExp, SettlementRate, ...
|
|
27
|
+
|
|
28
|
+
# Rate interpolation (flat forward, 252 bdays/year convention)
|
|
29
|
+
interp = yd.Interpolator("flat_forward", df["BDaysToExp"], df["SettlementRate"])
|
|
30
|
+
interp(45) # -> 0.04833...
|
|
31
|
+
interp([30, 60]) # -> pl.Series with interpolated rates
|
|
32
|
+
|
|
33
|
+
# Treasury bond pricing
|
|
34
|
+
yd.ntnb.quotation("31-05-2024", "15-05-2035", 0.061490) # -> 99.3651
|
|
35
|
+
|
|
36
|
+
# BCB indicators
|
|
37
|
+
yd.bc.selic_over("31-05-2024") # -> 0.000414...
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
A Colab notebook with more examples is available:
|
|
41
|
+
|
|
42
|
+
[](https://colab.research.google.com/github/crdcj/PYield/blob/main/examples/pyield_quickstart.ipynb)
|
|
43
|
+
|
|
44
|
+
## Core Building Blocks
|
|
45
|
+
|
|
46
|
+
### Business Days (`bday`)
|
|
47
|
+
|
|
48
|
+
The `bday` module is the foundation of PYield. All date calculations (pricing, duration, forward rates) depend on accurate business day counting with Brazilian holidays.
|
|
49
|
+
|
|
50
|
+
```python
|
|
51
|
+
from pyield import bday
|
|
52
|
+
|
|
53
|
+
# Count business days (start inclusive, end exclusive)
|
|
54
|
+
bday.count("29-12-2023", "02-01-2024") # -> 1
|
|
55
|
+
|
|
56
|
+
# Offset by N business days
|
|
57
|
+
bday.offset("29-12-2023", 1) # -> datetime.date(2024, 1, 2)
|
|
58
|
+
|
|
59
|
+
# Adjust non-business day to next business day
|
|
60
|
+
bday.offset("30-12-2023", 0) # -> datetime.date(2024, 1, 2)
|
|
61
|
+
|
|
62
|
+
# Generate business day range
|
|
63
|
+
bday.generate("22-12-2023", "02-01-2024")
|
|
64
|
+
# -> Series: [2023-12-22, 2023-12-26, 2023-12-27, 2023-12-28, 2023-12-29, 2024-01-02]
|
|
65
|
+
|
|
66
|
+
# Check if date is business day
|
|
67
|
+
bday.is_business_day("25-12-2023") # -> False (Christmas)
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
All functions support vectorized operations with lists, Series, or arrays.
|
|
71
|
+
|
|
72
|
+
### Rate Interpolation (`Interpolator`)
|
|
73
|
+
|
|
74
|
+
The `Interpolator` class interpolates interest rates using the 252 business days/year convention standard in Brazil.
|
|
75
|
+
|
|
76
|
+
```python
|
|
77
|
+
from pyield import Interpolator
|
|
78
|
+
|
|
79
|
+
known_bdays = [30, 60, 90]
|
|
80
|
+
known_rates = [0.045, 0.05, 0.055]
|
|
81
|
+
|
|
82
|
+
# Flat forward interpolation (market standard)
|
|
83
|
+
interp = Interpolator("flat_forward", known_bdays, known_rates)
|
|
84
|
+
interp(45) # -> 0.04833...
|
|
85
|
+
|
|
86
|
+
# Linear interpolation
|
|
87
|
+
linear = Interpolator("linear", known_bdays, known_rates)
|
|
88
|
+
linear(45) # -> 0.0475
|
|
89
|
+
|
|
90
|
+
# Vectorized
|
|
91
|
+
interp([15, 45, 75]) # -> pl.Series with 3 rates
|
|
92
|
+
|
|
93
|
+
# Extrapolation (disabled by default, returns NaN)
|
|
94
|
+
interp(100) # -> nan
|
|
95
|
+
Interpolator("flat_forward", known_bdays, known_rates, extrapolate=True)(100) # -> 0.055
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
### Forward Rates (`forward`, `forwards`)
|
|
99
|
+
|
|
100
|
+
Calculate forward rates from spot curves:
|
|
101
|
+
|
|
102
|
+
```python
|
|
103
|
+
from pyield import forward, forwards
|
|
104
|
+
|
|
105
|
+
# Single forward rate between two points
|
|
106
|
+
forward(bday1=10, bday2=20, rate1=0.05, rate2=0.06) # -> 0.0700952...
|
|
107
|
+
|
|
108
|
+
# Vectorized forward curve from spot rates
|
|
109
|
+
bdays = [10, 20, 30]
|
|
110
|
+
rates = [0.05, 0.06, 0.07]
|
|
111
|
+
forwards(bdays, rates) # -> Series: [0.05, 0.070095, 0.090284]
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
## Modules Overview
|
|
115
|
+
|
|
116
|
+
| Module | Purpose |
|
|
117
|
+
|--------|---------|
|
|
118
|
+
| `bday` | Business day calendar with Brazilian holidays |
|
|
119
|
+
| `futures` | B3 futures data (DI1, DDI, FRC, DAP, DOL, WDO, IND, WIN) |
|
|
120
|
+
| `Interpolator` | Rate interpolation (flat_forward, linear) |
|
|
121
|
+
| `forward` / `forwards` | Forward rate calculation |
|
|
122
|
+
| `ltn`, `ntnb`, `ntnf`, `lft`, `ntnc` | Treasury bond pricing and analytics |
|
|
123
|
+
| `anbima` | ANBIMA data (TPF prices, yield curves, IMA indices) |
|
|
124
|
+
| `bc` | BCB indicators (SELIC, PTAX, repo rates, VNA) |
|
|
125
|
+
| `ipca` | Inflation data (historical and projections) |
|
|
126
|
+
| `today` / `now` | Current date/time in Brazil (America/Sao_Paulo) |
|
|
127
|
+
|
|
128
|
+
## Treasury Bonds
|
|
129
|
+
|
|
130
|
+
```python
|
|
131
|
+
from pyield import ltn, ntnb, ntnf
|
|
132
|
+
|
|
133
|
+
# Fetch ANBIMA indicative rates
|
|
134
|
+
ltn.data("23-08-2024") # -> DataFrame with LTN bonds
|
|
135
|
+
ntnb.data("23-08-2024") # -> DataFrame with NTN-B bonds
|
|
136
|
+
|
|
137
|
+
# Calculate bond quotation (base 100)
|
|
138
|
+
ntnb.quotation("31-05-2024", "15-05-2035", 0.061490) # -> 99.3651
|
|
139
|
+
ntnb.quotation("31-05-2024", "15-08-2060", 0.061878) # -> 99.5341
|
|
140
|
+
|
|
141
|
+
# DI spreads (bps=True multiplies by 10,000)
|
|
142
|
+
ntnf.di_spreads("30-05-2025", bps=True)
|
|
143
|
+
# -> DataFrame: BondType, MaturityDate, DISpread
|
|
144
|
+
```
|
|
145
|
+
|
|
146
|
+
## Futures Data
|
|
147
|
+
|
|
148
|
+
```python
|
|
149
|
+
from pyield import futures
|
|
150
|
+
|
|
151
|
+
# DI1 (Interbank Deposit Futures)
|
|
152
|
+
futures("31-05-2024", "DI1")
|
|
153
|
+
|
|
154
|
+
# Other contracts: DDI, FRC, DAP, DOL, WDO, IND, WIN
|
|
155
|
+
futures("31-05-2024", "DAP")
|
|
156
|
+
|
|
157
|
+
# Intraday data (when market is open)
|
|
158
|
+
futures("16-01-2025", "DI1") # Returns live data if called during trading hours
|
|
159
|
+
```
|
|
160
|
+
|
|
161
|
+
## Date Handling
|
|
162
|
+
|
|
163
|
+
PYield accepts flexible date inputs (`DateLike`):
|
|
164
|
+
- Strings: `"31-05-2024"`, `"31/05/2024"`, `"2024-05-31"`
|
|
165
|
+
- `datetime.date`, `datetime.datetime`
|
|
166
|
+
- `pandas.Timestamp`, `numpy.datetime64`
|
|
167
|
+
|
|
168
|
+
Scalar functions return `datetime.date`. Vectorized functions return `polars.Series`.
|
|
169
|
+
|
|
170
|
+
Null handling: scalar functions return `float('nan')` for missing inputs (propagates through calculations). Vectorized functions propagate `null` element-wise.
|
|
171
|
+
|
|
172
|
+
```python
|
|
173
|
+
from pyield import ntnb, bday
|
|
174
|
+
|
|
175
|
+
ntnb.quotation(None, "15-05-2035", 0.06149) # -> nan
|
|
176
|
+
bday.count(["01-01-2024", None], "01-02-2024") # -> Series: [22, null]
|
|
177
|
+
```
|
|
178
|
+
|
|
179
|
+
## Polars Migration (v0.40.0+)
|
|
180
|
+
|
|
181
|
+
All functions return **Polars DataFrames/Series**. To convert to Pandas:
|
|
182
|
+
|
|
183
|
+
```python
|
|
184
|
+
df_pandas = df.to_pandas(use_pyarrow_extension_array=True)
|
|
185
|
+
```
|
|
186
|
+
|
|
187
|
+
## Documentation
|
|
188
|
+
|
|
189
|
+
Full documentation: [crdcj.github.io/PYield](https://crdcj.github.io/PYield/)
|
|
190
|
+
|
|
191
|
+
## Tests
|
|
192
|
+
|
|
193
|
+
```sh
|
|
194
|
+
pytest pyield --doctest-modules
|
|
195
|
+
```
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
__version__ = "0.42.3"
|
|
@@ -89,7 +89,7 @@ def _parse_df(text: str) -> pl.DataFrame:
|
|
|
89
89
|
separator="@",
|
|
90
90
|
decimal_comma=True,
|
|
91
91
|
null_values="--",
|
|
92
|
-
|
|
92
|
+
schema_overrides=IMA_SCHEMA,
|
|
93
93
|
)
|
|
94
94
|
return df
|
|
95
95
|
|
|
@@ -115,9 +115,7 @@ def _process_df(df: pl.DataFrame) -> pl.DataFrame:
|
|
|
115
115
|
.with_columns(
|
|
116
116
|
dv01_expr.alias("DV01"),
|
|
117
117
|
)
|
|
118
|
-
.with_columns(
|
|
119
|
-
(pl.col("DV01") * pl.col("MarketQuantity")).round(2).alias("MarketDV01"),
|
|
120
|
-
)
|
|
118
|
+
.with_columns(MarketDV01=(pl.col("DV01") * pl.col("MarketQuantity")).round(2))
|
|
121
119
|
)
|
|
122
120
|
return df
|
|
123
121
|
|
|
@@ -199,9 +197,9 @@ def last_ima(ima_type: ima_types | None = None) -> pl.DataFrame:
|
|
|
199
197
|
df = _parse_df(ima_text)
|
|
200
198
|
df = _process_df(df)
|
|
201
199
|
df = _reorder_columns(df)
|
|
202
|
-
if ima_type
|
|
200
|
+
if ima_type:
|
|
203
201
|
df = df.filter(pl.col("IMAType") == ima_type)
|
|
204
|
-
df = df.sort(
|
|
202
|
+
df = df.sort("IMAType", "BondType", "Maturity")
|
|
205
203
|
return df
|
|
206
204
|
except Exception as e:
|
|
207
205
|
logger.exception(f"Error fetching or processing the last IMA data: {e}")
|
|
@@ -51,7 +51,7 @@ def _fetch_url_content(target_date: dt.date) -> bytes:
|
|
|
51
51
|
r = requests.post(IMA_URL, data=payload, timeout=10)
|
|
52
52
|
r.raise_for_status()
|
|
53
53
|
if "Não há dados disponíveis" in r.text:
|
|
54
|
-
return ""
|
|
54
|
+
return b""
|
|
55
55
|
return r.content
|
|
56
56
|
|
|
57
57
|
|
|
@@ -72,15 +72,14 @@ def _extract_reference_date(html_content: bytes) -> dt.date | None:
|
|
|
72
72
|
return dt.datetime.strptime(date_string, "%d/%m/%Y").date()
|
|
73
73
|
|
|
74
74
|
|
|
75
|
-
def _parse_html_data(html_content:
|
|
75
|
+
def _parse_html_data(html_content: bytes) -> str:
|
|
76
76
|
dfs = pd.read_html(
|
|
77
|
-
io.BytesIO(html_content),
|
|
77
|
+
io.BytesIO(html_content), # type: ignore[arg-type]
|
|
78
78
|
flavor="lxml",
|
|
79
79
|
attrs={"width": "100%"},
|
|
80
80
|
header=0,
|
|
81
81
|
thousands=".",
|
|
82
82
|
decimal=",",
|
|
83
|
-
displayed_only=True,
|
|
84
83
|
dtype_backend="pyarrow",
|
|
85
84
|
na_values="--",
|
|
86
85
|
encoding="iso-8859-1",
|
|
@@ -107,13 +106,13 @@ def _process_data(csv: str, reference_date: dt.date) -> pl.DataFrame:
|
|
|
107
106
|
df = (
|
|
108
107
|
pl.read_csv(io.StringIO(csv))
|
|
109
108
|
.with_columns(
|
|
110
|
-
pl.col("MaturityDate").str.
|
|
109
|
+
pl.col("MaturityDate").str.to_date(format="%d/%m/%Y"),
|
|
111
110
|
(pl.col("MarketQuantity") * 1000),
|
|
112
111
|
(pl.col("MarketValue") * 1000),
|
|
113
112
|
(pl.col("QuantityVariation") * 1000),
|
|
114
113
|
Date=reference_date,
|
|
115
114
|
)
|
|
116
|
-
.sort(
|
|
115
|
+
.sort("BondType", "MaturityDate")
|
|
117
116
|
)
|
|
118
117
|
|
|
119
118
|
return df
|
|
@@ -121,8 +120,8 @@ def _process_data(csv: str, reference_date: dt.date) -> pl.DataFrame:
|
|
|
121
120
|
|
|
122
121
|
def _add_dv01(df: pl.DataFrame, reference_date: dt.date) -> pl.DataFrame:
|
|
123
122
|
df_anbima = tpf_data(reference_date)
|
|
124
|
-
|
|
125
|
-
df_anbima = df_anbima.select(
|
|
123
|
+
keep_cols = ["ReferenceDate", "BondType", "MaturityDate", "DV01", "DV01USD"]
|
|
124
|
+
df_anbima = df_anbima.select(keep_cols).rename({"ReferenceDate": "Date"})
|
|
126
125
|
# Guard clause for missing columns
|
|
127
126
|
if "DV01" not in df_anbima.columns or "DV01USD" not in df_anbima.columns:
|
|
128
127
|
return df
|
|
@@ -132,7 +131,7 @@ def _add_dv01(df: pl.DataFrame, reference_date: dt.date) -> pl.DataFrame:
|
|
|
132
131
|
df = df.with_columns(
|
|
133
132
|
MarketDV01=pl.col("DV01") * pl.col("MarketQuantity"),
|
|
134
133
|
MarketDV01USD=pl.col("DV01USD") * pl.col("MarketQuantity"),
|
|
135
|
-
).drop(
|
|
134
|
+
).drop("DV01", "DV01USD")
|
|
136
135
|
return df
|
|
137
136
|
|
|
138
137
|
|
|
@@ -178,9 +177,8 @@ def imaq(date: DateLike) -> pl.DataFrame:
|
|
|
178
177
|
fetching or processing, an empty DataFrame is returned.
|
|
179
178
|
|
|
180
179
|
Args:
|
|
181
|
-
date (DateLike):
|
|
182
|
-
|
|
183
|
-
The last is typically from 2 business days ago.
|
|
180
|
+
date (DateLike): The reference date for fetching the data. Only the last 5
|
|
181
|
+
business days are available. The latest is typically from 2 bdays ago.
|
|
184
182
|
|
|
185
183
|
Returns:
|
|
186
184
|
pl.DataFrame: A DataFrame containing the IMA data.
|
|
@@ -414,13 +414,13 @@ def tpf_data(
|
|
|
414
414
|
|
|
415
415
|
def tpf_maturities(
|
|
416
416
|
date: DateLike,
|
|
417
|
-
bond_type:
|
|
417
|
+
bond_type: BOND_TYPES,
|
|
418
418
|
) -> pl.Series:
|
|
419
419
|
"""Retrieve existing maturity dates for a given bond type on a specific date.
|
|
420
420
|
|
|
421
421
|
Args:
|
|
422
422
|
date (DateLike): The reference date for maturity dates.
|
|
423
|
-
bond_type (
|
|
423
|
+
bond_type (BOND_TYPES): The bond type to filter by (e.g., 'PRE' for both 'LTN'
|
|
424
424
|
and 'NTN-F', or specify 'LTN' or 'NTN-F' directly).
|
|
425
425
|
|
|
426
426
|
Returns:
|
|
@@ -447,4 +447,4 @@ def tpf_maturities(
|
|
|
447
447
|
]
|
|
448
448
|
|
|
449
449
|
"""
|
|
450
|
-
return tpf_data(date, bond_type)
|
|
450
|
+
return tpf_data(date, bond_type)["MaturityDate"].unique().sort()
|
|
@@ -0,0 +1,76 @@
|
|
|
1
|
+
import ftplib
|
|
2
|
+
import logging
|
|
3
|
+
|
|
4
|
+
from pyield.converters import convert_dates
|
|
5
|
+
from pyield.types import DateLike, has_nullable_args
|
|
6
|
+
|
|
7
|
+
logger = logging.getLogger(__name__)
|
|
8
|
+
|
|
9
|
+
# 4 decimal places in rate = 2 decimal places in percentage
|
|
10
|
+
DI_OVER_DECIMAL_PLACES = 4
|
|
11
|
+
|
|
12
|
+
|
|
13
|
+
def di_over(date: DateLike) -> float:
|
|
14
|
+
"""
|
|
15
|
+
Gets the DI (Interbank Deposit) rate for a specific date from B3/CETIP FTP server.
|
|
16
|
+
|
|
17
|
+
Args:
|
|
18
|
+
date (DateLike): The reference date for fetching the DI rate.
|
|
19
|
+
|
|
20
|
+
Returns:
|
|
21
|
+
float: DI rate for the specified date (e.g., 0.1315 for 13.15%).
|
|
22
|
+
Returns float("nan") if the file is not found (e.g., weekends, holidays).
|
|
23
|
+
|
|
24
|
+
Raises:
|
|
25
|
+
ValueError: If date is not in the correct format.
|
|
26
|
+
ConnectionError: If connection to the FTP server fails or other transfer
|
|
27
|
+
errors occur.
|
|
28
|
+
|
|
29
|
+
Examples:
|
|
30
|
+
>>> di_over("28/02/2025")
|
|
31
|
+
0.1315
|
|
32
|
+
>>> di_over("01/01/2025") # Holiday
|
|
33
|
+
nan
|
|
34
|
+
"""
|
|
35
|
+
if has_nullable_args(date):
|
|
36
|
+
return float("nan")
|
|
37
|
+
|
|
38
|
+
try:
|
|
39
|
+
# Convert date to expected file format: YYYYMMDD.txt
|
|
40
|
+
date_obj = convert_dates(date)
|
|
41
|
+
filename = date_obj.strftime("%Y%m%d.txt")
|
|
42
|
+
|
|
43
|
+
# Use context manager for safe resource handling (auto-close/quit)
|
|
44
|
+
with ftplib.FTP("ftp.cetip.com.br", timeout=10) as ftp:
|
|
45
|
+
ftp.login()
|
|
46
|
+
ftp.cwd("/MediaCDI")
|
|
47
|
+
|
|
48
|
+
lines = []
|
|
49
|
+
try:
|
|
50
|
+
ftp.retrlines(f"RETR {filename}", lines.append)
|
|
51
|
+
except ftplib.error_perm as e:
|
|
52
|
+
# Code 550 usually means "File not found" (weekend/holiday/future)
|
|
53
|
+
if str(e).startswith("550"):
|
|
54
|
+
logger.warning(f"DI Rate file not found for {date}: {e}")
|
|
55
|
+
return float("nan") # Return NaN instead of raising exception
|
|
56
|
+
|
|
57
|
+
# If it's another type of error, we raise it to be caught below
|
|
58
|
+
raise e
|
|
59
|
+
|
|
60
|
+
if not lines:
|
|
61
|
+
logger.error(f"File {filename} is empty.")
|
|
62
|
+
return float("nan")
|
|
63
|
+
|
|
64
|
+
# Parse the rate
|
|
65
|
+
# Format usually: "00001315" -> 13.15% -> 0.1315
|
|
66
|
+
raw_rate = lines[0].strip()
|
|
67
|
+
rate = int(raw_rate) / 10000
|
|
68
|
+
return round(rate, DI_OVER_DECIMAL_PLACES)
|
|
69
|
+
|
|
70
|
+
except ValueError as e:
|
|
71
|
+
logger.error(f"Date format error for input '{date}': {e}")
|
|
72
|
+
raise
|
|
73
|
+
|
|
74
|
+
except ftplib.all_errors as e:
|
|
75
|
+
logger.error(f"FTP connection or transfer error: {e}")
|
|
76
|
+
raise ConnectionError(f"Failed to fetch DI rate from FTP: {e}") from e
|
|
@@ -54,8 +54,7 @@ def futures(
|
|
|
54
54
|
- "WDO": Mini U.S. Dollar Futures from B3.
|
|
55
55
|
- "IND": Ibovespa Futures from B3.
|
|
56
56
|
- "WIN": Mini Ibovespa Futures from B3.
|
|
57
|
-
date (DateLike): The date for
|
|
58
|
-
If the reference date is a string, it should be in 'DD-MM-YYYY' format.
|
|
57
|
+
date (DateLike): The reference date for fetching the data.
|
|
59
58
|
|
|
60
59
|
Returns:
|
|
61
60
|
pl.DataFrame: DataFrame containing the fetched data for the specified futures
|
|
@@ -145,10 +145,8 @@ def tpf_monthly_trades(target_date: DateLike, extragroup: bool = False) -> pl.Da
|
|
|
145
145
|
all trades executed during the month, separated by each 'SettlementDate'.
|
|
146
146
|
|
|
147
147
|
Args:
|
|
148
|
-
target_date (DateLike): The date for
|
|
149
|
-
|
|
150
|
-
It will be converted to a date object. Only the year and month
|
|
151
|
-
of this date will be used to download the corresponding monthly file.
|
|
148
|
+
target_date (DateLike): The reference date for fetching the monthly trading
|
|
149
|
+
data. Only the year and month are used to download the corresponding file.
|
|
152
150
|
extragroup (bool): If True, fetches only the trades that are considered
|
|
153
151
|
'extragroup' (between different economic groups)".
|
|
154
152
|
If False, fetches all trades. Default is False.
|