PYield 0.29.4__tar.gz → 0.30.0__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.
Files changed (49) hide show
  1. {pyield-0.29.4 → pyield-0.30.0}/PKG-INFO +1 -1
  2. pyield-0.30.0/pyield/__about__.py +1 -0
  3. pyield-0.30.0/pyield/bc/__init__.py +27 -0
  4. {pyield-0.29.4 → pyield-0.30.0}/pyield/bc/bcdata.py +132 -28
  5. {pyield-0.29.4 → pyield-0.30.0}/pyield/bc/ptax.py +1 -1
  6. pyield-0.29.4/pyield/__about__.py +0 -1
  7. pyield-0.29.4/pyield/bc/__init__.py +0 -17
  8. {pyield-0.29.4 → pyield-0.30.0}/.gitignore +0 -0
  9. {pyield-0.29.4 → pyield-0.30.0}/LICENSE +0 -0
  10. {pyield-0.29.4 → pyield-0.30.0}/README.md +0 -0
  11. {pyield-0.29.4 → pyield-0.30.0}/pyield/__init__.py +0 -0
  12. {pyield-0.29.4 → pyield-0.30.0}/pyield/anbima/__init__.py +0 -0
  13. {pyield-0.29.4 → pyield-0.30.0}/pyield/anbima/ima.py +0 -0
  14. {pyield-0.29.4 → pyield-0.30.0}/pyield/anbima/imaq.py +0 -0
  15. {pyield-0.29.4 → pyield-0.30.0}/pyield/anbima/ipca.py +0 -0
  16. {pyield-0.29.4 → pyield-0.30.0}/pyield/anbima/tpf.py +0 -0
  17. {pyield-0.29.4 → pyield-0.30.0}/pyield/b3/__init__.py +0 -0
  18. {pyield-0.29.4 → pyield-0.30.0}/pyield/b3/di.py +0 -0
  19. {pyield-0.29.4 → pyield-0.30.0}/pyield/b3/di_over.py +0 -0
  20. {pyield-0.29.4 → pyield-0.30.0}/pyield/b3/futures/__init__.py +0 -0
  21. {pyield-0.29.4 → pyield-0.30.0}/pyield/b3/futures/common.py +0 -0
  22. {pyield-0.29.4 → pyield-0.30.0}/pyield/b3/futures/historical.py +0 -0
  23. {pyield-0.29.4 → pyield-0.30.0}/pyield/b3/futures/intraday.py +0 -0
  24. {pyield-0.29.4 → pyield-0.30.0}/pyield/b3/futures/xml.py +0 -0
  25. {pyield-0.29.4 → pyield-0.30.0}/pyield/bc/auction.py +0 -0
  26. /pyield-0.29.4/pyield/bc/repos.py → /pyield-0.30.0/pyield/bc/repo.py +0 -0
  27. {pyield-0.29.4 → pyield-0.30.0}/pyield/bc/sec.py +0 -0
  28. {pyield-0.29.4 → pyield-0.30.0}/pyield/bc/vna.py +0 -0
  29. {pyield-0.29.4 → pyield-0.30.0}/pyield/bday.py +0 -0
  30. {pyield-0.29.4 → pyield-0.30.0}/pyield/config.py +0 -0
  31. {pyield-0.29.4 → pyield-0.30.0}/pyield/conftest.py +0 -0
  32. {pyield-0.29.4 → pyield-0.30.0}/pyield/data_cache.py +0 -0
  33. {pyield-0.29.4 → pyield-0.30.0}/pyield/date_converter.py +0 -0
  34. {pyield-0.29.4 → pyield-0.30.0}/pyield/forwards.py +0 -0
  35. {pyield-0.29.4 → pyield-0.30.0}/pyield/holidays/__init__.py +0 -0
  36. {pyield-0.29.4 → pyield-0.30.0}/pyield/holidays/br_holidays_new.txt +0 -0
  37. {pyield-0.29.4 → pyield-0.30.0}/pyield/holidays/br_holidays_old.txt +0 -0
  38. {pyield-0.29.4 → pyield-0.30.0}/pyield/holidays/brholidays.py +0 -0
  39. {pyield-0.29.4 → pyield-0.30.0}/pyield/ibge/__init__.py +0 -0
  40. {pyield-0.29.4 → pyield-0.30.0}/pyield/ibge/ipca.py +0 -0
  41. {pyield-0.29.4 → pyield-0.30.0}/pyield/interpolator.py +0 -0
  42. {pyield-0.29.4 → pyield-0.30.0}/pyield/py.typed +0 -0
  43. {pyield-0.29.4 → pyield-0.30.0}/pyield/tpf/__init__.py +0 -0
  44. {pyield-0.29.4 → pyield-0.30.0}/pyield/tpf/lft.py +0 -0
  45. {pyield-0.29.4 → pyield-0.30.0}/pyield/tpf/ltn.py +0 -0
  46. {pyield-0.29.4 → pyield-0.30.0}/pyield/tpf/ntnb.py +0 -0
  47. {pyield-0.29.4 → pyield-0.30.0}/pyield/tpf/ntnf.py +0 -0
  48. {pyield-0.29.4 → pyield-0.30.0}/pyield/tpf/tools.py +0 -0
  49. {pyield-0.29.4 → pyield-0.30.0}/pyproject.toml +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: PYield
3
- Version: 0.29.4
3
+ Version: 0.30.0
4
4
  Summary: A Python library for analysis of fixed income instruments in Brazil
5
5
  Project-URL: Source, https://github.com/crdcj/PYield
6
6
  Author-email: Carlos Carvalho <cr.cj@outlook.com>
@@ -0,0 +1 @@
1
+ __version__ = "0.30.0"
@@ -0,0 +1,27 @@
1
+ from pyield.bc.auction import auctions
2
+ from pyield.bc.bcdata import (
3
+ di_over,
4
+ di_over_series,
5
+ selic_over,
6
+ selic_over_series,
7
+ selic_target,
8
+ selic_target_series,
9
+ )
10
+ from pyield.bc.ptax import ptax_series
11
+ from pyield.bc.repo import repos
12
+ from pyield.bc.sec import sec
13
+ from pyield.bc.vna import vna_lft
14
+
15
+ __all__ = [
16
+ "auctions",
17
+ "repos",
18
+ "ptax_series",
19
+ "vna_lft",
20
+ "selic_over_series",
21
+ "selic_target_series",
22
+ "di_over_series",
23
+ "sec",
24
+ "di_over",
25
+ "selic_over",
26
+ "selic_target",
27
+ ]
@@ -1,6 +1,21 @@
1
+ """
2
+ This module provides functions to fetch various financial indicators from
3
+ the Brazilian Central Bank's API.
4
+
5
+ Implementation Notes:
6
+ - Values are retrieved in percentage format and converted to decimal format
7
+ (divided by 100).
8
+ - Each rate type is rounded to maintain the same precision as provided by
9
+ the Central Bank:
10
+ - SELIC Over and SELIC Target: 4 decimal places (from 2 decimal places
11
+ in percentage format)
12
+ - DI Over: 8 decimal places for daily rates (from 6 decimal places in % format).
13
+ For annualized rates, the value is rounded to 4 decimal places.
14
+
15
+ """
16
+
1
17
  import logging
2
18
  from enum import Enum
3
- from functools import lru_cache
4
19
  from urllib.error import HTTPError
5
20
 
6
21
  import pandas as pd
@@ -9,7 +24,10 @@ from pyield.config import default_retry
9
24
  from pyield.date_converter import DateScalar, convert_input_dates
10
25
 
11
26
  logger = logging.getLogger(__name__)
27
+
12
28
  BASE_URL = "https://api.bcb.gov.br/dados/serie/bcdata.sgs."
29
+ DECIMAL_PLACES_ANNUALIZED = 4 # 2 decimal places in percentage format
30
+ DECIMAL_PLACES_DAILY = 8 # 6 decimal places in percentage format
13
31
 
14
32
 
15
33
  class BCSerie(Enum):
@@ -100,12 +118,11 @@ def _fetch_data_from_url(
100
118
  raise
101
119
 
102
120
 
103
- @lru_cache(maxsize=128)
104
- def selic_over(
121
+ def selic_over_series(
105
122
  start: DateScalar | None = None, end: DateScalar | None = None
106
123
  ) -> pd.DataFrame:
107
124
  """
108
- Fetches the SELIC Over rate for a specific reference date.
125
+ Fetches the SELIC Over rate from the Brazilian Central Bank.
109
126
 
110
127
  The SELIC Over rate is the daily average interest rate effectively practiced
111
128
  between banks in the interbank market, using public securities as collateral.
@@ -114,20 +131,23 @@ def selic_over(
114
131
  https://api.bcb.gov.br/dados/serie/bcdata.sgs.1178/dados?formato=json&dataInicial=12/04/2024&dataFinal=12/04/2024
115
132
 
116
133
  Args:
117
- start: The start date for the data to fetch
118
- end: The end date for the data to fetch
134
+ start: The start date for the data to fetch. If None, returns data from
135
+ the earliest available date.
136
+ end: The end date for the data to fetch. If None, returns data up to
137
+ the latest available date.
119
138
 
120
139
  Returns:
121
140
  DataFrame containing Date and Value columns with the SELIC Over rate,
122
141
  or empty DataFrame if data is not available.
123
142
 
124
143
  Examples:
125
- >>> yd.bc.selic_over("31-05-2024", "31-05-2024")
144
+ >>> from pyield import bc
145
+ >>> bc.selic_over_series("31-05-2024", "31-05-2024")
126
146
  Date Value
127
147
  0 2024-05-31 0.104
128
148
 
129
- # Rate changed due to Copom meeting
130
- >>> yd.bc.selic_over("26-01-2025") # No data on 26-01-2025 (sunday)
149
+ # No data on 26-01-2025 (sunday). Rate changed due to Copom meeting.
150
+ >>> bc.selic_over_series("26-01-2025") # Returns all data since 26-01-2025
131
151
  Date Value
132
152
  0 2025-01-27 0.1215
133
153
  1 2025-01-28 0.1215
@@ -138,56 +158,105 @@ def selic_over(
138
158
 
139
159
  """
140
160
  df = _fetch_data_from_url(BCSerie.SELIC_OVER, start, end)
141
- df["Value"] = df["Value"].round(4)
161
+ df["Value"] = df["Value"].round(DECIMAL_PLACES_ANNUALIZED)
142
162
  return df
143
163
 
144
164
 
145
- @lru_cache(maxsize=128)
146
- def selic_target(
165
+ def selic_over(date: DateScalar) -> float:
166
+ """
167
+ Fetches the SELIC Over rate value for a specific date.
168
+
169
+ This is a convenience function that returns only the value (not the DataFrame)
170
+ for the specified date.
171
+
172
+ Args:
173
+ date: The reference date to fetch the SELIC Over rate for.
174
+
175
+ Returns:
176
+ The SELIC Over rate as a float.
177
+
178
+ Examples:
179
+ >>> from pyield import bc
180
+ >>> bc.selic_over("31-05-2024")
181
+ 0.104
182
+ """
183
+ df = selic_over_series(date, date)
184
+ return float(df.at[0, "Value"])
185
+
186
+
187
+ def selic_target_series(
147
188
  start: DateScalar | None = None, end: DateScalar | None = None
148
189
  ) -> pd.DataFrame:
149
190
  """
150
- Fetches the SELIC Target rate for a specific reference date.
191
+ Fetches the SELIC Target rate from the Brazilian Central Bank.
151
192
 
152
- The SELIC Target rate is the official rate set by the Central Bank of Brazil.
193
+ The SELIC Target rate is the official interest rate set by the
194
+ Central Bank of Brazil's Monetary Policy Committee (COPOM).
153
195
 
154
196
  API URL Example:
155
197
  https://api.bcb.gov.br/dados/serie/bcdata.sgs.432/dados?formato=json&dataInicial=12/04/2024&dataFinal=12/04/2024
156
198
 
157
199
  Args:
158
- start: The start date for the data to fetch
159
- end: The end date for the data to fetch
200
+ start: The start date for the data to fetch. If None, returns data from
201
+ the earliest available date.
202
+ end: The end date for the data to fetch. If None, returns data up to
203
+ the latest available date.
160
204
 
161
205
  Returns:
162
206
  DataFrame containing Date and Value columns with the SELIC Target rate,
163
- or empty DataFrame if data is not available.
207
+ or empty DataFrame if data is not available
164
208
 
165
209
  Examples:
166
- >>> yd.bc.selic_target("31-05-2024", "31-05-2024")
210
+ >>> yd.bc.selic_target_series("31-05-2024", "31-05-2024")
167
211
  Date Value
168
212
  0 2024-05-31 0.105
169
213
  """
170
214
  df = _fetch_data_from_url(BCSerie.SELIC_TARGET, start, end)
171
- df["Value"] = df["Value"].round(4)
215
+ df["Value"] = df["Value"].round(DECIMAL_PLACES_ANNUALIZED)
172
216
  return df
173
217
 
174
218
 
175
- @lru_cache(maxsize=128)
176
- def di_over(
219
+ def selic_target(date: DateScalar) -> float:
220
+ """
221
+ Fetches the SELIC Target rate value for a specific date.
222
+
223
+ This is a convenience function that returns only the value (not the DataFrame)
224
+ for the specified date.
225
+
226
+ Args:
227
+ date: The reference date to fetch the SELIC Target rate for.
228
+
229
+ Returns:
230
+ The SELIC Target rate as a float.
231
+
232
+ Examples:
233
+ >>> from pyield import bc
234
+ >>> bc.selic_target("31-05-2024")
235
+ 0.105
236
+ """
237
+ df = selic_target_series(date, date)
238
+ return float(df.at[0, "Value"])
239
+
240
+
241
+ def di_over_series(
177
242
  start: DateScalar | None = None,
178
243
  end: DateScalar | None = None,
179
244
  annualized: bool = True,
180
245
  ) -> pd.DataFrame:
181
246
  """
182
- Fetches the DI (Interbank Deposit) rate for a specific reference date.
247
+ Fetches the DI (Interbank Deposit) rate from the Brazilian Central Bank.
248
+
249
+ The DI rate represents the average interest rate of interbank loans.
183
250
 
184
251
  API URL Example:
185
252
  https://api.bcb.gov.br/dados/serie/bcdata.sgs.11/dados?formato=json&dataInicial=12/04/2024&dataFinal=12/04/2024
186
253
  https://api.bcb.gov.br/dados/serie/bcdata.sgs.11/dados?formato=csv&dataInicial=12/04/2024&dataFinal=12/04/2024
187
254
 
188
255
  Args:
189
- start: The start date for the data to fetch
190
- end: The end date for the data to fetch
256
+ start: The start date for the data to fetch. If None, returns data from
257
+ the earliest available date.
258
+ end: The end date for the data to fetch. If None, returns data up to
259
+ the latest available date.
191
260
  annualized: If True, returns the annualized rate (252 trading
192
261
  days per year), otherwise returns the daily rate.
193
262
 
@@ -196,12 +265,47 @@ def di_over(
196
265
  or empty DataFrame if data is not available.
197
266
 
198
267
  Examples:
199
- >>> yd.bc.di_over("31-05-2024", "31-05-2024")
200
- Date Value
201
- 0 2024-05-31 0.104
268
+ >>> from pyield import bc
269
+ >>> bc.di_over_series("29-01-2025")
270
+ Date Value
271
+ 0 2025-01-29 0.1215
272
+ 1 2025-01-30 0.1315
273
+ 2 2025-01-31 0.1315
274
+ 3 2025-02-03 0.1315
275
+ ...
276
+
202
277
  """
203
278
  df = _fetch_data_from_url(BCSerie.DI_OVER, start, end)
204
279
  if annualized:
205
280
  df["Value"] = (df["Value"] + 1) ** 252 - 1
206
- df["Value"] = df["Value"].round(4)
281
+ df["Value"] = df["Value"].round(DECIMAL_PLACES_ANNUALIZED)
282
+ else:
283
+ df["Value"] = df["Value"].round(DECIMAL_PLACES_DAILY)
207
284
  return df
285
+
286
+
287
+ def di_over(date: DateScalar, annualized: bool = True) -> float:
288
+ """
289
+ Fetches the DI Over rate value for a specific date.
290
+
291
+ This is a convenience function that returns only the value (not the DataFrame)
292
+ for the specified date.
293
+
294
+ Args:
295
+ date: The reference date to fetch the DI Over rate for.
296
+ annualized: If True, returns the annualized rate (252 trading
297
+ days per year), otherwise returns the daily rate.
298
+
299
+ Returns:
300
+ The DI Over rate as a float.
301
+
302
+ Examples:
303
+ >>> from pyield import bc
304
+ >>> bc.di_over("31-05-2024")
305
+ 0.104
306
+
307
+ >>> bc.di_over("28-01-2025", annualized=False)
308
+ 0.00045513
309
+ """
310
+ df = di_over_series(date, date, annualized)
311
+ return float(df.at[0, "Value"])
@@ -78,7 +78,7 @@ def _fetch_df_from_url(url: str) -> pd.DataFrame:
78
78
  return pd.DataFrame()
79
79
 
80
80
 
81
- def ptax(
81
+ def ptax_series(
82
82
  start: DateScalar | None = None,
83
83
  end: DateScalar | None = None,
84
84
  ) -> pd.DataFrame:
@@ -1 +0,0 @@
1
- __version__ = "0.29.4"
@@ -1,17 +0,0 @@
1
- from pyield.bc.auction import auctions
2
- from pyield.bc.bcdata import di_over, selic_over, selic_target
3
- from pyield.bc.ptax import ptax
4
- from pyield.bc.repos import repos
5
- from pyield.bc.sec import sec
6
- from pyield.bc.vna import vna_lft
7
-
8
- __all__ = [
9
- "auctions",
10
- "repos",
11
- "ptax",
12
- "vna_lft",
13
- "selic_over",
14
- "selic_target",
15
- "di_over",
16
- "sec",
17
- ]
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes