PYield 0.19.2__tar.gz → 0.20.0__tar.gz

{pyield-0.19.2 → pyield-0.20.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: PYield
-Version: 0.19.2
+Version: 0.20.0
 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>
@@ -179,16 +179,12 @@ TradeDate  TickerSymbol ExpirationDate BDaysToExp ... LastRate LastAskRate LastB
 ```python
 >>> import pyield as yd
 # Fetch the SELIC target rate from the Central Bank of Brazil
->>> yd.indicator(indicator_code="SELIC", reference_date='12-04-2024')
+>>> yd.indicator(indicator_code="SELIC_TARGET", reference_date='12-04-2024')
 0.1075  # 10.75%
 
 # Fetch the IPCA monthly inflation rate from IBGE
->>> yd.indicator(indicator_code="IPCA", reference_date='18-03-2024')
-0.16  # 0.16%
-
-# If no data is yet available for the indicator, the function returns None
->>> yd.indicator(indicator_code="IPCA", reference_date='10-04-2024')
-None
+>>> yd.indicator(indicator_code="IPCA_MR", reference_date='18-03-2024')
+0.0016  # 0.16%
 ```
 
 ### Projections Data

{pyield-0.19.2 → pyield-0.20.0}/README.md

@@ -135,16 +135,12 @@ TradeDate  TickerSymbol ExpirationDate BDaysToExp ... LastRate LastAskRate LastB
 ```python
 >>> import pyield as yd
 # Fetch the SELIC target rate from the Central Bank of Brazil
->>> yd.indicator(indicator_code="SELIC", reference_date='12-04-2024')
+>>> yd.indicator(indicator_code="SELIC_TARGET", reference_date='12-04-2024')
 0.1075  # 10.75%
 
 # Fetch the IPCA monthly inflation rate from IBGE
->>> yd.indicator(indicator_code="IPCA", reference_date='18-03-2024')
-0.16  # 0.16%
-
-# If no data is yet available for the indicator, the function returns None
->>> yd.indicator(indicator_code="IPCA", reference_date='10-04-2024')
-None
+>>> yd.indicator(indicator_code="IPCA_MR", reference_date='18-03-2024')
+0.0016  # 0.16%
 ```
 
 ### Projections Data

pyield-0.20.0/pyield/__about__.py

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

pyield-0.20.0/pyield/__init__.py

@@ -0,0 +1,23 @@
+from pyield import anbima, bday, di, tools
+from pyield.__about__ import __version__
+from pyield.b3_futures import futures
+from pyield.bonds import lft, ltn, ntnb, ntnf
+from pyield.indicators import indicator
+from pyield.interpolator import Interpolator
+from pyield.projections import projection
+
+__all__ = [
+    "__version__",
+    "anbima",
+    "bday",
+    "futures",
+    "indicator",
+    "ntnb",
+    "ntnf",
+    "ltn",
+    "lft",
+    "di",
+    "projection",
+    "Interpolator",
+    "tools",
+]

{pyield-0.19.2/pyield/data_sources → pyield-0.20.0/pyield}/anbima.py

@@ -5,9 +5,9 @@ import zipfile as zp
 import pandas as pd
 import requests
 
-from .. import bday
-from .. import date_converter as dc
-from .data_cache import get_anbima_dataframe
+from pyield import bday
+from pyield import date_converter as dc
+from pyield.data_cache import get_anbima_dataframe
 
 # URL Constants
 ANBIMA_URL = "https://www.anbima.com.br/informacoes/merc-sec/arqs"
@@ -110,7 +110,7 @@ def data(
     bond_type: str | None = None,
 ) -> pd.DataFrame:
     # Normalize the reference date
-    reference_date = dc.convert_date(reference_date)
+    reference_date = dc.convert_input_dates(reference_date)
     file_content = _get_file_content(reference_date)
 
     if not file_content:
@@ -134,7 +134,7 @@ def rates(
 ) -> pd.DataFrame:
     df = get_anbima_dataframe()
 
-    reference_date = dc.convert_date(reference_date)
+    reference_date = dc.convert_input_dates(reference_date)
     df.query("ReferenceDate == @reference_date", inplace=True)
 
     if df.empty:
@@ -159,7 +159,7 @@ def pre_maturities(
     reference_date: str | pd.Timestamp,
 ) -> pd.Series:
     df = get_anbima_dataframe()
-    reference_date = dc.convert_date(reference_date)
+    reference_date = dc.convert_input_dates(reference_date)
     df.query("ReferenceDate == @reference_date", inplace=True)
     df.query("BondType in ['LTN', 'NTN-F']", inplace=True)
     maturity_dates = df["MaturityDate"].drop_duplicates()

{pyield-0.19.2/pyield/data_sources/futures_data → pyield-0.20.0/pyield/b3_futures}/__init__.py

@@ -3,7 +3,7 @@ import datetime as dt
 import pandas as pd
 from pytz import timezone
 
-from ... import date_converter as dc
+from .. import date_converter as dc
 from .historical import fetch_historical_df
 from .intraday import fetch_intraday_df
 
@@ -47,7 +47,7 @@ def futures(
     if contract_code not in SUPPORTED_FUTURES:
         raise ValueError("Futures contract not supported.")
 
-    trade_date = dc.convert_date(trade_date)
+    trade_date = dc.convert_input_dates(trade_date)
 
     # First, try to fetch historical data for the specified date
     df = fetch_historical_df(contract_code, trade_date)

{pyield-0.19.2/pyield/data_sources/futures_data → pyield-0.20.0/pyield/b3_futures}/common.py

@@ -1,6 +1,6 @@
 import pandas as pd
 
-from ... import bday
+from pyield import bday
 
 
 def get_expiration_date(expiration_code: str, expiration_day: int = 1) -> pd.Timestamp:

{pyield-0.19.2/pyield/data_sources/futures_data → pyield-0.20.0/pyield/b3_futures}/historical.py

@@ -3,8 +3,8 @@ import io
 import pandas as pd
 import requests
 
-from ... import bday
-from . import common
+from pyield import bday
+from pyield.b3_futures import common
 
 COUNT_CONVENTIONS = {
     "DAP": 252,

{pyield-0.19.2/pyield/data_sources/futures_data → pyield-0.20.0/pyield/b3_futures}/intraday.py

@@ -3,7 +3,7 @@ from io import StringIO
 import pandas as pd
 import requests
 
-from ... import bday
+from pyield import bday
 
 
 # Função para salvar DataFrame em CSV e ler com read_csv

{pyield-0.19.2/pyield/data_sources/futures_data → pyield-0.20.0/pyield/b3_futures}/xml.py

@@ -7,9 +7,8 @@ import pandas as pd
 import requests
 from lxml import etree
 
-import pyield as yd
-
-from . import common
+from pyield import bday
+from pyield.b3_futures import common
 
 
 def _get_file_from_path(file_path: Path) -> io.BytesIO:
@@ -201,7 +200,7 @@ def _process_df(df_raw: pd.DataFrame) -> pd.DataFrame:
     # Remove expired contracts
     df.query("DaysToExp > 0", inplace=True)
 
-    df["BDaysToExp"] = yd.bday.count(df["TradeDate"], df["ExpirationDate"])
+    df["BDaysToExp"] = bday.count(df["TradeDate"], df["ExpirationDate"])
 
     rate_cols = [col for col in df.columns if "Rate" in col]
     # Remove % and round to 5 (3 in %) dec. places in rate columns

{pyield-0.19.2 → pyield-0.20.0}/pyield/bday.py

@@ -1,58 +1,17 @@
-import datetime as dt
 from typing import Literal, overload
 
 import numpy as np
 import pandas as pd
 
-from . import holidays
-
-type ScalarDateTypes = str | np.datetime64 | pd.Timestamp | dt.datetime | dt.date
-type PandasArrayDateTypes = pd.Series | pd.DatetimeIndex | pd.Index
-type ArrayDateTypes = PandasArrayDateTypes | np.ndarray | list | tuple
+from pyield import date_converter as dc
+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
 
 # Initialize the BrHolidays class
-br_holidays = holidays.BrHolidays()
-
-
-@overload
-def _convert_input_dates(dates: ScalarDateTypes) -> pd.Timestamp: ...
-@overload
-def _convert_input_dates(dates: ArrayDateTypes) -> pd.Series: ...
-
-
-def _convert_input_dates(
-    dates: ScalarDateTypes | ArrayDateTypes,
-) -> pd.Timestamp | pd.Series:
-    result = pd.to_datetime(dates, dayfirst=True)
-    if isinstance(result, (pd.Timestamp, dt.date, dt.datetime, np.datetime64)):
-        result = pd.Timestamp(result).normalize()
-    elif isinstance(result, (pd.Series, pd.DatetimeIndex)):
-        result = pd.Series(result).astype("datetime64[ns]")
-    else:
-        raise ValueError("Invalid date input type.")
-
-    return result
-
-
-def _convert_to_numpy_date(
-    dates: pd.Timestamp | pd.Series,
-) -> np.datetime64 | np.ndarray:
-    """
-    Converts the input dates to a numpy datetime64[D] format.
-
-    Args:
-        dates (Timestamp | Series): A single date or a Series of dates.
-
-    Returns:
-        np.datetime64 | np.ndarray: The input dates in a numpy datetime64[D] format.
-    """
-    if isinstance(dates, pd.Timestamp):
-        return np.datetime64(dates, "D")
-    else:
-        return dates.to_numpy().astype("datetime64[D]")
+br_holidays = BrHolidays()
 
 
 @overload
@@ -188,14 +147,14 @@ def offset(
         information on error handling and behavior, refer to the `numpy.busday_offset`
         documentation: https://numpy.org/doc/stable/reference/generated/numpy.busday_offset.html
     """
-    normalized_dates = _convert_input_dates(dates)
+    converted_dates = dc.convert_input_dates(dates)
 
     selected_holidays = br_holidays.get_applicable_holidays(
-        normalized_dates, holiday_list
+        converted_dates, holiday_list
     )
-    selected_holidays_np = _convert_to_numpy_date(selected_holidays)
+    selected_holidays_np = dc.convert_to_numpy_date(selected_holidays)
 
-    dates_np = _convert_to_numpy_date(normalized_dates)
+    dates_np = dc.convert_to_numpy_date(converted_dates)
     offsetted_dates_np = np.busday_offset(
         dates_np, offsets=offset, roll=roll, holidays=selected_holidays_np
     )
@@ -304,18 +263,18 @@ def count(
         1    19
         dtype: Int64
     """
-    normalized_start = _convert_input_dates(start)
-    normalized_end = _convert_input_dates(end)
+    converted_start = dc.convert_input_dates(start)
+    converted_end = dc.convert_input_dates(end)
 
     # Determine which list of holidays to use
     selected_holidays = br_holidays.get_applicable_holidays(
-        normalized_start, holiday_list
+        converted_start, holiday_list
     )
-    selected_holidays_np = _convert_to_numpy_date(selected_holidays)
+    selected_holidays_np = dc.convert_to_numpy_date(selected_holidays)
 
     # Convert inputs to numpy datetime64[D] before calling numpy.busday_count
-    start_np = _convert_to_numpy_date(normalized_start)
-    end_np = _convert_to_numpy_date(normalized_end)
+    start_np = dc.convert_to_numpy_date(converted_start)
+    end_np = dc.convert_to_numpy_date(converted_end)
 
     result_np = np.busday_count(start_np, end_np, holidays=selected_holidays_np)
     if isinstance(result_np, np.integer):
@@ -371,11 +330,12 @@ def generate(
         https://pandas.pydata.org/docs/reference/api/pandas.bdate_range.html.
     """
     if start:
-        converted_start = _convert_input_dates(start)
+        converted_start = dc.convert_input_dates(start)
     else:
         converted_start = pd.Timestamp.today()
+
     if end:
-        converted_end = _convert_input_dates(end)
+        converted_end = dc.convert_input_dates(end)
     else:
         converted_end = pd.Timestamp.today()
 
@@ -410,6 +370,6 @@ def is_business_day(date: ScalarDateTypes) -> bool:
         >>> bday.is_business_day("25-12-2023")  # Christmas
         False
     """
-    converted_date = _convert_input_dates(date)
+    converted_date = dc.convert_input_dates(date)
     shifted_date = offset(converted_date, 0)  # Shift the date if it is not a bus. day
     return converted_date == shifted_date

{pyield-0.19.2 → pyield-0.20.0}/pyield/bonds/bond_tools.py

@@ -3,8 +3,8 @@ from typing import overload
 import numpy as np
 import pandas as pd
 
-from .. import date_converter as dc
-from ..data_sources import anbima, di
+from pyield import anbima, di
+from pyield import date_converter as dc
 
 
 @overload
@@ -77,7 +77,7 @@ def di_spreads(reference_date: str | pd.Timestamp) -> pd.DataFrame:
             bond type and maturity date.
     """
     # Fetch DI rates for the reference date
-    reference_date = dc.convert_date(reference_date)
+    reference_date = dc.convert_input_dates(reference_date)
     df_di = di.data(reference_date, adj_expirations=True)
     if "SettlementRate" not in df_di.columns:
         raise ValueError("DI rates data is missing the 'SettlementRate' column.")

{pyield-0.19.2 → pyield-0.20.0}/pyield/bonds/lft.py

@@ -1,9 +1,8 @@
 import pandas as pd
 
-from .. import bday
-from .. import date_converter as dc
-from ..data_sources import anbima
-from . import bond_tools as bt
+from pyield import anbima, bday
+from pyield import date_converter as dc
+from pyield.bonds import bond_tools as bt
 
 
 def rates(reference_date: str | pd.Timestamp) -> pd.DataFrame:
@@ -54,7 +53,7 @@ def quotation(
 
     Examples:
         Calculate the quotation of a LFT bond with a 0.02 yield rate:
-        >>> lft.quotation(
+        >>> yd.lft.quotation(
         ...     settlement="24-07-2024",
         ...     maturity="01-09-2030",
         ...     rate=0.001717,  # 0.1717%
@@ -62,8 +61,8 @@ def quotation(
         98.9645
     """
     # Validate and normalize dates
-    settlement = dc.convert_date(settlement)
-    maturity = dc.convert_date(maturity)
+    settlement = dc.convert_input_dates(settlement)
+    maturity = dc.convert_input_dates(maturity)
 
     # The number of bdays between settlement (inclusive) and the maturity (exclusive)
     bdays = bday.count(settlement, maturity)
@@ -92,8 +91,8 @@ def premium(lft_rate: float, selic_over: float) -> float:
         Calculate the premium of a LFT bond with a 0.02 yield rate over the Selic rate:
         >>> lft_rate = 0.1695 / 100  # 0.1695%
         >>> selic_over = 10.40 / 100  # 10.40%
-        >>> lft.premium(lft_rate, selic_over)
-        1.017121 # 101.7121%
+        >>> yd.lft.premium(lft_rate, selic_over)
+        1.017121
     """
     adjusted_lft_rate = (lft_rate + 1) * (selic_over + 1) - 1
     f1 = (adjusted_lft_rate + 1) ** (1 / 252) - 1

{pyield-0.19.2 → pyield-0.20.0}/pyield/bonds/ltn.py

@@ -1,9 +1,8 @@
 import pandas as pd
 
-from .. import bday
-from .. import date_converter as dc
-from ..data_sources import anbima, di
-from . import bond_tools as bt
+from pyield import anbima, bday, di
+from pyield import date_converter as dc
+from pyield.bonds import bond_tools as bt
 
 FACE_VALUE = 1000
 
@@ -61,13 +60,13 @@ def price(
         - https://www.anbima.com.br/data/files/A0/02/CC/70/8FEFC8104606BDC8B82BA2A8/Metodologias%20ANBIMA%20de%20Precificacao%20Titulos%20Publicos.pdf
 
     Examples:
-        >>> price("05-07-2024", "01-01-2030", 0.12145)
+        >>> yd.ltn.price("05-07-2024", "01-01-2030", 0.12145)
         535.279902
     """
 
     # Validate and normalize dates
-    settlement = dc.convert_date(settlement)
-    maturity = dc.convert_date(maturity)
+    settlement = dc.convert_input_dates(settlement)
+    maturity = dc.convert_input_dates(maturity)
 
     # Calculate the number of business days between settlement and cash flow dates
     bdays = bday.count(settlement, maturity)
@@ -90,11 +89,10 @@ def di_spreads(reference_date: str | pd.Timestamp) -> pd.DataFrame:
 
     Parameters:
         reference_date (str | pd.Timestamp, optional): The reference date for the
-            spread calculation. If None or not provided, defaults to the previous
-            business day according to the Brazilian calendar.
+            spread calculation.
 
     Returns:
-        pd.DataFrame: DataFrame with the columns "MaturityDate" and "DISpread".
+        pd.DataFrame: DataFrame with the columns "MaturityDate" and "DISpread" (in bps).
     """
     # Fetch DI Spreads for the reference date
     df = bt.di_spreads(reference_date)
@@ -113,6 +111,13 @@ def premium(ltn_rate: float, di_rate: float) -> float:
 
     Returns:
         float: The premium of the LTN bond over the DI Future rate.
+
+    Examples:
+        Reference date: 22-08-2024
+        LTN rate for 01-01-2030: 0.118746
+        DI (JAN30) Settlement rate: 0.11725
+        >>> yd.ltn.premium(0.118746, 0.11725)
+        1.012072
     """
     # Cálculo das taxas diárias
     ltn_factor = (1 + ltn_rate) ** (1 / 252)
@@ -138,8 +143,8 @@ def historical_premium(
                If the data is not available, returns NaN.
     """
     # Convert input dates to a consistent format
-    reference_date = dc.convert_date(reference_date)
-    maturity = dc.convert_date(maturity)
+    reference_date = dc.convert_input_dates(reference_date)
+    maturity = dc.convert_input_dates(maturity)
 
     # Retrieve LTN rates for the reference date
     df_anbima = rates(reference_date)

{pyield-0.19.2 → pyield-0.20.0}/pyield/bonds/ntnb.py

@@ -1,11 +1,10 @@
 import numpy as np
 import pandas as pd
 
-from .. import bday
-from .. import date_converter as dc
-from .. import interpolator as it
-from ..data_sources import anbima
-from . import bond_tools as bt
+from pyield import anbima, bday
+from pyield import date_converter as dc
+from pyield.bonds import bond_tools as bt
+from pyield.interpolator import Interpolator
 
 """
 Constants calculated as per Anbima Rules and in base 100
@@ -99,8 +98,8 @@ def _generate_coupon_dates_map(
         pd.Series: Series of coupon dates within the specified range.
     """
     # Validate and normalize dates
-    start = dc.convert_date(start)
-    end = dc.convert_date(end)
+    start = dc.convert_input_dates(start)
+    end = dc.convert_input_dates(end)
 
     # Initialize the first coupon date based on the reference date
     reference_year = start.year
@@ -136,10 +135,17 @@ def payment_dates(
 
     Returns:
         pd.Series: Series of coupon dates within the specified range.
+
+    Examples:
+        >>> yd.ntnb.payment_dates("10-05-2024", "15-05-2025")
+        0   2024-05-15
+        1   2024-11-15
+        2   2025-05-15
+        dtype: datetime64[ns]
     """
     # Validate and normalize dates
-    settlement = dc.convert_date(settlement)
-    maturity = dc.convert_date(maturity)
+    settlement = dc.convert_input_dates(settlement)
+    maturity = dc.convert_input_dates(maturity)
     _check_maturities(maturity)
 
     # Check if maturity date is after the start date
@@ -178,10 +184,17 @@ def cash_flows(
     Returned columns:
         - PaymentDate: The payment date of the cash flow
         - CashFlow: Cash flow value for the bond
+
+    Examples:
+        >>> yd.ntnb.cash_flows("10-05-2024", "15-05-2025")
+          PaymentDate    CashFlow
+        0  2024-05-15    2.956301
+        1  2024-11-15    2.956301
+        2  2025-05-15  102.956301
     """
     # Validate and normalize dates
-    settlement = dc.convert_date(settlement)
-    maturity = dc.convert_date(maturity)
+    settlement = dc.convert_input_dates(settlement)
+    maturity = dc.convert_input_dates(maturity)
 
     # Get the coupon dates between the settlement and maturity dates
     p_dates = payment_dates(settlement, maturity)
@@ -219,14 +232,14 @@ def quotation(
           Anbima rules.
 
     Examples:
-        >>> ntnb.quotation("31-05-2024", "15-05-2035", 0.061490)
+        >>> yd.ntnb.quotation("31-05-2024", "15-05-2035", 0.061490)
         99.3651
-        >>> ntnb.quotation("31-05-2024", "15-08-2060", 0.061878)
+        >>> yd.ntnb.quotation("31-05-2024", "15-08-2060", 0.061878)
         99.5341
     """
     # Validate and normalize dates
-    settlement = dc.convert_date(settlement)
-    maturity = dc.convert_date(maturity)
+    settlement = dc.convert_input_dates(settlement)
+    maturity = dc.convert_input_dates(maturity)
     _check_maturities(maturity)
 
     cf_df = cash_flows(settlement, maturity)
@@ -266,7 +279,7 @@ def price(
         - https://www.anbima.com.br/data/files/A0/02/CC/70/8FEFC8104606BDC8B82BA2A8/Metodologias%20ANBIMA%20de%20Precificacao%20Titulos%20Publicos.pdf
 
     Examples:
-        >>> ntnb.price(4299.160173, 99.3651)
+        >>> yd.ntnb.price(4299.160173, 99.3651)
         4271.864805
     """
     return bt.truncate(vna * quotation / 100, 6)
@@ -306,12 +319,12 @@ def spot_rates(
                 - SpotRate: The real spot rate for the bond.
     """
     # Process and validate the input data
-    settlement = dc.convert_date(settlement)
+    settlement = dc.convert_input_dates(settlement)
     maturities = pd.to_datetime(maturities, errors="raise", dayfirst=True)
     _check_maturities(maturities)
 
     # Create the interpolator object
-    ff_interpolator = it.Interpolator(
+    ff_interpolator = Interpolator(
         method="flat_forward",
         known_bdays=bday.count(settlement, maturities),
         known_rates=rates,
@@ -401,7 +414,7 @@ def bei_rates(
         settlement date to the bond's maturity.
     """
     # Normalize input dates
-    settlement = dc.convert_date(settlement)
+    settlement = dc.convert_input_dates(settlement)
     ntnb_maturities = pd.to_datetime(ntnb_maturities, errors="coerce", dayfirst=True)
 
     # Calculate Real Interest Rate (RIR)
@@ -409,7 +422,7 @@ def bei_rates(
     df["BDays"] = bday.count(settlement, df["MaturityDate"])
     df = df.rename(columns={"SpotRate": "RIR"})
 
-    nir_interplator = it.Interpolator(
+    nir_interplator = Interpolator(
         method="flat_forward",
         known_bdays=bday.count(settlement, nominal_maturities),
         known_rates=nominal_rates,
@@ -434,8 +447,8 @@ def duration(
     maturity: str | pd.Timestamp,
     rate: float,
 ) -> float:
-    settlement = dc.convert_date(settlement)
-    maturity = dc.convert_date(maturity)
+    settlement = dc.convert_input_dates(settlement)
+    maturity = dc.convert_input_dates(maturity)
 
     df = cash_flows(settlement, maturity)
     df["BY"] = bday.count(settlement, df["PaymentDate"]) / 252