Pular para conteúdo

Futuros

available_dates(contract_code)

Retorna as datas de negociação disponíveis no dataset histórico PR.

Parameters:

Name Type Description Default
contract_code str

Código do contrato futuro na B3 (ex.: DI1, DOL).

 required

Returns:

Type Description
Series

Series ordenada de datas (Date) para as quais há dados de ajuste.

Examples:

>>> from pyield.b3.futures import available_dates
>>> available_dates("DI1").head(3)
shape: (3,)
Series: 'data_referencia' [date]
[
    2018-01-02
    2018-01-03
    2018-01-04
]
Source code in pyield/b3/futures/__init__.py 
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
def available_dates(contract_code: str) -> pl.Series:
    """Retorna as datas de negociação disponíveis no dataset histórico PR.

    Args:
        contract_code: Código do contrato futuro na B3 (ex.: DI1, DOL).

    Returns:
        Series ordenada de datas (Date) para as quais há dados de ajuste.

    Examples:
        >>> from pyield.b3.futures import available_dates
        >>> available_dates("DI1").head(3)
        shape: (3,)
        Series: 'data_referencia' [date]
        [
            2018-01-02
            2018-01-03
            2018-01-04
        ]
    """
    return historical.listar_datas_disponiveis(contract_code)

futures(date, contract_code, full_report=False)

Busca dados de um contrato futuro da B3 para a data de referência.

Parameters:

Name Type Description Default
date DateLike | ArrayLike

Data de referência para consulta ou coleção de datas. Quando uma coleção é fornecida, os dados são buscados para cada data individualmente e concatenados. Datas inválidas (feriados, fins de semana, futuras) são silenciosamente ignoradas.

 required
contract_code str | list[str]

Código do contrato futuro na B3 ou coleção de códigos. Aceita qualquer código de contrato futuro listado na B3. Contratos com histórico pré-cacheado (desde 2018) são retornados instantaneamente: - Juros: DI1, DDI, FRC, FRO, DAP - Moedas: DOL, WDO - Índices: IND, WIN Para os demais contratos (OC1, IAP, EUR, GBR, JAP, CNY, ISP, WSP, BGI, CCM, ICF, SJC, SOY, ETH, GLD, etc.), os dados são baixados diretamente da B3 a cada chamada.

 required
full_report bool

Controla a fonte de dados quando o dado não está no cache. Se False (padrão), tenta o simplified price report (SPR, ~2 KB) primeiro e faz fallback para o price report completo (PR, ~2 MB). Se True, usa apenas o PR — indicado para processos batch noturnos.

 False

Returns:

Type Description
DataFrame

DataFrame Polars com os dados do contrato informado.

Examples:

>>> df = futures("31-05-2024", "DI1")
>>> df = futures("31-05-2024", "DAP")

Lista de datas:

>>> df = futures(["29-05-2024", "31-05-2024"], "DI1")
>>> df["data_referencia"].unique().sort().to_list()
[datetime.date(2024, 5, 29), datetime.date(2024, 5, 31)]

Véspera de Natal e Ano Novo não têm pregão:

>>> futures("24-12-2024", "DI1").is_empty()
True
>>> futures("31-12-2024", "DI1").is_empty()
True

Data futura e fim de semana retornam DataFrame vazio:

>>> import datetime as dt
>>> amanha = dt.date.today() + dt.timedelta(days=1)
>>> futures(amanha, "DI1").is_empty()
True
>>> futures("04-01-2025", "DI1").is_empty()  # sábado
True
Source code in pyield/b3/futures/__init__.py 
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
def futures(
    date: DateLike | ArrayLike,
    contract_code: str | list[str],
    full_report: bool = False,
) -> pl.DataFrame:
    """Busca dados de um contrato futuro da B3 para a data de referência.

    Args:
        date: Data de referência para consulta ou coleção de datas.
            Quando uma coleção é fornecida, os dados são buscados para cada
            data individualmente e concatenados. Datas inválidas (feriados,
            fins de semana, futuras) são silenciosamente ignoradas.
        contract_code: Código do contrato futuro na B3 ou coleção de
            códigos. Aceita qualquer código de contrato futuro listado
            na B3. Contratos com histórico pré-cacheado (desde 2018)
            são retornados instantaneamente:
            - Juros: DI1, DDI, FRC, FRO, DAP
            - Moedas: DOL, WDO
            - Índices: IND, WIN
            Para os demais contratos (OC1, IAP, EUR, GBR, JAP, CNY,
            ISP, WSP, BGI, CCM, ICF, SJC, SOY, ETH, GLD, etc.),
            os dados são baixados diretamente da B3 a cada chamada.
        full_report: Controla a fonte de dados quando o dado não está
            no cache. Se False (padrão), tenta o simplified price
            report (SPR, ~2 KB) primeiro e faz fallback para o price
            report completo (PR, ~2 MB). Se True, usa apenas o PR —
            indicado para processos batch noturnos.

    Returns:
        DataFrame Polars com os dados do contrato informado.

    Examples:
        >>> df = futures("31-05-2024", "DI1")
        >>> df = futures("31-05-2024", "DAP")

        Lista de datas:

        >>> df = futures(["29-05-2024", "31-05-2024"], "DI1")
        >>> df["data_referencia"].unique().sort().to_list()
        [datetime.date(2024, 5, 29), datetime.date(2024, 5, 31)]

        Véspera de Natal e Ano Novo não têm pregão:

        >>> futures("24-12-2024", "DI1").is_empty()
        True
        >>> futures("31-12-2024", "DI1").is_empty()
        True

        Data futura e fim de semana retornam DataFrame vazio:

        >>> import datetime as dt
        >>> amanha = dt.date.today() + dt.timedelta(days=1)
        >>> futures(amanha, "DI1").is_empty()
        True
        >>> futures("04-01-2025", "DI1").is_empty()  # sábado
        True

    """
    if any_is_empty(date, contract_code):
        return pl.DataFrame()

    codigos_contrato = normalizar_codigos_contrato(contract_code)
    if not codigos_contrato:
        return pl.DataFrame()

    if is_collection(date):
        # date é ArrayLike neste branch
        datas: ArrayLike = date  # type: ignore[assignment]
        return _buscar_varias_datas(datas, codigos_contrato, full_report)

    # date é escalar (DateLike) neste branch
    data_negociacao: dt.date = cv.converter_datas(date)  # type: ignore[assignment]
    if not data_negociacao_valida(data_negociacao):
        return pl.DataFrame()

    return _buscar_por_fonte(data_negociacao, codigos_contrato, full_report)