PYield 0.3.6__tar.gz → 0.3.7__tar.gz

{pyield-0.3.6 → pyield-0.3.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: PYield
-Version: 0.3.6
+Version: 0.3.7
 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>

pyield-0.3.7/pyield/__about__.py

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

pyield-0.3.7/pyield/__init__.py

@@ -0,0 +1,15 @@
+from .__about__ import __version__
+from .di_futures import get_di, read_di
+from .br_calendar import count_bdays, generate_bdays, offset_bdays
+from .anbima import get_treasury_rates, calculate_treasury_di_spreads
+
+__all__ = [
+    "__version__",
+    "get_di",
+    "read_di",
+    "count_bdays",
+    "generate_bdays",
+    "offset_bdays",
+    "get_treasury_rates",
+    "calculate_treasury_di_spreads",
+]

{pyield-0.3.6 → pyield-0.3.7}/pyield/anbima.py

@@ -1,4 +1,5 @@
 import pandas as pd
+from pandas import Timestamp, DataFrame
 from urllib.error import HTTPError
 
 from . import di_futures as di
@@ -12,9 +13,7 @@ ANBIMA_MEMBER_URL = "http://www.anbima.associados.rtm/merc_sec/arqs/"
 BP_CONVERSION_FACTOR = 10_000
 
 
-def process_reference_date(
-    reference_date: str | pd.Timestamp | None = None,
-) -> pd.Timestamp:
+def process_reference_date(reference_date: str | Timestamp | None = None) -> Timestamp:
     """
     Process the given reference date, converting it to a pandas Timestamp. If no date is provided,
     use the previous business day based on the Brazilian calendar.
@@ -26,17 +25,25 @@ def process_reference_date(
     - pd.Timestamp: The processed reference date.
     """
     if reference_date:  # Force reference_date to be a pd.Timestamp
-        processed_date = pd.Timestamp(reference_date)
+        processed_date = pd.to_datetime(reference_date)
     else:  # If no reference_date is given, use the previous business day
         today = pd.Timestamp.today().normalize()
-        processed_date = cl.offset_bdays(today, -1)
+        processed_date = cl.offset_bdays(today, -1)  # type: ignore
+
+    # Check if the reference date is Timestamp
+    if not isinstance(processed_date, Timestamp):
+        raise ValueError("Reference date must be a pandas Timestamp.")
+
+    # Raise an error if the reference date is in the future
+    if processed_date > pd.Timestamp.today().normalize():
+        raise ValueError("Reference date cannot be in the future.")
 
     return processed_date
 
 
 def get_raw_data(
-    reference_date: str | pd.Timestamp | None = None, is_anbima_member: bool = False
-) -> pd.DataFrame:
+    reference_date: str | Timestamp | None = None, is_anbima_member: bool = False
+) -> DataFrame:
     """
     Fetch indicative rates from ANBIMA for a specific date.
 
@@ -75,7 +82,7 @@ def get_raw_data(
     return df
 
 
-def process_raw_data(df: pd.DataFrame) -> pd.DataFrame:
+def process_raw_data(df_raw: DataFrame) -> DataFrame:
     """
     Process raw data from ANBIMA by filtering selected columns, renaming them, and adjusting data formats.
 
@@ -104,8 +111,8 @@ def process_raw_data(df: pd.DataFrame) -> pd.DataFrame:
         # "Criterio": "Criteria",
     }
     select_columns = list(selected_columns_dict.keys())
-    df = df[select_columns].copy()
-    df.rename(columns=selected_columns_dict, inplace=True)
+    df = df_raw[select_columns].copy()
+    df = df.rename(columns=selected_columns_dict)
 
     # Remove percentage from rates
     rate_cols = ["BidRate", "AskRate", "IndicativeRate"]
@@ -118,10 +125,10 @@ def process_raw_data(df: pd.DataFrame) -> pd.DataFrame:
 
 
 def get_treasury_rates(
-    reference_date: str | pd.Timestamp | None = None,
+    reference_date: str | Timestamp | None = None,
     return_raw=False,
     is_anbima_member=False,
-) -> pd.DataFrame:
+) -> DataFrame:
     """
     Fetch and process indicative rates from ANBIMA for a specific date.
     If no date is provided, the previous business day based on the Brazilian calendar
@@ -146,9 +153,9 @@ def get_treasury_rates(
 
 
 def calculate_treasury_di_spreads(
-    reference_date: str | pd.Timestamp | None = None,
+    reference_date: str | Timestamp | None = None,
     is_anbima_member=False,
-) -> pd.DataFrame:
+) -> DataFrame:
     """
     Calculate the DI spread for LTN and NTN-F bonds based on ANBIMA's indicative rates.
     If no date is provided, the previous business day based on the Brazilian calendar

{pyield-0.3.6 → pyield-0.3.7}/pyield/br_calendar.py

@@ -1,7 +1,8 @@
-from typing import Literal
+from typing import Literal, overload
 
-import pandas as pd
 import numpy as np
+import pandas as pd
+from pandas import Series, Timestamp
 
 from .br_holidays import BrHolidays
 
@@ -9,9 +10,28 @@ from .br_holidays import BrHolidays
 br_holidays = BrHolidays()
 
 
-def convert_to_numpy_date(
-    dates: pd.Timestamp | pd.Series,
-) -> np.datetime64 | np.ndarray:
+@overload
+def format_input_dates(dates: str | Timestamp | None) -> Timestamp: ...
+
+
+@overload
+def format_input_dates(dates: Series) -> Series: ...
+
+
+# Implementação da função que atende às sobrecargas acima
+def format_input_dates(dates: str | Timestamp | Series | None) -> Timestamp | Series:
+    if dates is None:
+        return pd.Timestamp.today().normalize()
+    result = pd.to_datetime(dates)
+    if isinstance(result, pd.Series):
+        return result
+    elif result is pd.NaT:
+        raise ValueError("Invalid date format.")
+    else:
+        return pd.Timestamp(result).normalize()
+
+
+def convert_to_numpy_date(dates: Timestamp | Series) -> np.datetime64 | np.ndarray:
     """
     Converts the input dates to a numpy datetime64[D] format.
 
@@ -27,11 +47,27 @@ def convert_to_numpy_date(
         return dates.to_numpy().astype("datetime64[D]")
 
 
+@overload
+def offset_bdays(
+    dates: str | Timestamp | None = None,
+    offset: int = 0,
+    holiday_list: Literal["old", "new", "infer"] = "infer",
+) -> Timestamp: ...
+
+
+@overload
+def offset_bdays(
+    dates: Series,
+    offset: int = 0,
+    holiday_list: Literal["old", "new", "infer"] = "infer",
+) -> Series: ...
+
+
 def offset_bdays(
-    dates: str | pd.Timestamp | pd.Series,
-    offset: int,
+    dates: str | Timestamp | Series | None = None,
+    offset: int = 0,
     holiday_list: Literal["old", "new", "infer"] = "infer",
-):
+) -> Timestamp | Series:
     """
     Offsets the dates to the next or previous business day. This function is a wrapper
     for `numpy.busday_offset` to be used directly with Pandas data types that infers the
@@ -65,22 +101,53 @@ def offset_bdays(
         >>> yd.offset_bdays(date, -1)
         Timestamp('2023-12-21') # Offset to the previous business day
     """
-    # Assure that the input is in pandas datetime64[ns] format
-    dates_pd = pd.to_datetime(dates)
+    formatted_dates = format_input_dates(dates)
 
-    selected_holidays = br_holidays.get_applicable_holidays(dates_pd, holiday_list)
+    selected_holidays = br_holidays.get_applicable_holidays(
+        formatted_dates, holiday_list
+    )
     selected_holidays_np = convert_to_numpy_date(selected_holidays)
 
-    dates_np = convert_to_numpy_date(dates_pd)
+    dates_np = convert_to_numpy_date(formatted_dates)
     offsetted_dates_np = np.busday_offset(
         dates_np, offsets=offset, roll="forward", holidays=selected_holidays_np
     )
+    if isinstance(offsetted_dates_np, np.datetime64):
+        return pd.Timestamp(offsetted_dates_np, unit="ns")
+    else:
+        result = pd.to_datetime(offsetted_dates_np, unit="ns")
+        return pd.Series(result)
+
+
+@overload
+def count_bdays(
+    start: str | Timestamp | None = None,
+    end: str | Timestamp | None = None,
+    holiday_list: Literal["old", "new", "infer"] = "infer",
+) -> int: ...
 
-    # Convert the dates back to a pandas datetime64[ns] format
-    return pd.to_datetime(offsetted_dates_np, unit="ns")
 
+@overload
+def count_bdays(
+    start: Series,
+    end: str | Timestamp | Series | None,
+    holiday_list: Literal["old", "new", "infer"] = "infer",
+) -> Series: ...
+
+
+@overload
+def count_bdays(
+    start: str | Timestamp | Series | None,
+    end: Series,
+    holiday_list: Literal["old", "new", "infer"] = "infer",
+) -> Series: ...
 
-def count_bdays(start, end, holiday_list: Literal["old", "new", "infer"] = "infer"):
+
+def count_bdays(
+    start: str | Timestamp | Series | None = None,
+    end: str | Timestamp | Series | None = None,
+    holiday_list: Literal["old", "new", "infer"] = "infer",
+) -> int | Series:
     """
     Counts the number of business days between a `start` (inclusive) and `end`
     (exclusive). If an end date is earlier than the start date, the count will be
@@ -88,16 +155,15 @@ def count_bdays(start, end, holiday_list: Literal["old", "new", "infer"] = "infe
     with Pandas data types.
 
     Args:
-        start (str | pd.Timestamp, optional): The start date. Defaults to None.
-        end (str | pd.Timestamp optional): The end date. Defaults to None.
+        start (str | Timestamp, optional): The start date. Defaults to None.
+        end (str | Timestamp optional): The end date. Defaults to None.
         holiday_list (str, optional): The list of holidays to use. Defaults to "infer",
             which infers the right list of holidays based on the most recent date in
             the input.
 
     Returns:
-        np.int64 | np.ndarray: The number of business days between the start date and
-        end dates. Returns a single integer if `end` is a single Timestamp, otherwise
-        returns an ndarray of integers.
+        int | pd.Series: The number of business days between the start date and end date.
+        Returns an integer if the result is a single value, otherwise returns a Series.
 
     Notes:
         - For more information on error handling, see numpy.busday_count documentation at
@@ -115,30 +181,36 @@ def count_bdays(start, end, holiday_list: Literal["old", "new", "infer"] = "infe
         >>> start = '2023-01-01'
         >>> end = pd.to_datetime(['2023-01-31', '2023-03-01'])
         >>> yd.count_bdays(start, end)
-        array([22, 40])
+        pd.Series([22, 40], dtype='int64')
     """
-    # Assure that the inputs are in pandas datetime64[ns] format
-    start_pd = pd.to_datetime(start)
-    end_pd = pd.to_datetime(end)
+    formatted_start = format_input_dates(start)
+    formatted_end = format_input_dates(end)
 
     # Determine which list of holidays to use
-    selected_holidays = br_holidays.get_applicable_holidays(start_pd, holiday_list)
+    selected_holidays = br_holidays.get_applicable_holidays(
+        formatted_start, holiday_list
+    )
     selected_holidays_np = convert_to_numpy_date(selected_holidays)
 
     # Convert inputs to numpy datetime64[D] before calling numpy.busday_count
-    start_np = convert_to_numpy_date(start_pd)
-    end_np = convert_to_numpy_date(end_pd)
+    start_np = convert_to_numpy_date(formatted_start)
+    end_np = convert_to_numpy_date(formatted_end)
 
-    return np.busday_count(start_np, end_np, holidays=selected_holidays_np)
+    result_np = np.busday_count(start_np, end_np, holidays=selected_holidays_np)
+    if isinstance(result_np, np.ndarray):
+        # Return pandas Int64 type for type consistency
+        return pd.Series(result_np, dtype="Int64")
+    else:
+        return int(result_np)
 
 
 def generate_bdays(
-    start: str | pd.Timestamp | None = None,
-    end: str | pd.Timestamp | None = None,
-    inclusive="both",
+    start: str | Timestamp | None = None,
+    end: str | Timestamp | None = None,
+    inclusive: Literal["both", "neither", "left", "right"] = "both",
     holiday_list: Literal["old", "new", "infer"] = "infer",
     **kwargs,
-) -> pd.DatetimeIndex:
+) -> Series:
     """
     Generates a Series of business days between a `start` (inclusive) and `end`
     (inclusive) that takes into account the list of brazilian holidays as the default.
@@ -179,24 +251,23 @@ def generate_bdays(
         2023-12-29    2023-12-29
         dtype: object
     """
-    if start:
-        start_pd = pd.to_datetime(start)
-    else:
-        start_pd = pd.Timestamp.today().normalize()
+    formatted_start = format_input_dates(start)
+    formatted_end = format_input_dates(end)
 
-    if end:
-        end_pd = pd.to_datetime(end)
-    else:
-        end_pd = pd.Timestamp.today().normalize()
+    if isinstance(formatted_start, Series) or isinstance(formatted_end, Series):
+        raise ValueError("The start and end dates must be single dates.")
 
-    selected_holidays = br_holidays.get_applicable_holidays(start_pd, holiday_list)
+    selected_holidays = br_holidays.get_applicable_holidays(
+        formatted_start, holiday_list
+    )
     selected_holidays_list = selected_holidays.to_list()
 
-    return pd.bdate_range(
-        start_pd,
-        end_pd,
+    result = pd.bdate_range(
+        formatted_start,
+        formatted_end,
         freq="C",
         inclusive=inclusive,
         holidays=selected_holidays_list,
         **kwargs,
     )
+    return pd.Series(result)

{pyield-0.3.6 → pyield-0.3.7}/pyield/br_holidays.py

@@ -2,6 +2,7 @@ from pathlib import Path
 from typing import Literal
 
 import pandas as pd
+from pandas import Series, Timestamp
 
 
 class BrHolidays:
@@ -15,7 +16,7 @@ class BrHolidays:
         self.new_holidays = self._load_holidays(new_holidays_path)
         self.old_holidays = self._load_holidays(old_holidays_path)
 
-    def _load_holidays(self, file_path: Path) -> pd.Series:
+    def _load_holidays(self, file_path: Path) -> Series:
         """Loads the list of holidays from a text file and returns it as a pd.Series of pd.Timestamp."""
         df = pd.read_csv(file_path, header=None, names=["date"], comment="#")
         # Convert the dates to a pd.Series of pd.Timestamp
@@ -23,9 +24,9 @@ class BrHolidays:
 
     def get_applicable_holidays(
         self,
-        dates: pd.Timestamp | pd.Series,
+        dates: Timestamp | Series,
         holiday_list: Literal["old", "new", "infer"] = "infer",
-    ) -> pd.Series:
+    ) -> Series:
         """
         Returns the correct list of holidays to use based on the most recent date in the input.
 
@@ -38,7 +39,7 @@ class BrHolidays:
         Returns:
             pd.Series: The list of holidays to use.
         """
-        if isinstance(dates, pd.Timestamp):
+        if isinstance(dates, Timestamp):
             earliest_date = dates
         else:
             earliest_date = dates.min()

{pyield-0.3.6 → pyield-0.3.7}/pyield/di_futures.py

@@ -1,14 +1,15 @@
-from typing import Literal, Optional
+from typing import Literal
 from pathlib import Path
+
 import pandas as pd
-import pandas.api.types
+from pandas import DataFrame, Timestamp
 
 from . import di_web as diw
 from . import di_xml as dix
 from . import br_calendar as brc
 
 
-def get_expiration_date(expiration_code: str) -> Optional[pd.Timestamp]:
+def get_expiration_date(expiration_code: str) -> Timestamp:
     """
     Internal function to convert the expiration code into its expiration date.
 
@@ -63,15 +64,18 @@ def get_expiration_date(expiration_code: str) -> Optional[pd.Timestamp]:
         year = int("20" + expiration_code[-2:])
         # The expiration date is always the first business day of the month
         expiration = pd.Timestamp(year, month, 1)
+
         # Adjust to the next business day when expiration date is a weekend or a holiday
-        return brc.offset_bdays(expiration, offset=0)
+        adj_expiration = brc.offset_bdays(expiration, offset=0)
+
+        return adj_expiration
 
     except (KeyError, ValueError):
-        return pd.NaT  # type: ignore
+        raise ValueError("Invalid expiration code.")
 
 
 def get_di(
-    trade_date: str | pd.Timestamp,
+    trade_date: str | Timestamp,
     source_type: Literal["bmf", "b3", "b3s"] = "bmf",
     return_raw: bool = False,
 ) -> pd.DataFrame:
@@ -121,7 +125,7 @@ def get_di(
         raise ValueError("source_type must be either 'bmf', 'b3' or 'b3s'.")
 
 
-def read_di(file_path: Path, return_raw: bool = False) -> pd.DataFrame:
+def read_di(file_path: Path, return_raw: bool = False) -> DataFrame:
     """
     Reads a DI futures data file and returns a DataFrame.
 

{pyield-0.3.6 → pyield-0.3.7}/pyield/di_web.py

@@ -3,6 +3,7 @@ import warnings
 from typing import Optional
 
 import pandas as pd
+from pandas import Timestamp, Series, DataFrame
 import requests
 
 from . import br_calendar as brc
@@ -10,8 +11,8 @@ from . import di_futures as dif
 
 
 def get_old_expiration_date(
-    ExpirationCode: str, trade_date: pd.Timestamp
-) -> Optional[pd.Timestamp]:
+    ExpirationCode: str, trade_date: Timestamp
+) -> Optional[Timestamp]:
     """
     Internal function to convert an old DI contract code into its ExpirationDate date. Valid for
     contract codes up to 21-05-2006.
@@ -71,7 +72,7 @@ def get_old_expiration_date(
         return pd.NaT  # type: ignore
 
 
-def get_raw_di(trade_date: pd.Timestamp) -> pd.DataFrame:
+def get_raw_di(trade_date: Timestamp) -> DataFrame:
     """
     Internal function to fetch raw DI futures data from B3 for a specific trade date.
 
@@ -119,7 +120,7 @@ def get_raw_di(trade_date: pd.Timestamp) -> pd.DataFrame:
         return pd.DataFrame()
 
 
-def convert_prices_to_rates(prices: pd.Series, bd: pd.Series) -> pd.Series:
+def convert_prices_to_rates(prices: Series, bd: Series) -> Series:
     """
     Internal function to convert DI futures prices to rates.
 
@@ -136,7 +137,7 @@ def convert_prices_to_rates(prices: pd.Series, bd: pd.Series) -> pd.Series:
     return 100 * rates
 
 
-def convert_prices_in_older_contracts(df: pd.DataFrame) -> pd.DataFrame:
+def convert_prices_in_older_contracts(df: DataFrame) -> DataFrame:
     # Prior to 01/01/2002, prices were not converted to rates
     convert_cols = [
         "FirstRate",
@@ -156,7 +157,7 @@ def convert_prices_in_older_contracts(df: pd.DataFrame) -> pd.DataFrame:
     return df
 
 
-def process_di(df: pd.DataFrame, trade_date: pd.Timestamp) -> pd.DataFrame:
+def process_di(df: DataFrame, trade_date: Timestamp) -> DataFrame:
     """
     Internal function to process and transform raw DI futures data.
 
@@ -265,7 +266,7 @@ def process_di(df: pd.DataFrame, trade_date: pd.Timestamp) -> pd.DataFrame:
     return df[ordered_cols]
 
 
-def get_di(trade_date: pd.Timestamp, return_raw: bool = False) -> pd.DataFrame:
+def get_di(trade_date: Timestamp, return_raw: bool = False) -> DataFrame:
     """
     Gets the DI futures data for a given date from B3.
 

{pyield-0.3.6 → pyield-0.3.7}/pyield/di_xml.py

@@ -4,13 +4,14 @@ from pathlib import Path
 
 import requests
 import pandas as pd
+from pandas import Timestamp, DataFrame
 from lxml import etree
 
 from . import di_futures as dif
 from . import br_calendar as brc
 
 
-def get_file_from_url(trade_date: pd.Timestamp, source_type: str) -> io.BytesIO:
+def get_file_from_url(trade_date: Timestamp, source_type: str) -> io.BytesIO:
     """
     Types of XML files available:
     Full Price Report (all assets)
@@ -119,7 +120,7 @@ def extract_di_data_from_xml(xml_file: io.BytesIO) -> list[dict]:
     return di_data
 
 
-def create_df_from_di_data(di1_data: list) -> pd.DataFrame:
+def create_df_from_di_data(di1_data: list) -> DataFrame:
     # Criar um DataFrame com os dados coletados
     df = pd.DataFrame(di1_data)
 
@@ -128,7 +129,7 @@ def create_df_from_di_data(di1_data: list) -> pd.DataFrame:
     return pd.read_csv(file, dtype_backend="numpy_nullable")
 
 
-def filter_and_order_pr_df(df: pd.DataFrame) -> pd.DataFrame:
+def filter_and_order_pr_df(df: DataFrame) -> DataFrame:
     selected_columns = [
         "TradDt",
         "TckrSymb",
@@ -164,7 +165,7 @@ def filter_and_order_pr_df(df: pd.DataFrame) -> pd.DataFrame:
     return df[selected_columns]
 
 
-def filter_and_order_sprd_df(df: pd.DataFrame) -> pd.DataFrame:
+def filter_and_order_sprd_df(df: DataFrame) -> DataFrame:
     cols = [
         "TradDt",
         "TckrSymb",
@@ -186,7 +187,7 @@ def filter_and_order_sprd_df(df: pd.DataFrame) -> pd.DataFrame:
     return df[cols]
 
 
-def standardize_column_names(df: pd.DataFrame) -> pd.DataFrame:
+def standardize_column_names(df: DataFrame) -> DataFrame:
     rename_dict = {
         "TradDt": "TradeDate",
         "TckrSymb": "Ticker",
@@ -223,7 +224,7 @@ def standardize_column_names(df: pd.DataFrame) -> pd.DataFrame:
     return df.rename(columns=rename_dict)
 
 
-def process_di_df(df_raw: pd.DataFrame) -> pd.DataFrame:
+def process_di_df(df_raw: DataFrame) -> DataFrame:
     df = df_raw.copy()
     # Convert to datetime64[ns] since it is pandas default type for timestamps
     df["TradDt"] = df["TradDt"].astype("datetime64[ns]")
@@ -243,11 +244,7 @@ def process_di_df(df_raw: pd.DataFrame) -> pd.DataFrame:
     return df.sort_values(by=["ExpirationDate"], ignore_index=True)
 
 
-def get_di(
-    trade_date: pd.Timestamp,
-    source_type: str,
-    return_raw: bool,
-) -> pd.DataFrame:
+def get_di(trade_date: Timestamp, source_type: str, return_raw: bool) -> DataFrame:
     zip_file = get_file_from_url(trade_date, source_type)
 
     xml_file = extract_xml_from_zip(zip_file)
@@ -263,6 +260,8 @@ def get_di(
         df_di = filter_and_order_pr_df(df_raw)
     elif source_type == "b3s":
         df_di = filter_and_order_sprd_df(df_raw)
+    else:
+        raise ValueError("Invalid source type. Must be 'b3' or 'b3s'.")
 
     # Process and transform data
     df_di = process_di_df(df_di)
@@ -273,7 +272,7 @@ def get_di(
     return df_di
 
 
-def read_di(file_path: Path, return_raw: bool = False) -> pd.DataFrame:
+def read_di(file_path: Path, return_raw: bool = False) -> DataFrame:
     if file_path:
         if file_path.exists():
             content = file_path.read_bytes()

{pyield-0.3.6 → pyield-0.3.7}/pyproject.toml

@@ -31,7 +31,7 @@ dependencies = [
     "lxml",
 ]
 dynamic = []
-version = "0.3.6"
+version = "0.3.7"
 
 [project.license]
 file = "LICENSE"

pyield-0.3.6/pyield/__about__.py

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

pyield-0.3.6/pyield/__init__.py

@@ -1,4 +0,0 @@
-from .__about__ import __version__  # noqa: F401
-from .di_futures import get_di, read_di  # noqa: F401
-from .br_calendar import count_bdays, generate_bdays, offset_bdays  # noqa: F401
-from .anbima import get_treasury_rates, calculate_treasury_di_spreads  # noqa: F401