IPCA

def indice(data: DateLike) -> float:
    """Número-índice do IPCA para um mês específico.

    Args:
        data: Qualquer data dentro do mês desejado.

    Returns:
        Número-índice do IPCA ou ``nan`` se não disponível.

    Examples:
        >>> from pyield import ipca
        >>> ipca.indice("01-01-2025")
        7111.86
    """
    if any_is_empty(data):
        return float("nan")
    return _extrair_escalar(indice_serie(data, data), "indice")

def indice_serie(
    inicio: DateLike | None = None,
    fim: DateLike | None = None,
    *,
    ultimos: int | None = None,
) -> pl.DataFrame:
    """Obtém os valores do número-índice do IPCA por intervalo ou últimos meses.

    Realiza chamada à API do portal de dados do IBGE no formato:
    https://servicodados.ibge.gov.br/api/v3/agregados/1737/periodos/YYYYMM-YYYYMM/variaveis/2266?localidades=N1[all]
    Para os últimos meses, usa o formato:
    https://servicodados.ibge.gov.br/api/v3/agregados/1737/periodos/-N/variaveis/2266?localidades=N1[all]

    Args:
        inicio: Data de início do intervalo.
        fim: Data de fim do intervalo. Se ``None``, usa a data atual no Brasil.
        ultimos: Número de meses mais recentes a recuperar. Se informado,
            tem prioridade sobre ``inicio`` e ``fim``.

    Returns:
        pl.DataFrame com colunas 'periodo' e 'indice'.

    Output Columns:
        * periodo (Int64): período no formato YYYYMM.
        * indice (Float64): número-índice do IPCA.

    Raises:
        ValueError: Se não informar ``inicio`` nem ``ultimos``, ou se
            ``ultimos`` for menor ou igual a 0.

    Examples:
        >>> from pyield import ipca
        >>> # Obter os números-índice do IPCA para o primeiro trimestre
        >>> ipca.indice_serie(inicio="01-01-2025", fim="01-03-2025")
        shape: (3, 2)
        ┌─────────┬─────────┐
        │ periodo ┆ indice  │
        │ ---     ┆ ---     │
        │ i64     ┆ f64     │
        ╞═════════╪═════════╡
        │ 202501  ┆ 7111.86 │
        │ 202502  ┆ 7205.03 │
        │ 202503  ┆ 7245.38 │
        └─────────┴─────────┘
        >>> # Obter o número-índice do IPCA do último mês
        >>> df = ipca.indice_serie(ultimos=1)
        >>> # Obter os números-índice do IPCA dos últimos 3 meses
        >>> df = ipca.indice_serie(ultimos=3)
    """
    return _buscar_serie(inicio, fim, ultimos, _VAR_INDICE).rename({"valor": "indice"})

def taxa(data: DateLike) -> float:
    """Taxa mensal do IPCA para um mês específico.

    Args:
        data: Qualquer data dentro do mês desejado.

    Returns:
        Taxa mensal do IPCA em decimal ou ``nan`` se não disponível.

    Examples:
        >>> from pyield import ipca
        >>> taxa = ipca.taxa("01-01-2025")  # decimal (0.0016 = 0,16%)
        >>> f"{taxa:.2%}"
        '0.16%'
    """
    if any_is_empty(data):
        return float("nan")
    return _extrair_escalar(taxa_serie(data, data), "taxa")

def taxa_projetada() -> ProjecaoIndicador:
    """
    Obtém a projeção atual do IPCA no site da ANBIMA.

    A função baixa a planilha XLS de indicadores da ANBIMA e extrai os
    dados da projeção do IPCA.

    Returns:
        ProjecaoIndicador: Objeto contendo:
            - ultima_atualizacao (dt.datetime): Data e hora da última
              atualização.
            - periodo_referencia (str): Período de referência no formato
              "MMM/YY" (ex.: "mar/26").
            - valor_projetado (float): Valor projetado do IPCA (decimal).

    Raises:
        ConnectionError: Se houver erro de conexão com o site da ANBIMA.
        ValueError: Se os dados esperados não forem encontrados na
            planilha.

    Notes:
        Requer conexão com a internet para acessar o site da ANBIMA.

    Examples:
        >>> from pyield import ipca
        >>> # Obter a projeção atual do IPCA na ANBIMA
        >>> ipca.taxa_projetada()
        ProjecaoIndicador(ultima_atualizacao=..., periodo_referencia=..., valor_projetado=...)
    """
    conteudo = _baixar_planilha()
    df = ler_sem_cabecalho(conteudo)

    # Linha 0: "Data e Hora da Última Atualização: DD/MM/YYYY - HH:MM h"
    texto_atualizacao = df.item(0, "column_1")
    ultima_atualizacao = _extrair_datetime(texto_atualizacao)

    # Linha do IPCA: column_1 começa com "IPCA" e column_2 com "Projeção"
    linha_ipca = df.filter(
        pl.col("column_1").str.starts_with("IPCA"),
        pl.col("column_2").str.starts_with("Projeção"),
    )
    if linha_ipca.is_empty():
        raise ValueError("Não foi possível encontrar a projeção do IPCA na planilha.")

    periodo_referencia = _extrair_periodo(linha_ipca.item(0, "column_2"))
    valor_projetado = round(float(linha_ipca.item(0, "column_3")) / 100, 4)

    return ProjecaoIndicador(
        ultima_atualizacao=ultima_atualizacao,
        periodo_referencia=periodo_referencia,
        valor_projetado=valor_projetado,
    )

def taxa_serie(
    inicio: DateLike | None = None,
    fim: DateLike | None = None,
    *,
    ultimos: int | None = None,
) -> pl.DataFrame:
    """Obtém as taxas mensais do IPCA por intervalo ou últimos meses.

    Realiza chamada à API do portal de dados do IBGE no formato:
    https://servicodados.ibge.gov.br/api/v3/agregados/1737/periodos/YYYYMM-YYYYMM/variaveis/63?localidades=N1[all]
    Para os últimos meses, usa o formato:
    https://servicodados.ibge.gov.br/api/v3/agregados/1737/periodos/-N/variaveis/63?localidades=N1[all]

    Args:
        inicio: Data de início do intervalo.
        fim: Data de fim do intervalo. Se ``None``, usa a data atual no Brasil.
        ultimos: Número de meses mais recentes a recuperar. Se informado,
            tem prioridade sobre ``inicio`` e ``fim``.

    Returns:
        pl.DataFrame com colunas 'periodo' e 'taxa' (decimal).

    Output Columns:
        * periodo (Int64): período no formato YYYYMM.
        * taxa (Float64): taxa mensal em decimal (ex: 0.0016 = 0,16%).

    Raises:
        ValueError: Se não informar ``inicio`` nem ``ultimos``, ou se
            ``ultimos`` for menor ou igual a 0.

    Examples:
        >>> from pyield import ipca
        >>> ipca.taxa_serie("01-01-2025", "01-03-2025")  # decimal (0.0016 = 0,16%)
        shape: (3, 2)
        ┌─────────┬────────┐
        │ periodo ┆ taxa   │
        │ ---     ┆ ---    │
        │ i64     ┆ f64    │
        ╞═════════╪════════╡
        │ 202501  ┆ 0.0016 │
        │ 202502  ┆ 0.0131 │
        │ 202503  ┆ 0.0056 │
        └─────────┴────────┘
        >>> # Obter a taxa do IPCA do último mês
        >>> df = ipca.taxa_serie(ultimos=1)
        >>> # Obter as taxas do IPCA dos últimos 3 meses
        >>> df = ipca.taxa_serie(ultimos=3)
    """
    return (
        _buscar_serie(inicio, fim, ultimos, _VAR_TAXA)
        .with_columns(taxa=pct_para_decimal(pl.col("valor")))
        .select("periodo", "taxa")
    )