PYield 0.43.1__tar.gz → 0.43.2__tar.gz

{pyield-0.43.1 → pyield-0.43.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyield
-Version: 0.43.1
+Version: 0.43.2
 Summary: A Python library for analysis of fixed income instruments in Brazil
 Project-URL: Homepage, https://github.com/crdcj/PYield
 Project-URL: Documentation, https://crdcj.github.io/PYield
@@ -47,76 +47,80 @@ Description-Content-Type: text/markdown
 [![Made with Python](https://img.shields.io/badge/Python->=3.12-blue?logo=python&logoColor=white)](https://python.org "Go to Python homepage")
 [![License](https://img.shields.io/badge/License-MIT-blue)](https://github.com/crdcj/PYield/blob/main/LICENSE)
 
-# PYield: Brazilian Fixed Income Toolkit
+# PYield: Toolkit de Renda Fixa Brasileira
 
-PYield is a Python library for analyzing Brazilian fixed income instruments. It fetches and processes data from ANBIMA, BCB, IBGE and B3, returning Polars DataFrames for fast, type-safe data pipelines.
+Português | [English](https://github.com/crdcj/PYield/blob/main/README.en.md)
 
-## Installation
+PYield é uma biblioteca Python voltada para análise de títulos públicos brasileiros. Ela busca e processa dados da ANBIMA, BCB, IBGE, B3 e **Tesouro Nacional**, retornando DataFrames do Polars para pipelines rápidos e com tipagem consistente.
+
+Embora inclua dados e ferramentas de outros mercados (como DI1, DAP e PTAX), esses recursos são auxiliares para o objetivo central: análise, precificação e acompanhamento de títulos públicos.
+
+## Instalação
 
 ```sh
 pip install pyield
 ```
 
-## Quick Start
+## Início Rápido
 
 ```python
 import pyield as yd
 
-# Business days (foundation of all calculations)
+# Dias úteis (base de todos os cálculos)
 yd.bday.count("02-01-2025", "15-01-2025")  # -> 9
 yd.bday.offset("29-12-2023", 1)            # -> datetime.date(2024, 1, 2)
 
-# DI Futures curve
+# Curva de DI Futuro
 df = yd.futures("31-05-2024", "DI1")
 # Columns: TradeDate, TickerSymbol, ExpirationDate, BDaysToExp, SettlementRate, ...
 
-# Rate interpolation (flat forward, 252 bdays/year convention)
+# Interpolação de taxas (flat forward, convenção 252 dias úteis/ano)
 interp = yd.Interpolator("flat_forward", df["BDaysToExp"], df["SettlementRate"])
 interp(45)       # -> 0.04833...
 interp([30, 60]) # -> pl.Series with interpolated rates
 
-# Treasury bond pricing
+# Precificação de títulos públicos
 yd.ntnb.quotation("31-05-2024", "15-05-2035", 0.061490)  # -> 99.3651
 
-# BCB indicators
+# Indicadores do BCB
 yd.bc.selic_over("31-05-2024")  # -> 0.000414...
 ```
 
-A Colab notebook with more examples is available:
+Um notebook no Colab com mais exemplos:
 
 [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/crdcj/PYield/blob/main/examples/pyield_quickstart.ipynb)
 
-## Core Building Blocks
+## Blocos Principais
 
-### Business Days (`bday`)
+### Dias Úteis (`bday`)
 
-The `bday` module is the foundation of PYield. All date calculations (pricing, duration, forward rates) depend on accurate business day counting with Brazilian holidays.
+O módulo `bday` é a base do PYield. Todos os cálculos com datas (preço, duration, taxas a termo) dependem da contagem correta de dias úteis com feriados brasileiros.
 
 ```python
 from pyield import bday
 
-# Count business days (start inclusive, end exclusive)
+# Conta dias úteis (início inclusivo, fim exclusivo)
 bday.count("29-12-2023", "02-01-2024")  # -> 1
 
-# Offset by N business days
+# Avança N dias úteis
 bday.offset("29-12-2023", 1)  # -> datetime.date(2024, 1, 2)
 
-# Adjust non-business day to next business day
+# Ajusta dia não útil para o próximo dia útil
 bday.offset("30-12-2023", 0)  # -> datetime.date(2024, 1, 2)
 
-# Generate business day range
+# Gera intervalo de dias úteis
 bday.generate("22-12-2023", "02-01-2024")
 # -> Series: [2023-12-22, 2023-12-26, 2023-12-27, 2023-12-28, 2023-12-29, 2024-01-02]
 
-# Check if date is business day
+# Verifica se a data é dia útil
 bday.is_business_day("25-12-2023")  # -> False (Christmas)
 ```
 
-All functions support vectorized operations with lists, Series, or arrays.
+Todas as funções suportam operações vetorizadas com listas, Series ou arrays.
 
-### Rate Interpolation (`Interpolator`)
+### Interpolação de Taxas (`Interpolator`)
 
-The `Interpolator` class interpolates interest rates using the 252 business days/year convention standard in Brazil.
+A classe `Interpolator` interpola taxas usando a convenção de 252 dias úteis/ano, padrão no mercado brasileiro.
 
 ```python
 from pyield import Interpolator
@@ -124,95 +128,100 @@ from pyield import Interpolator
 known_bdays = [30, 60, 90]
 known_rates = [0.045, 0.05, 0.055]
 
-# Flat forward interpolation (market standard)
+# Interpolação flat forward (padrão de mercado)
 interp = Interpolator("flat_forward", known_bdays, known_rates)
 interp(45)  # -> 0.04833...
 
-# Linear interpolation
+# Interpolação linear
 linear = Interpolator("linear", known_bdays, known_rates)
 linear(45)  # -> 0.0475
 
-# Vectorized
+# Vetorizado
 interp([15, 45, 75])  # -> pl.Series with 3 rates
 
-# Extrapolation (disabled by default, returns NaN)
+# Extrapolação (desabilitada por padrão, retorna NaN)
 interp(100)  # -> nan
 Interpolator("flat_forward", known_bdays, known_rates, extrapolate=True)(100)  # -> 0.055
 ```
 
-### Forward Rates (`forward`, `forwards`)
+### Taxas a Termo (`forward`, `forwards`)
 
-Calculate forward rates from spot curves:
+Calcula taxas a termo a partir de curvas spot:
 
 ```python
 from pyield import forward, forwards
 
-# Single forward rate between two points
+# Taxa a termo única entre dois pontos
 forward(bday1=10, bday2=20, rate1=0.05, rate2=0.06)  # -> 0.0700952...
 
-# Vectorized forward curve from spot rates
+# Curva a termo vetorizada a partir de taxas spot
 bdays = [10, 20, 30]
 rates = [0.05, 0.06, 0.07]
 forwards(bdays, rates)  # -> Series: [0.05, 0.070095, 0.090284]
 ```
 
-## Modules Overview
+## Visão Geral dos Módulos
 
-| Module | Purpose |
+| Módulo | Finalidade |
 |--------|---------|
-| `bday` | Business day calendar with Brazilian holidays |
-| `futures` | B3 futures data (DI1, DDI, FRC, DAP, DOL, WDO, IND, WIN) |
-| `Interpolator` | Rate interpolation (flat_forward, linear) |
-| `forward` / `forwards` | Forward rate calculation |
-| `ltn`, `ntnb`, `ntnf`, `lft`, `ntnc` | Treasury bond pricing and analytics |
-| `anbima` | ANBIMA data (TPF prices, yield curves, IMA indices) |
-| `bc` | BCB indicators (SELIC, PTAX, repo rates, VNA) |
-| `ipca` | Inflation data (historical and projections) |
-| `today` / `now` | Current date/time in Brazil (America/Sao_Paulo) |
-
-## Treasury Bonds
+| `bday` | Calendário de dias úteis com feriados brasileiros |
+| `futures` | Dados de futuros da B3 (DI1, DDI, FRC, DAP, DOL, WDO, IND, WIN) |
+| `Interpolator` | Interpolação de taxas (flat_forward, linear) |
+| `forward` / `forwards` | Cálculo de taxas a termo |
+| `ltn`, `ntnb`, `ntnf`, `lft`, `ntnc` | Precificação e análise de títulos públicos |
+| `anbima` | Dados da ANBIMA (preços de TPF, curvas de juros, índices IMA) |
+| `bc` | Indicadores do BCB (SELIC, PTAX, repos, VNA) |
+| `ipca` | Dados de inflação (histórico e projeções) |
+| `today` / `now` | Data/hora atual no Brasil (America/Sao_Paulo) |
+
+## Títulos Públicos
 
 ```python
 from pyield import ltn, ntnb, ntnf
 
-# Fetch ANBIMA indicative rates
+# Busca taxas indicativas da ANBIMA
 ltn.data("23-08-2024")   # -> DataFrame with LTN bonds
 ntnb.data("23-08-2024")  # -> DataFrame with NTN-B bonds
 
-# Calculate bond quotation (base 100)
+# Calcula cotação do título (base 100)
 ntnb.quotation("31-05-2024", "15-05-2035", 0.061490)  # -> 99.3651
 ntnb.quotation("31-05-2024", "15-08-2060", 0.061878)  # -> 99.5341
 
-# DI spreads (bps=True multiplies by 10,000)
+# Spreads de DI (bps=True multiplica por 10.000)
 ntnf.di_spreads("30-05-2025", bps=True)
 # -> DataFrame: BondType, MaturityDate, DISpread
 ```
 
-## Futures Data
+## Dados de Futuros
 
 ```python
 from pyield import futures
 
-# DI1 (Interbank Deposit Futures)
+# DI1 (Futuro de Depósito Interfinanceiro)
 futures("31-05-2024", "DI1")
 
-# Other contracts: DDI, FRC, DAP, DOL, WDO, IND, WIN
+# Outros contratos: DDI, FRC, DAP, DOL, WDO, IND, WIN
 futures("31-05-2024", "DAP")
 
-# Intraday data (when market is open)
-futures("16-01-2025", "DI1")  # Returns live data if called during trading hours
+# Dados intradiários (quando o mercado estiver aberto)
+futures("16-01-2025", "DI1")  # Retorna dados ao vivo durante o horário de negociação
 ```
 
-## Date Handling
+## Tratamento de Datas
 
-PYield accepts flexible date inputs (`DateLike`):
+PYield aceita entradas de data flexíveis (`DateLike`):
 - Strings: `"31-05-2024"`, `"31/05/2024"`, `"2024-05-31"`
 - `datetime.date`, `datetime.datetime`
 - `pandas.Timestamp`, `numpy.datetime64`
 
-Scalar functions return `datetime.date`. Vectorized functions return `polars.Series`.
+Funções escalares retornam `datetime.date`. Funções vetorizadas retornam `polars.Series`.
+
+O parsing de strings é elemento a elemento entre os formatos aceitos. Strings
+inválidas são convertidas para valores nulos (`None` em saídas escalares e `null`
+em saídas vetorizadas).
 
-Null handling: scalar functions return `float('nan')` for missing inputs (propagates through calculations). Vectorized functions propagate `null` element-wise.
+Tratamento de nulos: funções escalares retornam `float('nan')` para entradas ausentes
+(propaga nos cálculos). Funções vetorizadas propagam `null` elemento a elemento.
 
 ```python
 from pyield import ntnb, bday
@@ -221,19 +230,19 @@ ntnb.quotation(None, "15-05-2035", 0.06149)  # -> nan
 bday.count(["01-01-2024", None], "01-02-2024")  # -> Series: [22, null]
 ```
 
-## Polars Migration (v0.40.0+)
+## Migração para Polars (v0.40.0+)
 
-All functions return **Polars DataFrames/Series**. To convert to Pandas:
+Todas as funções retornam **DataFrames/Series do Polars**. Para converter para Pandas:
 
 ```python
 df_pandas = df.to_pandas(use_pyarrow_extension_array=True)
 ```
 
-## Documentation
+## Documentação
 
-Full documentation: [crdcj.github.io/PYield](https://crdcj.github.io/PYield/)
+Documentação completa: [crdcj.github.io/PYield](https://crdcj.github.io/PYield/)
 
-## Tests
+## Testes
 
 ```sh
 pytest pyield --doctest-modules

pyield-0.43.2/README.md

@@ -0,0 +1,204 @@
+[![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.12-blue?logo=python&logoColor=white)](https://python.org "Go to Python homepage")
+[![License](https://img.shields.io/badge/License-MIT-blue)](https://github.com/crdcj/PYield/blob/main/LICENSE)
+
+# PYield: Toolkit de Renda Fixa Brasileira
+
+Português | [English](https://github.com/crdcj/PYield/blob/main/README.en.md)
+
+PYield é uma biblioteca Python voltada para análise de títulos públicos brasileiros. Ela busca e processa dados da ANBIMA, BCB, IBGE, B3 e **Tesouro Nacional**, retornando DataFrames do Polars para pipelines rápidos e com tipagem consistente.
+
+Embora inclua dados e ferramentas de outros mercados (como DI1, DAP e PTAX), esses recursos são auxiliares para o objetivo central: análise, precificação e acompanhamento de títulos públicos.
+
+## Instalação
+
+```sh
+pip install pyield
+```
+
+## Início Rápido
+
+```python
+import pyield as yd
+
+# Dias úteis (base de todos os cálculos)
+yd.bday.count("02-01-2025", "15-01-2025")  # -> 9
+yd.bday.offset("29-12-2023", 1)            # -> datetime.date(2024, 1, 2)
+
+# Curva de DI Futuro
+df = yd.futures("31-05-2024", "DI1")
+# Columns: TradeDate, TickerSymbol, ExpirationDate, BDaysToExp, SettlementRate, ...
+
+# Interpolação de taxas (flat forward, convenção 252 dias úteis/ano)
+interp = yd.Interpolator("flat_forward", df["BDaysToExp"], df["SettlementRate"])
+interp(45)       # -> 0.04833...
+interp([30, 60]) # -> pl.Series with interpolated rates
+
+# Precificação de títulos públicos
+yd.ntnb.quotation("31-05-2024", "15-05-2035", 0.061490)  # -> 99.3651
+
+# Indicadores do BCB
+yd.bc.selic_over("31-05-2024")  # -> 0.000414...
+```
+
+Um notebook no Colab com mais exemplos:
+
+[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/crdcj/PYield/blob/main/examples/pyield_quickstart.ipynb)
+
+## Blocos Principais
+
+### Dias Úteis (`bday`)
+
+O módulo `bday` é a base do PYield. Todos os cálculos com datas (preço, duration, taxas a termo) dependem da contagem correta de dias úteis com feriados brasileiros.
+
+```python
+from pyield import bday
+
+# Conta dias úteis (início inclusivo, fim exclusivo)
+bday.count("29-12-2023", "02-01-2024")  # -> 1
+
+# Avança N dias úteis
+bday.offset("29-12-2023", 1)  # -> datetime.date(2024, 1, 2)
+
+# Ajusta dia não útil para o próximo dia útil
+bday.offset("30-12-2023", 0)  # -> datetime.date(2024, 1, 2)
+
+# Gera intervalo de dias úteis
+bday.generate("22-12-2023", "02-01-2024")
+# -> Series: [2023-12-22, 2023-12-26, 2023-12-27, 2023-12-28, 2023-12-29, 2024-01-02]
+
+# Verifica se a data é dia útil
+bday.is_business_day("25-12-2023")  # -> False (Christmas)
+```
+
+Todas as funções suportam operações vetorizadas com listas, Series ou arrays.
+
+### Interpolação de Taxas (`Interpolator`)
+
+A classe `Interpolator` interpola taxas usando a convenção de 252 dias úteis/ano, padrão no mercado brasileiro.
+
+```python
+from pyield import Interpolator
+
+known_bdays = [30, 60, 90]
+known_rates = [0.045, 0.05, 0.055]
+
+# Interpolação flat forward (padrão de mercado)
+interp = Interpolator("flat_forward", known_bdays, known_rates)
+interp(45)  # -> 0.04833...
+
+# Interpolação linear
+linear = Interpolator("linear", known_bdays, known_rates)
+linear(45)  # -> 0.0475
+
+# Vetorizado
+interp([15, 45, 75])  # -> pl.Series with 3 rates
+
+# Extrapolação (desabilitada por padrão, retorna NaN)
+interp(100)  # -> nan
+Interpolator("flat_forward", known_bdays, known_rates, extrapolate=True)(100)  # -> 0.055
+```
+
+### Taxas a Termo (`forward`, `forwards`)
+
+Calcula taxas a termo a partir de curvas spot:
+
+```python
+from pyield import forward, forwards
+
+# Taxa a termo única entre dois pontos
+forward(bday1=10, bday2=20, rate1=0.05, rate2=0.06)  # -> 0.0700952...
+
+# Curva a termo vetorizada a partir de taxas spot
+bdays = [10, 20, 30]
+rates = [0.05, 0.06, 0.07]
+forwards(bdays, rates)  # -> Series: [0.05, 0.070095, 0.090284]
+```
+
+## Visão Geral dos Módulos
+
+| Módulo | Finalidade |
+|--------|---------|
+| `bday` | Calendário de dias úteis com feriados brasileiros |
+| `futures` | Dados de futuros da B3 (DI1, DDI, FRC, DAP, DOL, WDO, IND, WIN) |
+| `Interpolator` | Interpolação de taxas (flat_forward, linear) |
+| `forward` / `forwards` | Cálculo de taxas a termo |
+| `ltn`, `ntnb`, `ntnf`, `lft`, `ntnc` | Precificação e análise de títulos públicos |
+| `anbima` | Dados da ANBIMA (preços de TPF, curvas de juros, índices IMA) |
+| `bc` | Indicadores do BCB (SELIC, PTAX, repos, VNA) |
+| `ipca` | Dados de inflação (histórico e projeções) |
+| `today` / `now` | Data/hora atual no Brasil (America/Sao_Paulo) |
+
+## Títulos Públicos
+
+```python
+from pyield import ltn, ntnb, ntnf
+
+# Busca taxas indicativas da ANBIMA
+ltn.data("23-08-2024")   # -> DataFrame with LTN bonds
+ntnb.data("23-08-2024")  # -> DataFrame with NTN-B bonds
+
+# Calcula cotação do título (base 100)
+ntnb.quotation("31-05-2024", "15-05-2035", 0.061490)  # -> 99.3651
+ntnb.quotation("31-05-2024", "15-08-2060", 0.061878)  # -> 99.5341
+
+# Spreads de DI (bps=True multiplica por 10.000)
+ntnf.di_spreads("30-05-2025", bps=True)
+# -> DataFrame: BondType, MaturityDate, DISpread
+```
+
+## Dados de Futuros
+
+```python
+from pyield import futures
+
+# DI1 (Futuro de Depósito Interfinanceiro)
+futures("31-05-2024", "DI1")
+
+# Outros contratos: DDI, FRC, DAP, DOL, WDO, IND, WIN
+futures("31-05-2024", "DAP")
+
+# Dados intradiários (quando o mercado estiver aberto)
+futures("16-01-2025", "DI1")  # Retorna dados ao vivo durante o horário de negociação
+```
+
+## Tratamento de Datas
+
+PYield aceita entradas de data flexíveis (`DateLike`):
+- Strings: `"31-05-2024"`, `"31/05/2024"`, `"2024-05-31"`
+- `datetime.date`, `datetime.datetime`
+- `pandas.Timestamp`, `numpy.datetime64`
+
+Funções escalares retornam `datetime.date`. Funções vetorizadas retornam `polars.Series`.
+
+O parsing de strings é elemento a elemento entre os formatos aceitos. Strings
+inválidas são convertidas para valores nulos (`None` em saídas escalares e `null`
+em saídas vetorizadas).
+
+Tratamento de nulos: funções escalares retornam `float('nan')` para entradas ausentes
+(propaga nos cálculos). Funções vetorizadas propagam `null` elemento a elemento.
+
+```python
+from pyield import ntnb, bday
+
+ntnb.quotation(None, "15-05-2035", 0.06149)  # -> nan
+bday.count(["01-01-2024", None], "01-02-2024")  # -> Series: [22, null]
+```
+
+## Migração para Polars (v0.40.0+)
+
+Todas as funções retornam **DataFrames/Series do Polars**. Para converter para Pandas:
+
+```python
+df_pandas = df.to_pandas(use_pyarrow_extension_array=True)
+```
+
+## Documentação
+
+Documentação completa: [crdcj.github.io/PYield](https://crdcj.github.io/PYield/)
+
+## Testes
+
+```sh
+pytest pyield --doctest-modules
+```

pyield-0.43.2/pyield/__about__.py

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

pyield-0.43.2/pyield/_internal/__init__.py

@@ -0,0 +1,5 @@
+"""Namespace interno para utilitários compartilhados do pacote.
+
+Este módulo não faz parte da API pública estável do PYield.
+"""
+

{pyield-0.43.1/pyield → pyield-0.43.2/pyield/_internal}/converters.py

@@ -3,56 +3,54 @@ from typing import overload
 
 import polars as pl
 
-from pyield import types
-from pyield.types import ArrayLike, DateLike
+from pyield._internal import types
+from pyield._internal.types import ArrayLike, DateLike
 
 
-def _validar_formato_data(date_str: str) -> str:
-    """Valida se a string de data está em formatos suportados e retorna o *formato*.
+def converter_datas_expr(expr: pl.Expr | str) -> pl.Expr:
+    """Converte expressão Polars para ``Date`` com parse tolerante por linha.
 
-    Formatos aceitos:
-    - Brasileiro: ``dd-mm-YYYY`` ou ``dd/mm/YYYY`` (day-first explícito)
-    - ISO: ``YYYY-mm-dd``
-
-    Regras / Observações:
-    - Não fazemos autodetecção ambígua: ``2024-05-06`` só é válido como ISO.
-    - Uma coleção (coluna) não deve misturar estilos.
-    - Retorna o padrão para uso explícito em ``pl.Series.str.to_date(..., format=fmt)``.
+    Esta função é voltada para pipelines em ``DataFrame``/``LazyFrame``.
+    O parse aceita os formatos ``dd-mm-YYYY``, ``dd/mm/YYYY`` e ``YYYY-mm-dd``.
+    Valores inválidos (incluindo string vazia) viram ``null``.
 
     Args:
-        date_str: String de data a ser validada.
+        expr: Expressão Polars ou nome da coluna com datas.
 
     Returns:
-        O padrão ``strftime`` correspondente ao formato detectado.
-
-    Raises:
-        ValueError: Se não corresponder a nenhum dos formatos suportados.
+        Uma ``pl.Expr`` com dtype ``Date``.
 
     Examples:
-        >>> _validar_formato_data("25-12-2024")
-        '%d-%m-%Y'
-        >>> _validar_formato_data("25/12/2024")
-        '%d/%m/%Y'
-        >>> _validar_formato_data("2024-12-25")
-        '%Y-%m-%d'
-        >>> _validar_formato_data("12.25.2024")
-        Traceback (most recent call last):
-        ...
-        ValueError: Formato de data inválido: '12.25.2024'. Formatos aceitos: dd-mm-YYYY, dd/mm/YYYY ou YYYY-mm-dd.
-        >>> _validar_formato_data("not-a-date")
-        Traceback (most recent call last):
-        ...
-        ValueError: Formato de data inválido: 'not-a-date'. Formatos aceitos: dd-mm-YYYY, dd/mm/YYYY ou YYYY-mm-dd.
-    """  # noqa:E501
-    for fmt in ("%d-%m-%Y", "%d/%m/%Y", "%Y-%m-%d"):
-        try:
-            dt.datetime.strptime(date_str, fmt)
-            return fmt
-        except ValueError:
-            pass
-    raise ValueError(
-        f"Formato de data inválido: '{date_str}'."
-        " Formatos aceitos: dd-mm-YYYY, dd/mm/YYYY ou YYYY-mm-dd."
+        >>> import polars as pl
+        >>> df = pl.DataFrame(
+        ...     {"d": ["02-01-2024", "03/01/2024", "2024-01-04", "31-02-2024", ""]}
+        ... )
+        >>> df.select(converter_datas_expr("d"))
+        shape: (5, 1)
+        ┌────────────┐
+        │ d          │
+        │ ---        │
+        │ date       │
+        ╞════════════╡
+        │ 2024-01-02 │
+        │ 2024-01-03 │
+        │ 2024-01-04 │
+        │ null       │
+        │ null       │
+        └────────────┘
+    """
+    if isinstance(expr, str):
+        expr = pl.col(expr)
+
+    # Fallback por linha: o primeiro valor não-nulo vence.
+    # Se o elemento já for Date, o cast resolve no 1o termo.
+    # Se o elemento for null, ele permanece null em todos os termos.
+    expr_str = expr.cast(pl.String, strict=False).str.strip_chars()
+    return pl.coalesce(
+        expr.cast(pl.Date, strict=False),
+        expr_str.str.to_date(format="%d-%m-%Y", strict=False),
+        expr_str.str.to_date(format="%d/%m/%Y", strict=False),
+        expr_str.str.to_date(format="%Y-%m-%d", strict=False),
     )
 
 
@@ -74,8 +72,8 @@ def converter_datas(
     - Coleções (list, tuple, ndarray, Series) retornam ``pl.Series`` com dtype ``Date``
     - Entradas nulas retornam ``None``
 
-    O formato da string é detectado automaticamente pelo primeiro valor não-nulo
-    da coleção usando ``_validar_formato_data()``.
+    O parse de strings é feito por elemento com fallback entre formatos
+    suportados. Valores inválidos viram ``null``.
 
     Args:
         dates: Data(s) a converter. Aceita:
@@ -109,7 +107,7 @@ def converter_datas(
         Conversão de lista de strings:
         >>> converter_datas(["01-01-2024", "15-06-2024"])
         shape: (2,)
-        Series: '' [date]
+        Series: 'dates' [date]
         [
             2024-01-01
             2024-06-15
@@ -126,7 +124,7 @@ def converter_datas(
         Lista com valores nulos propaga os nulls:
         >>> converter_datas(["01-01-2024", None])
         shape: (2,)
-        Series: '' [date]
+        Series: 'dates' [date]
         [
             2024-01-01
             null
@@ -135,19 +133,19 @@ def converter_datas(
         Lista com strings vazias vira série nula:
         >>> converter_datas(["", "  "])
         shape: (2,)
-        Series: '' [date]
+        Series: 'dates' [date]
         [
             null
             null
         ]
 
-        Formatos mistos: formato do primeiro valor válido prevalece:
+        Formatos mistos por linha:
         >>> converter_datas(["25-12-2024", "2024-12-26"])
         shape: (2,)
-        Series: '' [date]
+        Series: 'dates' [date]
         [
             2024-12-25
-            null
+            2024-12-26
         ]
     """
     if not types.is_collection(dates):
@@ -157,18 +155,11 @@ def converter_datas(
         eh_escalar = False
         serie = pl.Series(values=dates)
 
-    if serie.dtype == pl.String:
-        # Usa primeiro valor não-nulo para determinar o formato.
-        valores_validos = serie.str.strip_chars().replace("", None).drop_nulls()
-        if valores_validos.len() > 0:
-            formato = _validar_formato_data(valores_validos.item(0))
-            serie = serie.str.to_date(format=formato, strict=False)
-        else:
-            serie = pl.Series(values=[None] * serie.len(), dtype=pl.Date)
-    else:
-        # Para todos os outros dtypes (datetime, date, etc.),
-        # o cast nativo do Polars é suficiente e muito rápido.
-        serie = serie.cast(pl.Date)
+    serie = (
+        pl.DataFrame({"dates": serie}, nan_to_null=True)
+        .select(converter_datas_expr("dates"))
+        .get_column("dates")
+    )
 
     if eh_escalar:
         return serie.item()

{pyield-0.43.1/pyield → pyield-0.43.2/pyield/_internal}/data_cache.py

@@ -8,7 +8,7 @@ import polars as pl
 import requests
 
 from pyield.clock import now
-from pyield.retry import retry_padrao
+from pyield._internal.retry import retry_padrao
 
 URL_BASE = "https://github.com/crdcj/pyield-data/releases/latest/download"
 registro = logging.getLogger(__name__)