PYield 0.23.2__tar.gz → 0.23.4__tar.gz

pyield-0.23.4/.gitignore

@@ -0,0 +1,45 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# pdm
+pdm.lock
+.pdm-python
+
+# uv
+uv.lock
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Jupiter Notebook
+.ipynb_checkpoints
+*.ipynb
+
+# Dev folder
+dev/

{pyield-0.23.2 → pyield-0.23.4}/PKG-INFO

@@ -1,45 +1,42 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.3
 Name: PYield
-Version: 0.23.2
+Version: 0.23.4
 Summary: A Python library for analysis of fixed income instruments in Brazil
-Keywords: fixed-income, brazil, finance, analysis, bonds
-Author-Email: Carlos Carvalho <cr.cj@outlook.com>
+Project-URL: Source, https://github.com/crdcj/PYield
+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
+        
+        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.
+License-File: LICENSE
+Keywords: fixed-income, brazil, finance, analysis, bonds
+Classifier: Intended Audience :: Financial and Insurance Industry
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
-Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: Programming Language :: Python :: 3
 Classifier: Topic :: Office/Business :: Financial :: Investment
-Project-URL: Source, https://github.com/crdcj/PYield
 Requires-Python: >=3.12
+Requires-Dist: numpy>=2.0.0
 Requires-Dist: pandas[html,parquet]>=2.0.0
-Requires-Dist: numpy
 Requires-Dist: python-calamine>=0.2.0
 Requires-Dist: requests>=2.31.0
-Requires-Dist: pandas-stubs
-Requires-Dist: lxml-stubs
-Requires-Dist: types-requests
 Description-Content-Type: text/markdown
 
 [![PyPI version](https://img.shields.io/pypi/v/pyield.svg)](https://pypi.python.org/pypi/pyield)

pyield-0.23.4/pyield/__about__.py

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

{pyield-0.23.2 → pyield-0.23.4}/pyield/b3_futures/intraday.py

@@ -1,19 +1,9 @@
-from io import StringIO
-
 import pandas as pd
 import requests
 
 from pyield import bday
 
 
-# Função para salvar DataFrame em CSV e ler com read_csv
-def _convert_with_read_csv(df):
-    buffer = StringIO()
-    df.to_csv(buffer, index=False)
-    buffer.seek(0)  # Reposiciona o cursor no início do buffer
-    return pd.read_csv(buffer, dtype_backend="numpy_nullable")
-
-
 def _fetch_b3_df(future_code: str) -> pd.DataFrame:
     """
     Fetch the latest data for a given future code from B3 derivatives quotation API.
@@ -47,8 +37,8 @@ def _fetch_b3_df(future_code: str) -> pd.DataFrame:
     # Normalize JSON response into a flat table
     df = pd.json_normalize(r.json()["Scty"])
 
-    # Convert DataFrame to use nullable data types for better type consistency
-    return _convert_with_read_csv(df)
+    # Convert columns to the most appropriate data type
+    return df.convert_dtypes()
 
 
 def _rename_columns(df: pd.DataFrame) -> pd.DataFrame:

{pyield-0.23.2 → pyield-0.23.4}/pyield/bday.py

@@ -3,15 +3,15 @@ from typing import Literal, overload
 import numpy as np
 import pandas as pd
 
-from pyield import date_converter as dc
+import pyield.date_converter as dc
+import pyield.holidays as hl
 from pyield.date_converter import ArrayDateTypes, ScalarDateTypes
-from pyield.holidays import BrHolidays
 
-type ArrayIntTypes = np.ndarray | pd.Series | list | tuple
-type ScalarIntTypes = int | np.integer
+ArrayIntTypes = np.ndarray | pd.Series | list | tuple
+ScalarIntTypes = int | np.integer
 
 # Initialize Brazilian holidays data
-br_holidays = BrHolidays()
+br_holidays = hl.BrHolidays()
 OLD_HOLIDAYS_ARRAY = br_holidays.get_holiday_array(holiday_option="old")
 NEW_HOLIDAYS_ARRAY = br_holidays.get_holiday_array(holiday_option="new")
 

{pyield-0.23.2 → pyield-0.23.4}/pyield/bonds/ntnb.py

@@ -457,34 +457,67 @@ def bei_rates(
 ) -> pd.DataFrame:
     """
     Calculate the Breakeven Inflation (BEI) for NTN-B bonds based on nominal and real
-    interest rates.
+    interest rates. The BEI represents the inflation rate that equalizes the real and
+    nominal yields. The calculation is based on the spot rates for NTN-B bonds.
 
     Args:
-        settlement (str or pd.Timestamp): The settlement date for the bonds.
-        ntnb_maturities (pd.Series): Series of maturity dates for the inflation-indexed
-            bonds (NTN-B).
-        ntnb_rates (pd.Series): Series of real interest rates (Yield to Maturity - YTM)
-            corresponding to the inflation-indexed bonds' maturity dates.
-        nominal_maturities (pd.Series): Series of maturity dates corresponding to the
+        settlement (str or pd.Timestamp): The settlement date of the operation.
+        ntnb_maturities (pd.Series): The maturity dates for the NTN-B bonds.
+        ntnb_rates (pd.Series): The real interest rates (Yield to Maturity - YTM)
+            corresponding to the given NTN-B maturities.
+        nominal_maturities (pd.Series): The maturity dates to be used as reference for
             nominal reates.
-        nominal_rates (pd.Series): Series of nominal interest rates
-            (e.g., DI or prefixed bonds) used as reference for the calculation.
+        nominal_rates (pd.Series): The nominal interest rates (e.g. DI Futures or
+             zero prefixed bonds rates) used as reference for the calculation.
 
     Returns:
         pd.DataFrame: DataFrame containing the calculated breakeven inflation rates.
 
     Returned columns:
         - MaturityDate: The maturity date of the bonds.
-        - BDays: Number of business days from the settlement date to the maturity date.
-        - RIR: The calculated Real Interest Rate based on the spot rates.
-        - NIR: Nominal Interest Rate interpolated for the corresponding maturity date.
-        - BEI: The calculated Breakeven Inflation Rate, which represents the inflation
-            rate that equalizes the real and nominal yields.
+        - RIR: The calculated Real Interest Rates based on the spot rates.
+        - NIR: The Nominal Interest Rates interpolated for the maturity date.
+        - BEI: The calculated Breakeven Inflation Rates.
 
     Notes:
         The BEI is calculated by comparing the nominal and real interest rates,
         indicating the market's inflation expectations over the period from the
         settlement date to the bond's maturity.
+
+    Examples:
+        Get the NTN-B rates for a specific reference date.
+        These are YTM rates and the spot rates are calculated based on them
+        >>> df_ntnb = yd.ntnb.rates("05-09-2024")
+
+        Get the DI Futures settlement rates for the same reference date to be used as
+        reference for the nominal rates:
+        >>> di = yd.DIFutures("05-09-2024")
+        >>> df_di = di.data
+
+        Calculate the BEI rates considering the settlement at the reference date:
+        >>> yd.ntnb.bei_rates(
+        ...     settlement="05-09-2024",
+        ...     ntnb_maturities=df_ntnb["MaturityDate"],
+        ...     ntnb_rates=df_ntnb["IndicativeRate"],
+        ...     nominal_maturities=df_di["ExpirationDate"],
+        ...     nominal_rates=df_di["SettlementRate"],
+        ... )
+           MaturityDate       RIR       NIR       BEI
+        0    2025-05-15  0.061749  0.113836  0.049058
+        1    2026-08-15  0.066133  0.117126   0.04783
+        2    2027-05-15  0.063816  0.117169  0.050152
+        3    2028-08-15  0.063635   0.11828  0.051376
+        4    2029-05-15  0.062532   0.11838  0.052561
+        5    2030-08-15  0.061809  0.118499   0.05339
+        6    2032-08-15  0.062135  0.118084  0.052676
+        7    2033-05-15  0.061897   0.11787   0.05271
+        8    2035-05-15  0.061711  0.117713  0.052747
+        9    2040-08-15  0.060468   0.11759  0.053865
+        10   2045-05-15    0.0625   0.11759   0.05185
+        11   2050-08-15  0.063016   0.11759  0.051339
+        12   2055-05-15  0.062252   0.11759  0.052095
+        13   2060-08-15  0.063001   0.11759  0.051354
+
     """
     # Normalize input dates
     settlement = dc.convert_input_dates(settlement)

{pyield-0.23.2 → pyield-0.23.4}/pyield/date_converter.py

@@ -4,8 +4,8 @@ from typing import overload
 import numpy as np
 import pandas as pd
 
-type ScalarDateTypes = str | np.datetime64 | pd.Timestamp | dt.datetime | dt.date
-type ArrayDateTypes = pd.Series | pd.DatetimeIndex | np.ndarray | list | tuple
+ScalarDateTypes = str | np.datetime64 | pd.Timestamp | dt.datetime | dt.date
+ArrayDateTypes = pd.Series | pd.DatetimeIndex | np.ndarray | list | tuple
 
 
 def validate_date_format(date_str):

{pyield-0.23.2 → pyield-0.23.4}/pyield/di.py

@@ -15,9 +15,15 @@ class DIFutures:
     includes options to adjust expiration dates and apply filters based on LTN and
     NTN-F bond maturities.
 
+    Args:
+        trade_date (str | pd.Timestamp): The date to retrieve the contract data.
+        adj_expirations (bool): If True, adjusts the expiration dates to the start
+            of the month.
+        prefixed_filter (bool): If True, filters the DI contracts to match only
+            expirations with existing LTN and NTN-F bond maturities.
+
     Examples:
         To create a `DIFutures` instance and retrieve data:
-
         >>> di = yd.DIFutures(trade_date="16-10-2024", adj_expirations=True)
         >>> df = di.data  # Retrieve DI contract dataframe for the specified date
         >>> df.iloc[:5, :5]  # Show the first five rows and columns
@@ -29,7 +35,6 @@ class DIFutures:
         4       DI1H25     2025-03-01          94         344056         221
 
         You can also retrieve forward rates for the DI contracts:
-
         >>> di.forwards.iloc[:5]  # Show the first five rows
           ExpirationDate  SettlementRate  ForwardRate
         0     2024-11-01         0.10653      0.10653
@@ -59,13 +64,6 @@ class DIFutures:
     ):
         """
         Initialize the DIFutures instance with a specific trade date.
-
-        Args:
-            trade_date (str | pd.Timestamp): The date to retrieve the contract data.
-            adj_expirations (bool): If True, adjusts the expiration dates to the start
-                of the month.
-            prefixed_filter (bool): If True, filters the DI contracts to match LTN and
-                NTN-F bond maturities.
         """
         self._trade_date = dc.convert_input_dates(trade_date)
         self._adj_expirations = adj_expirations

{pyield-0.23.2 → pyield-0.23.4}/pyield/indicators.py

@@ -44,6 +44,7 @@ def indicator(
 
     Raises:
         ValueError: If an invalid `indicator_code` is provided.
+        ValueError: After all retries, if the indicator value cannot be fetched.
 
     Examples:
         >>> yd.indicator("IPCA_MR", "01-04-2024")
@@ -102,7 +103,7 @@ def ipca_monthly_rate(reference_date: pd.Timestamp) -> float:
     data = response.json()
 
     if not data:
-        return float("nan")
+        raise ValueError("No data available for the specified date")
     # Extract and return the IPCA monthly growth rate if data is available
     ipca_str = data[0]["resultados"][0]["series"][0]["serie"][ipca_date]
     return round(float(ipca_str) / 100, 4)
@@ -146,8 +147,8 @@ def _selic_target(reference_date: pd.Timestamp) -> float:
         attempt += 1
         time.sleep(1.5**attempt)  # Exponential backoff: 1.5, 2.3, 3.9, 5.1, 7.6 seconds
 
-    # After all retries, return NaN
-    return float("nan")
+    # After all retries, raise an error
+    raise ValueError("Failed to fetch SELIC Target rate after maximum attempts")
 
 
 def _selic_over(reference_date: pd.Timestamp) -> float:
@@ -191,8 +192,8 @@ def _selic_over(reference_date: pd.Timestamp) -> float:
         attempt += 1
         time.sleep(1.5**attempt)  # Exponential backoff: 1.5, 2.3, 3.9, 5.1, 7.6 seconds
 
-    # After all retries, return NaN
-    return float("nan")
+    # After all retries, raise an error
+    raise ValueError("Failed to fetch SELIC Over rate after maximum attempts")
 
 
 def _di(reference_date: pd.Timestamp) -> float:
@@ -210,22 +211,13 @@ def _di(reference_date: pd.Timestamp) -> float:
     return round((1 + value) ** 252 - 1, 4)
 
 
-def _vna_lft(reference_date: pd.Timestamp) -> float:
-    # url example: https://www3.bcb.gov.br/novoselic/rest/arquivosDiarios/pub/download/3/20240418APC238
-    url_base = "https://www3.bcb.gov.br/novoselic/rest/arquivosDiarios/pub/download/3/"
-    url_file = f"{reference_date.strftime('%Y%m%d')}APC238"
-    url_vna = url_base + url_file
-
-    response = requests.get(url_vna, timeout=TIMEOUT)
-    response.raise_for_status()
-    file_text = response.text
-
+def _extract_vna_value(text: str) -> float:
     # Finding the part that contains the table
-    start_of_table = file_text.find("EMISSAO")
-    end_of_table = file_text.find("99999999*")
+    start_of_table = text.find("EMISSAO")
+    end_of_table = text.find("99999999*")
 
     # Extracting the table
-    table_text = file_text[start_of_table:end_of_table].strip()
+    table_text = text[start_of_table:end_of_table].strip()
     table_lines = table_text.splitlines()
 
     # Remove empty lines
@@ -246,3 +238,29 @@ def _vna_lft(reference_date: pd.Timestamp) -> float:
         raise ValueError(f"VNA values are not the same. Please check data at {bcb_url}")
 
     return vna_value
+
+
+def _vna_lft(reference_date: pd.Timestamp) -> float:
+    # url example: https://www3.bcb.gov.br/novoselic/rest/arquivosDiarios/pub/download/3/20240418APC238
+    url_base = "https://www3.bcb.gov.br/novoselic/rest/arquivosDiarios/pub/download/3/"
+    url_file = f"{reference_date.strftime('%Y%m%d')}APC238"
+    url_vna = url_base + url_file
+    session = requests.Session()
+
+    attempt = 0
+    while attempt < MAX_ATTEMPTS:
+        try:
+            response = session.get(url_vna, timeout=TIMEOUT)
+            response.raise_for_status()
+            return _extract_vna_value(response.text)
+
+        except (RequestException, KeyError, IndexError, ValueError) as e:
+            msg = f"Error fetching SELIC Over rate (attempt {attempt + 1}): {e}"
+            logging.error(msg)
+
+        # Increment attempt count and add backoff delay
+        attempt += 1
+        time.sleep(1.5**attempt)  # Exponential backoff: 1.5, 2.3, 3.9, 5.1, 7.6 seconds
+
+    # After all retries, raise an error
+    raise ValueError("Failed to fetch VNA LFT value after maximum attempts")

{pyield-0.23.2 → pyield-0.23.4}/pyield/interpolator.py

@@ -11,17 +11,16 @@ class Interpolator:
 
     Args:
         method (Literal["flat_forward", "linear"]): The interpolation method to use.
-        known_bdays (pd.Series | pd.Index | list): Series of known business days.
-        known_rates (pd.Series | pd.Index | list): Series of known interest rates.
-        extrapolate (bool, optional): Whether to extrapolate beyond known business days.
+        known_bdays (pd.Series | list[int]): The known business days sequence.
+        known_rates (pd.Series | list[float]): The known interest rates sequence.
+        extrapolate (bool, optional): If True, extrapolates beyond known business days
+            using the last available rate. Defaults to False, returning NaN for
+            out-of-range values.
 
     Raises:
         ValueError: If known_bdays and known_rates do not have the same length.
         ValueError: If the interpolation method is not recognized
 
-    Returns:
-        Interpolator: An instance of the Interpolator
-
     Note:
         This class uses a 252 business days per year convention.
 
@@ -30,10 +29,12 @@ class Interpolator:
         >>> known_bdays = [30, 60, 90]
         >>> known_rates = [0.045, 0.05, 0.055]
 
+        Linear interpolation example:
         >>> lin_interp = Interpolator("linear", known_bdays, known_rates)
         >>> lin_interp(45)
         0.0475
 
+        Flat forward interpolation example:
         >>> ffo_interp = Interpolator("flat_forward", known_bdays, known_rates)
         >>> ffo_interp(45)
         0.04833068080970859
@@ -42,8 +43,8 @@ class Interpolator:
     def __init__(
         self,
         method: Literal["flat_forward", "linear"],
-        known_bdays: pd.Series | list,
-        known_rates: pd.Series | list,
+        known_bdays: pd.Series | list[int],
+        known_rates: pd.Series | list[float],
         extrapolate: bool = False,
     ):
         self.method = method

{pyield-0.23.2 → pyield-0.23.4}/pyproject.toml

@@ -1,20 +1,11 @@
-[build-system]
-requires = [
-    "pdm-backend",
-]
-build-backend = "pdm.backend"
-
 [project]
 name = "PYield"
-authors = [
-    { name = "Carlos Carvalho", email = "cr.cj@outlook.com" },
-]
+authors = [{ name = "Carlos Carvalho", email = "cr.cj@outlook.com" }]
 description = "A Python library for analysis of fixed income instruments in Brazil"
 readme = "README.md"
 requires-python = ">=3.12"
-keywords = [
-    "fixed-income, brazil, finance, analysis, bonds",
-]
+keywords = ["fixed-income, brazil, finance, analysis, bonds"]
+license = { file = "LICENSE" }
 classifiers = [
     "Programming Language :: Python :: 3",
     "License :: OSI Approved :: MIT License",
@@ -24,36 +15,16 @@ classifiers = [
 ]
 dependencies = [
     "pandas[html,parquet]>=2.0.0",
-    "numpy",
-    "python-calamine>=0.2.0",
+    "numpy>=2.0.0",
+    "python-calamine>=0.2.0",    
     "requests>=2.31.0",
-    "pandas-stubs",
-    "lxml-stubs",
-    "types-requests",
 ]
-dynamic = []
-version = "0.23.2"
-
-[project.license]
-file = "LICENSE"
+dynamic = ["version"]
 
 [project.urls]
 Source = "https://github.com/crdcj/PYield"
 
-[tool.pdm]
-distribution = true
-
-[tool.pdm.version]
-source = "file"
-path = "pyield/__about__.py"
-
-[tool.pdm.build]
-excludes = [
-    "tests",
-    "docs",
-]
-
-[tool.pdm.dev-dependencies]
+[dependency-groups]
 dev = [
     "ipykernel",
     "pytest",
@@ -62,27 +33,42 @@ dev = [
     "mkdocs-material",
     "mkdocstrings[python]",
     "mkdocs-autorefs",
+    "pandas-stubs",
+    "lxml-stubs",
+    "types-requests",
 ]
 
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.version]
+path = "pyield/__about__.py"
+
+[tool.hatch.build.targets.sdist]
+only-include = ["pyield"]
+
+[tool.pdm]
+version = { source = "file", path = "pyield/__about__.py" }
+distribution = true
+
+[tool.pdm.build]
+excludes = ["tests", "docs"]
+
+[tool.uv]
+package = true
+
 [tool.ruff]
 line-length = 88
 indent-width = 4
 target-version = "py312"
-extend-include = [
-    "*.ipynb",
-]
+extend-include = ["*.ipynb"]
 
 [tool.ruff.lint]
 preview = true
-select = [
-    "I",
-    "F",
-    "E",
-    "W",
-    "PL",
-    "PT",
-]
+select = ["I", "F", "E", "W", "PL", "PT"]
 
 [tool.ruff.format]
 docstring-code-format = true
 docstring-code-line-length = 88
+

pyield-0.23.2/pyield/__about__.py

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