PYield 0.5.1__tar.gz → 0.7.0__tar.gz

{pyield-0.5.1 → pyield-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: PYield
-Version: 0.5.1
+Version: 0.7.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>
@@ -44,7 +44,7 @@ Description-Content-Type: text/markdown
 [![Made with Python](https://img.shields.io/badge/Python->=3.11-blue?logo=python&logoColor=white)](https://python.org "Go to Python homepage")
 [![License](https://img.shields.io/badge/License-MIT-blue)](#license)
 
-# PYield: Brazilian Fixed Income Analysis Library
+# PYield: Fixed Income Toolbox for Brazilian Markets
 
 ## Introduction
 
@@ -55,7 +55,7 @@ Welcome to PYield, a Python library designed for the analysis of fixed income in
 - **Data Collection**: Automated fetching of data from ANBIMA and B3.
 - **Data Processing**: Efficient processing and normalization of fixed income data.
 - **Analysis Tools**: Built-in functions for common analysis tasks in fixed income markets.
-- **Easy Integration**: Seamless integration with Python data analysis workflows.
+- **Easy Integration**: Seamless integration with pandas data analysis workflows.
 - **Type Hints**: Full support for static type checking, enhancing development experience and code quality.
 
 ## Installation
@@ -67,30 +67,14 @@ pip install pyield
 
 ## How to use PYield
 
-### DI Futures Data
-```python
-import pyield as yd
-
-# Get a pandas dataframe with the DI processed data from B3 (default)
->>> yd.get_di(trade_date='2024-03-08')
- TradeDate ExpirationCode ExpirationDate  BDToExpiration  ...  LastRate  LastAskRate  LastBidRate  SettlementRate
-2024-03-08            J24     2024-04-01              15  ...    10.952       10.952       10.956          10.956
-2024-03-08            K24     2024-05-02              37  ...    10.776       10.774       10.780          10.777
-2024-03-08            M24     2024-06-03              58  ...    10.604       10.602       10.604          10.608
-       ...            ...            ...             ...  ...       ...          ...          ...             ...
-2024-03-08            F37     2037-01-02            3213  ...      <NA>         <NA>         <NA>          10.859
-2024-03-08            F38     2038-01-04            3462  ...      <NA>         <NA>         <NA>          10.859
-2024-03-08            F39     2039-01-03            3713  ...      <NA>         <NA>         <NA>          10.85
-```
-
 ### Business Days Tools (Brazilian holidays are automatically considered)
 ```python
-# Generate a pandas series with the business days between two dates
->>> yd.generate_bdays(start='2023-12-29', end='2024-01-03')
-0   2023-12-29
-1   2024-01-02
-2   2024-01-03
-dtype: datetime64[ns]
+>>> import pyield as yd
+
+# Count the number of business days between two dates
+# Start date is included, end date is excluded
+>>> yd.count_bdays(start='2023-12-29', end='2024-01-02')
+1
 
 # Get the next business day after a given date (offset=1)
 >>> yd.offset_bdays(dates="2023-12-29", offset=1)
@@ -104,8 +88,72 @@ Timestamp('2024-01-02 00:00:00')
 >>> yd.offset_bdays(dates="2023-12-29", offset=0)
 Timestamp('2023-12-29 00:00:00')
 
-# Count the number of business days between two dates
-# Start date is included, end date is excluded
->>> yd.count_bdays(start='2023-12-29', end='2024-01-02')
-1
+# Generate a pandas series with the business days between two dates
+>>> yd.generate_bdays(start='2023-12-29', end='2024-01-03')
+0   2023-12-29
+1   2024-01-02
+2   2024-01-03
+dtype: datetime64[ns]
+```
+
+### Futures Data
+```python
+# Fetch a DataFrame with the DI Futures data from B3
+>>> yd.fetch_asset(asset_code="DI1", reference_date='2024-03-08')
+
+TradeDate  ExpirationCode ExpirationDate BDToExpiration  ... LastRate LastAskRate LastBidRate SettlementRate
+2024-03-08 J24            2024-04-01     15              ... 10.952   10.952      10.956      10.956
+2024-03-08 K24            2024-05-02     37              ... 10.776   10.774      10.780      10.777
+2024-03-08 M24            2024-06-03     58              ... 10.604   10.602      10.604      10.608
+...        ...            ...            ...             ... ...      ...         ...         ...
+2024-03-08 F37            2037-01-02     3213            ... <NA>     <NA>        <NA>        10.859
+2024-03-08 F38            2038-01-04     3462            ... <NA>     <NA>        <NA>        10.859
+2024-03-08 F39            2039-01-03     3713            ... <NA>     <NA>        <NA>        10.85
+```
+
+### Treasury Bonds Data
+```python
+# Fetch a DataFrame with the NTN-B data from ANBIMA
+# Anbima data is available for the last 5 working days
+# Obs: Anbima members have access to the full history
+>>> yd.fetch_asset(asset_code="NTN-B", reference_date='2024-04-12')
+
+BondType ReferenceDate MaturityDate BidRate AskRate IndicativeRate Price
+NTN-B    2024-04-12    2024-08-15   0.07540 0.07504 0.07523        4,271.43565
+NTN-B    2024-04-12    2025-05-15   0.05945 0.05913 0.05930        4,361.34391
+NTN-B    2024-04-12    2026-08-15   0.05927 0.05897 0.05910        4,301.40082
+...      ...           ...          ...     ...     ...            ...
+NTN-B    2024-04-12    2050-08-15   0.06039 0.06006 0.06023        4,299.28233
+NTN-B    2024-04-12    2055-05-15   0.06035 0.05998 0.06017        4,367.13360
+NTN-B    2024-04-12    2060-08-15   0.06057 0.06016 0.06036        4,292.26323
+```
+
+### Spreads Calculation
+```python
+# Calculate the spread between two DI Futures contracts and the pre-fix bonds
+>>> yd.calculate_spreads(spread_type="di_vs_pre", reference_date="2024-4-11")
+
+BondType ReferenceDate MaturityDate  DISpread
+LTN      2024-04-11    2024-07-01    -20.28000
+LTN      2024-04-11    2024-10-01    -10.19000
+LTN      2024-04-11    2025-01-01    -15.05000
+...      ...           ...           ...
+NTN-F    2024-04-11    2031-01-01    -0.66000
+NTN-F    2024-04-11    2033-01-01    -5.69000
+NTN-F    2024-04-11    2035-01-01    -1.27000
+```
+
+### Indicators Data
+```python
+# Fetch the SELIC target rate from the Central Bank of Brazil
+>>> yd.fetch_indicator(indicator_code="SELIC", reference_date='2024-04-12')
+10.75
+
+# Fetch the IPCA monthly inflation rate from IBGE
+>>> yd.fetch_indicator(indicator_code="IPCA", reference_date='2024-03-18')
+0.16
+
+# If no data is yet available for the indicator, the function returns None
+>>> yd.fetch_indicator(indicator_code="IPCA", reference_date='2024-04-10')
+None
 ```

pyield-0.7.0/README.md

@@ -0,0 +1,117 @@
+[![PyPI version](https://img.shields.io/pypi/v/pyield.svg)](https://pypi.python.org/pypi/pyield)
+[![Made with Python](https://img.shields.io/badge/Python->=3.11-blue?logo=python&logoColor=white)](https://python.org "Go to Python homepage")
+[![License](https://img.shields.io/badge/License-MIT-blue)](#license)
+
+# PYield: Fixed Income Toolbox for Brazilian Markets
+
+## Introduction
+
+Welcome to PYield, a Python library designed for the analysis of fixed income instruments in Brazil. This library is tailored for financial analysts, researchers, and enthusiasts interested in the Brazilian fixed income market. Leveraging the power of popular Python libraries like Pandas and Requests, PYield simplifies the process of obtaining and processing data from key sources such as ANBIMA and B3.
+
+## Features
+
+- **Data Collection**: Automated fetching of data from ANBIMA and B3.
+- **Data Processing**: Efficient processing and normalization of fixed income data.
+- **Analysis Tools**: Built-in functions for common analysis tasks in fixed income markets.
+- **Easy Integration**: Seamless integration with pandas data analysis workflows.
+- **Type Hints**: Full support for static type checking, enhancing development experience and code quality.
+
+## Installation
+
+You can install PYield using pip:
+```sh
+pip install pyield
+```
+
+## How to use PYield
+
+### Business Days Tools (Brazilian holidays are automatically considered)
+```python
+>>> import pyield as yd
+
+# Count the number of business days between two dates
+# Start date is included, end date is excluded
+>>> yd.count_bdays(start='2023-12-29', end='2024-01-02')
+1
+
+# Get the next business day after a given date (offset=1)
+>>> yd.offset_bdays(dates="2023-12-29", offset=1)
+Timestamp('2024-01-02 00:00:00')
+
+# Get the next business day if it is not a business day (offset=0)
+>>> yd.offset_bdays(dates="2023-12-30", offset=0)
+Timestamp('2024-01-02 00:00:00')
+
+# Since 2023-12-29 is a business day, it returns the same date (offset=0)
+>>> yd.offset_bdays(dates="2023-12-29", offset=0)
+Timestamp('2023-12-29 00:00:00')
+
+# Generate a pandas series with the business days between two dates
+>>> yd.generate_bdays(start='2023-12-29', end='2024-01-03')
+0   2023-12-29
+1   2024-01-02
+2   2024-01-03
+dtype: datetime64[ns]
+```
+
+### Futures Data
+```python
+# Fetch a DataFrame with the DI Futures data from B3
+>>> yd.fetch_asset(asset_code="DI1", reference_date='2024-03-08')
+
+TradeDate  ExpirationCode ExpirationDate BDToExpiration  ... LastRate LastAskRate LastBidRate SettlementRate
+2024-03-08 J24            2024-04-01     15              ... 10.952   10.952      10.956      10.956
+2024-03-08 K24            2024-05-02     37              ... 10.776   10.774      10.780      10.777
+2024-03-08 M24            2024-06-03     58              ... 10.604   10.602      10.604      10.608
+...        ...            ...            ...             ... ...      ...         ...         ...
+2024-03-08 F37            2037-01-02     3213            ... <NA>     <NA>        <NA>        10.859
+2024-03-08 F38            2038-01-04     3462            ... <NA>     <NA>        <NA>        10.859
+2024-03-08 F39            2039-01-03     3713            ... <NA>     <NA>        <NA>        10.85
+```
+
+### Treasury Bonds Data
+```python
+# Fetch a DataFrame with the NTN-B data from ANBIMA
+# Anbima data is available for the last 5 working days
+# Obs: Anbima members have access to the full history
+>>> yd.fetch_asset(asset_code="NTN-B", reference_date='2024-04-12')
+
+BondType ReferenceDate MaturityDate BidRate AskRate IndicativeRate Price
+NTN-B    2024-04-12    2024-08-15   0.07540 0.07504 0.07523        4,271.43565
+NTN-B    2024-04-12    2025-05-15   0.05945 0.05913 0.05930        4,361.34391
+NTN-B    2024-04-12    2026-08-15   0.05927 0.05897 0.05910        4,301.40082
+...      ...           ...          ...     ...     ...            ...
+NTN-B    2024-04-12    2050-08-15   0.06039 0.06006 0.06023        4,299.28233
+NTN-B    2024-04-12    2055-05-15   0.06035 0.05998 0.06017        4,367.13360
+NTN-B    2024-04-12    2060-08-15   0.06057 0.06016 0.06036        4,292.26323
+```
+
+### Spreads Calculation
+```python
+# Calculate the spread between two DI Futures contracts and the pre-fix bonds
+>>> yd.calculate_spreads(spread_type="di_vs_pre", reference_date="2024-4-11")
+
+BondType ReferenceDate MaturityDate  DISpread
+LTN      2024-04-11    2024-07-01    -20.28000
+LTN      2024-04-11    2024-10-01    -10.19000
+LTN      2024-04-11    2025-01-01    -15.05000
+...      ...           ...           ...
+NTN-F    2024-04-11    2031-01-01    -0.66000
+NTN-F    2024-04-11    2033-01-01    -5.69000
+NTN-F    2024-04-11    2035-01-01    -1.27000
+```
+
+### Indicators Data
+```python
+# Fetch the SELIC target rate from the Central Bank of Brazil
+>>> yd.fetch_indicator(indicator_code="SELIC", reference_date='2024-04-12')
+10.75
+
+# Fetch the IPCA monthly inflation rate from IBGE
+>>> yd.fetch_indicator(indicator_code="IPCA", reference_date='2024-03-18')
+0.16
+
+# If no data is yet available for the indicator, the function returns None
+>>> yd.fetch_indicator(indicator_code="IPCA", reference_date='2024-04-10')
+None
+```

pyield-0.7.0/pyield/__about__.py

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

pyield-0.7.0/pyield/__init__.py

@@ -0,0 +1,15 @@
+from .__about__ import __version__
+from .bday import count_bdays, generate_bdays, is_bday, offset_bdays
+from .data_access import fetch_asset, fetch_indicator
+from .data_analysis import calculate_spreads
+
+__all__ = [
+    "__version__",
+    "is_bday",
+    "generate_bdays",
+    "offset_bdays",
+    "count_bdays",
+    "fetch_asset",
+    "fetch_indicator",
+    "calculate_spreads",
+]

pyield-0.5.1/pyield/calendar.py → pyield-0.7.0/pyield/bday.py

@@ -1,16 +1,13 @@
-from typing import Literal, overload, Union
 from datetime import datetime
+from typing import Literal, overload
 
 import numpy as np
 import pandas as pd
 
-
 from .holidays import BrHolidays
 
-
-SingleDateTypes = Union[str, np.datetime64, pd.Timestamp, datetime]
-
-SeriesDateTypes = Union[list, tuple, np.ndarray, pd.Series, pd.Index, pd.DatetimeIndex]
+SingleDateTypes = str | np.datetime64 | pd.Timestamp | datetime
+SeriesDateTypes = list | tuple | np.ndarray | pd.Series | pd.Index | pd.DatetimeIndex
 
 TO_TIMESTAMP_TYPES = (str, np.datetime64, datetime)
 TO_SERIES_TYPES = (list, tuple, np.ndarray, pd.Series, pd.Index, pd.DatetimeIndex)
@@ -113,25 +110,33 @@ def offset_bdays(
     holiday_list: Literal["old", "new", "infer"] = "infer",
 ) -> pd.Timestamp | pd.Series:
     """
-    Offsets the dates to the next or previous business day, considering brazilian holidays.
-    This function supports both single dates and collections of dates, handling them
-    intelligently to return either a single offset date or a series of offset dates.
-    It is a wrapper for `numpy.busday_offset` adapted for Pandas data types and holiday adjustments.
+    Offsets the dates to the next or previous business day, considering brazilian
+    holidays. This function supports both single dates and collections of dates,
+    handling them intelligently to return either a single offset date or a series of
+    offset dates. It is a wrapper for `numpy.busday_offset` adapted for Pandas data
+    types and holiday adjustments.
 
     Args:
-        dates (str | np.datetime64 | pd.Timestamp | datetime | list | tuple | np.ndarray | pd.Series | pd.Index | pd.DatetimeIndex, optional):
-            The date(s) to offset. Can be a single date in various formats (string, `datetime`, `Timestamp`, etc.)
-            or a collection of dates (list, tuple, `Series`, etc.). If None, the current date is used.
-        offset (int): The number of business days to offset the dates. Positive for future dates, negative for past dates.
-            Zero will return the same date if it's a business day, or the next business day otherwise.
-        roll (Literal["forward", "backward"], optional): Direction to roll the date if it falls on a holiday or weekend.
-            'forward' to the next business day, 'backward' to the previous. Defaults to 'forward'.
-        holiday_list (Literal["old", "new", "infer"], optional): The list of holidays to consider. 'old' or 'new' use predefined lists,
-            while 'infer' determines the most appropriate list based on the input dates. Defaults to "infer".
+        dates (str | np.datetime64 | pd.Timestamp | datetime | list | tuple | np.ndarray
+        | pd.Series | pd.Index | pd.DatetimeIndex, optional):
+            The date(s) to offset. Can be a single date in various formats (string,
+            `datetime`, `Timestamp`, etc.) or a collection of dates (list, tuple,
+            `Series`, etc.). If None, the current date is used.
+        offset (int): The number of business days to offset the dates. Positive for
+            future dates, negative for past dates. Zero will return the same date if
+            it's a business day, or the next business day otherwise.
+        roll (Literal["forward", "backward"], optional): Direction to roll the date if
+            it falls on a holiday or weekend. 'forward' to the next business day,
+            'backward' to the previous. Defaults to 'forward'.
+        holiday_list (Literal["old", "new", "infer"], optional):
+            The list of holidays to consider. 'old' or 'new' use predefined lists, while
+            'infer' determines the most appropriate list based on the input dates.
+            Defaults to "infer".
 
     Returns:
-         pd.Timestamp | pd.Series: If a single date is provided, returns a single `Timestamp` of the offset date.
-            If a series of dates is provided, returns a `Series` of offset dates.
+         pd.Timestamp | pd.Series: If a single date is provided, returns a single
+            `Timestamp` of the offset date. If a series of dates is provided, returns a
+            `Series` of offset dates.
 
     Examples:
         >>> date = '2023-12-23' # Saturday before Christmas
@@ -149,8 +154,9 @@ def offset_bdays(
         Timestamp('2023-12-21') # Offset to the previous business day
 
     Note:
-        This function uses `numpy.busday_offset` under the hood, which means it follows the same conventions and limitations
-        for business day calculations. For detailed information on error handling and behavior, refer to the `numpy.busday_offset`
+        This function uses `numpy.busday_offset` under the hood, which means it follows
+        the same conventions and limitations for business day calculations. For detailed
+        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 = _normalize_input_dates(dates)
@@ -209,30 +215,40 @@ def count_bdays(
     holiday_list: Literal["old", "new", "infer"] = "infer",
 ) -> int | pd.Series:
     """
-    Counts the number of business days between a `start` and `end` date(s), inclusively for
-    the start date and exclusively for the end date. The function can handle single dates,
-    arrays of dates, and mixed inputs, returning either a single integer or a Series
-    depending on the inputs. It accounts for specified holidays, effectively excluding
-    them from the business day count.
+    Counts the number of business days between a `start` and `end` date(s), inclusively
+    for the start date and exclusively for the end date. The function can handle single
+    dates, arrays of dates, and mixed inputs, returning either a single integer or a
+    Series depending on the inputs. It accounts for specified holidays, effectively
+    excluding them from the business day count.
 
     Args:
-        start (str | np.datetime64 | pd.Timestamp | datetime | list | tuple | np.ndarray | pd.Series | pd.Index | pd.DatetimeIndex, optional):
+        start (str | np.datetime64 | pd.Timestamp | datetime | list | tuple |
+            np.ndarray | pd.Series | pd.Index | pd.DatetimeIndex, optional):
             The start date(s) for counting. Defaults to the current date if None.
-        end (str | np.datetime64 | pd.Timestamp | datetime | list | tuple | np.ndarray | pd.Series | pd.Index | pd.DatetimeIndex, optional):
-            The end date(s) for counting, which are excluded from the count themselves. Defaults to the current date if None.
+        end (str | np.datetime64 | pd.Timestamp | datetime | list | tuple |
+            np.ndarray | pd.Series | pd.Index | pd.DatetimeIndex, optional):
+            The end date(s) for counting, which are excluded from the count themselves.
+            Defaults to the current date if None.
         holiday_list (Literal["old", "new", "infer"], optional):
-            Specifies which set of holidays to consider in the count. 'old' or 'new' refer to predefined holiday lists,
-            while 'infer' automatically selects the list based on the most recent date in the input. Defaults to "infer".
+            Specifies which set of holidays to consider in the count. 'old' or 'new'
+            refer to predefined holiday lists, while 'infer' automatically selects the
+            list based on the most recent date in the input. Defaults to "infer".
 
     Returns:
         int | pd.Series: Returns an integer if `start` and `end` are single dates,
-            or a Series if either or both are arrays of dates. The value(s) represent the count of business days between `start` and `end`.
+            or a Series if either or both are arrays of dates. The value(s) represent
+            the count of business days between `start` and `end`.
 
     Notes:
-        - This function is a wrapper around `numpy.busday_count`, adapted to work directly with various Pandas and Numpy date formats.
-        - It supports flexible date inputs, including single dates, lists, Series, and more, for both `start` and `end` parameters.
-        - The return type depends on the input types: single dates return an int, while arrays of dates return a pd.Series with the count for each date range.
-        - See `numpy.busday_count` documentation for more details on how holidays are handled and how business day counts are calculated: https://numpy.org/doc/stable/reference/generated/numpy.busday_count.html.
+        - This function is a wrapper around `numpy.busday_count`, adapted to work
+          directly with various Pandas and Numpy date formats.
+        - It supports flexible date inputs, including single dates, lists, Series, and
+          more, for both `start` and `end` parameters.
+        - The return type depends on the input types: single dates return an int, while
+          arrays of dates return a pd.Series with the count for each date range.
+        - See `numpy.busday_count` documentation for more details on how holidays are
+          handled and how business day counts are calculated:
+          https://numpy.org/doc/stable/reference/generated/numpy.busday_count.html.
 
     Examples:
         >>> yd.count_bdays('2023-12-15', '2024-01-01')
@@ -277,28 +293,34 @@ def generate_bdays(
 
     Args:
         start (str | np.datetime64 | pd.Timestamp | datetime, optional):
-            The start date for generating business days. Defaults to None, using the current date.
+            The start date for generating business days. Defaults to None, using the
+            current date.
         end (str | np.datetime64 | pd.Timestamp | datetime, optional):
-            The end date for generating business days. Defaults to None, using the current date.
+            The end date for generating business days. Defaults to None, using the
+            current date.
         inclusive (Literal["both", "neither", "left", "right"], optional):
             Determines which of the start and end dates are included in the result.
             Valid options are 'both', 'neither', 'left', 'right'. Defaults to 'both'.
         holiday_list (Literal["old", "new", "infer"], optional):
-            Specifies the list of holidays to consider. 'old' or 'new' refer to predefined lists,
-            'infer' selects the list based on the most recent date in the range. Defaults to "infer".
+            Specifies the list of holidays to consider. 'old' or 'new' refer to
+            predefined lists, 'infer' selects the list based on the most recent date in
+            the range. Defaults to "infer".
         **kwargs:
-            Additional keyword arguments passed to `pandas.bdate_range` for customization.
+            Additional keyword arguments passed to `pandas.bdate_range` for
+            customization.
 
     Returns:
-        pd.Series: A Series representing a range of business days between the specified start and end dates,
-            considering the specified holidays.
+        pd.Series: A Series representing a range of business days between the specified
+            start and end dates, considering the specified holidays.
 
     Examples:
         >>> yd.generate_bdays(start='2023-12-22', end='2024-01-02')
-        pd.Series(['2023-12-22', '2023-12-26', '2023-12-27', '2023-12-28', '2023-12-29', '2024-01-02'], dtype='datetime64[ns]')
+        pd.Series(['2023-12-22', '2023-12-26', '2023-12-27', '2023-12-28', '2023-12-29',
+            '2024-01-02'], dtype='datetime64[ns]')
 
     Note:
-        For detailed information on parameters and error handling, refer to `pandas.bdate_range` documentation:
+        For detailed information on parameters and error handling, refer to
+        `pandas.bdate_range` documentation:
         https://pandas.pydata.org/docs/reference/api/pandas.bdate_range.html.
     """
     normalized_start = _normalize_input_dates(start)

pyield-0.7.0/pyield/data_access.py

@@ -0,0 +1,88 @@
+import pandas as pd
+
+from . import di
+from . import indicators as ir
+from . import treasuries as tr
+from .utils import _normalize_date
+
+
+def fetch_asset(
+    asset_code: str,
+    reference_date: str | pd.Timestamp | None = None,
+    **kwargs,
+) -> pd.DataFrame:
+    """
+    Fetches data for a specified asset based on type and reference date.
+
+    Args:
+        asset_code (str): The asset code identifying the type of financial asset.
+        Supported options:
+            - "TRB": Treasury bonds (indicative rates from ANBIMA).
+            - "LTN", "LFT", "NTN-F", "NTN-B": Specific types of Brazilian treasury bonds
+                  (indicative rates from ANBIMA).
+            - "DI1": DI Futures rates from B3.
+        reference_date (str | pd.Timestamp | None): The reference date for which data is
+            fetched. Defaults to the previous business day if None.
+        **kwargs: Additional keyword arguments, specifically:
+            - return_raw (bool): Whether to return raw data without processing. Defaults
+              to False.
+
+    Returns:
+        pd.DataFrame: A DataFrame containing the fetched data for the specified asset.
+
+    Raises:
+        ValueError: If the asset code is not recognized or supported.
+
+    Examples:
+        >>> fetch_asset('TRB', '2023-04-01')
+        >>> fetch_asset('DI1', '2023-04-01', return_raw=True)
+    """
+    return_raw = kwargs.get("return_raw", False)
+    normalized_date = _normalize_date(reference_date)
+
+    if asset_code.lower() == "trb":
+        return tr.fetch_data(reference_date=normalized_date, return_raw=return_raw)
+    elif asset_code.lower() in ["ltn", "lft", "ntn-f", "ntn-b"]:
+        df = tr.fetch_data(reference_date=normalized_date)
+        return df.query(f"BondType == '{asset_code.upper()}'")
+
+    elif asset_code.lower() == "di1":
+        return di.fetch_data(
+            trade_date=normalized_date, source_type="bmf", return_raw=return_raw
+        )
+    else:
+        raise ValueError("Asset type not supported.")
+
+
+def fetch_indicator(
+    indicator_code: str,
+    reference_date: str | pd.Timestamp | None = None,
+) -> float | None:
+    """
+    Fetches data for a specified economic indicator and reference date.
+
+    Args:
+        indicator_code (str): The code for the economic indicator. Supported options:
+            - "SELIC": SELIC target rate from the Central Bank of Brazil.
+            - "IPCA": IPCA monthly inflation rate from IBGE.
+        reference_date (str | pd.Timestamp | None): The reference date for which data is
+            fetched. Defaults to the previous business day if None.
+
+    Returns:
+        pd.Series: A Series containing the fetched data for the specified indicator.
+
+    Raises:
+        ValueError: If the indicator code is not recognized or supported.
+
+    Examples:
+        >>> fetch_indicator('SELIC', '2023-04-01')
+        >>> fetch_indicator('IPCA', '2023-04-01')
+    """
+    normalized_date = _normalize_date(reference_date)
+
+    if indicator_code.lower() == "selic":
+        return ir.fetch_selic_target(reference_date=normalized_date)
+    elif indicator_code.lower() == "ipca":
+        return ir.fetch_ipca_mr(reference_date=normalized_date)
+    else:
+        raise ValueError("Indicator type not supported.")

pyield-0.7.0/pyield/data_analysis.py

@@ -0,0 +1,31 @@
+import pandas as pd
+
+from . import treasuries as tr
+from .utils import _normalize_date
+
+
+def calculate_spreads(spread_type: str, reference_date: pd.Timestamp) -> pd.DataFrame:
+    """
+    Calculates spreads between assets based on the specified spread type.
+    If no reference date is provided, the function uses the previous business day.
+
+    Parameters:
+        spread_type (str): The type of spread to calculate. Available options are:
+            - "DI_vs_PRE": the spread between DI Futures and Treasury Pre-Fixed bonds.
+        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.
+
+    Returns:
+        pd.DataFrame: A DataFrame containing the calculated spread in basis points.
+        The data is sorted by asset type and maturity/expiration date.
+
+    Raises:
+        ValueError: If an invalid spread type is provided.
+    """
+    # Normalize the reference date
+    normalized_date = _normalize_date(reference_date)
+    if spread_type.lower() == "di_vs_pre":
+        return tr.calculate_di_spreads(normalized_date)
+    else:
+        raise ValueError("Invalid spread type.")

pyield-0.7.0/pyield/di/__init__.py

@@ -0,0 +1,6 @@
+from .core import fetch_data, read_data
+
+__all__ = [
+    "fetch_data",
+    "read_data",
+]