Calendário do Copom

def calendario(
    inicio: DateLike | None = None,
    fim: DateLike | None = None,
) -> pl.DataFrame:
    """Consulta reuniões históricas e agendadas do Copom nas fontes do BCB.

    Combina a API de atas históricas com o calendário ICS de reuniões do BCB,
    sem datas anuais fixas. As atas têm prioridade na data de decisão; o ICS
    complementa o início e mantém reuniões ainda sem ata, inclusive passadas.

    Args:
        inicio: Limite inicial inclusivo para a data de decisão. Sem limite
            quando None. Aceita DD-MM-YYYY, DD/MM/YYYY, YYYY-MM-DD e date.
        fim: Limite final inclusivo para a data de decisão, nos mesmos formatos.
            Sem limite quando None.

    Returns:
        DataFrame ordenado por data_decisao, sem duplicatas nessa coluna.
        Consultas sem registros retornam DataFrame vazio com o mesmo esquema.

    Output Columns:
        nro_reuniao (Int64): Número sequencial informado na ata; nulo sem ata.
        data_inicio (Date): Primeiro dia informado no ICS; nulo fora da agenda.
        data_decisao (Date): Último dia da reunião, dataReferencia nas atas.
        data_publicacao (Date): Publicação da ata; nula quando não disponível.
        data_efetividade (Date): Próximo dia útil após a decisão, calculado pelo
            calendário brasileiro de yd.du; data de vencimento/liquidação CPM.
        status (String): "Realizada" se a decisão for até hoje no Brasil;
            "A realizar" caso contrário. Classificação por data, não por ata.
        titulo (String): Título original da ata; nulo quando não disponível.
        fonte (String): "Ata" ou "Calendário", conforme a origem da decisão.

    Notes:
        O horizonte depende das datas publicadas pelo BCB. A consulta às atas
        solicita até 500 registros. O conteúdo bruto fica em cache por oito
        horas; o status é recalculado a cada chamada. Erros de rede e payload
        inválido são propagados. O ICS publica um evento por dia: dias únicos
        consecutivos devem formar pares; grupos incompletos geram ValueError.
        O início histórico não é inferido subtraindo um dia da decisão.

    Examples:
        >>> cal = yd.copom.calendario(inicio="01-01-2026")  # doctest: +SKIP
        >>> cal["data_decisao"].is_sorted()  # doctest: +SKIP
        True
    """
    inicio = converter_datas(inicio)
    fim = converter_datas(fim)
    if inicio is not None and fim is not None and inicio > fim:
        raise ValueError("inicio deve ser anterior ou igual a fim.")
    atas = _processar_atas(_parsear_atas(_buscar_atas()))
    agenda = _processar_calendario(_parsear_calendario(_buscar_calendario()))
    df = (
        atas.join(agenda, on="data_decisao", how="full", coalesce=True)
        .with_columns(
            data_efetividade=du.deslocar_expr("data_decisao", 1),
            status=pl.when(pl.col("data_decisao") <= relogio.hoje())
            .then(pl.lit("Realizada"))
            .otherwise(pl.lit("A realizar")),
            fonte=pl.when(pl.col("nro_reuniao").is_not_null())
            .then(pl.lit("Ata"))
            .otherwise(pl.lit("Calendário")),
        )
        .select(tuple(_SCHEMA))
        .sort("data_decisao")
    )
    if inicio is not None:
        df = df.filter(pl.col("data_decisao") >= inicio)
    if fim is not None:
        df = df.filter(pl.col("data_decisao") <= fim)
    return df

def proxima_reuniao(referencia: DateLike | None = None) -> pl.DataFrame:
    """Consulta a primeira reunião com decisão em ou após a referência.

    Usa a API de atas e o calendário ICS do BCB, através de calendario.

    Args:
        referencia: Data inclusiva nos formatos DD-MM-YYYY, DD/MM/YYYY,
            YYYY-MM-DD ou date. None usa a data atual no Brasil.

    Returns:
        DataFrame com até uma linha, com o mesmo esquema de calendario.
        Retorna vazio quando não há reunião publicada a partir da referência.

    Output Columns:
        nro_reuniao (Int64): Número sequencial da ata, quando disponível.
        data_inicio (Date): Primeiro dia no ICS, quando disponível.
        data_decisao (Date): Último dia da reunião.
        data_publicacao (Date): Publicação da ata, quando disponível.
        data_efetividade (Date): Próximo dia útil após a decisão.
        status (String): "Realizada" ou "A realizar", conforme a data atual.
        titulo (String): Título da ata, quando disponível.
        fonte (String): "Ata" ou "Calendário".

    Examples:
        >>> yd.copom.proxima_reuniao("01-01-2026").height  # doctest: +SKIP
        1
    """
    referencia = relogio.hoje() if referencia is None else converter_datas(referencia)
    return calendario(inicio=referencia).head(1)