Títulos Públicos Federais (TPF)

def benchmarks(
    titulo: str | None = None,
    incluir_historico: bool = False,
) -> pl.DataFrame:
    """Busca benchmarks de títulos públicos brasileiros.

    Fonte: API do Tesouro Nacional.

    Args:
        titulo: Tipo do título a filtrar (ex.: ``"LFT"``). Se ``None``,
            retorna todos os títulos.
        incluir_historico: Se ``True``, inclui benchmarks históricos; se
            ``False`` (padrão), retorna apenas benchmarks vigentes
            (on-the-run).

    Returns:
        DataFrame Polars com os benchmarks. Retorna DataFrame vazio se
        não houver dados.

    Output Columns:
        * titulo (String): tipo do título (ex.: ``"LTN"``, ``"LFT"``).
        * data_vencimento (Date): data de vencimento do benchmark.
        * benchmark (String): nome/identificador do benchmark.
        * data_inicio (Date): data de início da vigência.
        * data_fim (Date): data de término da vigência.

    Notes:
        Documentação da API:
        https://portal-conhecimento.tesouro.gov.br/catalogo-componentes/api-leil%C3%B5es

    Examples:
        >>> df = yd.tpf.benchmarks(incluir_historico=False)
    """
    dados = _buscar_json_api(incluir_historico)
    df = _parsear_df(dados)
    if df.is_empty():
        return pl.DataFrame()
    df = _processar_df(df)

    if incluir_historico:
        colunas_ordenacao = ["data_inicio", "titulo", "data_vencimento"]
    else:
        colunas_ordenacao = ["titulo", "data_vencimento"]
        hoje = relogio.hoje()
        df = df.filter(pl.lit(hoje).is_between("data_inicio", "data_fim"))

    if titulo:
        df = df.filter(pl.col("titulo") == titulo.upper())

    return df.sort(colunas_ordenacao)

def curva_pre(data: DateLike) -> pl.DataFrame:
    """Constrói a curva PRE (taxas zero cupom prefixadas).

    Combina taxas de LTN (já zero cupom) com taxas spot derivadas de NTN-F
    via bootstrap. O resultado é a curva de juros prefixada brasileira expressa
    em taxas zero cupom.

    Fonte: ANBIMA (taxas indicativas de LTN e NTN-F).

    Args:
        data: Data de referência.

    Returns:
        DataFrame com a curva PRE para a data solicitada. Retorna DataFrame
        vazio se não houver dados de LTN disponíveis.

    Output Columns:
        * data_vencimento (Date): data de vencimento do vértice.
        * dias_uteis (Int64): dias úteis entre a data de referência e o vencimento.
        * taxa_zero (Float64): taxa zero cupom anualizada (base 252), em formato
          decimal.

    Raises:
        ValueError: Se houver NTN-F sem dados de LTN para bootstrap.

    Examples:
        >>> import polars.selectors as cs
        >>> curva = yd.tpf.curva_pre("18-06-2025")
        >>> curva.with_columns(cs.starts_with("taxa_") * 100)
        shape: (17, 3)
        ┌─────────────────┬────────────┬───────────┐
        │ data_vencimento ┆ dias_uteis ┆ taxa_zero │
        │ ---             ┆ ---        ┆ ---       │
        │ date            ┆ i64        ┆ f64       │
        ╞═════════════════╪════════════╪═══════════╡
        │ 2025-07-01      ┆ 8          ┆ 14.835    │
        │ 2025-10-01      ┆ 74         ┆ 14.7463   │
        │ 2026-01-01      ┆ 138        ┆ 14.7752   │
        │ 2026-04-01      ┆ 199        ┆ 14.7947   │
        │ 2026-07-01      ┆ 260        ┆ 14.7069   │
        │ …               ┆ …          ┆ …         │
        │ 2030-01-01      ┆ 1135       ┆ 13.7279   │
        │ 2031-01-01      ┆ 1387       ┆ 13.815381 │
        │ 2032-01-01      ┆ 1639       ┆ 13.876    │
        │ 2033-01-01      ┆ 1891       ┆ 13.930017 │
        │ 2035-01-01      ┆ 2390       ┆ 14.106777 │
        └─────────────────┴────────────┴───────────┘
    """
    from pyield.tpf.titulos import ntnf  # noqa: PLC0415

    df_ltn = _utils.obter_tpf(data, "LTN").select("data_vencimento", "taxa_indicativa")
    df_ntnf = _utils.obter_tpf(data, "NTN-F").select(
        "data_vencimento", "taxa_indicativa"
    )

    if df_ltn.is_empty() and df_ntnf.is_empty():
        return pl.DataFrame(
            schema={
                "data_vencimento": pl.Date,
                "dias_uteis": pl.Int64,
                "taxa_zero": pl.Float64,
            }
        )

    if df_ltn.is_empty():
        raise ValueError(
            "Não é possível construir a curva PRE sem taxas de LTN para bootstrap"
        )

    if df_ntnf.is_empty():
        df = _processar_ltn_adicionais(data, df_ltn)
    else:
        df_spots = ntnf.taxas_zero(
            data_liquidacao=data,
            vencimentos_ltn=df_ltn["data_vencimento"],
            taxas_ltn=df_ltn["taxa_indicativa"],
            vencimentos_ntnf=df_ntnf["data_vencimento"],
            taxas_ntnf=df_ntnf["taxa_indicativa"],
            incluir_cupons=False,
        )

        ltn_mask = ~df_ltn["data_vencimento"].is_in(
            df_spots["data_vencimento"].to_list()
        )
        ltn_not_in_ntnf = df_ltn.filter(ltn_mask)

        if not ltn_not_in_ntnf.is_empty():
            ltn_subset = _processar_ltn_adicionais(data, ltn_not_in_ntnf)
            df = pl.concat([df_spots, ltn_subset])
        else:
            df = df_spots

    _validar_resultado_final(df)
    return df.sort("data_vencimento")

def estoque(data: DateLike) -> pl.DataFrame:
    """Busca dados de estoque de TPFs.

    Fonte: IMA-Q da ANBIMA. Contém quantidade em mercado, valor de mercado
    e variação diária da quantidade dos títulos.

    Args:
        data: Data de referência.

    Returns:
        DataFrame Polars com dados de estoque. Retorna DataFrame vazio se a
        data for inválida ou não houver dados.

    Output Columns:
        * data_referencia (Date): data de referência dos dados.
        * titulo (String): tipo do título público.
        * data_vencimento (Date): data de vencimento do título.
        * codigo_selic (Int64): código SELIC do título.
        * isin (String): código ISIN.
        * pu (Float64): preço unitário do título em reais.
        * quantidade_mercado (Int64): quantidade em mercado.
        * valor_mercado (Int64): valor de mercado em reais.
        * variacao_quantidade (Int64): variação diária da quantidade.
        * status_titulo (String): status do título.

    Examples:
        >>> import datetime as dt
        >>> data = yd.du.deslocar(dt.date.today(), -2)
        >>> df = yd.tpf.estoque(data)
        >>> df.shape[0] > 0
        True
    """
    data = cv.converter_datas(data)
    if not cv.data_referencia_valida(data):
        return pl.DataFrame()

    url_content = _buscar_conteudo_url(data)
    if not url_content:
        return pl.DataFrame()

    df = _parsear_tabelas_html(url_content)
    if df.is_empty():
        return pl.DataFrame()
    return _processar_df(df, data)

def leiloes_bcb(
    *,
    data: DateLike | DatesLike | None = None,
    inicio: DateLike | None = None,
    fim: DateLike | None = None,
) -> pl.DataFrame:
    """Busca resultados de leilões de TPFs no BCB.

    Fonte: Banco Central do Brasil, disponível desde 12/11/2012. Alternativa a
    ``yd.tpf.leiloes`` (Tesouro Nacional) para quando o Tesouro estiver
    indisponível ou ainda não trouxer a 2ª volta. Recebe os mesmos parâmetros e
    usa os mesmos nomes de colunas; colunas exclusivas de cada fonte ficam
    ausentes na outra. Os resultados podem ser unidos com
    ``pl.concat(..., how="diagonal")``.

    Args:
        data: Data ou sequência de datas do leilão. Padrão é ``None``.
        inicio: Data inicial da consulta. Padrão é ``None``.
        fim: Data final da consulta. Padrão é ``None``.

    Returns:
        DataFrame Polars com os leilões no período, ordenado por data, título e
        vencimento. Sem filtros temporais, retorna o histórico completo.
        Retorna DataFrame vazio se não houver dados.

    Output Columns:
        * data_1v (Date): data de realização do leilão.
        * data_liquidacao_1v (Date): data de liquidação financeira da 1ª volta.
        * numero_edital (Int64): número do edital do leilão.
        * tipo_leilao (String): ``"Venda"`` ou ``"Compra"``.
        * tipo_publico (String): público do leilão (exclusiva do BCB).
        * titulo (String): LTN, LFT, NTN-B ou NTN-F.
        * codigo_selic (Int64): código do título no Selic (exclusiva do BCB).
        * data_vencimento (Date): data de vencimento do título.
        * dias_uteis (Int64): dias úteis entre liquidação e vencimento.
        * dias_corridos (Int64): dias corridos entre liquidação e vencimento.
        * duration (Float64): duration de Macaulay em anos.
        * prazo_medio (Float64): maturidade média em anos.
        * quantidade_ofertada_1v (Int64): quantidade ofertada na 1ª volta.
        * quantidade_ofertada_2v (Int64): quantidade ofertada na 2ª volta.
        * quantidade_aceita_1v (Int64): quantidade aceita na 1ª volta.
        * quantidade_aceita_2v (Int64): quantidade aceita na 2ª volta.
        * quantidade_aceita_total (Int64): quantidade aceita total.
        * quantidade_liquidada_1v (Int64): quantidade liquidada na 1ª volta.
        * quantidade_liquidada_2v (Int64): quantidade liquidada na 2ª volta.
        * financeiro_ofertado_1v (Float64): quantidade ofertada na 1ª volta
            vezes ``pu_medio``.
        * financeiro_ofertado_2v (Float64): quantidade ofertada na 2ª volta
            vezes ``pu_medio``.
        * financeiro_ofertado_total (Float64): financeiro ofertado total.
        * financeiro_aceito_1v (Float64): quantidade aceita na 1ª volta vezes
            ``pu_medio``.
        * financeiro_aceito_2v (Float64): quantidade aceita na 2ª volta vezes
            ``pu_medio``.
        * financeiro_aceito_total (Float64): financeiro aceito total.
        * colocacao_1v (Float64): taxa de colocação da 1ª volta.
        * colocacao_2v (Float64): taxa de colocação da 2ª volta.
        * colocacao_total (Float64): taxa de colocação total.
        * dv01_1v (Float64): DV01 da 1ª volta em reais.
        * dv01_2v (Float64): DV01 da 2ª volta em reais.
        * dv01_total (Float64): DV01 total em reais.
        * ptax (Float64): PTAX usada na conversão para dólar.
        * dv01_1v_usd (Float64): DV01 da 1ª volta em dólar.
        * dv01_2v_usd (Float64): DV01 da 2ª volta em dólar.
        * dv01_total_usd (Float64): DV01 total em dólar.
        * pu_minimo (Float64): PU de corte.
        * pu_medio (Float64): PU médio aceito.
        * taxa_media (Float64): taxa média aceita.
        * taxa_maxima (Float64): taxa de corte.

    Notes:
        Diferenças em relação ao Tesouro Nacional:

        - O BCB não publica ``data_liquidacao_2v``, ``tipo_ocorrencia``,
          ``benchmark``, ``quantidade_bcb``, ``financeiro_bcb`` nem
          ``tipo_pu_medio``.
        - O financeiro publicado pelo BCB é arredondado a R$ 100 mil. Por
          isso, os financeiros são calculados como quantidade vezes
          ``pu_medio``, o que reproduz o Tesouro na 1ª volta; na 2ª volta, a
          diferença típica é inferior a 0,1%.
        - Na 2ª volta, a quantidade ofertada do BCB é a nominal do edital,
          enquanto o Tesouro pode informar valores ligeiramente menores.
        - Até 10/06/2024, o BCB publica cotação, e não PU, para LFT e NTN-B.
          Nesses casos, ``pu_medio`` é estimado pelo financeiro dividido pela
          quantidade aceita (sujeito ao arredondamento acima) e
          ``pu_minimo`` é nulo.

        ``data`` não pode ser combinado com ``inicio`` ou ``fim``. ``fim`` só
        pode ser usado junto com ``inicio``.

    Examples:
        >>> df = yd.tpf.leiloes_bcb(data="19-08-2025")
        >>> df.select("titulo", "quantidade_aceita_total", "pu_medio", "taxa_media")
        shape: (5, 4)
        ┌────────┬─────────────────────────┬──────────────┬────────────┐
        │ titulo ┆ quantidade_aceita_total ┆ pu_medio     ┆ taxa_media │
        │ ---    ┆ ---                     ┆ ---          ┆ ---        │
        │ str    ┆ i64                     ┆ f64          ┆ f64        │
        ╞════════╪═════════════════════════╪══════════════╪════════════╡
        │ LFT    ┆ 150000                  ┆ 17149.069465 ┆ 0.000636   │
        │ LFT    ┆ 751003                  ┆ 17072.592044 ┆ 0.001068   │
        │ NTN-B  ┆ 300759                  ┆ 4299.806542  ┆ 0.08167    │
        │ NTN-B  ┆ 500542                  ┆ 4143.249763  ┆ 0.07748    │
        │ NTN-B  ┆ 500000                  ┆ 4021.3613    ┆ 0.07323    │
        └────────┴─────────────────────────┴──────────────┴────────────┘
    """
    _validar_periodo(data, inicio, fim)

    datas = None
    if data is not None:
        if any_is_empty(data):
            return pl.DataFrame()
        convertidas = cv.converter_datas(data)
        if isinstance(convertidas, pl.Series):
            datas = sorted(convertidas.drop_nulls().to_list())
        else:
            datas = [convertidas]
        data_inicio, data_fim = datas[0], datas[-1]
    else:
        data_inicio = cv.converter_datas(inicio) if inicio is not None else None
        data_fim = cv.converter_datas(fim) if fim is not None else None

    if data_inicio is not None and data_fim is not None and data_inicio > data_fim:
        msg = "inicio deve ser menor ou igual a fim."
        raise ValueError(msg)

    df = parsear_csv(_buscar_csv(data_inicio, data_fim))
    if df.is_empty():
        return pl.DataFrame()

    df = _processar_df(df)
    if datas is not None:
        df = df.filter(pl.col("data_1v").is_in(datas))
    if df.is_empty():
        return pl.DataFrame()

    return (
        _enriquecer(df)
        .select(ORDEM_FINAL_COLUNAS)
        .sort("data_1v", "titulo", "data_vencimento")
    )

def premios_pre(data: DateLike) -> pl.DataFrame:
    """Calcula o prêmio dos títulos prefixados (LTN e NTN-F) sobre o DI.

    Em linguagem de mercado, esse valor é chamado de prêmio. Em termos
    descritivos, trata-se do spread sobre o DI.

    Definição do prêmio:
        premio = taxa indicativa do PRE - taxa de ajuste do DI

    A coluna retorna essa diferença em formato decimal (ex: 0.000439 ≈
    4.39 bps). Para exibir o prêmio em pontos-base, multiplique a coluna
    ``premio`` por 10_000 no DataFrame retornado. No exemplo abaixo, essa
    coluna é sobrescrita apenas para facilitar a leitura em pontos-base.

    Args:
        data: Data da consulta para buscar as taxas.

    Returns:
        DataFrame com as colunas do prêmio. Retorna DataFrame vazio se
        não houver dados.

    Output Columns:
        * titulo (String): tipo do título.
        * data_vencimento (Date): data de vencimento.
        * premio (Float64): prêmio em formato decimal (spread sobre o DI).

    Examples:
        >>> # Exemplo em pontos-base para facilitar a leitura
        >>> yd.tpf.premios_pre("30-05-2025").with_columns(
        ...     premio=pl.col("premio") * 10_000
        ... )
        shape: (18, 3)
        ┌────────┬─────────────────┬────────┐
        │ titulo ┆ data_vencimento ┆ premio │
        │ ---    ┆ ---             ┆ ---    │
        │ str    ┆ date            ┆ f64    │
        ╞════════╪═════════════════╪════════╡
        │ LTN    ┆ 2025-07-01      ┆ 4.39   │
        │ LTN    ┆ 2025-10-01      ┆ -9.0   │
        │ LTN    ┆ 2026-01-01      ┆ -4.88  │
        │ LTN    ┆ 2026-04-01      ┆ -4.45  │
        │ LTN    ┆ 2026-07-01      ┆ 0.81   │
        │ …      ┆ …               ┆ …      │
        │ 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   │
        └────────┴─────────────────┴────────┘
    """
    df = _utils.obter_tpf(data, "PRE").select(
        "titulo", "data_vencimento", "taxa_indicativa"
    )
    if df.is_empty():
        return df.select(
            pl.lit("").alias("titulo"),
            pl.lit(None, dtype=pl.Date).alias("data_vencimento"),
            pl.lit(None, dtype=pl.Float64).alias("premio"),
        ).clear()
    df = _utils.adicionar_taxa_di(df, data)
    return (
        df.with_columns(premio=pl.col("taxa_indicativa") - pl.col("taxa_di"))
        .select("titulo", "data_vencimento", "premio")
        .sort("titulo", "data_vencimento")
    )

def taxas(
    data: DateLike,
    titulo: TipoTPF | None = None,
) -> pl.DataFrame:
    """Busca taxas e preços indicativos de TPFs.

    Fonte: ANBIMA. Primeiro consulta o cache local de dados históricos; se a
    data não estiver no cache, busca diretamente na fonte da ANBIMA.

    Args:
        data: Data de referência.
        titulo: Tipo do título público federal. Aceita ``LFT``, ``NTN-B``,
            ``NTN-C``, ``LTN``, ``NTN-F`` ou ``PRE``.

    Returns:
        DataFrame Polars com taxas e preços indicativos. Retorna DataFrame
        vazio, com as colunas abaixo, se não houver dados para a data.

    Output Columns:
        * titulo (String): tipo do título público.
        * data_referencia (Date): data de referência dos dados.
        * codigo_selic (Int64): código do título no SELIC.
        * data_base (Date): data base ou de emissão do título.
        * data_vencimento (Date): data de vencimento do título.
        * pu (Float64): preço unitário para liquidação em D0.
        * taxa_compra (Float64): taxa de compra em D0.
        * taxa_venda (Float64): taxa de venda em D0.
        * taxa_indicativa (Float64): taxa indicativa em D0.

    Examples:
        >>> df = yd.tpf.taxas(data="06-02-2026")
    """
    data = converter_datas(data)

    if not data_referencia_valida(data):
        return pl.DataFrame(schema=_SCHEMA_SAIDA)

    try:
        df = _obter_historico()
    except (requests.exceptions.RequestException, pl.exceptions.PolarsError):
        df = pl.DataFrame()
    if not df.is_empty():
        df = df.filter(pl.col("data_referencia") == data)
    if df.is_empty():
        df = _anbima_taxas.buscar(data)

    if df.is_empty():
        return pl.DataFrame(schema=_SCHEMA_SAIDA)

    df = df.select(col for col in _COLUNAS_SAIDA if col in df.columns)
    if titulo:
        tipos_titulo = _mapear_tipo_titulo(titulo)
        df = df.filter(pl.col("titulo").is_in(tipos_titulo))

    return df.sort("data_referencia", "titulo", "data_vencimento")

def taxas_historicas(
    inicio: DateLike | None = None,
    fim: DateLike | None = None,
    titulo: TipoTPF | None = None,
) -> pl.DataFrame:
    """Consulta o histórico de taxas e preços indicativos de TPFs.

    Fonte: ANBIMA, em painel histórico publicado pela PYield. Os filtros de
    período são inclusivos. Sem argumentos, retorna todo o histórico disponível.

    Args:
        inicio: Data inicial do período. Se omitida, não limita o início.
        fim: Data final do período. Se omitida, não limita o fim.
        titulo: Tipo do título público federal. Aceita ``LFT``, ``NTN-B``,
            ``NTN-C``, ``LTN``, ``NTN-F`` ou ``PRE``.

    Returns:
        DataFrame Polars com o histórico de taxas e preços indicativos. Retorna
        DataFrame vazio se não houver dados para os filtros informados.

    Output Columns:
        * titulo (String): tipo do título público.
        * data_referencia (Date): data de referência dos dados.
        * codigo_selic (Int64): código do título no SELIC.
        * data_base (Date): data base ou de emissão do título.
        * data_vencimento (Date): data de vencimento do título.
        * pu (Float64): preço unitário para liquidação em D0.
        * taxa_compra (Float64): taxa de compra em D0.
        * taxa_venda (Float64): taxa de venda em D0.
        * taxa_indicativa (Float64): taxa indicativa em D0.

    Raises:
        ValueError: Se ``inicio`` for posterior a ``fim``.

    Examples:
        >>> df = yd.tpf.taxas_historicas(
        ...     inicio="01-01-2025", fim="31-01-2025", titulo="PRE"
        ... )
    """
    data_inicio = converter_datas(inicio) if inicio is not None else None
    data_fim = converter_datas(fim) if fim is not None else None
    if data_inicio is not None and data_fim is not None and data_inicio > data_fim:
        msg = "inicio deve ser menor ou igual a fim."
        raise ValueError(msg)

    df = _obter_historico()
    if df.is_empty():
        return df

    if data_inicio is not None:
        df = df.filter(pl.col("data_referencia") >= data_inicio)
    if data_fim is not None:
        df = df.filter(pl.col("data_referencia") <= data_fim)
    if titulo:
        tipos_titulo = _mapear_tipo_titulo(titulo)
        df = df.filter(pl.col("titulo").is_in(tipos_titulo))

    return df.select(_COLUNAS_SAIDA).sort(
        "data_referencia", "titulo", "data_vencimento"
    )

def vencimentos(
    data: DateLike,
    titulo: TipoTPF,
) -> pl.Series:
    """Busca vencimentos de TPFs disponíveis nas taxas indicativas.

    Fonte: ANBIMA, mesma base usada por ``yd.tpf.taxas``.

    Args:
        data: Data de referência.
        titulo: Tipo do título público federal. Aceita ``LFT``, ``NTN-B``,
            ``NTN-C``, ``LTN``, ``NTN-F`` ou ``PRE``.

    Returns:
        Series ordenada com os vencimentos disponíveis.

    Examples:
        >>> yd.tpf.vencimentos(data="22-08-2025", titulo="PRE")
        shape: (18,)
        Series: 'data_vencimento' [date]
        [
            2025-10-01
            2026-01-01
            2026-04-01
            2026-07-01
            2026-10-01
            …
            2030-01-01
            2031-01-01
            2032-01-01
            2033-01-01
            2035-01-01
        ]
    """
    return taxas(data, titulo)["data_vencimento"].unique().sort()

def baixar_arquivo(data: DateLike) -> bytes:
    """Baixa o arquivo bruto de taxas de TPF publicado pela ANBIMA.

    Args:
        data: Data de referência do arquivo.

    Returns:
        Bytes do arquivo publicado pela ANBIMA, sem decodificação ou parsing.

    Raises:
        requests.HTTPError: Se o arquivo não estiver disponível ou a resposta
            HTTP indicar erro.
        ValueError: Se ``data`` não for uma data escalar válida.
    """
    if isinstance(data, str) and not data.strip():
        msg = "data deve ser escalar para baixar um arquivo da ANBIMA"
        raise ValueError(msg)
    data_arquivo = converter_datas(data)
    return _obter_csv(data_arquivo)

def buscar(data: DateLike) -> pl.DataFrame:
    """Busca e processa taxas de TPF diretamente na ANBIMA.

    Fonte: arquivo de taxas de títulos públicos da ANBIMA.

    Args:
        data: Data de referência do arquivo.

    Returns:
        DataFrame com todas as colunas processadas da fonte. Retorna DataFrame
        vazio para datas válidas sem dados disponíveis.

    Output Columns:
        * titulo (String): tipo do título público.
        * data_referencia (Date): data de referência dos dados.
        * codigo_selic (Int64): código do título no SELIC.
        * data_base (Date): data base ou de emissão do título.
        * data_vencimento (Date): data de vencimento do título.
        * taxa_compra (Float64): taxa de compra em D0.
        * taxa_venda (Float64): taxa de venda em D0.
        * taxa_indicativa (Float64): taxa indicativa em D0.
        * pu (Float64): preço unitário para liquidação em D0.
        * desvio_padrao (Float64): desvio padrão das taxas observadas.
        * taxa_intervalo_inf_d0 (Float64): limite inferior indicativo em D0.
        * taxa_intervalo_sup_d0 (Float64): limite superior indicativo em D0.
        * taxa_intervalo_inf_d1 (Float64): limite inferior indicativo em D+1.
        * taxa_intervalo_sup_d1 (Float64): limite superior indicativo em D+1.
        * criterio (String): critério usado pela ANBIMA para o título.

    Raises:
        ValueError: Se ``data`` não for uma data escalar válida.
    """
    data = converter_datas(data)
    if not data_referencia_valida(data):
        return pl.DataFrame()

    url_arquivo = _montar_url_arquivo(data)

    # Fail-fast: se a URL é RTM e o host não resolve, não adianta tentar
    if ANBIMA_RTM_URL in url_arquivo:
        try:
            socket.gethostbyname(ANBIMA_RTM_HOSTNAME)
        except socket.gaierror:
            data_str = data.strftime("%d/%m/%Y")
            logger.warning(
                f"Não foi possível resolver o host da RTM para {data_str}. "
                "Dados históricos exigem acesso à rede RTM."
            )
            return pl.DataFrame()

    csv_bytes = _obter_csv(data)
    if not csv_bytes.strip():
        return pl.DataFrame()

    return ler(csv_bytes)

def ler(fonte: bytes | _CaminhoArquivo) -> pl.DataFrame:
    """Lê taxas de TPF da ANBIMA a partir de bytes ou arquivo local.

    Fonte: arquivo de taxas de títulos públicos da ANBIMA.

    Arquivos atuais ``.txt`` são lidos diretamente. Arquivos históricos
    ``.exe`` são tratados como ZIPs e o arquivo interno é lido.

    Args:
        fonte: Bytes do arquivo bruto ou caminho do arquivo salvo localmente.

    Returns:
        DataFrame Polars com todas as colunas processadas da fonte.

    Output Columns:
        * titulo (String): tipo do título público.
        * data_referencia (Date): data de referência dos dados.
        * codigo_selic (Int64): código do título no SELIC.
        * data_base (Date): data base ou de emissão do título.
        * data_vencimento (Date): data de vencimento do título.
        * taxa_compra (Float64): taxa de compra em D0.
        * taxa_venda (Float64): taxa de venda em D0.
        * taxa_indicativa (Float64): taxa indicativa em D0.
        * pu (Float64): preço unitário para liquidação em D0.
        * desvio_padrao (Float64): desvio padrão das taxas observadas.
        * taxa_intervalo_inf_d0 (Float64): limite inferior indicativo em D0.
        * taxa_intervalo_sup_d0 (Float64): limite superior indicativo em D0.
        * taxa_intervalo_inf_d1 (Float64): limite inferior indicativo em D+1.
        * taxa_intervalo_sup_d1 (Float64): limite superior indicativo em D+1.
        * criterio (String): critério usado pela ANBIMA para o título.
    """
    conteudo = fonte if isinstance(fonte, bytes) else Path(fonte).read_bytes()
    if zf.is_zipfile(io.BytesIO(conteudo)):
        with zf.ZipFile(io.BytesIO(conteudo)) as arquivo_zip:
            conteudo = arquivo_zip.read(arquivo_zip.namelist()[0])
    return _processar_df(_parsear_df(conteudo))

def baixar_zip(data: DateLike, extragrupo: bool = False) -> bytes:
    """Baixa o ZIP bruto mensal de negociações secundárias de TPFs.

    Fonte: Banco Central do Brasil, sistema SELIC. A fonte publica um arquivo
    por mês; por isso, apenas o ano e o mês de ``data`` são usados.

    A função valida a estrutura mínima do ZIP antes de retornar os bytes, para
    evitar que pipelines de ingestão salvem arquivo vazio, corrompido ou sem
    CSV plausível. Use :func:`ler` para processar os bytes ou o arquivo salvo.

    Args:
        data: Data de referência. Apenas ano e mês definem o arquivo.
        extragrupo: Se verdadeiro, baixa o arquivo extragrupo.

    Returns:
        Bytes validados do arquivo ZIP mensal publicado pelo BCB.

    Raises:
        requests.HTTPError: Se o arquivo não estiver disponível no BCB ou a
            resposta HTTP indicar erro.
        ValueError: Se o conteúdo baixado não for um ZIP bruto plausível.

    Examples:
        >>> conteudo = yd.tpf.secundario.baixar_zip("07-01-2025")  # doctest: +SKIP
    """
    arquivo = _nome_arquivo_mensal(data, extragrupo)
    conteudo_zip = _baixar_url_zip(f"{URL_BASE_MENSAL}/{arquivo}")
    _validar_zip(conteudo_zip, arquivo)
    return conteudo_zip

def intradia() -> pl.DataFrame:
    """Busca dados intradia do mercado secundário de TPFs.

    Fonte: Banco Central do Brasil, sistema SELIC. Os dados ficam disponíveis
    apenas durante o horário do SELIC (09:00-22:00 BRT) em dias úteis.

    Returns:
        DataFrame Polars com negociações intradia do mercado secundário.
        Retorna DataFrame vazio fora do horário do SELIC.

    Output Columns:
        * data_hora_consulta (Datetime): data e hora da consulta.
        * data_liquidacao (Date): data de liquidação à vista.
        * titulo (String): sigla do título público.
        * codigo_selic (Int64): código SELIC do título.
        * data_vencimento (Date): data de vencimento do título.
        * pu_minimo (Float64): menor preço negociado.
        * pu_medio (Float64): preço médio negociado.
        * pu_maximo (Float64): maior preço negociado.
        * pu_ultimo (Float64): último preço negociado.
        * taxa_minima (Float64): menor taxa negociada.
        * taxa_media (Float64): taxa média negociada.
        * taxa_maxima (Float64): maior taxa negociada.
        * taxa_ultima (Float64): última taxa negociada.
        * operacoes (Int64): total de operações liquidadas.
        * quantidade (Int64): quantidade total de títulos negociados.
        * financeiro (Float64): valor financeiro total negociado.
        * operacoes_corretagem (Int64): operações via corretagem.
        * quantidade_corretagem (Int64): títulos via corretagem.
        * termo_pu_minimo (Float64): menor preço a termo negociado.
        * termo_pu_medio (Float64): preço médio a termo negociado.
        * termo_pu_ultimo (Float64): último preço a termo negociado.
        * termo_pu_maximo (Float64): maior preço a termo negociado.
        * termo_taxa_ultima (Float64): última taxa a termo negociada.
        * termo_taxa_minima (Float64): menor taxa a termo negociada.
        * termo_taxa_media (Float64): taxa média a termo negociada.
        * termo_taxa_maxima (Float64): maior taxa a termo negociada.
        * termo_operacoes (Int64): total de operações a termo.
        * termo_quantidade (Int64): total de títulos a termo negociados.
        * termo_financeiro (Float64): valor financeiro total a termo.
        * termo_operacoes_corretagem (Int64): operações a termo via corretagem.
        * termo_quantidade_corretagem (Int64): títulos a termo via corretagem.

    Examples:
        >>> df = yd.tpf.secundario.intradia()  # doctest: +SKIP
    """
    if not _mercado_selic_aberto():
        return pl.DataFrame()

    texto_bruto = _buscar_csv_intradia()
    df = _parsear_csv_intradia(texto_bruto)
    return _processar_df_intradia(df)

def ler(fonte: bytes | CaminhoArquivo) -> pl.DataFrame:
    """Lê o ZIP mensal bruto do secundário de TPFs.

    Fonte: Banco Central do Brasil, sistema SELIC. Mesma saída de
    :func:`mensal`, mas recebe o ZIP bruto em vez de baixá-lo. Útil para
    processar arquivos salvos com :func:`baixar_zip`.

    Args:
        fonte: ZIP bruto em bytes ou caminho para o arquivo ZIP no disco.

    Returns:
        DataFrame Polars com as colunas documentadas em :func:`mensal`.

    Raises:
        ValueError: Se o conteúdo não for um ZIP válido.

    Examples:
        >>> conteudo = yd.tpf.secundario.baixar_zip("07-01-2025")  # doctest: +SKIP
        >>> df = yd.tpf.secundario.ler(conteudo)  # doctest: +SKIP
        >>> df = yd.tpf.secundario.ler("NegT202501.ZIP")  # doctest: +SKIP
    """
    conteudo_zip = fonte if isinstance(fonte, bytes) else Path(fonte).read_bytes()
    return _processar_df_mensal(_parsear_csv_mensal(_extrair_csv_zip(conteudo_zip)))

def mensal(data: DateLike, extragrupo: bool = False) -> pl.DataFrame:
    """Busca dados mensais do mercado secundário de TPFs.

    Fonte: Banco Central do Brasil, sistema SELIC. Baixa e valida o ZIP mensal
    de negociações secundárias e retorna os dados processados.
    Apenas o ano e o mês de ``data`` são usados para identificar o arquivo.

    Args:
        data: Data de referência. Apenas ano e mês definem o arquivo.
        extragrupo: Se verdadeiro, busca apenas negociações extragrupo.

    Returns:
        DataFrame Polars com dados mensais do mercado secundário.

    Output Columns:
        * data_liquidacao (Date): data de liquidação da negociação.
        * titulo (String): sigla do título público.
        * codigo_selic (Int64): código único no sistema SELIC.
        * isin (String): código ISIN.
        * data_emissao (Date): data de emissão do título.
        * data_vencimento (Date): data de vencimento do título.
        * operacoes (Int64): número total de operações.
        * quantidade (Int64): quantidade total negociada.
        * pu_minimo (Float64): preço unitário mínimo.
        * pu_medio (Float64): preço unitário médio.
        * pu_maximo (Float64): preço unitário máximo.
        * pu_lastro (Float64): preço unitário de lastro.
        * valor_par (Float64): valor par do título.
        * taxa_minima (Float64): taxa mínima.
        * taxa_media (Float64): taxa média.
        * taxa_maxima (Float64): taxa máxima.
        * operacoes_corretagem (Int64): operações com corretagem.
        * quantidade_corretagem (Int64): quantidade com corretagem.
        * financeiro (Float64): valor financeiro negociado
            (``quantidade * pu_medio``).

    Notes:
        O schema é estável para concatenação entre meses. Em layouts antigos
        da fonte que não trazem corretagem, ``operacoes_corretagem`` e
        ``quantidade_corretagem`` são retornadas como nulas.

    Examples:
        >>> df = yd.tpf.secundario.mensal("07-01-2025", extragrupo=True)
    """
    if any_is_empty(data):
        return pl.DataFrame()

    data_alvo = _data_mensal(data)
    hoje = relogio.hoje()
    if (data_alvo.year, data_alvo.month) > (hoje.year, hoje.month):
        return pl.DataFrame()

    return ler(baixar_zip(data_alvo, extragrupo))