PYield 0.30.2__tar.gz → 0.30.4__tar.gz

{pyield-0.30.2 → pyield-0.30.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: PYield
-Version: 0.30.2
+Version: 0.30.4
 Summary: A Python library for analysis of fixed income instruments in Brazil
 Project-URL: Source, https://github.com/crdcj/PYield
 Author-email: Carlos Carvalho <cr.cj@outlook.com>

pyield-0.30.4/pyield/__about__.py

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

{pyield-0.30.2 → pyield-0.30.4}/pyield/anbima/ettj.py

@@ -117,15 +117,17 @@ def last_ettj() -> pd.DataFrame:
     calculated and included in the returned DataFrame.
 
     Returns:
-        pd.DataFrame: A DataFrame containing the following columns:
-            - date: Reference date of the yield curve
-            - vertex: Time point in business days
-            - nominal_rate: Zero-coupon nominal interest rate
-            - real_rate: Zero-coupon real interest rate (IPCA-indexed)
-            - implied_inflation: Implied inflation rate (break-even inflation)
-            - nominal_rate_fwd: Forward nominal interest rate
-            - real_rate_fwd: Forward real interest rate
-            - implied_inflation_fwd: Forward implied inflation rate
+        pd.DataFrame: A DataFrame containing the latest ETTJ data.
+
+    DataFrame columns:
+        - date: Reference date of the yield curve
+        - vertex: Time point in business days
+        - nominal_rate: Zero-coupon nominal interest rate
+        - real_rate: Zero-coupon real interest rate (IPCA-indexed)
+        - implied_inflation: Implied inflation rate (break-even inflation)
+        - nominal_rate_fwd: Forward nominal interest rate
+        - real_rate_fwd: Forward real interest rate
+        - implied_inflation_fwd: Forward implied inflation rate
 
     Note:
         All rates are expressed in decimal format (e.g., 0.12 for 12%).

{pyield-0.30.2 → pyield-0.30.4}/pyield/anbima/ima.py

@@ -128,29 +128,31 @@ def last_ima(ima_type: ima_types | None = None) -> pd.DataFrame:
             IMA indexes are returned. Defaults to None.
 
     Returns:
-        pd.DataFrame: A DataFrame containing the IMA data with the following columns:
-            - Date: reference date of the data.
-            - IMAType: type of IMA index.
-            - BondType: type of bond.
-            - Maturity: bond maturity date.
-            - SelicCode: bond code in the SELIC system.
-            - ISIN: international Securities Identification Number.
-            - BDToMat: business days to maturity.
-            - Duration: duration of the bond in business years (252 days/year).
-            - IndicativeRate: indicative rate.
-            - Price: bond price.
-            - InterestPrice: interest price.
-            - DV01: DV01 in R$.
-            - PMR: average repurchase term.
-            - Weight: weight of the bond in the index.
-            - Convexity: convexity of the bond.
-            - TheoreticalQuantity: theoretical quantity.
-            - NumberOfOperations: number of operations.
-            - NegotiatedQuantity: negotiated quantity.
-            - NegotiatedValue: negotiated value.
-            - MarketQuantity: market quantity.
-            - MarketDV01: market DV01 in R$.
-            - MarketValue: market value in R$.
+        pd.DataFrame: A DataFrame containing the IMA data.
+
+    DataFrame columns:
+        - Date: reference date of the data.
+        - IMAType: type of IMA index.
+        - BondType: type of bond.
+        - Maturity: bond maturity date.
+        - SelicCode: bond code in the SELIC system.
+        - ISIN: international Securities Identification Number.
+        - BDToMat: business days to maturity.
+        - Duration: duration of the bond in business years (252 days/year).
+        - IndicativeRate: indicative rate.
+        - Price: bond price.
+        - InterestPrice: interest price.
+        - DV01: DV01 in R$.
+        - PMR: average repurchase term.
+        - Weight: weight of the bond in the index.
+        - Convexity: convexity of the bond.
+        - TheoreticalQuantity: theoretical quantity.
+        - NumberOfOperations: number of operations.
+        - NegotiatedQuantity: negotiated quantity.
+        - NegotiatedValue: negotiated value.
+        - MarketQuantity: market quantity.
+        - MarketDV01: market DV01 in R$.
+        - MarketValue: market value in R$.
 
     Raises:
         Exception: Logs error and returns an empty DataFrame if any error occurs during

{pyield-0.30.2 → pyield-0.30.4}/pyield/anbima/imaq.py

@@ -117,17 +117,19 @@ def imaq(date: DateScalar) -> pd.DataFrame:
             the data.
 
     Returns:
-        pd.DataFrame: A DataFrame containing the IMA data with the following columns:
-            - Date: Reference date of the data.
-            - BondType: Type of bond.
-            - Maturity: Bond maturity date.
-            - SelicCode: Code representing the SELIC rate.
-            - ISIN: International Securities Identification Number.
-            - Price: Bond price.
-            - MarketQuantity: Market quantity (in units of 1000 bonds).
-            - MarketValue: Market value (in units of 1000 reais).
-            - QuantityVariation: Variation in quantity (in units of 1000 bonds).
-            - BondStatus: Status of the bond.
+        pd.DataFrame: A DataFrame containing the IMA data.
+
+    DataFrame columns:
+        - Date: Reference date of the data.
+        - BondType: Type of bond.
+        - Maturity: Bond maturity date.
+        - SelicCode: Code representing the SELIC rate.
+        - ISIN: International Securities Identification Number.
+        - Price: Bond price.
+        - MarketQuantity: Market quantity (in units of 1000 bonds).
+        - MarketValue: Market value (in units of 1000 reais).
+        - QuantityVariation: Variation in quantity (in units of 1000 bonds).
+        - BondStatus: Status of the bond.
 
     Raises:
         Exception: Logs error and returns an empty DataFrame if any error occurs during

{pyield-0.30.2 → pyield-0.30.4}/pyield/anbima/ipca.py

@@ -25,12 +25,12 @@ def ipca_projection() -> IndicatorProjection:
     containing economic indicators, and specifically processes the IPCA projection data.
 
     Process:
-    1. Accesses the ANBIMA indicators webpage
-    2. Extracts the third table that contains the IPCA projection
-    3. Locates the row labeled as "IPCA1"
-    4. Extracts the projection value and converts it to decimal format
-    5. Extracts and formats the reference month of the projection
-    6. Extracts the date and time of the last update
+        1. Accesses the ANBIMA indicators webpage
+        2. Extracts the third table that contains the IPCA projection
+        3. Locates the row labeled as "IPCA1"
+        4. Extracts the projection value and converts it to decimal format
+        5. Extracts and formats the reference month of the projection
+        6. Extracts the date and time of the last update
 
     Returns:
         IndicatorProjection: An object containing:

{pyield-0.30.2 → pyield-0.30.4}/pyield/anbima/tpf.py

@@ -78,7 +78,7 @@ def _process_raw_df(df_raw: pd.DataFrame) -> pd.DataFrame:
     return df.sort_values(["BondType", "MaturityDate"], ignore_index=True)
 
 
-def tpf_data(date: DateScalar, bond_type: str | None = None) -> pd.DataFrame:
+def tpf_data(date: DateScalar, bond_type: BOND_TYPES | None = None) -> pd.DataFrame:
     """Fetch and process TPF secondary market data from ANBIMA.
 
     This function retrieves bond market data from the ANBIMA website for a
@@ -109,8 +109,8 @@ def tpf_data(date: DateScalar, bond_type: str | None = None) -> pd.DataFrame:
             return df
         df = _process_raw_df(df)
         if bond_type:
-            bond_type = _bond_type_mapping(bond_type)
-            df = df.query("BondType == @bond_type").reset_index(drop=True)
+            norm_bond_type = _bond_type_mapping(bond_type)  # noqa
+            df = df.query("BondType == @norm_bond_type").reset_index(drop=True)
         return df.sort_values(["BondType", "MaturityDate"]).reset_index(drop=True)
     except HTTPError as e:
         if e.code == 404:  # noqa

{pyield-0.30.2 → pyield-0.30.4}/pyield/b3/di.py

@@ -1,3 +1,5 @@
+import logging
+
 import pandas as pd
 
 import pyield.date_converter as dc
@@ -6,6 +8,8 @@ from pyield import b3, bday, interpolator
 from pyield.data_cache import get_anbima_dataset, get_di_dataset
 from pyield.date_converter import DateArray, DateScalar
 
+logger = logging.getLogger(__name__)
+
 
 class DIFutures:
     """
@@ -61,7 +65,7 @@ class DIFutures:
 
     def __init__(
         self,
-        date: DateScalar | None = None,
+        date: DateScalar,
         month_start: bool = False,
         pre_filter: bool = False,
         all_columns: bool = True,
@@ -100,19 +104,22 @@ class DIFutures:
 
     def _update_df(self) -> pd.DataFrame:
         """Retrieve DI contract DataFrame for the initialized trade date."""
-        bz_today = pd.Timestamp.today(tz="America/Sao_Paulo").normalize()
-        if bz_today == self.date:
-            # Try to get intraday data
-            df = b3.futures(contract_code="DI1", date=bz_today)
-        else:
-            # Get historical data
-            df = (
-                get_di_dataset()
-                .query("TradeDate == @self._date")
-                .reset_index(drop=True)
-            )
+        # Return an empty DataFrame if the trade date is a holiday
+        if not bday.is_business_day(self._date):
+            logger.warning("Specified date is not a business day.")
+            logger.warning("Returning empty DataFrame.")
+            return pd.DataFrame()
+
+        # Get historical data
+        df = get_di_dataset().query("TradeDate == @self._date").reset_index(drop=True)
+
+        if df.empty:
+            logger.info("No historical data found. Trying real-time data.")
+            df = b3.futures(contract_code="DI1", date=self._date)
 
         if df.empty:
+            logger.warning("No DI Futures data found for the specified date.")
+            logger.warning("Returning empty DataFrame.")
             return pd.DataFrame()
 
         if "DaysToExpiration" in df.columns:
@@ -349,12 +356,12 @@ class DIFutures:
         return self._date
 
     @date.setter
-    def date(self, value: DateScalar | None):
-        if value:
-            self._date = dc.convert_input_dates(value)
-        else:
-            self._date = self.historical_dates.max()
-
+    def date(self, value: DateScalar):
+        self._date = dc.convert_input_dates(value)
+        bz_today = pd.Timestamp.today(tz="America/Sao_Paulo")
+        bz_today = bz_today.normalize().tz_localize(None)
+        if self._date > bz_today:
+            raise ValueError("Trade date cannot be in the future.")
         self._dirty = True
 
     @property

{pyield-0.30.2 → pyield-0.30.4}/pyield/b3/di_over.py

@@ -5,6 +5,9 @@ from pyield.date_converter import DateScalar, convert_input_dates
 
 logger = logging.getLogger(__name__)
 
+# 4 decimal places in rate = 2 decimal places in percentage
+DI_OVER_DECIMAL_PLACES = 4
+
 
 def di_over(date: DateScalar) -> float:
     """
@@ -14,7 +17,7 @@ def di_over(date: DateScalar) -> float:
         date (str): Date in DD/MM/YYYY format
 
     Returns:
-        float: DI rate for the specified date
+        float: DI rate for the specified date or NaN (Not a Number) if no data is found.
 
     Raises:
         ValueError: If date is not in the correct format
@@ -47,7 +50,7 @@ def di_over(date: DateScalar) -> float:
         if lines:
             raw_rate = lines[0].strip()
             rate = int(raw_rate) / 10000
-            return round(rate, 5)
+            return round(rate, DI_OVER_DECIMAL_PLACES)
         else:
             logger.error(f"No data found for date {date}")
             return float("nan")
@@ -62,8 +65,7 @@ def di_over(date: DateScalar) -> float:
         logger.exception("Unexpected error")
         raise
     finally:
-        # Ensure FTP connection is closed
-        if ftp:
+        if ftp and ftp.sock:  # Ensure FTP connection is closed AND socket exists
             try:
                 ftp.quit()
             except:  # noqa

{pyield-0.30.2 → pyield-0.30.4}/pyield/bc/__init__.py

@@ -9,19 +9,19 @@ from pyield.bc.bcdata import (
 )
 from pyield.bc.ptax import ptax_series
 from pyield.bc.repo import repos
-from pyield.bc.sec import sec
+from pyield.bc.trade import sec
 from pyield.bc.vna import vna_lft
 
 __all__ = [
     "auctions",
-    "repos",
-    "ptax_series",
-    "vna_lft",
-    "selic_over_series",
-    "selic_target_series",
+    "di_over",
     "di_over_series",
+    "ptax_series",
+    "repos",
     "sec",
-    "di_over",
     "selic_over",
+    "selic_over_series",
     "selic_target",
+    "selic_target_series",
+    "vna_lft",
 ]

{pyield-0.30.2 → pyield-0.30.4}/pyield/bc/bcdata.py

@@ -146,7 +146,7 @@ def selic_over_series(
                 Date  Value
         0 2024-05-31  0.104
 
-        # No data on 26-01-2025 (sunday). Rate changed due to Copom meeting.
+        >>> # No data on 26-01-2025 (sunday). Rate changed due to Copom meeting.
         >>> bc.selic_over_series("26-01-2025")  # Returns all data since 26-01-2025
                 Date   Value
         0 2025-01-27  0.1215

pyield-0.30.2/pyield/bc/sec.py → pyield-0.30.4/pyield/bc/trade.py

@@ -62,22 +62,42 @@ def _fetch_data_from_url(file_url: str) -> pd.DataFrame:
 
 
 def sec(target_date: DateScalar) -> pd.DataFrame:
-    """Fetches bond trading data for a specific date from the Brazilian Central Bank.
+    """Fetches secondary market trading data for all Federal Public Securities (TPF)
+    registered on SELIC for the *month* of the specified date.
 
-    Downloads the daily bond trading data from the Brazilian Central Bank
-    website for the given target date.  The data is downloaded as a ZIP file,
-    extracted, and read into a Pandas DataFrame.  The columns are then
-    renamed to English names for easier use.
+    Downloads the monthly bond trading data from the Brazilian Central Bank (BCB)
+    website for the month corresponding to the provided date. The data is downloaded as
+    a ZIP file, extracted, and loaded into a Pandas DataFrame.
+    The data contains all trades executed during the month, separated by settlement day
+    ('SettlementDate').
 
     Args:
-        target_date (DateScalar): The date for which to fetch the bond
-            trading data.  This can be a date-like object understood by
-            `pyield.date_converter.convert_input_dates`.
+        target_date (DateScalar): The date for which to fetch the bond trading data.
+            This can be any date-like object understood by
+            `pyield.date_converter.convert_input_dates`. Only the year and month
+            of this date will be used to download the corresponding monthly file.
 
     Returns:
         pd.DataFrame: A DataFrame containing the bond trading data for the
-            specified date.  Columns are renamed according to `COLUMN_MAPPING`
-            for English readability.
+            specified month.
+
+    DataFrame columns:
+        - SettlementDate: Date when the trade settled
+        - BondType: Security type abbreviation
+        - SelicCode: Unique code in the SELIC system
+        - ISIN: International Securities Identification Number
+        - IssueDate: Date when the security was issued
+        - Maturity: Security's maturity date
+        - TradeCount: Number of trades executed
+        - TradeQuantity: Quantity traded
+        - TradeValue: Total value traded
+        - AvgPrice: Average price
+        - AvgRate: Average rate
+        And additional trading metrics like min/max prices and rates.
+
+    Examples:
+        >>> from pyield import bc
+        >>> df = bc.sec("07-01-2025")  # Returns all trades for January 2025
     """
     url = _build_download_url(target_date)
     df = _fetch_data_from_url(url)

{pyield-0.30.2 → pyield-0.30.4}/pyield/tpf/ntnf.py

@@ -258,7 +258,6 @@ def spot_rates(  # noqa
             "BDToMat" is the business days from the settlement date to the maturities.
 
     Examples:
-
         >>> df_ltn = yd.ltn.rates("03-09-2024")
         >>> df_ntnf = yd.ntnf.rates("03-09-2024")
         >>> yd.ntnf.spot_rates(
@@ -522,7 +521,7 @@ def premium(
         factor.
 
     Examples:
-        # Obs: only some of the DI rates will be used in the example.
+        >>> # Obs: only some of the DI rates will be used in the example.
         >>> exp_dates = pd.to_datetime(["2025-01-01", "2030-01-01", "2035-01-01"])
         >>> di_rates = pd.Series([0.10823, 0.11594, 0.11531])
         >>> premium(

{pyield-0.30.2 → pyield-0.30.4}/pyield/tpf/tools.py

@@ -79,8 +79,8 @@ def pre_spreads(date: DateScalar) -> pd.DataFrame:
     converted_date = dc.convert_input_dates(date)
     di = DIFutures(date=converted_date, month_start=True)
     df_di = di.df
-    if "SettlementRate" not in df_di.columns:
-        raise ValueError("DI rates data is missing the 'SettlementRate' column.")
+    if "SettlementRate" not in df_di.columns or df_di.empty:
+        raise ValueError("DI data is missing the 'SettlementRate' column or is empty.")
 
     df_di = df_di[["ExpirationDate", "SettlementRate"]].copy()
 

pyield-0.30.2/pyield/__about__.py

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