Pular para conteúdo

Futuro

Contratos futuros negociados na B3.

datas_disponiveis(contrato)

Retorna as datas disponíveis no dataset histórico cacheado.

Parameters:

Name Type Description Default
contrato str

Contrato futuro (ex.: DI1, DOL).

 required

Returns:

Type Description
Series

Series ordenada de datas para as quais há dados históricos.

Examples:

>>> yd.futuro.datas_disponiveis("DI1").head(3)
shape: (3,)
Series: 'data_referencia' [date]
[
    2018-01-02
    2018-01-03
    2018-01-04
]
Source code in pyield/futuro/historico.py 
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
def datas_disponiveis(contrato: str) -> pl.Series:
    """Retorna as datas disponíveis no dataset histórico cacheado.

    Args:
        contrato: Contrato futuro (ex.: ``DI1``, ``DOL``).

    Returns:
        Series ordenada de datas para as quais há dados históricos.

    Examples:
        >>> yd.futuro.datas_disponiveis("DI1").head(3)
        shape: (3,)
        Series: 'data_referencia' [date]
        [
            2018-01-02
            2018-01-03
            2018-01-04
        ]
    """
    return (
        _obter_cache_filtrado(contrato)
        .get_column("TradDt")
        .drop_nulls()
        .unique()
        .sort()
        .alias("data_referencia")
    )

enriquecer(df, contrato)

Enriquece DataFrame bruto do Price Report (PR) da B3.

Aceita um DataFrame com colunas no schema original da B3 (ex.: TradDt, TckrSymb). Filtra pelo contrato informado, adiciona data de vencimento, dias úteis/corridos e colunas derivadas (dv01, taxa_forward) conforme o contrato.

Parameters:

Name Type Description Default
df DataFrame

DataFrame com dados brutos do PR da B3.

 required
contrato str

Contrato futuro (ex.: DI1, DOL).

 required

Returns:

Type Description
DataFrame

DataFrame Polars enriquecido e ordenado.
Source code in pyield/futuro/historico.py 
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
def enriquecer(df: pl.DataFrame, contrato: str) -> pl.DataFrame:
    """Enriquece DataFrame bruto do Price Report (PR) da B3.

    Aceita um DataFrame com colunas no schema original da B3
    (ex.: ``TradDt``, ``TckrSymb``). Filtra pelo contrato informado,
    adiciona data de vencimento, dias úteis/corridos e colunas
    derivadas (dv01, taxa_forward) conforme o contrato.

    Args:
        df: DataFrame com dados brutos do PR da B3.
        contrato: Contrato futuro (ex.: ``DI1``, ``DOL``).

    Returns:
        DataFrame Polars enriquecido e ordenado.
    """
    if df.is_empty():
        return pl.DataFrame()

    df = df.rename(_RENOMEAR_COLUNAS_PR)
    df = df.filter(
        pl.col("codigo_negociacao").str.starts_with(contrato),
        pl.col("codigo_negociacao").str.len_chars() == _COMPRIMENTO_TICKER,
    )
    if df.is_empty():
        return pl.DataFrame()
    df = df.with_columns(
        data_vencimento=ct.vencimento_expr("codigo_negociacao", contrato)
    )
    df = _enriquecer_dados(df, contrato)
    df = _selecionar_colunas_saida(df, contrato)

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

vencimento(codigo, contrato)

Calcula a data de vencimento de contratos futuros da B3.

Parameters:

Name Type Description Default
codigo str | ArrayLike | None

Código de negociação ou coleção de códigos.

 required
contrato str

Contrato futuro na B3 (ex.: DI1 ou DAP).

 required

Returns:

Type Description
date | Series | None

Data de vencimento para código escalar, ou pl.Series para coleção.

Examples:

>>> yd.futuro.vencimento("DI1F25", "DI1")
datetime.date(2025, 1, 2)

>>> yd.futuro.vencimento(["DI1F25", "di1g25", "DI1E27"], "DI1")
shape: (3,)
Series: 'vencimento' [date]
[
    2025-01-02
    2025-02-03
    null
]
Source code in pyield/futuro/contratos.py 
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
def vencimento(
    codigo: str | ArrayLike | None,
    contrato: str,
) -> dt.date | pl.Series | None:
    """Calcula a data de vencimento de contratos futuros da B3.

    Args:
        codigo: Código de negociação ou coleção de códigos.
        contrato: Contrato futuro na B3 (ex.: ``DI1`` ou ``DAP``).

    Returns:
        Data de vencimento para código escalar, ou ``pl.Series`` para coleção.

    Examples:
        >>> yd.futuro.vencimento("DI1F25", "DI1")
        datetime.date(2025, 1, 2)

        >>> yd.futuro.vencimento(["DI1F25", "di1g25", "DI1E27"], "DI1")
        shape: (3,)
        Series: 'vencimento' [date]
        [
            2025-01-02
            2025-02-03
            null
        ]
    """
    dados = codigo if any_is_collection(codigo) else [codigo]
    serie = (
        pl.DataFrame({"codigo": dados})
        .select(vencimento=vencimento_expr("codigo", contrato))
        .get_column("vencimento")
    )

    if any_is_collection(codigo):
        return serie

    return serie.item()

vencimento_expr(coluna_codigo, contrato)

Cria expressão Polars para a data de vencimento de futuros da B3.

Assume códigos de negociação no formato padrão de futuros da B3 (ex.: DI1F25). A caixa dos caracteres é ignorada e o vencimento é ajustado para dia útil.

Parameters:

Name Type Description Default
coluna_codigo str

Nome da coluna com o código de negociação.

 required
contrato str

Contrato futuro na B3 (ex.: DI1 ou DAP).

 required

Returns:

Type Description
Expr

Uma pl.Expr que resulta em Date.

Examples:

>>> df = pl.DataFrame({"codigo_negociacao": ["DI1F25", "di1g25", "DI1E27"]})
>>> df.select(
...     yd.futuro.vencimento_expr("codigo_negociacao", "DI1").alias(
...         "vencimento"
...     )
... )
shape: (3, 1)
┌────────────┐
│ vencimento │
│ ---        │
│ date       │
╞════════════╡
│ 2025-01-02 │
│ 2025-02-03 │
│ null       │
└────────────┘

Contratos DAP vencem no dia 15:

>>> df = pl.DataFrame({"codigo_negociacao": ["DAPF25"]})
>>> df.select(
...     yd.futuro.vencimento_expr("codigo_negociacao", "DAP").alias(
...         "vencimento"
...     )
... )
shape: (1, 1)
┌────────────┐
│ vencimento │
│ ---        │
│ date       │
╞════════════╡
│ 2025-01-15 │
└────────────┘
Source code in pyield/futuro/contratos.py 
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
def vencimento_expr(coluna_codigo: str, contrato: str) -> pl.Expr:
    """Cria expressão Polars para a data de vencimento de futuros da B3.

    Assume códigos de negociação no formato padrão de futuros da B3 (ex.:
    ``DI1F25``). A caixa dos caracteres é ignorada e o vencimento é ajustado
    para dia útil.

    Args:
        coluna_codigo: Nome da coluna com o código de negociação.
        contrato: Contrato futuro na B3 (ex.: ``DI1`` ou ``DAP``).

    Returns:
        Uma ``pl.Expr`` que resulta em Date.

    Examples:
        >>> df = pl.DataFrame({"codigo_negociacao": ["DI1F25", "di1g25", "DI1E27"]})
        >>> df.select(
        ...     yd.futuro.vencimento_expr("codigo_negociacao", "DI1").alias(
        ...         "vencimento"
        ...     )
        ... )
        shape: (3, 1)
        ┌────────────┐
        │ vencimento │
        │ ---        │
        │ date       │
        ╞════════════╡
        │ 2025-01-02 │
        │ 2025-02-03 │
        │ null       │
        └────────────┘

        Contratos DAP vencem no dia 15:
        >>> df = pl.DataFrame({"codigo_negociacao": ["DAPF25"]})
        >>> df.select(
        ...     yd.futuro.vencimento_expr("codigo_negociacao", "DAP").alias(
        ...         "vencimento"
        ...     )
        ... )
        shape: (1, 1)
        ┌────────────┐
        │ vencimento │
        │ ---        │
        │ date       │
        ╞════════════╡
        │ 2025-01-15 │
        └────────────┘
    """
    dia_vencimento = 15 if "DAP" in contrato.upper() else 1
    codigo = pl.col(coluna_codigo).str.to_uppercase()
    data_vencimento = pl.date(
        year=codigo.str.slice(4, 2).cast(pl.Int32, strict=False) + 2000,
        month=codigo.str.slice(3, 1).replace_strict(
            _MAPA_MESES, default=None, return_dtype=pl.Int8
        ),
        day=dia_vencimento,
    )
    return du.deslocar_expr(data_vencimento, 0)