PYield 0.30.4__tar.gz → 0.30.7__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: PYield
-Version: 0.30.4
+Version: 0.30.7
 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.7/pyield/__about__.py

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

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

@@ -21,8 +21,7 @@ class DIFutures:
 
     Args:
         date (DateScalar | None): The trade date to retrieve the
-            DI contract data. If None, the latest available historical trade date is
-            used.
+            DI contract data. If None, an empty DataFrame is returned.
         month_start (bool): If True, adjusts the expirations to the start of the month.
         pre_filter (bool): If True, filters the DI contracts to match only
             expirations with existing prefixed TN bond maturities (LTN and NTN-F).
@@ -65,7 +64,7 @@ class DIFutures:
 
     def __init__(
         self,
-        date: DateScalar,
+        date: DateScalar | None = None,
         month_start: bool = False,
         pre_filter: bool = False,
         all_columns: bool = True,
@@ -104,6 +103,9 @@ class DIFutures:
 
     def _update_df(self) -> pd.DataFrame:
         """Retrieve DI contract DataFrame for the initialized trade date."""
+        if self._date is None:
+            logger.info("No date specified. Returning empty DataFrame.")
+            return pd.DataFrame()
         # 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.")
@@ -189,7 +191,9 @@ class DIFutures:
                 - SettlementRate: The zero rate (interest rate) for each expiration.
                 - ForwardRate: The fwd rate calculated between successive expirations.
         """
+        # Use a local copy of the DI DataFrame
         df = self.df
+
         if df.empty:
             return pd.DataFrame()
 
@@ -356,12 +360,13 @@ class DIFutures:
         return self._date
 
     @date.setter
-    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.")
+    def date(self, value: DateScalar | None):
+        if value:
+            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
@@ -380,7 +385,7 @@ class DIFutures:
 
     @month_start.setter
     def month_start(self, value: bool):
-        self._month_start = value
+        self._month_start = bool(value)
         self._dirty = True
 
     @property
@@ -399,7 +404,7 @@ class DIFutures:
 
     @pre_filter.setter
     def pre_filter(self, value: bool):
-        self._pre_filter = value
+        self._pre_filter = bool(value)
         self._dirty = True
 
     @property
@@ -408,5 +413,5 @@ class DIFutures:
 
     @all_columns.setter
     def all_columns(self, value: bool):
-        self._all_columns = value
+        self._all_columns = bool(value)
         self._dirty = True

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

@@ -9,7 +9,7 @@ from pyield.bc.bcdata import (
 )
 from pyield.bc.ptax import ptax_series
 from pyield.bc.repo import repos
-from pyield.bc.trade import sec
+from pyield.bc.trade import tpf_trades
 from pyield.bc.vna import vna_lft
 
 __all__ = [
@@ -18,7 +18,7 @@ __all__ = [
     "di_over_series",
     "ptax_series",
     "repos",
-    "sec",
+    "tpf_trades",
     "selic_over",
     "selic_over_series",
     "selic_target",

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

@@ -207,7 +207,8 @@ def selic_target_series(
         or empty DataFrame if data is not available
 
     Examples:
-        >>> yd.bc.selic_target_series("31-05-2024", "31-05-2024")
+        >>> from pyield import bc
+        >>> bc.selic_target_series("31-05-2024", "31-05-2024")
                 Date  Value
         0 2024-05-31  0.105
     """

{pyield-0.30.4 → pyield-0.30.7}/pyield/bc/ptax.py

@@ -88,27 +88,40 @@ def ptax_series(
     - Unidade: R$
 
     Documentação da API do BCB:
+
         https://olinda.bcb.gov.br/olinda/servico/PTAX/versao/v1/documentacao
+
     Exemplo de chamada à API:
-        https://olinda.bcb.gov.br/olinda/servico/PTAX/versao/v1/odata/CotacaoDolarPeriodo(dataInicial=@dataInicial,dataFinalCotacao=@dataFinalCotacao)?
-        @dataInicial='08-01-2025'&@dataFinalCotacao='08-05-2025'&$format=text/csv
 
-    **Consultas de Período:**
+        https://olinda.bcb.gov.br/olinda/servico/PTAX/versao/v1/odata/CotacaoDolarPeriodo(dataInicial=@dataInicial,dataFinalCotacao=@dataFinalCotacao)?@dataInicial='08-01-2025'&@dataFinalCotacao='08-05-2025'&$format=text/csv
+
+    Consultas de Período:
+
     - Para consultar dados de um intervalo, forneça as datas de `start` e `end`.
-    Exemplo: `ptax(start='2024-10-20', end='2024-10-27')`
+    Exemplo:
+
+            `ptax_series(start='2024-10-20', end='2024-10-27')`
+
     - Se apenas `start` for fornecido, a API do BC retornará dados a partir
-    da data de `start` **até a data mais recente disponível**.
-    Exemplo: `ptax(start='2024-10-20')`
-    - Se apenas `end` for fornecido, a API do BC retornará dados **desde a
-    data mais antiga disponível até a data de `end`**.
-    Exemplo: `ptax(end='2024-10-27')`
+    da data de `start` até a data mais recente disponível. Exemplo:
+
+            `ptax_series(start='2024-10-20')`
+
+    - Se apenas `end` for fornecido, a API do BC retornará dados desde a data mais
+    antiga disponível até a data de `end`. Exemplo:
+
+        `ptax_series(end='2024-10-27')`
+
+    Série Histórica Completa:
 
-    **Série Histórica Completa:**
     - Para recuperar a série histórica completa de leilões (desde 28.11.1984
     até o último dia útil), chame a função sem fornecer os parâmetros `start` e `end`.
-    Exemplo: `ptax()`
+    Exemplo:
+
+            `ptax_series()`
 
     Busca dados de cotações de dólar PTAX (taxa de câmbio) para o período:
+
     - Se `start` for fornecido e `end` não, a função retorna dados de `start` até o fim.
     - Se `end` for fornecido e `start` não, a API retorna dados do início até `end`.
     - Se ambos `start` e `end` forem omitidos, a API retorna a série histórica completa.
@@ -130,6 +143,15 @@ def ptax_series(
         Se não houver dados disponíveis para o período especificado, um DataFrame vazio
         será retornado.
 
+    Examples:
+        >>> from pyield import bc
+        >>> df = yd.bc.ptax_series(start="01-01-2025", end="05-01-2025")
+        >>> selected_columns = ["Date", "BuyRate", "SellRate", "MidRate"]
+        >>> df[selected_columns]
+                Date  BuyRate  SellRate  MidRate
+        0 2025-01-02    6.208    6.2086   6.2083
+        1 2025-01-03   6.1557    6.1563    6.156
+
     Notes:
         Disponível desde 28.11.1984, refere-se às taxas administradas até março de 1990
         e às taxas livres a partir de então (Resolução 1690, de 18.3.1990). As taxas
@@ -143,15 +165,19 @@ def ptax_series(
         o boletim de fechamento PTAX corresponde à média aritmética das taxas dos
         boletins do dia.
 
-        O DataFrame possui as seguintes colunas:
-            - Date: Data da cotação.
-            - Time: Hora da cotação.
-            - DateTime: Data e hora da cotação.
-            - BuyRate: Taxa de compra.
-            - SellRate: Taxa de venda.
-            - MidRate: Taxa média entre a taxa de compra e venda.
         - Primeira data disponível: 28.11.1984
         - Última data disponível: data atual
+
+        O DataFrame possui as seguintes colunas:
+
+        - Date: Data da cotação.
+        - Time: Hora da cotação.
+        - DateTime: Data e hora da cotação.
+        - BuyRate: Taxa de compra.
+        - SellRate: Taxa de venda.
+        - MidRate: Taxa média entre a taxa de compra e venda.
+
+
     """
     if start:
         start = dc.convert_input_dates(start)

{pyield-0.30.4 → pyield-0.30.7}/pyield/bc/trade.py

@@ -61,20 +61,19 @@ def _fetch_data_from_url(file_url: str) -> pd.DataFrame:
     return df
 
 
-def sec(target_date: DateScalar) -> pd.DataFrame:
-    """Fetches secondary market trading data for all Federal Public Securities (TPF)
-    registered on SELIC for the *month* of the specified date.
+def tpf_trades(target_date: DateScalar) -> pd.DataFrame:
+    """Fetches monthly secondary trading data for the 'títulos públicos federais' (TPF)
+    registered in the Brazilian Central Bank (BCB) system.
 
     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').
+    a ZIP file, extracted, and loaded into a Pandas DataFrame. The data contains all
+    trades executed during the month, separated by each 'SettlementDate'.
 
     Args:
-        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
+        target_date (DateScalar): The date for which the monthly trading data will be
+            fetched. This date can be a string, datetime, or pandas Timestamp object.
+            It will be converted to a pandas Timestamp object. Only the year and month
             of this date will be used to download the corresponding monthly file.
 
     Returns:
@@ -97,7 +96,7 @@ def sec(target_date: DateScalar) -> pd.DataFrame:
 
     Examples:
         >>> from pyield import bc
-        >>> df = bc.sec("07-01-2025")  # Returns all trades for January 2025
+        >>> df = bc.tpf_trades("07-01-2025")  # Returns all trades for January 2025
     """
     url = _build_download_url(target_date)
     df = _fetch_data_from_url(url)

{pyield-0.30.4 → pyield-0.30.7}/pyield/bc/vna.py

@@ -71,7 +71,8 @@ def vna_lft(date: DateScalar) -> float:
         float: The VNA (Valor Nominal Atualizado) value for the specified date.
 
     Examples:
-        >>> yd.bc.vna_lft("31-05-2024")
+        >>> from pyield import bc
+        >>> bc.vna_lft("31-05-2024")
         14903.01148
 
     Raises:

{pyield-0.30.4 → pyield-0.30.7}/pyield/interpolator.py

@@ -129,8 +129,10 @@ class Interpolator:
         return self.interpolate(bday)
 
     def __repr__(self) -> str:
-        """
-        Textual representation, used in terminal or scripts.
-        """
+        """Textual representation, used in terminal or scripts."""
 
         return repr(self._df)
+
+    def __len__(self) -> int:
+        """Returns the number of known business days."""
+        return len(self._df)

pyield-0.30.4/pyield/__about__.py

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