PYield 0.40.0__tar.gz → 0.40.2__tar.gz

{pyield-0.40.0 → pyield-0.40.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: PYield
-Version: 0.40.0
+Version: 0.40.2
 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>
@@ -49,9 +49,9 @@ Description-Content-Type: text/markdown
 PYield is a Python library designed for the analysis of Brazilian fixed income instruments. Leveraging the power of popular Python libraries like Polars, Pandas, Numpy and Requests, PYield simplifies the process of obtaining and processing data from key sources such as ANBIMA, BCB, IBGE and B3.
 
 ---
-### ✅ Polars Migration Completed
+### ✅ Polars migration from version 0.40.0 onwards:
 
-All public functions now return **Polars DataFrames or Series** as the canonical format. This provides stronger typing, faster execution and more reliable date/rate handling.
+All public functions now return **Polars DataFrames or Series** as the canonical format. This provides stronger typing, faster execution and more reliable date/rate handling. The last version to return Pandas objects by default was **0.39.xx**.
 
 Need Pandas? Convert explicitly:
 ```python
@@ -171,16 +171,16 @@ Series: 'bdays' [i64]
 # Get ANBIMA LTN data for a given date
 >>> ltn.data("23-08-2024")
 shape: (13, 14)
-┌──────────────┬─────────┬──────────┬──────────────┬───┬─────────┬─────────┬──────────────┬────────┐
+┌──────────────┬─────────┬──────────┬──────────────┬───┬─────────┬─────────┬───────────────┬────────┐
 │ ReferenceDate│ BondType│ SelicCode│ IssueBaseDate│ … │ BidRate │ AskRate │ IndicativeRate│ DIRate │
 │ ---          │ ---     │ ---      │ ---          │   │ ---     │ ---     │ ---           │ ---    │
 │ date         │ str     │ i64      │ date         │   │ f64     │ f64     │ f64           │ f64    │
-├──────────────┼─────────┼──────────┼──────────────┼───┼─────────┼─────────┼──────────────┼────────┤
+├──────────────┼─────────┼──────────┼──────────────┼───┼─────────┼─────────┼───────────────┼────────┤
 │ 2024-08-23   │ LTN     │ 100000   │ 2022-07-08   │ … │ 0.10459 │ 0.104252│ 0.104416      │ 0.10472│
 │ 2024-08-23   │ LTN     │ 100000   │ 2018-02-01   │ … │ 0.107366│ 0.107016│ 0.107171      │ 0.10823│
 │ 2024-08-23   │ LTN     │ 100000   │ 2023-01-06   │ … │ 0.110992│ 0.110746│ 0.110866      │ 0.11179│
 │ …            │ …       │ …        │ …            │ … │ …       │ …       │ …             │ …      │
-└──────────────┴─────────┴──────────┴──────────────┴───┴─────────┴─────────┴──────────────┴────────┘
+└──────────────┴─────────┴──────────┴──────────────┴───┴─────────┴─────────┴───────────────┴────────┘
 
 # Calculate the quotation of an NTN-B bond (base 100, truncated to 4 decimals)
 >>> ntnb.quotation("31-05-2024", "15-05-2035", 0.061490)
@@ -191,17 +191,17 @@ shape: (13, 14)
 # DI Spreads: IndicativeRate - SettlementRate (bps=True multiplies by 10_000)
 >>> ntnf.di_spreads("30-05-2025", bps=True)
 shape: (5, 3)
-┌─────────┬────────────┬──────────┐
+┌─────────┬─────────────┬──────────┐
 │ BondType│ MaturityDate│ DISpread │
 │ ---     │ ---         │ ---      │
 │ str     │ date        │ f64      │
-├─────────┼────────────┼──────────┤
+├─────────┼─────────────┼──────────┤
 │ NTN-F   │ 2027-01-01  │ -3.31    │
 │ NTN-F   │ 2029-01-01  │ 14.21    │
 │ NTN-F   │ 2031-01-01  │ 21.61    │
 │ NTN-F   │ 2033-01-01  │ 11.51    │
 │ NTN-F   │ 2035-01-01  │ 22.0     │
-└─────────┴────────────┴──────────┘
+└─────────┴─────────────┴──────────┘
 ```
 
 ### Business Days Tools (Brazilian holidays automatically considered)
@@ -244,16 +244,16 @@ Series: '' [date]
 # Fetch DI1 futures (historical)
 >>> futures("DI1", "31-05-2024")
 shape: (40, 20)
-┌────────────┬──────────────┬──────────────┬────────────┬───┬──────────────┬─────────┬──────────────┬─────────────┐
+┌────────────┬──────────────┬───────────────┬────────────┬───┬──────────────┬──────────┬───────────────┬─────────────┐
 │ TradeDate  ┆ TickerSymbol ┆ ExpirationDate┆ BDaysToExp ┆ … ┆ CloseBidRate ┆ CloseRate┆ SettlementRate┆ ForwardRate │
 │ ---        ┆ ---          ┆ ---           ┆ ---        ┆   ┆ ---          ┆ ---      ┆ ---           ┆ ---         │
 │ date       ┆ str          ┆ date          ┆ i64        ┆   ┆ f64          ┆ f64      ┆ f64           ┆ f64         │
-├────────────┼──────────────┼──────────────┼────────────┼───┼──────────────┼─────────┼──────────────┼─────────────┤
+├────────────┼──────────────┼───────────────┼────────────┼───┼──────────────┼──────────┼───────────────┼─────────────┤
 │ 2024-05-31 ┆ DI1M24       ┆ 2024-06-03    ┆ 1          ┆ … ┆ 0.10404      ┆ 0.10404  ┆ 0.10399       ┆ 0.10399     │
 │ 2024-05-31 ┆ DI1N24       ┆ 2024-07-01    ┆ 21         ┆ … ┆ 0.1039       ┆ 0.10386  ┆ 0.1039        ┆ 0.103896    │
 │ 2024-05-31 ┆ DI1Q24       ┆ 2024-08-01    ┆ 44         ┆ … ┆ 0.10374      ┆ 0.10374  ┆ 0.1037        ┆ 0.103517    │
-│ …          ┆ …            ┆ …            ┆ …          ┆ … ┆ …            ┆ …        ┆ …             ┆ …           │
-└────────────┴──────────────┴──────────────┴────────────┴───┴──────────────┴─────────┴──────────────┴─────────────┘
+│ …          ┆ …            ┆ …             ┆ …          ┆ … ┆ …            ┆ …        ┆ …             ┆ …           │
+└────────────┴──────────────┴───────────────┴────────────┴───┴──────────────┴──────────┴───────────────┴─────────────┘
 ```
 
 ### Indicators Data

{pyield-0.40.0 → pyield-0.40.2}/README.md

@@ -7,9 +7,9 @@
 PYield is a Python library designed for the analysis of Brazilian fixed income instruments. Leveraging the power of popular Python libraries like Polars, Pandas, Numpy and Requests, PYield simplifies the process of obtaining and processing data from key sources such as ANBIMA, BCB, IBGE and B3.
 
 ---
-### ✅ Polars Migration Completed
+### ✅ Polars migration from version 0.40.0 onwards:
 
-All public functions now return **Polars DataFrames or Series** as the canonical format. This provides stronger typing, faster execution and more reliable date/rate handling.
+All public functions now return **Polars DataFrames or Series** as the canonical format. This provides stronger typing, faster execution and more reliable date/rate handling. The last version to return Pandas objects by default was **0.39.xx**.
 
 Need Pandas? Convert explicitly:
 ```python
@@ -129,16 +129,16 @@ Series: 'bdays' [i64]
 # Get ANBIMA LTN data for a given date
 >>> ltn.data("23-08-2024")
 shape: (13, 14)
-┌──────────────┬─────────┬──────────┬──────────────┬───┬─────────┬─────────┬──────────────┬────────┐
+┌──────────────┬─────────┬──────────┬──────────────┬───┬─────────┬─────────┬───────────────┬────────┐
 │ ReferenceDate│ BondType│ SelicCode│ IssueBaseDate│ … │ BidRate │ AskRate │ IndicativeRate│ DIRate │
 │ ---          │ ---     │ ---      │ ---          │   │ ---     │ ---     │ ---           │ ---    │
 │ date         │ str     │ i64      │ date         │   │ f64     │ f64     │ f64           │ f64    │
-├──────────────┼─────────┼──────────┼──────────────┼───┼─────────┼─────────┼──────────────┼────────┤
+├──────────────┼─────────┼──────────┼──────────────┼───┼─────────┼─────────┼───────────────┼────────┤
 │ 2024-08-23   │ LTN     │ 100000   │ 2022-07-08   │ … │ 0.10459 │ 0.104252│ 0.104416      │ 0.10472│
 │ 2024-08-23   │ LTN     │ 100000   │ 2018-02-01   │ … │ 0.107366│ 0.107016│ 0.107171      │ 0.10823│
 │ 2024-08-23   │ LTN     │ 100000   │ 2023-01-06   │ … │ 0.110992│ 0.110746│ 0.110866      │ 0.11179│
 │ …            │ …       │ …        │ …            │ … │ …       │ …       │ …             │ …      │
-└──────────────┴─────────┴──────────┴──────────────┴───┴─────────┴─────────┴──────────────┴────────┘
+└──────────────┴─────────┴──────────┴──────────────┴───┴─────────┴─────────┴───────────────┴────────┘
 
 # Calculate the quotation of an NTN-B bond (base 100, truncated to 4 decimals)
 >>> ntnb.quotation("31-05-2024", "15-05-2035", 0.061490)
@@ -149,17 +149,17 @@ shape: (13, 14)
 # DI Spreads: IndicativeRate - SettlementRate (bps=True multiplies by 10_000)
 >>> ntnf.di_spreads("30-05-2025", bps=True)
 shape: (5, 3)
-┌─────────┬────────────┬──────────┐
+┌─────────┬─────────────┬──────────┐
 │ BondType│ MaturityDate│ DISpread │
 │ ---     │ ---         │ ---      │
 │ str     │ date        │ f64      │
-├─────────┼────────────┼──────────┤
+├─────────┼─────────────┼──────────┤
 │ NTN-F   │ 2027-01-01  │ -3.31    │
 │ NTN-F   │ 2029-01-01  │ 14.21    │
 │ NTN-F   │ 2031-01-01  │ 21.61    │
 │ NTN-F   │ 2033-01-01  │ 11.51    │
 │ NTN-F   │ 2035-01-01  │ 22.0     │
-└─────────┴────────────┴──────────┘
+└─────────┴─────────────┴──────────┘
 ```
 
 ### Business Days Tools (Brazilian holidays automatically considered)
@@ -202,16 +202,16 @@ Series: '' [date]
 # Fetch DI1 futures (historical)
 >>> futures("DI1", "31-05-2024")
 shape: (40, 20)
-┌────────────┬──────────────┬──────────────┬────────────┬───┬──────────────┬─────────┬──────────────┬─────────────┐
+┌────────────┬──────────────┬───────────────┬────────────┬───┬──────────────┬──────────┬───────────────┬─────────────┐
 │ TradeDate  ┆ TickerSymbol ┆ ExpirationDate┆ BDaysToExp ┆ … ┆ CloseBidRate ┆ CloseRate┆ SettlementRate┆ ForwardRate │
 │ ---        ┆ ---          ┆ ---           ┆ ---        ┆   ┆ ---          ┆ ---      ┆ ---           ┆ ---         │
 │ date       ┆ str          ┆ date          ┆ i64        ┆   ┆ f64          ┆ f64      ┆ f64           ┆ f64         │
-├────────────┼──────────────┼──────────────┼────────────┼───┼──────────────┼─────────┼──────────────┼─────────────┤
+├────────────┼──────────────┼───────────────┼────────────┼───┼──────────────┼──────────┼───────────────┼─────────────┤
 │ 2024-05-31 ┆ DI1M24       ┆ 2024-06-03    ┆ 1          ┆ … ┆ 0.10404      ┆ 0.10404  ┆ 0.10399       ┆ 0.10399     │
 │ 2024-05-31 ┆ DI1N24       ┆ 2024-07-01    ┆ 21         ┆ … ┆ 0.1039       ┆ 0.10386  ┆ 0.1039        ┆ 0.103896    │
 │ 2024-05-31 ┆ DI1Q24       ┆ 2024-08-01    ┆ 44         ┆ … ┆ 0.10374      ┆ 0.10374  ┆ 0.1037        ┆ 0.103517    │
-│ …          ┆ …            ┆ …            ┆ …          ┆ … ┆ …            ┆ …        ┆ …             ┆ …           │
-└────────────┴──────────────┴──────────────┴────────────┴───┴──────────────┴─────────┴──────────────┴─────────────┘
+│ …          ┆ …            ┆ …             ┆ …          ┆ … ┆ …            ┆ …        ┆ …             ┆ …           │
+└────────────┴──────────────┴───────────────┴────────────┴───┴──────────────┴──────────┴───────────────┴─────────────┘
 ```
 
 ### Indicators Data

pyield-0.40.2/pyield/__about__.py

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

{pyield-0.40.0 → pyield-0.40.2}/pyield/b3/di1.py

@@ -255,7 +255,7 @@ def interpolate_rates(
             0.13881
         ]
 
-        >>> # With extrapolation set to False, the second rate will be null
+        >>> # With extrapolation set to False, the second rate will be NaN
         >>> # Note: 0.13576348733268917 is shown as 0.135763
         >>> di1.interpolate_rates(
         ...     dates="25-04-2025",
@@ -266,7 +266,7 @@ def interpolate_rates(
         Series: 'FlatFwdRate' [f64]
         [
             0.135763
-            null
+            NaN
         ]
 
     Raises:
@@ -331,7 +331,7 @@ def interpolate_rate(
     date: DateScalar,
     expiration: DateScalar,
     extrapolate: bool = False,
-) -> float | None:
+) -> float:
     """
     Interpolates or retrieves the DI rate for a single expiration date.
 
@@ -349,8 +349,8 @@ def interpolate_rate(
             expirations for the given `date`. Defaults to False.
 
     Returns:
-        float | None: The exact or interpolated DI settlement rate for the specified
-            date and expiration. Returns `None` if:
+        float: The exact or interpolated DI settlement rate for the specified
+            date and expiration. Returns `float("nan")` if:
                 - No DI data is found for the `date`.
                 - The `expiration` is outside range and `extrapolate` is False.
                 - An interpolation calculation fails.
@@ -371,7 +371,7 @@ def interpolate_rate(
     """
     if has_null_args(date, expiration):
         logger.warning("Both 'date' and 'expiration' must be provided. Returning NaN.")
-        return None
+        return float("nan")
 
     converted_date = cv.convert_dates(date)
     converted_expiration = cv.convert_dates(expiration)
@@ -385,7 +385,7 @@ def interpolate_rate(
     df = _get_data(dates=converted_date)
 
     if df.is_empty():
-        return None
+        return float("nan")
 
     ff_interp = interpolator.Interpolator(
         method="flat_forward",

{pyield-0.40.0 → pyield-0.40.2}/pyield/b3/di_over.py

@@ -10,7 +10,7 @@ logger = logging.getLogger(__name__)
 DI_OVER_DECIMAL_PLACES = 4
 
 
-def di_over(date: DateScalar) -> float | None:
+def di_over(date: DateScalar) -> float:
     """
     Gets the DI (Interbank Deposit) rate for a specific date from B3/CETIP FTP server.
 
@@ -18,7 +18,7 @@ def di_over(date: DateScalar) -> float | None:
         date (str): Date in DD/MM/YYYY format
 
     Returns:
-        float | None: DI rate for the specified date or None if no data is found.
+        float: DI rate for the specified date or float("nan") if no data is found.
 
     Raises:
         ValueError: If date is not in the correct format
@@ -30,7 +30,7 @@ def di_over(date: DateScalar) -> float | None:
         0.1315
     """
     if has_null_args(date):
-        return None
+        return float("nan")
     ftp = None
     try:
         # Convert date to file format

{pyield-0.40.0 → pyield-0.40.2}/pyield/b3/futures/__init__.py

@@ -181,7 +181,7 @@ def futures(
         # Existe a chance de que os dados consolidados estejam disponíveis após as 20h
         if time >= HISTORICAL_START_TIME:
             df_hist = _get_historical_data(selected_contract, trade_date)
-            if not df_hist.empty:
+            if not df_hist.is_empty():
                 logger.info("Consolidated data is already available and will be used.")
                 return df_hist
 

{pyield-0.40.0 → pyield-0.40.2}/pyield/bc/ptax_api.py

@@ -241,7 +241,7 @@ def ptax_series(
         return pl.DataFrame()
 
 
-def ptax(date: DateScalar) -> float | None:
+def ptax(date: DateScalar) -> float:
     """Busca a cotação PTAX média de fechamento para uma data específica.
 
     Esta função é um wrapper para a função `ptax_series`, otimizada para
@@ -263,8 +263,8 @@ def ptax(date: DateScalar) -> float | None:
         5.4389
 
         >>> # Busca a PTAX para um fim de semana (sem dados)
-        >>> bc.ptax("23-08-2025") is None
-        True
+        >>> bc.ptax("23-08-2025")
+        nan
     """
     # Reutiliza a função ptax_series para buscar os dados para o dia específico.
     # Definir start e end com a mesma data busca a cotação para aquele dia.
@@ -274,7 +274,7 @@ def ptax(date: DateScalar) -> float | None:
     # Isso ocorre em fins de semana, feriados ou datas futuras.
     if df_ptax.is_empty():
         logger.warning(f"No PTAX data found for date: {date}")
-        return None
+        return float("nan")
 
     # A API retorna uma única linha para a cotação de fechamento de um dia.
     # A coluna "MidRate" representa a PTAX de fechamento.

{pyield-0.40.0 → pyield-0.40.2}/pyield/bc/rates.py

@@ -245,7 +245,7 @@ def selic_over_series(
     return df.with_columns(pl.col("Value").round(DECIMAL_PLACES_ANNUALIZED))
 
 
-def selic_over(date: DateScalar) -> float | None:
+def selic_over(date: DateScalar) -> float:
     """
     Fetches the SELIC Over rate value for a specific date.
 
@@ -264,10 +264,10 @@ def selic_over(date: DateScalar) -> float | None:
         0.104
     """
     if has_null_args(date):
-        return None
+        return float("nan")
     df = selic_over_series(date, date)
     if df.is_empty():
-        return None
+        return float("nan")
     return df["Value"].item(0)
 
 
@@ -312,7 +312,7 @@ def selic_target_series(
     return df
 
 
-def selic_target(date: DateScalar) -> float | None:
+def selic_target(date: DateScalar) -> float:
     """
     Fetches the SELIC Target rate value for a specific date.
 
@@ -331,10 +331,10 @@ def selic_target(date: DateScalar) -> float | None:
         0.105
     """
     if has_null_args(date):
-        return None
+        return float("nan")
     df = selic_target_series(date, date)
     if df.is_empty():
-        return None
+        return float("nan")
     return df["Value"].item(0)
 
 
@@ -397,7 +397,7 @@ def di_over_series(
     return df
 
 
-def di_over(date: DateScalar, annualized: bool = True) -> float | None:
+def di_over(date: DateScalar, annualized: bool = True) -> float:
     """
     Fetches the DI Over rate value for a specific date.
 
@@ -410,7 +410,7 @@ def di_over(date: DateScalar, annualized: bool = True) -> float | None:
             days per year), otherwise returns the daily rate.
 
     Returns:
-        The DI Over rate as a float or None if not available.
+        The DI Over rate as a float or float("nan") if not available.
 
     Examples:
         >>> from pyield import bc
@@ -421,8 +421,8 @@ def di_over(date: DateScalar, annualized: bool = True) -> float | None:
         0.00045513
     """
     if has_null_args(date):
-        return None
+        return float("nan")
     df = di_over_series(date, date, annualized)
     if df.is_empty():
-        return None
+        return float("nan")
     return df["Value"].item(0)

{pyield-0.40.0 → pyield-0.40.2}/pyield/bc/vna.py

@@ -59,7 +59,7 @@ def _validate_vna_values(vnas: list[float]) -> float:
     return vna_value
 
 
-def vna_lft(date: DateScalar) -> float | None:
+def vna_lft(date: DateScalar) -> float:
     """Retrieves the VNA (Valor Nominal Atualizado) from the BCB for a given date.
 
     This function fetches daily data from the BCB website, extracts the
@@ -73,7 +73,7 @@ def vna_lft(date: DateScalar) -> float | None:
             `convert_input_dates` function.
 
     Returns:
-        float | None: The VNA (Valor Nominal Atualizado) value for the specified date,
+        float: The VNA (Valor Nominal Atualizado) value for the specified date,
             or None if the date is invalid or data is not available.
 
     Examples:
@@ -93,7 +93,7 @@ def vna_lft(date: DateScalar) -> float | None:
     """
     if has_null_args(date):
         logger.warning("No valid date provided. Returning NaN.")
-        return None
+        return float("nan")
     text = _get_text(date)
     table_text = _extract_vna_table_text(text)
     table_lines = _parse_vna_table_lines(table_text)

{pyield-0.40.0 → pyield-0.40.2}/pyield/bday/core.py

@@ -34,43 +34,37 @@ def count(
     end: DateScalar | DateArray,
 ) -> int | pl.Series | None:
     """
-    Counts the number of business days between a `start` date (inclusive) and an `end`
-    date (exclusive). The function can handle single dates, arrays of dates and
-    mixed inputs, returning either a single integer or a series of integers depending
-    on the inputs. It accounts for specified holidays, effectively excluding them from
-    the business day count.
-
-    **Important Note:** Each date in the `start` input is evaluated individually to
-    determine which list of holidays (old or new) applies to the calculation. The
-    transition date is 2023-12-26, which means:
-    - Dates before 2023-12-26 use the old holiday list.
-    - Dates on or after 2023-12-26 use the new holiday list.
+    Count business days between `start` (inclusive) and `end` (exclusive) with
+    Brazilian holiday adjustment and per-row holiday regime selection.
+
+    ORDER PRESERVATION (critical): The output order ALWAYS matches the element-wise
+    order of the original inputs. No sorting, deduplication, alignment or reshaping is
+    performed. If you pass arrays, the i-th result corresponds to the i-th pair of
+    (`start`, `end`) after broadcasting. This guarantees safe assignment back to the
+    originating DataFrame.
+
+    Holiday regime: For each `start` value, the holiday list (old vs. new) is chosen
+    based on the transition date 2023-12-26 (`TRANSITION_DATE`). Starts before the
+    transition use the old list for that row's count; starts on/after use the new list.
+
+    Null propagation: If any scalar argument is null, returns `None`. Nulls inside
+    array inputs yield nulls in corresponding result positions.
+
+    Return type: If both inputs are scalars (non-null) an `int` is returned; otherwise
+    a `polars.Series` of int counts (name: 'bdays'). If a null scalar short-circuits,
+    `None` is returned.
 
     Args:
-        start (DateScalar | DateArray): The start date(s) for counting (inclusive).
-            **Transition Handling:** The holiday list used for the *entire* counting
-            period between `start` and `end` is determined solely by the `start` date's
-            relation to the holiday transition date (2023-12-26). If `start` is before
-            this date, the old holiday list is used for the whole count, even if `end`
-            is after it. If `start` is on or after this date, new holiday list is used.
-        end (DateScalar | DateArray): The end date(s) for counting (exclusive).
+        start: Single date or collection (inclusive boundary).
+        end: Single date or collection (exclusive boundary).
 
     Returns:
         int | pl.Series | None: Returns an integer or None if `start` and `end` are
             single dates, or a Series if any of them is an array of dates.
 
     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 pl.Series with the count for each date range.
-        - The `start` date determines the holiday list, ensuring consistency with the
-            applicable calendar at the time.
-        - 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 `polars.business_day_count`.
+        - The holiday list is determined per-row based on the `start` date.
 
     Examples:
         >>> from pyield import bday
@@ -157,7 +151,7 @@ def count(
 
     s_bdays = df.select(result_expr.alias("bdays"))["bdays"]
 
-    # Se a entrada original era escalar, retorna o valor escalar
+    # Se a série resultante tem tamanho 1, retorna o valor escalar
     if len(s_bdays) == 1:
         return s_bdays.item()
 
@@ -184,37 +178,56 @@ def offset(
     roll: Literal["forward", "backward"] = "forward",
 ) -> dt.date | pl.Series | None:
     """
-    First adjusts the date to fall on a valid day according to the roll rule, then
-    applies offsets to the given dates to the next or previous business day, considering
-    brazilian holidays. This function supports both single dates and collections of
-    dates. It is a wrapper for `polars.Expr.dt.add_business_days`.
-
-    **Important Note:** Each date in the `dates` input is evaluated individually to
-    determine which list of holidays applies to the calculation. Transition date
-    is 2023-12-26, which means:
-    - Dates before 2023-12-26 use the old holiday list.
-    - Dates on or after 2023-12-26 use the new holiday list.
+    Offset date(s) by a number of business days with per-row Brazilian holiday
+    regime selection. The operation is performed in two steps per element:
+    1) ROLL: If the original date falls on a weekend or holiday, move it according
+       to ``roll`` ("forward" -> next business day; "backward" -> previous).
+    2) ADD: Apply the signed business-day ``offset`` (positive forward, negative
+       backward, zero = stay on the rolled date).
+
+    ORDER PRESERVATION (critical): Output ordering strictly matches the element-wise
+    pairing after broadcasting between ``dates`` and ``offset``. No sorting,
+    deduplication or shape changes occur. The i-th result corresponds to the i-th
+    (date, offset) pair, enabling safe assignment back into the originating DataFrame.
+
+    Holiday regime: For EACH date the appropriate holiday list (old vs. new) is
+    chosen based on the transition date ``2023-12-26`` (``TRANSITION_DATE``). Dates
+    before the transition use the *old* list; dates on/after use the *new* list.
+
+    Roll semantics: ``roll`` only acts when the original date is not already a
+    business day under its regime. After rolling, the subsequent business-day
+    addition is applied from that rolled anchor. An ``offset`` of 0 therefore
+    returns either the original date (if already a business day) or the rolled
+    business day.
+
+    Null propagation: If any scalar argument is null, the function short-circuits
+    to ``None``. Nulls inside array inputs propagate to their corresponding output
+    positions.
+
+    Broadcasting: ``dates`` and ``offset`` may be scalars or array-like. Standard
+    Polars broadcasting rules apply when constructing the per-row pairs.
+
+    Return type: If both inputs are non-null scalars a ``datetime.date`` is returned.
+    Otherwise a ``polars.Series`` of dates named ``'result'`` is produced. Null scalar
+    inputs yield ``None``.
 
     Args:
-        dates (DateScalar | DateArray): The date(s) to offset. Can be a scalar date type
-            or a collection of dates. **Transition Handling:** Due to a change in
-            Brazilian national holidays effective from 2023-12-26 (`TRANSITION_DATE`),
-            this function automatically selects the appropriate holiday list
-            (old or new) based on **each individual date** in the `dates` input.
-            Dates before 2023-12-26 use the old list for their offset calculation,
-            while dates on or after 2023-12-26 use the new list.
-        offset (int | Series | np.ndarray | list[int] | tuple[int], optional):
-            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/previous business day otherwise, according to `roll`.
-        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'.
+        dates: Single date or collection of dates to be rolled (if needed) and then
+            offset. Each date independently selects the holiday regime.
+        offset: Signed count of business days to apply after rolling. Positive moves
+            forward, negative backward, zero keeps the rolled anchor.
+        roll: Direction to roll a non-business starting date ("forward" or
+            "backward"). Defaults to "forward".
 
     Returns:
-        dt.date | pl.Series | None: If a single date is provided, returns a single
-            `date` of the offset date or None. If a series of dates is provided, returns
-            a `polars.Series` of offset dates.
+        dt.date | pl.Series | None: A Python ``date`` for scalar inputs, a Polars
+        Series of dates for any array input, or ``None`` if a null scalar argument
+        was provided.
+
+    Notes:
+        - Wrapper around ``polars.Expr.dt.add_business_days`` applied conditionally.
+        - Holiday regime is decided per element by comparing to ``TRANSITION_DATE``.
+        - Weekends are always treated as non-business days.
 
     Examples:
         >>> from pyield import bday
@@ -337,7 +350,7 @@ def offset(
     # Executa a expressão e obtém a série de resultados
     result_series = df.select(result_expr.alias("result"))["result"]
 
-    # Se a entrada original era escalar, retorna o valor escalar
+    # Se a série resultante tem tamanho 1, retorna o valor escalar
     if len(result_series) == 1:
         return result_series.item()
 
@@ -419,7 +432,7 @@ def generate(
         holidays=applicable_holidays,
     )
     s_pd = pd.Series(result_dti.values).astype("date32[pyarrow]")
-    return pl.Series(s_pd)
+    return pl.from_pandas(s_pd)
 
 
 @overload
@@ -427,25 +440,40 @@ def is_business_day(dates: DateScalar) -> bool | None: ...
 @overload
 def is_business_day(dates: DateArray) -> pl.Series: ...
 def is_business_day(dates: DateScalar | DateArray) -> bool | pl.Series | None:
-    """Check if date(s) are business day(s) in Brazil.
+    """Determine whether date(s) are Brazilian business days with per-element
+    holiday regime selection.
+
+    PER-ROW HOLIDAY REGIME: For EACH input date the appropriate holiday list
+    ("old" vs. "new") is selected by comparing to the transition date
+    ``2023-12-26`` (``TRANSITION_DATE``). Dates strictly before the transition
+    use the old list; dates on or after it use the new list. This mirrors the
+    behavior of ``count`` and ``offset`` which apply regime logic element-wise.
+
+    ORDER & SHAPE PRESERVATION: The output preserves the original element order.
+    No sorting, deduplication, reshaping or alignment is performed; the i-th
+    result corresponds to the i-th provided date after broadcasting (if any
+    broadcasting occurred from a scalar input elsewhere in the call chain).
+
+    NULL PROPAGATION: A null scalar argument short-circuits to ``None``. Null
+    values inside array-like inputs produce nulls at the corresponding output
+    positions.
 
-    This function applies the correct holiday list (old vs. new) for EACH date
-    relative to the transition date ``2023-12-26``. Dates before the transition
-    use the *old* holiday list; dates on/after the transition use the *new*
-    holiday list.
+    RETURN TYPE: If the (non-null) input resolves to a single element a Python
+    ``bool`` is returned. If that lone element is null, ``None`` is returned.
+    Otherwise a ``polars.Series`` of booleans named ``'is_bday'`` is produced.
 
-    Behavior mirrors other functions in this module: if the resulting length is 1
-    (even if the user passed a single-element collection) a Python ``bool`` (or
-    ``None`` for null input) is returned; otherwise a ``polars.Series`` of booleans
-    is returned with nulls propagated.
+    WEEKENDS: Saturdays and Sundays are never business days regardless of the
+    holiday regime.
 
     Args:
-        dates: A single date or a collection of dates (scalar, list/tuple/Series,
-            numpy array, Polars/Pandas Series). Null scalar inputs return ``None``.
+        dates: Single date or collection (list/tuple/ndarray/Polars/Pandas
+            Series). May include nulls which propagate. Null scalar input
+            returns ``None``.
 
     Returns:
-        bool | pl.Series | None: ``True`` if business day, ``False`` if not, ``None``
-        for null scalar input, or a Polars boolean Series for array inputs.
+        bool | pl.Series | None: ``True`` if business day, ``False`` otherwise
+        for scalar input; ``None`` for null scalar input; or a Polars boolean
+        Series (name: ``'is_bday'``) for array inputs.
 
     Examples:
         >>> from pyield import bday
@@ -462,9 +490,10 @@ def is_business_day(dates: DateScalar | DateArray) -> bool | pl.Series | None:
         ]
 
     Notes:
-        - The transition date is defined in ``TRANSITION_DATE``.
-        - Null elements in array inputs propagate as nulls.
-        - Weekends are never business days.
+        - Transition date defined in ``TRANSITION_DATE``.
+        - Mirrors per-row logic used in ``count`` and ``offset``.
+        - Weekends always evaluate to ``False``.
+        - Null elements propagate.
     """
     # Validate and normalize inputs
     if has_null_args(dates):