Skip to content

API reference

Auto-generated from the docstrings. Every public function has a Portuguese name and an English alias; both are listed below, grouped by API.

Utilities

tesouropy_clear_cache 

tesouropy_clear_cache() -> None

Clear the tesouropy in-memory cache.

Removes all cached API responses stored during the current session. This applies to every API covered by the package (SICONFI, CUSTOS, SADIPEM, Transferencias, SIORG, SIOPE): they share a single in-memory store.

Source code in src/tesouropy/_core.py 
159
160
161
162
163
164
165
166
167
def tesouropy_clear_cache() -> None:
    """Clear the tesouropy in-memory cache.

    Removes **all** cached API responses stored during the current session.
    This applies to every API covered by the package (SICONFI, CUSTOS,
    SADIPEM, Transferencias, SIORG, SIOPE): they share a single in-memory store.
    """
    _CACHE.clear()
    log.info("Cache cleared (all APIs).")

set_verbose 

set_verbose(value: bool) -> None

Set the package-wide default for the verbose argument.

Equivalent to options(tesouror.verbose = TRUE) in the R package.

Source code in src/tesouropy/_core.py 
42
43
44
45
46
47
48
def set_verbose(value: bool) -> None:
    """Set the package-wide default for the ``verbose`` argument.

    Equivalent to ``options(tesouror.verbose = TRUE)`` in the R package.
    """
    global _VERBOSE_DEFAULT
    _VERBOSE_DEFAULT = bool(value)

TesouroError

Bases: RuntimeError

Raised for actionable errors talking to a Treasury API.

Source code in src/tesouropy/_core.py 
33
34
class TesouroError(RuntimeError):
    """Raised for actionable errors talking to a Treasury API."""

SICONFI

siconfi

SICONFI API functions (RREO, RGF, DCA, MSC, entities).

API docs: https://apidatalake.tesouro.gov.br/docs/siconfi/

Every public function has a Portuguese name (PT parameters) and an English alias that maps the English parameter names onto the PT ones.

get_entes 

get_entes(
    use_cache=True,
    verbose=False,
    page_size=None,
    max_rows=INF,
)

Get the list of Brazilian government entities (states, municipalities, DF).

Returns a polars DataFrame with columns cod_ibge, ente, capital, regiao, uf, esfera, an_exercicio, populacao, co_cnpj.

Source code in src/tesouropy/siconfi.py 
38
39
40
41
42
43
44
45
46
47
def get_entes(use_cache=True, verbose=False, page_size=None, max_rows=INF):
    """Get the list of Brazilian government entities (states, municipalities, DF).

    Returns a polars DataFrame with columns ``cod_ibge``, ``ente``, ``capital``,
    ``regiao``, ``uf``, ``esfera``, ``an_exercicio``, ``populacao``, ``co_cnpj``.
    """
    return siconfi_fetch_all(
        "/entes", use_cache=use_cache, verbose=verbose, page_size=page_size,
        max_rows=max_rows,
    )

get_entities 

get_entities(
    use_cache=True,
    verbose=False,
    page_size=None,
    max_rows=INF,
)

English alias for :func:get_entes.

Source code in src/tesouropy/siconfi.py 
50
51
52
53
def get_entities(use_cache=True, verbose=False, page_size=None, max_rows=INF):
    """English alias for :func:`get_entes`."""
    return get_entes(use_cache=use_cache, verbose=verbose, page_size=page_size,
                     max_rows=max_rows)

get_anexos 

get_anexos(
    use_cache=True,
    verbose=False,
    page_size=None,
    max_rows=INF,
)

Get the report appendix reference table grouped by government sphere.

Source code in src/tesouropy/siconfi.py 
59
60
61
62
63
64
def get_anexos(use_cache=True, verbose=False, page_size=None, max_rows=INF):
    """Get the report appendix reference table grouped by government sphere."""
    return siconfi_fetch_all(
        "/anexos-relatorios", use_cache=use_cache, verbose=verbose,
        page_size=page_size, max_rows=max_rows,
    )

get_annexes 

get_annexes(
    use_cache=True,
    verbose=False,
    page_size=None,
    max_rows=INF,
)

English alias for :func:get_anexos.

Source code in src/tesouropy/siconfi.py 
67
68
69
70
def get_annexes(use_cache=True, verbose=False, page_size=None, max_rows=INF):
    """English alias for :func:`get_anexos`."""
    return get_anexos(use_cache=use_cache, verbose=verbose, page_size=page_size,
                      max_rows=max_rows)

get_dca_ufs 

get_dca_ufs(
    an_exercicio,
    id_ente,
    no_anexo=None,
    use_cache=True,
    verbose=False,
    page_size=None,
    max_rows=INF,
)

Get Annual Accounts Declaration (DCA) data for an entity and fiscal year.

Parameters:

Name Type Description Default
an_exercicio int

Fiscal year (e.g. 2022). Required.

 required
id_ente int

IBGE code of the entity. Required.

 required
no_anexo str

Appendix name filter (e.g. "DCA-Anexo I-AB").

 None
Source code in src/tesouropy/siconfi.py 
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
def get_dca_ufs(an_exercicio, id_ente, no_anexo=None, use_cache=True, verbose=False,
            page_size=None, max_rows=INF):
    """Get Annual Accounts Declaration (DCA) data for an entity and fiscal year.

    Parameters
    ----------
    an_exercicio : int
        Fiscal year (e.g. ``2022``). Required.
    id_ente : int
        IBGE code of the entity. Required.
    no_anexo : str, optional
        Appendix name filter (e.g. ``"DCA-Anexo I-AB"``).
    """
    check_required(an_exercicio=an_exercicio, id_ente=id_ente)
    params = {
        "an_exercicio": an_exercicio,
        "id_ente": id_ente,
        "no_anexo": no_anexo,
    }
    return siconfi_fetch_all("/dca", params, use_cache=use_cache,
                             verbose=verbose, page_size=page_size,
                             max_rows=max_rows)

get_annual_accounts_ufs 

get_annual_accounts_ufs(
    fiscal_year,
    entity_id,
    appendix=None,
    use_cache=True,
    verbose=False,
    page_size=None,
    max_rows=INF,
)

English alias for :func:get_dca_ufs.

Source code in src/tesouropy/siconfi.py 
100
101
102
103
104
105
106
def get_annual_accounts_ufs(fiscal_year, entity_id, appendix=None, use_cache=True,
                        verbose=False, page_size=None, max_rows=INF):
    """English alias for :func:`get_dca_ufs`."""
    check_required(fiscal_year=fiscal_year, entity_id=entity_id)
    return get_dca_ufs(an_exercicio=fiscal_year, id_ente=entity_id,
                   no_anexo=appendix, use_cache=use_cache, verbose=verbose,
                   page_size=page_size, max_rows=max_rows)

get_dca_municipios 

get_dca_municipios(
    state_uf,
    an_exercicio,
    no_anexo=None,
    include_capital=True,
    on_error="warn",
    use_cache=True,
    verbose=False,
    page_size=None,
    max_rows=INF,
)

Get DCA data for every municipality of a Brazilian state (fault tolerant).

Failed calls are recorded on result.failed.

Source code in src/tesouropy/siconfi.py 
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
def get_dca_municipios(state_uf, an_exercicio, no_anexo=None,
                      include_capital=True, on_error="warn", use_cache=True,
                      verbose=False, page_size=None, max_rows=INF):
    """Get DCA data for every municipality of a Brazilian state (fault tolerant).

    Failed calls are recorded on ``result.failed``.
    """
    check_required(state_uf=state_uf, an_exercicio=an_exercicio)
    munis = resolve_state_munis(state_uf, include_capital=include_capital,
                                use_cache=use_cache, verbose=verbose)
    param_list = [
        {
            "an_exercicio": an_exercicio,
            "id_ente": id_ente,
            "no_anexo": no_anexo,
            "use_cache": use_cache,
            "verbose": verbose,
            "page_size": page_size,
            "max_rows": max_rows,
        }
        for id_ente in munis["cod_ibge"].to_list()
    ]
    return tnr_loop(get_dca_ufs, param_list, id_key="id_ente", on_error=on_error,
                    progress_label=f"DCA {state_uf}")

get_annual_accounts_municipalities 

get_annual_accounts_municipalities(
    state_uf,
    fiscal_year,
    appendix=None,
    include_capital=True,
    on_error="warn",
    use_cache=True,
    verbose=False,
    page_size=None,
    max_rows=INF,
)

English alias for :func:get_dca_municipios.

Source code in src/tesouropy/siconfi.py 
138
139
140
141
142
143
144
145
146
147
148
def get_annual_accounts_municipalities(state_uf, fiscal_year, appendix=None,
                                  include_capital=True, on_error="warn",
                                  use_cache=True, verbose=False, page_size=None,
                                  max_rows=INF):
    """English alias for :func:`get_dca_municipios`."""
    check_required(state_uf=state_uf, fiscal_year=fiscal_year)
    return get_dca_municipios(state_uf=state_uf, an_exercicio=fiscal_year,
                             no_anexo=appendix, include_capital=include_capital,
                             on_error=on_error, use_cache=use_cache,
                             verbose=verbose, page_size=page_size,
                             max_rows=max_rows)

get_extrato 

get_extrato(
    id_ente,
    an_referencia,
    use_cache=True,
    verbose=False,
    page_size=None,
    max_rows=INF,
)

Get the delivery status extract for an entity and reference year.

Source code in src/tesouropy/siconfi.py 
154
155
156
157
158
159
160
161
def get_extrato(id_ente, an_referencia, use_cache=True, verbose=False,
                page_size=None, max_rows=INF):
    """Get the delivery status extract for an entity and reference year."""
    check_required(id_ente=id_ente, an_referencia=an_referencia)
    params = {"id_ente": id_ente, "an_referencia": an_referencia}
    return siconfi_fetch_all("/extrato_entregas", params, use_cache=use_cache,
                             verbose=verbose, page_size=page_size,
                             max_rows=max_rows)

get_delivery_status 

get_delivery_status(
    entity_id,
    year,
    use_cache=True,
    verbose=False,
    page_size=None,
    max_rows=INF,
)

English alias for :func:get_extrato.

Source code in src/tesouropy/siconfi.py 
164
165
166
167
168
169
170
def get_delivery_status(entity_id, year, use_cache=True, verbose=False,
                        page_size=None, max_rows=INF):
    """English alias for :func:`get_extrato`."""
    check_required(entity_id=entity_id, year=year)
    return get_extrato(id_ente=entity_id, an_referencia=year,
                       use_cache=use_cache, verbose=verbose, page_size=page_size,
                       max_rows=max_rows)

get_rreo_ufs 

get_rreo_ufs(
    an_exercicio,
    nr_periodo,
    co_tipo_demonstrativo,
    no_anexo,
    id_ente,
    co_esfera=None,
    use_cache=True,
    verbose=False,
    page_size=None,
    max_rows=INF,
)

Get Budget Execution Summary Report (RREO) data.

co_esfera is optional: some entities (e.g. the Federal District constitutional fund) only return data when the sphere filter is omitted, so leave it None if a sphere-filtered call comes back empty.

Source code in src/tesouropy/siconfi.py 
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
def get_rreo_ufs(an_exercicio, nr_periodo, co_tipo_demonstrativo, no_anexo, id_ente,
             co_esfera=None, use_cache=True, verbose=False, page_size=None,
             max_rows=INF):
    """Get Budget Execution Summary Report (RREO) data.

    ``co_esfera`` is optional: some entities (e.g. the Federal District
    constitutional fund) only return data when the sphere filter is omitted, so
    leave it ``None`` if a sphere-filtered call comes back empty.
    """
    check_required(an_exercicio=an_exercicio, nr_periodo=nr_periodo,
                   co_tipo_demonstrativo=co_tipo_demonstrativo,
                   no_anexo=no_anexo, id_ente=id_ente)
    params = {
        "an_exercicio": an_exercicio,
        "nr_periodo": nr_periodo,
        "co_tipo_demonstrativo": co_tipo_demonstrativo,
        "no_anexo": no_anexo,
        "co_esfera": co_esfera,
        "id_ente": id_ente,
    }
    return siconfi_fetch_all("/rreo", params, use_cache=use_cache,
                             verbose=verbose, page_size=page_size,
                             max_rows=max_rows)

get_budget_report_ufs 

get_budget_report_ufs(
    fiscal_year,
    period,
    report_type,
    appendix,
    entity_id,
    sphere=None,
    use_cache=True,
    verbose=False,
    page_size=None,
    max_rows=INF,
)

English alias for :func:get_rreo_ufs.

Source code in src/tesouropy/siconfi.py 
201
202
203
204
205
206
207
208
209
210
211
def get_budget_report_ufs(fiscal_year, period, report_type, appendix, entity_id,
                      sphere=None, use_cache=True, verbose=False, page_size=None,
                      max_rows=INF):
    """English alias for :func:`get_rreo_ufs`."""
    check_required(fiscal_year=fiscal_year, period=period,
                   report_type=report_type, appendix=appendix,
                   entity_id=entity_id)
    return get_rreo_ufs(an_exercicio=fiscal_year, nr_periodo=period,
                    co_tipo_demonstrativo=report_type, no_anexo=appendix,
                    id_ente=entity_id, co_esfera=sphere, use_cache=use_cache,
                    verbose=verbose, page_size=page_size, max_rows=max_rows)

get_rreo_municipios 

get_rreo_municipios(
    state_uf,
    an_exercicio,
    nr_periodo,
    co_tipo_demonstrativo,
    no_anexo,
    include_capital=True,
    on_error="warn",
    use_cache=True,
    verbose=False,
    page_size=None,
    max_rows=INF,
)

Get RREO data for every municipality of a Brazilian state (fault tolerant).

Failed calls are recorded on result.failed.

Source code in src/tesouropy/siconfi.py 
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
def get_rreo_municipios(state_uf, an_exercicio, nr_periodo,
                       co_tipo_demonstrativo, no_anexo, include_capital=True,
                       on_error="warn", use_cache=True, verbose=False,
                       page_size=None, max_rows=INF):
    """Get RREO data for every municipality of a Brazilian state (fault tolerant).

    Failed calls are recorded on ``result.failed``.
    """
    check_required(state_uf=state_uf, an_exercicio=an_exercicio,
                   nr_periodo=nr_periodo,
                   co_tipo_demonstrativo=co_tipo_demonstrativo,
                   no_anexo=no_anexo)
    munis = resolve_state_munis(state_uf, include_capital=include_capital,
                                use_cache=use_cache, verbose=verbose)
    param_list = [
        {
            "an_exercicio": an_exercicio,
            "nr_periodo": nr_periodo,
            "co_tipo_demonstrativo": co_tipo_demonstrativo,
            "no_anexo": no_anexo,
            "co_esfera": "M",
            "id_ente": id_ente,
            "use_cache": use_cache,
            "verbose": verbose,
            "page_size": page_size,
            "max_rows": max_rows,
        }
        for id_ente in munis["cod_ibge"].to_list()
    ]
    return tnr_loop(get_rreo_ufs, param_list, id_key="id_ente", on_error=on_error,
                    progress_label=f"RREO {state_uf}")

get_budget_report_municipalities 

get_budget_report_municipalities(
    state_uf,
    fiscal_year,
    period,
    report_type,
    appendix,
    include_capital=True,
    on_error="warn",
    use_cache=True,
    verbose=False,
    page_size=None,
    max_rows=INF,
)

English alias for :func:get_rreo_municipios.

Source code in src/tesouropy/siconfi.py 
250
251
252
253
254
255
256
257
258
259
260
261
262
263
def get_budget_report_municipalities(state_uf, fiscal_year, period, report_type,
                                appendix, include_capital=True, on_error="warn",
                                use_cache=True, verbose=False, page_size=None,
                                max_rows=INF):
    """English alias for :func:`get_rreo_municipios`."""
    check_required(state_uf=state_uf, fiscal_year=fiscal_year, period=period,
                   report_type=report_type, appendix=appendix)
    return get_rreo_municipios(state_uf=state_uf, an_exercicio=fiscal_year,
                              nr_periodo=period,
                              co_tipo_demonstrativo=report_type,
                              no_anexo=appendix,
                              include_capital=include_capital, on_error=on_error,
                              use_cache=use_cache, verbose=verbose,
                              page_size=page_size, max_rows=max_rows)

get_rgf_ufs 

get_rgf_ufs(
    an_exercicio,
    in_periodicidade,
    nr_periodo,
    co_tipo_demonstrativo,
    no_anexo,
    co_esfera,
    co_poder,
    id_ente,
    use_cache=True,
    verbose=False,
    page_size=None,
    max_rows=INF,
)

Get Fiscal Management Report (RGF) data.

in_periodicidade is "Q" (four-monthly) or "S" (semi-annual); co_poder is the branch: "E" exec, "L" legislative, "J" judiciary, "M" public ministry, "D" public defender.

Source code in src/tesouropy/siconfi.py 
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
def get_rgf_ufs(an_exercicio, in_periodicidade, nr_periodo, co_tipo_demonstrativo,
            no_anexo, co_esfera, co_poder, id_ente, use_cache=True,
            verbose=False, page_size=None, max_rows=INF):
    """Get Fiscal Management Report (RGF) data.

    ``in_periodicidade`` is ``"Q"`` (four-monthly) or ``"S"`` (semi-annual);
    ``co_poder`` is the branch: ``"E"`` exec, ``"L"`` legislative, ``"J"``
    judiciary, ``"M"`` public ministry, ``"D"`` public defender.
    """
    check_required(an_exercicio=an_exercicio, in_periodicidade=in_periodicidade,
                   nr_periodo=nr_periodo,
                   co_tipo_demonstrativo=co_tipo_demonstrativo,
                   no_anexo=no_anexo, co_esfera=co_esfera, co_poder=co_poder,
                   id_ente=id_ente)
    params = {
        "an_exercicio": an_exercicio,
        "in_periodicidade": in_periodicidade,
        "nr_periodo": nr_periodo,
        "co_tipo_demonstrativo": co_tipo_demonstrativo,
        "no_anexo": no_anexo,
        "co_esfera": co_esfera,
        "co_poder": co_poder,
        "id_ente": id_ente,
    }
    return siconfi_fetch_all("/rgf", params, use_cache=use_cache,
                             verbose=verbose, page_size=page_size,
                             max_rows=max_rows)

get_fiscal_report_ufs 

get_fiscal_report_ufs(
    fiscal_year,
    periodicity,
    period,
    report_type,
    appendix,
    sphere,
    branch,
    entity_id,
    use_cache=True,
    verbose=False,
    page_size=None,
    max_rows=INF,
)

English alias for :func:get_rgf_ufs.

Source code in src/tesouropy/siconfi.py 
298
299
300
301
302
303
304
305
306
307
308
309
def get_fiscal_report_ufs(fiscal_year, periodicity, period, report_type, appendix,
                      sphere, branch, entity_id, use_cache=True, verbose=False,
                      page_size=None, max_rows=INF):
    """English alias for :func:`get_rgf_ufs`."""
    check_required(fiscal_year=fiscal_year, periodicity=periodicity,
                   period=period, report_type=report_type, appendix=appendix,
                   sphere=sphere, branch=branch, entity_id=entity_id)
    return get_rgf_ufs(an_exercicio=fiscal_year, in_periodicidade=periodicity,
                   nr_periodo=period, co_tipo_demonstrativo=report_type,
                   no_anexo=appendix, co_esfera=sphere, co_poder=branch,
                   id_ente=entity_id, use_cache=use_cache, verbose=verbose,
                   page_size=page_size, max_rows=max_rows)

get_rgf_municipios 

get_rgf_municipios(
    state_uf,
    an_exercicio,
    in_periodicidade,
    nr_periodo,
    co_tipo_demonstrativo,
    no_anexo,
    co_poder,
    include_capital=True,
    on_error="warn",
    use_cache=True,
    verbose=False,
    page_size=None,
    max_rows=INF,
)

Get RGF data for every municipality of a Brazilian state (fault tolerant).

Source code in src/tesouropy/siconfi.py 
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
def get_rgf_municipios(state_uf, an_exercicio, in_periodicidade, nr_periodo,
                      co_tipo_demonstrativo, no_anexo, co_poder,
                      include_capital=True, on_error="warn", use_cache=True,
                      verbose=False, page_size=None, max_rows=INF):
    """Get RGF data for every municipality of a Brazilian state (fault tolerant)."""
    check_required(state_uf=state_uf, an_exercicio=an_exercicio,
                   in_periodicidade=in_periodicidade, nr_periodo=nr_periodo,
                   co_tipo_demonstrativo=co_tipo_demonstrativo,
                   no_anexo=no_anexo, co_poder=co_poder)
    munis = resolve_state_munis(state_uf, include_capital=include_capital,
                                use_cache=use_cache, verbose=verbose)
    param_list = [
        {
            "an_exercicio": an_exercicio,
            "in_periodicidade": in_periodicidade,
            "nr_periodo": nr_periodo,
            "co_tipo_demonstrativo": co_tipo_demonstrativo,
            "no_anexo": no_anexo,
            "co_esfera": "M",
            "co_poder": co_poder,
            "id_ente": id_ente,
            "use_cache": use_cache,
            "verbose": verbose,
            "page_size": page_size,
            "max_rows": max_rows,
        }
        for id_ente in munis["cod_ibge"].to_list()
    ]
    return tnr_loop(get_rgf_ufs, param_list, id_key="id_ente", on_error=on_error,
                    progress_label=f"RGF {state_uf}")

get_fiscal_report_municipalities 

get_fiscal_report_municipalities(
    state_uf,
    fiscal_year,
    periodicity,
    period,
    report_type,
    appendix,
    branch,
    include_capital=True,
    on_error="warn",
    use_cache=True,
    verbose=False,
    page_size=None,
    max_rows=INF,
)

English alias for :func:get_rgf_municipios.

Source code in src/tesouropy/siconfi.py 
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
def get_fiscal_report_municipalities(state_uf, fiscal_year, periodicity, period,
                                report_type, appendix, branch,
                                include_capital=True, on_error="warn",
                                use_cache=True, verbose=False, page_size=None,
                                max_rows=INF):
    """English alias for :func:`get_rgf_municipios`."""
    check_required(state_uf=state_uf, fiscal_year=fiscal_year,
                   periodicity=periodicity, period=period,
                   report_type=report_type, appendix=appendix, branch=branch)
    return get_rgf_municipios(state_uf=state_uf, an_exercicio=fiscal_year,
                             in_periodicidade=periodicity, nr_periodo=period,
                             co_tipo_demonstrativo=report_type,
                             no_anexo=appendix, co_poder=branch,
                             include_capital=include_capital, on_error=on_error,
                             use_cache=use_cache, verbose=verbose,
                             page_size=page_size, max_rows=max_rows)

get_msc_controle 

get_msc_controle(
    id_ente,
    an_referencia,
    me_referencia,
    co_tipo_matriz,
    classe_conta,
    id_tv,
    use_cache=True,
    verbose=False,
    page_size=None,
    max_rows=INF,
)

Get MSC control accounts data (classes 7 and 8).

co_tipo_matriz is "MSCC" (monthly aggregate) or "MSCE" (annual closing); id_tv is "beginning_balance", "ending_balance" or "period_change".

Source code in src/tesouropy/siconfi.py 
386
387
388
389
390
391
392
393
394
395
396
397
def get_msc_controle(id_ente, an_referencia, me_referencia, co_tipo_matriz,
                     classe_conta, id_tv, use_cache=True, verbose=False,
                     page_size=None, max_rows=INF):
    """Get MSC control accounts data (classes 7 and 8).

    ``co_tipo_matriz`` is ``"MSCC"`` (monthly aggregate) or ``"MSCE"`` (annual
    closing); ``id_tv`` is ``"beginning_balance"``, ``"ending_balance"`` or
    ``"period_change"``.
    """
    return _get_msc("/msc_controle", id_ente, an_referencia, me_referencia,
                    co_tipo_matriz, classe_conta, id_tv, use_cache, verbose,
                    page_size, max_rows)

get_msc_control 

get_msc_control(
    entity_id,
    year,
    month,
    matrix_type,
    account_class,
    value_type,
    use_cache=True,
    verbose=False,
    page_size=None,
    max_rows=INF,
)

English alias for :func:get_msc_controle.

Source code in src/tesouropy/siconfi.py 
400
401
402
403
404
405
406
407
408
def get_msc_control(entity_id, year, month, matrix_type, account_class,
                    value_type, use_cache=True, verbose=False, page_size=None,
                    max_rows=INF):
    """English alias for :func:`get_msc_controle`."""
    return get_msc_controle(id_ente=entity_id, an_referencia=year,
                            me_referencia=month, co_tipo_matriz=matrix_type,
                            classe_conta=account_class, id_tv=value_type,
                            use_cache=use_cache, verbose=verbose,
                            page_size=page_size, max_rows=max_rows)

get_msc_orcamentaria 

get_msc_orcamentaria(
    id_ente,
    an_referencia,
    me_referencia,
    co_tipo_matriz,
    classe_conta,
    id_tv,
    use_cache=True,
    verbose=False,
    page_size=None,
    max_rows=INF,
)

Get MSC budgetary accounts data (classes 5 and 6).

Source code in src/tesouropy/siconfi.py 
411
412
413
414
415
416
417
def get_msc_orcamentaria(id_ente, an_referencia, me_referencia, co_tipo_matriz,
                         classe_conta, id_tv, use_cache=True, verbose=False,
                         page_size=None, max_rows=INF):
    """Get MSC budgetary accounts data (classes 5 and 6)."""
    return _get_msc("/msc_orcamentaria", id_ente, an_referencia, me_referencia,
                    co_tipo_matriz, classe_conta, id_tv, use_cache, verbose,
                    page_size, max_rows)

get_msc_budget 

get_msc_budget(
    entity_id,
    year,
    month,
    matrix_type,
    account_class,
    value_type,
    use_cache=True,
    verbose=False,
    page_size=None,
    max_rows=INF,
)

English alias for :func:get_msc_orcamentaria.

Source code in src/tesouropy/siconfi.py 
420
421
422
423
424
425
426
427
428
def get_msc_budget(entity_id, year, month, matrix_type, account_class,
                   value_type, use_cache=True, verbose=False, page_size=None,
                   max_rows=INF):
    """English alias for :func:`get_msc_orcamentaria`."""
    return get_msc_orcamentaria(id_ente=entity_id, an_referencia=year,
                                me_referencia=month, co_tipo_matriz=matrix_type,
                                classe_conta=account_class, id_tv=value_type,
                                use_cache=use_cache, verbose=verbose,
                                page_size=page_size, max_rows=max_rows)

get_msc_patrimonial 

get_msc_patrimonial(
    id_ente,
    an_referencia,
    me_referencia,
    co_tipo_matriz,
    classe_conta,
    id_tv,
    use_cache=True,
    verbose=False,
    page_size=None,
    max_rows=INF,
)

Get MSC equity/asset accounts data (classes 1 to 4).

Source code in src/tesouropy/siconfi.py 
431
432
433
434
435
436
437
def get_msc_patrimonial(id_ente, an_referencia, me_referencia, co_tipo_matriz,
                        classe_conta, id_tv, use_cache=True, verbose=False,
                        page_size=None, max_rows=INF):
    """Get MSC equity/asset accounts data (classes 1 to 4)."""
    return _get_msc("/msc_patrimonial", id_ente, an_referencia, me_referencia,
                    co_tipo_matriz, classe_conta, id_tv, use_cache, verbose,
                    page_size, max_rows)

get_msc_equity 

get_msc_equity(
    entity_id,
    year,
    month,
    matrix_type,
    account_class,
    value_type,
    use_cache=True,
    verbose=False,
    page_size=None,
    max_rows=INF,
)

English alias for :func:get_msc_patrimonial.

Source code in src/tesouropy/siconfi.py 
440
441
442
443
444
445
446
447
448
def get_msc_equity(entity_id, year, month, matrix_type, account_class,
                   value_type, use_cache=True, verbose=False, page_size=None,
                   max_rows=INF):
    """English alias for :func:`get_msc_patrimonial`."""
    return get_msc_patrimonial(id_ente=entity_id, an_referencia=year,
                               me_referencia=month, co_tipo_matriz=matrix_type,
                               classe_conta=account_class, id_tv=value_type,
                               use_cache=use_cache, verbose=verbose,
                               page_size=page_size, max_rows=max_rows)

CUSTOS

custos

CUSTOS API functions (federal government cost data).

API docs: https://apidatalake.tesouro.gov.br/docs/custos/

PERFORMANCE WARNING: the CUSTOS API is slow (server default 250 rows/page, frequent HTTP 504 timeouts). Unfiltered queries return hundreds of thousands of rows. Always filter by organizacao_n1 + organizacao_n2, ano + mes, natureza_juridica, and/or cap with max_rows.

SIORG codes are auto-padded: pass 244 or "244"; both become "000244". Use :func:tesouropy.get_siorg_orgaos / :func:tesouropy.get_siorg_estrutura to look up codes.

get_custos_pessoal_ativo 

get_custos_pessoal_ativo(
    ano=None,
    mes=None,
    natureza_juridica=None,
    organizacao_n1=None,
    organizacao_n2=None,
    organizacao_n3=None,
    use_cache=True,
    verbose=False,
    page_size=500,
    max_rows=INF,
)

Get active staff cost data. All parameters are optional filters.

natureza_juridica: 1 Public Company, 2 Public Foundation, 3 Direct Administration, 4 Autarchy, 6 Mixed Economy Company. organizacao_n* are SIORG codes (auto zero-padded to 6 digits).

Source code in src/tesouropy/custos.py 
51
52
53
54
55
56
57
58
59
60
61
62
63
def get_custos_pessoal_ativo(ano=None, mes=None, natureza_juridica=None,
                             organizacao_n1=None, organizacao_n2=None,
                             organizacao_n3=None, use_cache=True, verbose=False,
                             page_size=500, max_rows=INF):
    """Get active staff cost data. All parameters are optional filters.

    ``natureza_juridica``: ``1`` Public Company, ``2`` Public Foundation,
    ``3`` Direct Administration, ``4`` Autarchy, ``6`` Mixed Economy Company.
    ``organizacao_n*`` are SIORG codes (auto zero-padded to 6 digits).
    """
    return _custos("/pessoal_ativo", ano, mes, natureza_juridica,
                   organizacao_n1, organizacao_n2, organizacao_n3, use_cache,
                   verbose, page_size, max_rows)

get_costs_active_staff 

get_costs_active_staff(
    year=None,
    month=None,
    legal_nature=None,
    org_level1=None,
    org_level2=None,
    org_level3=None,
    use_cache=True,
    verbose=False,
    page_size=500,
    max_rows=INF,
)

English alias for :func:get_custos_pessoal_ativo.

Source code in src/tesouropy/custos.py 
66
67
68
69
70
71
72
73
74
75
76
77
def get_costs_active_staff(year=None, month=None, legal_nature=None,
                           org_level1=None, org_level2=None, org_level3=None,
                           use_cache=True, verbose=False, page_size=500,
                           max_rows=INF):
    """English alias for :func:`get_custos_pessoal_ativo`."""
    return get_custos_pessoal_ativo(ano=year, mes=month,
                                    natureza_juridica=legal_nature,
                                    organizacao_n1=org_level1,
                                    organizacao_n2=org_level2,
                                    organizacao_n3=org_level3,
                                    use_cache=use_cache, verbose=verbose,
                                    page_size=page_size, max_rows=max_rows)

get_custos_pessoal_inativo 

get_custos_pessoal_inativo(
    ano=None,
    mes=None,
    natureza_juridica=None,
    organizacao_n1=None,
    organizacao_n2=None,
    organizacao_n3=None,
    use_cache=True,
    verbose=False,
    page_size=500,
    max_rows=INF,
)

Get retired (inactive) staff cost data. All parameters are optional.

Source code in src/tesouropy/custos.py 
80
81
82
83
84
85
86
87
def get_custos_pessoal_inativo(ano=None, mes=None, natureza_juridica=None,
                               organizacao_n1=None, organizacao_n2=None,
                               organizacao_n3=None, use_cache=True,
                               verbose=False, page_size=500, max_rows=INF):
    """Get retired (inactive) staff cost data. All parameters are optional."""
    return _custos("/pessoal_inativo", ano, mes, natureza_juridica,
                   organizacao_n1, organizacao_n2, organizacao_n3, use_cache,
                   verbose, page_size, max_rows)

get_costs_retired_staff 

get_costs_retired_staff(
    year=None,
    month=None,
    legal_nature=None,
    org_level1=None,
    org_level2=None,
    org_level3=None,
    use_cache=True,
    verbose=False,
    page_size=500,
    max_rows=INF,
)

English alias for :func:get_custos_pessoal_inativo.

Source code in src/tesouropy/custos.py 
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
def get_costs_retired_staff(year=None, month=None, legal_nature=None,
                            org_level1=None, org_level2=None, org_level3=None,
                            use_cache=True, verbose=False, page_size=500,
                            max_rows=INF):
    """English alias for :func:`get_custos_pessoal_inativo`."""
    return get_custos_pessoal_inativo(ano=year, mes=month,
                                      natureza_juridica=legal_nature,
                                      organizacao_n1=org_level1,
                                      organizacao_n2=org_level2,
                                      organizacao_n3=org_level3,
                                      use_cache=use_cache, verbose=verbose,
                                      page_size=page_size, max_rows=max_rows)

get_custos_pensionistas 

get_custos_pensionistas(
    ano=None,
    mes=None,
    natureza_juridica=None,
    organizacao_n1=None,
    organizacao_n2=None,
    organizacao_n3=None,
    use_cache=True,
    verbose=False,
    page_size=500,
    max_rows=INF,
)

Get pensioner cost data. All parameters are optional filters.

Source code in src/tesouropy/custos.py 
104
105
106
107
108
109
110
111
def get_custos_pensionistas(ano=None, mes=None, natureza_juridica=None,
                            organizacao_n1=None, organizacao_n2=None,
                            organizacao_n3=None, use_cache=True, verbose=False,
                            page_size=500, max_rows=INF):
    """Get pensioner cost data. All parameters are optional filters."""
    return _custos("/pensionistas", ano, mes, natureza_juridica, organizacao_n1,
                   organizacao_n2, organizacao_n3, use_cache, verbose,
                   page_size, max_rows)

get_costs_pensioners 

get_costs_pensioners(
    year=None,
    month=None,
    legal_nature=None,
    org_level1=None,
    org_level2=None,
    org_level3=None,
    use_cache=True,
    verbose=False,
    page_size=500,
    max_rows=INF,
)

English alias for :func:get_custos_pensionistas.

Source code in src/tesouropy/custos.py 
114
115
116
117
118
119
120
121
122
123
124
125
def get_costs_pensioners(year=None, month=None, legal_nature=None,
                         org_level1=None, org_level2=None, org_level3=None,
                         use_cache=True, verbose=False, page_size=500,
                         max_rows=INF):
    """English alias for :func:`get_custos_pensionistas`."""
    return get_custos_pensionistas(ano=year, mes=month,
                                   natureza_juridica=legal_nature,
                                   organizacao_n1=org_level1,
                                   organizacao_n2=org_level2,
                                   organizacao_n3=org_level3,
                                   use_cache=use_cache, verbose=verbose,
                                   page_size=page_size, max_rows=max_rows)

get_custos_demais 

get_custos_demais(
    ano=None,
    mes=None,
    natureza_juridica=None,
    organizacao_n1=None,
    organizacao_n2=None,
    organizacao_n3=None,
    use_cache=True,
    verbose=False,
    page_size=500,
    max_rows=INF,
)

Get other (non-personnel) cost data. All parameters are optional.

Source code in src/tesouropy/custos.py 
128
129
130
131
132
133
134
135
def get_custos_demais(ano=None, mes=None, natureza_juridica=None,
                      organizacao_n1=None, organizacao_n2=None,
                      organizacao_n3=None, use_cache=True, verbose=False,
                      page_size=500, max_rows=INF):
    """Get other (non-personnel) cost data. All parameters are optional."""
    return _custos("/demais", ano, mes, natureza_juridica, organizacao_n1,
                   organizacao_n2, organizacao_n3, use_cache, verbose,
                   page_size, max_rows)

get_costs_other 

get_costs_other(
    year=None,
    month=None,
    legal_nature=None,
    org_level1=None,
    org_level2=None,
    org_level3=None,
    use_cache=True,
    verbose=False,
    page_size=500,
    max_rows=INF,
)

English alias for :func:get_custos_demais.

Source code in src/tesouropy/custos.py 
138
139
140
141
142
143
144
145
146
def get_costs_other(year=None, month=None, legal_nature=None, org_level1=None,
                    org_level2=None, org_level3=None, use_cache=True,
                    verbose=False, page_size=500, max_rows=INF):
    """English alias for :func:`get_custos_demais`."""
    return get_custos_demais(ano=year, mes=month, natureza_juridica=legal_nature,
                             organizacao_n1=org_level1, organizacao_n2=org_level2,
                             organizacao_n3=org_level3, use_cache=use_cache,
                             verbose=verbose, page_size=page_size,
                             max_rows=max_rows)

get_custos_depreciacao 

get_custos_depreciacao(
    ano=None,
    mes=None,
    natureza_juridica=None,
    organizacao_n1=None,
    organizacao_n2=None,
    organizacao_n3=None,
    use_cache=True,
    verbose=False,
    page_size=500,
    max_rows=INF,
)

Get depreciation cost data. All parameters are optional filters.

Source code in src/tesouropy/custos.py 
149
150
151
152
153
154
155
156
def get_custos_depreciacao(ano=None, mes=None, natureza_juridica=None,
                           organizacao_n1=None, organizacao_n2=None,
                           organizacao_n3=None, use_cache=True, verbose=False,
                           page_size=500, max_rows=INF):
    """Get depreciation cost data. All parameters are optional filters."""
    return _custos("/depreciacao", ano, mes, natureza_juridica, organizacao_n1,
                   organizacao_n2, organizacao_n3, use_cache, verbose,
                   page_size, max_rows)

get_costs_depreciation 

get_costs_depreciation(
    year=None,
    month=None,
    legal_nature=None,
    org_level1=None,
    org_level2=None,
    org_level3=None,
    use_cache=True,
    verbose=False,
    page_size=500,
    max_rows=INF,
)

English alias for :func:get_custos_depreciacao.

Source code in src/tesouropy/custos.py 
159
160
161
162
163
164
165
166
167
168
169
170
def get_costs_depreciation(year=None, month=None, legal_nature=None,
                           org_level1=None, org_level2=None, org_level3=None,
                           use_cache=True, verbose=False, page_size=500,
                           max_rows=INF):
    """English alias for :func:`get_custos_depreciacao`."""
    return get_custos_depreciacao(ano=year, mes=month,
                                  natureza_juridica=legal_nature,
                                  organizacao_n1=org_level1,
                                  organizacao_n2=org_level2,
                                  organizacao_n3=org_level3, use_cache=use_cache,
                                  verbose=verbose, page_size=page_size,
                                  max_rows=max_rows)

get_custos_transferencias 

get_custos_transferencias(
    ano=None,
    mes=None,
    natureza_juridica=None,
    organizacao_n1=None,
    organizacao_n2=None,
    organizacao_n3=None,
    use_cache=True,
    verbose=False,
    page_size=500,
    max_rows=INF,
)

Get transfer cost data. All parameters are optional filters.

Source code in src/tesouropy/custos.py 
173
174
175
176
177
178
179
180
def get_custos_transferencias(ano=None, mes=None, natureza_juridica=None,
                              organizacao_n1=None, organizacao_n2=None,
                              organizacao_n3=None, use_cache=True, verbose=False,
                              page_size=500, max_rows=INF):
    """Get transfer cost data. All parameters are optional filters."""
    return _custos("/transferencias", ano, mes, natureza_juridica,
                   organizacao_n1, organizacao_n2, organizacao_n3, use_cache,
                   verbose, page_size, max_rows)

get_costs_transfers 

get_costs_transfers(
    year=None,
    month=None,
    legal_nature=None,
    org_level1=None,
    org_level2=None,
    org_level3=None,
    use_cache=True,
    verbose=False,
    page_size=500,
    max_rows=INF,
)

English alias for :func:get_custos_transferencias.

Source code in src/tesouropy/custos.py 
183
184
185
186
187
188
189
190
191
192
193
194
def get_costs_transfers(year=None, month=None, legal_nature=None,
                        org_level1=None, org_level2=None, org_level3=None,
                        use_cache=True, verbose=False, page_size=500,
                        max_rows=INF):
    """English alias for :func:`get_custos_transferencias`."""
    return get_custos_transferencias(ano=year, mes=month,
                                     natureza_juridica=legal_nature,
                                     organizacao_n1=org_level1,
                                     organizacao_n2=org_level2,
                                     organizacao_n3=org_level3,
                                     use_cache=use_cache, verbose=verbose,
                                     page_size=page_size, max_rows=max_rows)

SADIPEM

sadipem

SADIPEM API functions (public debt and credit operations).

API docs: https://apidatalake.tesouro.gov.br/docs/sadipem/

Typical workflow: 1. Search PVLs with :func:get_pvl / :func:get_debt_requests. 2. Pick an id_pleito from the results. 3. Use that id_pleito in the detail functions below.

get_pvl 

get_pvl(
    uf=None,
    tipo_interessado=None,
    id_ente=None,
    use_cache=True,
    verbose=False,
    page_size=None,
    max_rows=INF,
)

Get public debt verification requests (PVL).

Use the resulting id_pleito column to query the detail functions (:func:get_pvl_tramitacao, :func:get_opc_cronograma_liberacoes, ...).

Source code in src/tesouropy/sadipem.py 
26
27
28
29
30
31
32
33
34
35
36
def get_pvl(uf=None, tipo_interessado=None, id_ente=None, use_cache=True,
            verbose=False, page_size=None, max_rows=INF):
    """Get public debt verification requests (PVL).

    Use the resulting ``id_pleito`` column to query the detail functions
    (:func:`get_pvl_tramitacao`, :func:`get_opc_cronograma_liberacoes`, ...).
    """
    params = {"uf": uf, "tipo_interessado": tipo_interessado, "id_ente": id_ente}
    return sadipem_fetch_all("/pvl", params, use_cache=use_cache,
                             verbose=verbose, page_size=page_size,
                             max_rows=max_rows)

get_debt_requests 

get_debt_requests(
    state=None,
    entity_type=None,
    entity_id=None,
    use_cache=True,
    verbose=False,
    page_size=None,
    max_rows=INF,
)

English alias for :func:get_pvl.

Source code in src/tesouropy/sadipem.py 
39
40
41
42
43
44
45
def get_debt_requests(state=None, entity_type=None, entity_id=None,
                      use_cache=True, verbose=False, page_size=None,
                      max_rows=INF):
    """English alias for :func:`get_pvl`."""
    return get_pvl(uf=state, tipo_interessado=entity_type, id_ente=entity_id,
                   use_cache=use_cache, verbose=verbose, page_size=page_size,
                   max_rows=max_rows)

get_pvl_tramitacao 

get_pvl_tramitacao(
    id_pleito,
    use_cache=True,
    verbose=False,
    page_size=None,
    max_rows=INF,
)

Get PVL processing status for approved non-credit operations.

Only returns data for PVLs with status "Deferido"; otherwise an empty DataFrame is returned.

Source code in src/tesouropy/sadipem.py 
48
49
50
51
52
53
54
55
56
57
58
59
def get_pvl_tramitacao(id_pleito, use_cache=True, verbose=False, page_size=None,
                       max_rows=INF):
    """Get PVL processing status for approved non-credit operations.

    Only returns data for PVLs with status ``"Deferido"``; otherwise an empty
    DataFrame is returned.
    """
    check_required(id_pleito=id_pleito)
    return sadipem_fetch_all("/opnc-pvl-tramitacao-deferido",
                             {"id_pleito": id_pleito}, use_cache=use_cache,
                             verbose=verbose, page_size=page_size,
                             max_rows=max_rows)

get_pvl_status 

get_pvl_status(
    request_id,
    use_cache=True,
    verbose=False,
    page_size=None,
    max_rows=INF,
)

English alias for :func:get_pvl_tramitacao.

Source code in src/tesouropy/sadipem.py 
62
63
64
65
66
67
68
def get_pvl_status(request_id, use_cache=True, verbose=False, page_size=None,
                   max_rows=INF):
    """English alias for :func:`get_pvl_tramitacao`."""
    check_required(request_id=request_id)
    return get_pvl_tramitacao(id_pleito=request_id, use_cache=use_cache,
                              verbose=verbose, page_size=page_size,
                              max_rows=max_rows)

get_opc_cronograma_liberacoes 

get_opc_cronograma_liberacoes(
    id_pleito,
    use_cache=True,
    verbose=False,
    page_size=None,
    max_rows=INF,
)

Get the credit operation release schedule for a PVL request.

Source code in src/tesouropy/sadipem.py 
71
72
73
74
75
76
77
78
def get_opc_cronograma_liberacoes(id_pleito, use_cache=True, verbose=False,
                                  page_size=None, max_rows=INF):
    """Get the credit operation release schedule for a PVL request."""
    check_required(id_pleito=id_pleito)
    return sadipem_fetch_all("/opc-cronograma-liberacoes",
                             {"id_pleito": id_pleito}, use_cache=use_cache,
                             verbose=verbose, page_size=page_size,
                             max_rows=max_rows)

get_credit_release_schedule 

get_credit_release_schedule(
    request_id,
    use_cache=True,
    verbose=False,
    page_size=None,
    max_rows=INF,
)

English alias for :func:get_opc_cronograma_liberacoes.

Source code in src/tesouropy/sadipem.py 
81
82
83
84
85
86
87
def get_credit_release_schedule(request_id, use_cache=True, verbose=False,
                                page_size=None, max_rows=INF):
    """English alias for :func:`get_opc_cronograma_liberacoes`."""
    check_required(request_id=request_id)
    return get_opc_cronograma_liberacoes(id_pleito=request_id,
                                         use_cache=use_cache, verbose=verbose,
                                         page_size=page_size, max_rows=max_rows)

get_opc_cronograma_pagamentos 

get_opc_cronograma_pagamentos(
    id_pleito,
    use_cache=True,
    verbose=False,
    page_size=None,
    max_rows=INF,
)

Get the credit operation payment schedule for a PVL request.

Source code in src/tesouropy/sadipem.py 
90
91
92
93
94
95
96
97
def get_opc_cronograma_pagamentos(id_pleito, use_cache=True, verbose=False,
                                  page_size=None, max_rows=INF):
    """Get the credit operation payment schedule for a PVL request."""
    check_required(id_pleito=id_pleito)
    return sadipem_fetch_all("/opc-cronograma-pagamentos",
                             {"id_pleito": id_pleito}, use_cache=use_cache,
                             verbose=verbose, page_size=page_size,
                             max_rows=max_rows)

get_credit_payment_schedule 

get_credit_payment_schedule(
    request_id,
    use_cache=True,
    verbose=False,
    page_size=None,
    max_rows=INF,
)

English alias for :func:get_opc_cronograma_pagamentos.

Source code in src/tesouropy/sadipem.py 
100
101
102
103
104
105
106
def get_credit_payment_schedule(request_id, use_cache=True, verbose=False,
                                page_size=None, max_rows=INF):
    """English alias for :func:`get_opc_cronograma_pagamentos`."""
    check_required(request_id=request_id)
    return get_opc_cronograma_pagamentos(id_pleito=request_id,
                                         use_cache=use_cache, verbose=verbose,
                                         page_size=page_size, max_rows=max_rows)

get_opc_taxa_cambio 

get_opc_taxa_cambio(
    id_pleito,
    use_cache=True,
    verbose=False,
    page_size=None,
    max_rows=INF,
)

Get credit operation exchange rate data for a PVL request.

Source code in src/tesouropy/sadipem.py 
109
110
111
112
113
114
115
def get_opc_taxa_cambio(id_pleito, use_cache=True, verbose=False, page_size=None,
                        max_rows=INF):
    """Get credit operation exchange rate data for a PVL request."""
    check_required(id_pleito=id_pleito)
    return sadipem_fetch_all("/opc-taxa-cambio", {"id_pleito": id_pleito},
                             use_cache=use_cache, verbose=verbose,
                             page_size=page_size, max_rows=max_rows)

get_credit_exchange_rate 

get_credit_exchange_rate(
    request_id,
    use_cache=True,
    verbose=False,
    page_size=None,
    max_rows=INF,
)

English alias for :func:get_opc_taxa_cambio.

Source code in src/tesouropy/sadipem.py 
118
119
120
121
122
123
124
def get_credit_exchange_rate(request_id, use_cache=True, verbose=False,
                             page_size=None, max_rows=INF):
    """English alias for :func:`get_opc_taxa_cambio`."""
    check_required(request_id=request_id)
    return get_opc_taxa_cambio(id_pleito=request_id, use_cache=use_cache,
                               verbose=verbose, page_size=page_size,
                               max_rows=max_rows)

get_res_cdp 

get_res_cdp(
    id_pleito,
    use_cache=True,
    verbose=False,
    page_size=None,
    max_rows=INF,
)

Get the Debt Capacity Result (CDP) for a PVL request.

Source code in src/tesouropy/sadipem.py 
127
128
129
130
131
132
133
def get_res_cdp(id_pleito, use_cache=True, verbose=False, page_size=None,
                max_rows=INF):
    """Get the Debt Capacity Result (CDP) for a PVL request."""
    check_required(id_pleito=id_pleito)
    return sadipem_fetch_all("/res-cdp", {"id_pleito": id_pleito},
                             use_cache=use_cache, verbose=verbose,
                             page_size=page_size, max_rows=max_rows)

get_debt_capacity 

get_debt_capacity(
    request_id,
    use_cache=True,
    verbose=False,
    page_size=None,
    max_rows=INF,
)

English alias for :func:get_res_cdp.

Source code in src/tesouropy/sadipem.py 
136
137
138
139
140
141
def get_debt_capacity(request_id, use_cache=True, verbose=False, page_size=None,
                      max_rows=INF):
    """English alias for :func:`get_res_cdp`."""
    check_required(request_id=request_id)
    return get_res_cdp(id_pleito=request_id, use_cache=use_cache,
                       verbose=verbose, page_size=page_size, max_rows=max_rows)

get_res_cronograma_pagamentos 

get_res_cronograma_pagamentos(
    id_pleito,
    use_cache=True,
    verbose=False,
    page_size=None,
    max_rows=INF,
)

Get the debt payment schedule result for a PVL request.

Source code in src/tesouropy/sadipem.py 
144
145
146
147
148
149
150
151
def get_res_cronograma_pagamentos(id_pleito, use_cache=True, verbose=False,
                                  page_size=None, max_rows=INF):
    """Get the debt payment schedule result for a PVL request."""
    check_required(id_pleito=id_pleito)
    return sadipem_fetch_all("/res-cronograma-pagamentos",
                             {"id_pleito": id_pleito}, use_cache=use_cache,
                             verbose=verbose, page_size=page_size,
                             max_rows=max_rows)

get_debt_payment_schedule 

get_debt_payment_schedule(
    request_id,
    use_cache=True,
    verbose=False,
    page_size=None,
    max_rows=INF,
)

English alias for :func:get_res_cronograma_pagamentos.

Source code in src/tesouropy/sadipem.py 
154
155
156
157
158
159
160
def get_debt_payment_schedule(request_id, use_cache=True, verbose=False,
                              page_size=None, max_rows=INF):
    """English alias for :func:`get_res_cronograma_pagamentos`."""
    check_required(request_id=request_id)
    return get_res_cronograma_pagamentos(id_pleito=request_id,
                                         use_cache=use_cache, verbose=verbose,
                                         page_size=page_size, max_rows=max_rows)

Transferências Constitucionais

transferencias

Transferencias Constitucionais API functions.

Docs: https://apiapex.tesouro.gov.br/aria/v1/transferencias_constitucionais/docs

IMPORTANT: all filter parameters use NUMERIC CODES from the Treasury's internal systems. These are NOT IBGE codes. Use the dictionary functions to look codes up: :func:get_tc_transferencias, :func:get_tc_estados, :func:get_tc_municipios.

Multi-value parameters accept either a colon-separated string ("1:2:3") or a Python sequence ([1, 2, 3]).

get_tc_transferencias 

get_tc_transferencias(use_cache=True, verbose=False)

Get the transfer-type dictionary (codigo, nome).

These are internal Treasury codes, not IBGE codes.

Source code in src/tesouropy/transferencias.py 
38
39
40
41
42
43
44
def get_tc_transferencias(use_cache=True, verbose=False):
    """Get the transfer-type dictionary (``codigo``, ``nome``).

    These are internal Treasury codes, not IBGE codes.
    """
    return transferencias_fetch("/transferencias", use_cache=use_cache,
                                verbose=verbose)

get_tc_transfer_types 

get_tc_transfer_types(use_cache=True, verbose=False)

English alias for :func:get_tc_transferencias.

Source code in src/tesouropy/transferencias.py 
47
48
49
def get_tc_transfer_types(use_cache=True, verbose=False):
    """English alias for :func:`get_tc_transferencias`."""
    return get_tc_transferencias(use_cache=use_cache, verbose=verbose)

get_tc_estados 

get_tc_estados(use_cache=True, verbose=False)

Get the state dictionary (codigo, nome).

These are internal Treasury codes, not IBGE codes.

Source code in src/tesouropy/transferencias.py 
52
53
54
55
56
57
def get_tc_estados(use_cache=True, verbose=False):
    """Get the state dictionary (``codigo``, ``nome``).

    These are internal Treasury codes, not IBGE codes.
    """
    return transferencias_fetch("/estados", use_cache=use_cache, verbose=verbose)

get_tc_states 

get_tc_states(use_cache=True, verbose=False)

English alias for :func:get_tc_estados.

Source code in src/tesouropy/transferencias.py 
60
61
62
def get_tc_states(use_cache=True, verbose=False):
    """English alias for :func:`get_tc_estados`."""
    return get_tc_estados(use_cache=use_cache, verbose=verbose)

get_tc_municipios 

get_tc_municipios(
    p_nome=None, p_uf=None, use_cache=True, verbose=False
)

Get the municipality dictionary.

p_uf is a Treasury state code from :func:get_tc_estados (not a UF abbreviation or IBGE code).

Source code in src/tesouropy/transferencias.py 
65
66
67
68
69
70
71
72
73
74
def get_tc_municipios(p_nome=None, p_uf=None, use_cache=True, verbose=False):
    """Get the municipality dictionary.

    ``p_uf`` is a Treasury state code from :func:`get_tc_estados` (not a UF
    abbreviation or IBGE code).
    """
    check_not_uf_abbrev(p_uf, "p_uf")
    params = {"p_nome": p_nome, "p_uf": p_uf}
    return transferencias_fetch("/municipios", params, use_cache=use_cache,
                                verbose=verbose)

get_tc_municipalities 

get_tc_municipalities(
    name=None,
    state_code=None,
    use_cache=True,
    verbose=False,
)

English alias for :func:get_tc_municipios.

Source code in src/tesouropy/transferencias.py 
77
78
79
80
81
def get_tc_municipalities(name=None, state_code=None, use_cache=True,
                          verbose=False):
    """English alias for :func:`get_tc_municipios`."""
    return get_tc_municipios(p_nome=name, p_uf=state_code, use_cache=use_cache,
                             verbose=verbose)

get_tc_por_estados 

get_tc_por_estados(
    p_estado=None,
    p_ano=None,
    p_mes=None,
    p_transferencia=None,
    p_sn_detalhar=None,
    use_cache=True,
    verbose=False,
)

Get constitutional transfers aggregated by state.

Multi-value parameters accept a sequence or a colon-separated string.

Source code in src/tesouropy/transferencias.py 
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
def get_tc_por_estados(p_estado=None, p_ano=None, p_mes=None,
                       p_transferencia=None, p_sn_detalhar=None, use_cache=True,
                       verbose=False):
    """Get constitutional transfers aggregated by state.

    Multi-value parameters accept a sequence or a colon-separated string.
    """
    check_not_uf_abbrev(p_estado, "p_estado")
    params = {
        "p_estado": collapse_param(p_estado),
        "p_ano": collapse_param(p_ano),
        "p_mes": collapse_param(p_mes),
        "p_transferencia": collapse_param(p_transferencia),
        "p_sn_detalhar": p_sn_detalhar,
    }
    return transferencias_fetch("/por_estados", params, use_cache=use_cache,
                                verbose=verbose)

get_tc_by_state 

get_tc_by_state(
    state_code=None,
    year=None,
    month=None,
    transfer_type=None,
    detailed=None,
    use_cache=True,
    verbose=False,
)

English alias for :func:get_tc_por_estados.

Source code in src/tesouropy/transferencias.py 
106
107
108
109
110
111
112
def get_tc_by_state(state_code=None, year=None, month=None, transfer_type=None,
                    detailed=None, use_cache=True, verbose=False):
    """English alias for :func:`get_tc_por_estados`."""
    return get_tc_por_estados(p_estado=state_code, p_ano=year, p_mes=month,
                              p_transferencia=transfer_type,
                              p_sn_detalhar=detailed, use_cache=use_cache,
                              verbose=verbose)

get_tc_por_estados_detalhe 

get_tc_por_estados_detalhe(
    p_estado=None,
    p_ano=None,
    p_mes=None,
    p_transferencia=None,
    use_cache=True,
    verbose=False,
)

Get detailed constitutional transfers by state.

Source code in src/tesouropy/transferencias.py 
115
116
117
118
119
120
121
122
123
124
125
126
127
def get_tc_por_estados_detalhe(p_estado=None, p_ano=None, p_mes=None,
                               p_transferencia=None, use_cache=True,
                               verbose=False):
    """Get detailed constitutional transfers by state."""
    check_not_uf_abbrev(p_estado, "p_estado")
    params = {
        "p_estado": collapse_param(p_estado),
        "p_ano": collapse_param(p_ano),
        "p_mes": collapse_param(p_mes),
        "p_transferencia": collapse_param(p_transferencia),
    }
    return transferencias_fetch("/por_estados_detalhe", params,
                                use_cache=use_cache, verbose=verbose)

get_tc_by_state_detail 

get_tc_by_state_detail(
    state_code=None,
    year=None,
    month=None,
    transfer_type=None,
    use_cache=True,
    verbose=False,
)

English alias for :func:get_tc_por_estados_detalhe.

Source code in src/tesouropy/transferencias.py 
130
131
132
133
134
135
136
def get_tc_by_state_detail(state_code=None, year=None, month=None,
                           transfer_type=None, use_cache=True, verbose=False):
    """English alias for :func:`get_tc_por_estados_detalhe`."""
    return get_tc_por_estados_detalhe(p_estado=state_code, p_ano=year,
                                      p_mes=month,
                                      p_transferencia=transfer_type,
                                      use_cache=use_cache, verbose=verbose)

get_tc_por_municipio 

get_tc_por_municipio(
    p_estado=None,
    p_municipio=None,
    p_ano=None,
    p_mes=None,
    p_transferencia=None,
    p_sn_detalhar=None,
    use_cache=True,
    verbose=False,
    page_size=1000,
    max_rows=INF,
)

Get constitutional transfers for municipalities within states.

The server-side contract changed in 2026-09: parameter names are case-sensitive lower case (p_municipio in the singular) and the response is paginated (10 rows per page by default upstream). With the old upper-case names the server ignored every filter and timed out (HTTP 504), so this function fetches every page with the names the server expects. If a page after the first fails, the rows already fetched are returned with result.partial == True.

Source code in src/tesouropy/transferencias.py 
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
def get_tc_por_municipio(p_estado=None, p_municipio=None, p_ano=None, p_mes=None,
                         p_transferencia=None, p_sn_detalhar=None, use_cache=True,
                         verbose=False, page_size=1000, max_rows=INF):
    """Get constitutional transfers for municipalities within states.

    The server-side contract changed in 2026-09: parameter names are
    case-sensitive lower case (``p_municipio`` in the singular) and the
    response is paginated (10 rows per page by default upstream). With the
    old upper-case names the server ignored every filter and timed out
    (HTTP 504), so this function fetches every page with the names the
    server expects. If a page after the first fails, the rows already
    fetched are returned with ``result.partial == True``.
    """
    check_not_uf_abbrev(p_estado, "p_estado")
    params = {
        "p_estado": collapse_param(p_estado),
        "p_municipio": collapse_param(p_municipio),
        "p_ano": collapse_param(p_ano),
        "p_mes": collapse_param(p_mes),
        "p_transferencia": collapse_param(p_transferencia),
        "p_sn_detalhar": p_sn_detalhar,
    }
    return transferencias_fetch_all("/por_estado_municipio", params,
                                    page_size=page_size, max_rows=max_rows,
                                    use_cache=use_cache, verbose=verbose)

get_tc_by_municipality 

get_tc_by_municipality(
    state_code=None,
    municipality=None,
    year=None,
    month=None,
    transfer_type=None,
    detailed=None,
    use_cache=True,
    verbose=False,
    page_size=1000,
    max_rows=INF,
)

English alias for :func:get_tc_por_municipio.

Source code in src/tesouropy/transferencias.py 
169
170
171
172
173
174
175
176
177
178
179
def get_tc_by_municipality(state_code=None, municipality=None, year=None,
                           month=None, transfer_type=None, detailed=None,
                           use_cache=True, verbose=False, page_size=1000,
                           max_rows=INF):
    """English alias for :func:`get_tc_por_municipio`."""
    return get_tc_por_municipio(p_estado=state_code, p_municipio=municipality,
                                p_ano=year, p_mes=month,
                                p_transferencia=transfer_type,
                                p_sn_detalhar=detailed, use_cache=use_cache,
                                verbose=verbose, page_size=page_size,
                                max_rows=max_rows)

get_tc_por_municipio_detalhe 

get_tc_por_municipio_detalhe(
    p_estado=None,
    p_municipio=None,
    p_ano=None,
    p_mes=None,
    p_transferencia=None,
    use_cache=True,
    verbose=False,
)

Get detailed constitutional transfers by municipality.

Unlike /por_estado_municipio, this endpoint kept its original contract: UPPERCASE parameter names, P_MUNICIPIOS in the plural and no pagination (lower-case names answer HTTP 504). It returns the three ten-day installments (va_primeiro_dec, va_segundo_dec, va_terceiro_dec) plus total.

Source code in src/tesouropy/transferencias.py 
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
def get_tc_por_municipio_detalhe(p_estado=None, p_municipio=None, p_ano=None,
                                 p_mes=None, p_transferencia=None, use_cache=True,
                                 verbose=False):
    """Get detailed constitutional transfers by municipality.

    Unlike ``/por_estado_municipio``, this endpoint kept its original
    contract: UPPERCASE parameter names, ``P_MUNICIPIOS`` in the plural and
    no pagination (lower-case names answer HTTP 504). It returns the three
    ten-day installments (``va_primeiro_dec``, ``va_segundo_dec``,
    ``va_terceiro_dec``) plus ``total``.
    """
    check_not_uf_abbrev(p_estado, "p_estado")
    params = {
        "P_ESTADO": collapse_param(p_estado),
        "P_MUNICIPIOS": collapse_param(p_municipio),
        "P_ANO": collapse_param(p_ano),
        "P_MES": collapse_param(p_mes),
        "P_TRANSFERENCIA": collapse_param(p_transferencia),
    }
    return transferencias_fetch("/por_estado_municipio_detalhe", params,
                                use_cache=use_cache, verbose=verbose)

get_tc_by_municipality_detail 

get_tc_by_municipality_detail(
    state_code=None,
    municipality=None,
    year=None,
    month=None,
    transfer_type=None,
    use_cache=True,
    verbose=False,
)

English alias for :func:get_tc_por_municipio_detalhe.

Source code in src/tesouropy/transferencias.py 
205
206
207
208
209
210
211
212
213
def get_tc_by_municipality_detail(state_code=None, municipality=None, year=None,
                                  month=None, transfer_type=None, use_cache=True,
                                  verbose=False):
    """English alias for :func:`get_tc_por_municipio_detalhe`."""
    return get_tc_por_municipio_detalhe(p_estado=state_code,
                                        p_municipio=municipality, p_ano=year,
                                        p_mes=month,
                                        p_transferencia=transfer_type,
                                        use_cache=use_cache, verbose=verbose)

SIORG

siorg

SIORG API functions (federal organizational structure).

API docs: https://api.siorg.economia.gov.br/ Base URL: https://estruturaorganizacional.dados.gov.br

SIORG codes are used as the organizacao_n1/n2/n3 parameters in the CUSTOS API. The API returns identifiers as URIs (e.g. https://.../id/unidade-organizacional/46); the numeric tail is extracted for ease of use.

get_siorg_orgaos 

get_siorg_orgaos(
    codigo_poder=None,
    codigo_esfera=None,
    use_cache=True,
    verbose=False,
)

Get federal organizations (organs and entities) from SIORG.

codigo_poder: 1 Executive, 2 Legislative, 3 Judiciary. codigo_esfera: 1 Federal, 2 State/District, 3 Municipal. Use the returned codigo_unidade as organizacao_n1 in CUSTOS.

Source code in src/tesouropy/siorg.py 
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
def get_siorg_orgaos(codigo_poder=None, codigo_esfera=None, use_cache=True,
                     verbose=False):
    """Get federal organizations (organs and entities) from SIORG.

    ``codigo_poder``: ``1`` Executive, ``2`` Legislative, ``3`` Judiciary.
    ``codigo_esfera``: ``1`` Federal, ``2`` State/District, ``3`` Municipal.
    Use the returned ``codigo_unidade`` as ``organizacao_n1`` in CUSTOS.
    """
    params = {"codigoPoder": codigo_poder, "codigoEsfera": codigo_esfera}
    body = _siorg_fetch("/doc/orgao-entidade/resumida", params,
                        use_cache=use_cache, verbose=verbose)
    result = _parse_unidades(body)
    if result.height == 0:
        log.warning("No organizations returned from SIORG.")
        return pl.DataFrame()
    log.info("Done: %s organizations.", result.height)
    return result

get_siorg_organizations 

get_siorg_organizations(
    power_code=None,
    sphere_code=None,
    use_cache=True,
    verbose=False,
)

English alias for :func:get_siorg_orgaos.

Source code in src/tesouropy/siorg.py 
106
107
108
109
110
def get_siorg_organizations(power_code=None, sphere_code=None, use_cache=True,
                            verbose=False):
    """English alias for :func:`get_siorg_orgaos`."""
    return get_siorg_orgaos(codigo_poder=power_code, codigo_esfera=sphere_code,
                            use_cache=use_cache, verbose=verbose)

get_siorg_estrutura 

get_siorg_estrutura(
    codigo_unidade,
    vinculados=None,
    use_cache=True,
    verbose=False,
)

Get the organizational structure tree for a SIORG unit (flat DataFrame).

Use the returned codes as organizacao_n2/organizacao_n3 in CUSTOS. vinculados is "SIM" or "NAO".

Source code in src/tesouropy/siorg.py 
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
def get_siorg_estrutura(codigo_unidade, vinculados=None, use_cache=True,
                        verbose=False):
    """Get the organizational structure tree for a SIORG unit (flat DataFrame).

    Use the returned codes as ``organizacao_n2``/``organizacao_n3`` in CUSTOS.
    ``vinculados`` is ``"SIM"`` or ``"NAO"``.
    """
    check_required(codigo_unidade=codigo_unidade)
    params = {
        "codigoUnidade": codigo_unidade,
        "retornarOrgaoEntidadeVinculados": vinculados,
    }
    body = _siorg_fetch("/doc/estrutura-organizacional/resumida", params,
                        use_cache=use_cache, verbose=verbose)
    result = _parse_unidades(body)
    if result.height == 0:
        log.warning("No structure returned for unit %s.", codigo_unidade)
        return pl.DataFrame()
    log.info("Done: %s units in structure.", result.height)
    return result

get_siorg_structure 

get_siorg_structure(
    unit_code,
    include_linked=None,
    use_cache=True,
    verbose=False,
)

English alias for :func:get_siorg_estrutura.

Source code in src/tesouropy/siorg.py 
135
136
137
138
139
140
141
def get_siorg_structure(unit_code, include_linked=None, use_cache=True,
                        verbose=False):
    """English alias for :func:`get_siorg_estrutura`."""
    check_required(unit_code=unit_code)
    return get_siorg_estrutura(codigo_unidade=unit_code,
                               vinculados=include_linked, use_cache=use_cache,
                               verbose=verbose)

get_siorg_unidade 

get_siorg_unidade(
    codigo_unidade, use_cache=True, verbose=False
)

Get details of a single SIORG unit by its code (single-row DataFrame).

Source code in src/tesouropy/siorg.py 
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
def get_siorg_unidade(codigo_unidade, use_cache=True, verbose=False):
    """Get details of a single SIORG unit by its code (single-row DataFrame)."""
    check_required(codigo_unidade=codigo_unidade)
    path = f"/doc/unidade-organizacional/{codigo_unidade}/resumida"
    body = _siorg_fetch(path, use_cache=use_cache, verbose=verbose)

    unidade = body.get("unidade") if isinstance(body, Mapping) else None
    if not unidade:
        log.warning("No data returned for unit %s.", codigo_unidade)
        return pl.DataFrame()

    rec = {
        k: (None if v is None else str(v))
        for k, v in unidade.items()
        if v is not None
    }
    for col in _URI_COLS:
        if col in rec:
            rec[col] = _extract_siorg_code(rec[col])
    result = pl.from_dicts([rec], infer_schema_length=None)
    result = clean_names(result)
    log.info("Done: retrieved unit %s.", codigo_unidade)
    return result

get_siorg_unit 

get_siorg_unit(unit_code, use_cache=True, verbose=False)

English alias for :func:get_siorg_unidade.

Source code in src/tesouropy/siorg.py 
169
170
171
172
173
def get_siorg_unit(unit_code, use_cache=True, verbose=False):
    """English alias for :func:`get_siorg_unidade`."""
    check_required(unit_code=unit_code)
    return get_siorg_unidade(codigo_unidade=unit_code, use_cache=use_cache,
                             verbose=verbose)

SIOPE

siope

SIOPE API functions (education spending data, FNDE/MEC).

API docs: https://www.fnde.gov.br/olinda-ide/servico/DADOS_ABERTOS_SIOPE/versao/v1/aplicacao Base URL: https://www.fnde.gov.br/olinda-ide/servico/DADOS_ABERTOS_SIOPE/versao/v1/odata

Most endpoints share three required parameters: ano / year, periodo / period (bimester 1-6) and uf / state. get_siope_remuneracao additionally requires mes / month.

All functions accept OData filter, orderby and select to narrow results server-side. Column names in those options must use the original API names (uppercase), e.g. filter="NOM_MUNI eq 'Recife'".

They also accept a convenience tipo (type in the English aliases) to filter by entity type server-side via the DS_TIPO column: pass tipo="estado" (or "uf") for the state-level row only, or tipo="municipio" for the municipalities, instead of downloading the whole UF payload. Accepts PT/EN synonyms (accent- and case-insensitive) and combines with an existing filter via and.

get_siope_dados_gerais 

get_siope_dados_gerais(
    ano,
    periodo,
    uf,
    use_cache=True,
    verbose=False,
    page_size=1000,
    max_rows=INF,
    filter=None,
    orderby=None,
    select=None,
    tipo=None,
)

Get SIOPE general data (demographics, GDP, revenues, expenses, metadata).

Source code in src/tesouropy/siope.py 
85
86
87
88
89
90
def get_siope_dados_gerais(ano, periodo, uf, use_cache=True, verbose=False,
                           page_size=1000, max_rows=INF, filter=None,
                           orderby=None, select=None, tipo=None):
    """Get SIOPE general data (demographics, GDP, revenues, expenses, metadata)."""
    return _siope("Dados_Gerais_Siope", ano, periodo, uf, use_cache, verbose,
                  page_size, max_rows, filter, orderby, select, tipo)

get_siope_general_data 

get_siope_general_data(
    year,
    period,
    state,
    use_cache=True,
    verbose=False,
    page_size=1000,
    max_rows=INF,
    filter=None,
    orderby=None,
    select=None,
    type=None,
)

English alias for :func:get_siope_dados_gerais.

Source code in src/tesouropy/siope.py 
 93
 94
 95
 96
 97
 98
 99
100
def get_siope_general_data(year, period, state, use_cache=True, verbose=False,
                           page_size=1000, max_rows=INF, filter=None,
                           orderby=None, select=None, type=None):
    """English alias for :func:`get_siope_dados_gerais`."""
    return get_siope_dados_gerais(ano=year, periodo=period, uf=state,
                                  use_cache=use_cache, verbose=verbose,
                                  page_size=page_size, max_rows=max_rows,
                                  filter=filter, orderby=orderby, select=select, tipo=type)

get_siope_responsaveis 

get_siope_responsaveis(
    ano,
    periodo,
    uf,
    use_cache=True,
    verbose=False,
    page_size=1000,
    max_rows=INF,
    filter=None,
    orderby=None,
    select=None,
    tipo=None,
)

Get SIOPE officials/responsible persons data.

Source code in src/tesouropy/siope.py 
103
104
105
106
107
108
109
def get_siope_responsaveis(ano, periodo, uf, use_cache=True, verbose=False,
                           page_size=1000, max_rows=INF, filter=None,
                           orderby=None, select=None, tipo=None):
    """Get SIOPE officials/responsible persons data."""
    return _siope("Dados_Gerais_Siope_Dados_Responsaveis", ano, periodo, uf,
                  use_cache, verbose, page_size, max_rows, filter, orderby,
                  select, tipo)

get_siope_officials 

get_siope_officials(
    year,
    period,
    state,
    use_cache=True,
    verbose=False,
    page_size=1000,
    max_rows=INF,
    filter=None,
    orderby=None,
    select=None,
    type=None,
)

English alias for :func:get_siope_responsaveis.

Source code in src/tesouropy/siope.py 
112
113
114
115
116
117
118
119
def get_siope_officials(year, period, state, use_cache=True, verbose=False,
                        page_size=1000, max_rows=INF, filter=None, orderby=None,
                        select=None, type=None):
    """English alias for :func:`get_siope_responsaveis`."""
    return get_siope_responsaveis(ano=year, periodo=period, uf=state,
                                  use_cache=use_cache, verbose=verbose,
                                  page_size=page_size, max_rows=max_rows,
                                  filter=filter, orderby=orderby, select=select, tipo=type)

get_siope_despesas 

get_siope_despesas(
    ano,
    periodo,
    uf,
    use_cache=True,
    verbose=False,
    page_size=1000,
    max_rows=INF,
    filter=None,
    orderby=None,
    select=None,
    tipo=None,
)

Get SIOPE education expenses data broken down by category.

Source code in src/tesouropy/siope.py 
122
123
124
125
126
127
def get_siope_despesas(ano, periodo, uf, use_cache=True, verbose=False,
                       page_size=1000, max_rows=INF, filter=None, orderby=None,
                       select=None, tipo=None):
    """Get SIOPE education expenses data broken down by category."""
    return _siope("Despesas_Siope", ano, periodo, uf, use_cache, verbose,
                  page_size, max_rows, filter, orderby, select, tipo)

get_siope_expenses 

get_siope_expenses(
    year,
    period,
    state,
    use_cache=True,
    verbose=False,
    page_size=1000,
    max_rows=INF,
    filter=None,
    orderby=None,
    select=None,
    type=None,
)

English alias for :func:get_siope_despesas.

Source code in src/tesouropy/siope.py 
130
131
132
133
134
135
136
137
def get_siope_expenses(year, period, state, use_cache=True, verbose=False,
                       page_size=1000, max_rows=INF, filter=None, orderby=None,
                       select=None, type=None):
    """English alias for :func:`get_siope_despesas`."""
    return get_siope_despesas(ano=year, periodo=period, uf=state,
                              use_cache=use_cache, verbose=verbose,
                              page_size=page_size, max_rows=max_rows,
                              filter=filter, orderby=orderby, select=select, tipo=type)

get_siope_despesas_funcao 

get_siope_despesas_funcao(
    ano,
    periodo,
    uf,
    use_cache=True,
    verbose=False,
    page_size=1000,
    max_rows=INF,
    filter=None,
    orderby=None,
    select=None,
    tipo=None,
)

Get SIOPE expenses broken down by government function.

Source code in src/tesouropy/siope.py 
140
141
142
143
144
145
def get_siope_despesas_funcao(ano, periodo, uf, use_cache=True, verbose=False,
                              page_size=1000, max_rows=INF, filter=None,
                              orderby=None, select=None, tipo=None):
    """Get SIOPE expenses broken down by government function."""
    return _siope("Despesas_Funcao_Educacao_Siope", ano, periodo, uf, use_cache,
                  verbose, page_size, max_rows, filter, orderby, select, tipo)

get_siope_expenses_by_function 

get_siope_expenses_by_function(
    year,
    period,
    state,
    use_cache=True,
    verbose=False,
    page_size=1000,
    max_rows=INF,
    filter=None,
    orderby=None,
    select=None,
    type=None,
)

English alias for :func:get_siope_despesas_funcao.

Source code in src/tesouropy/siope.py 
148
149
150
151
152
153
154
155
156
def get_siope_expenses_by_function(year, period, state, use_cache=True,
                                   verbose=False, page_size=1000, max_rows=INF,
                                   filter=None, orderby=None, select=None, type=None):
    """English alias for :func:`get_siope_despesas_funcao`."""
    return get_siope_despesas_funcao(ano=year, periodo=period, uf=state,
                                     use_cache=use_cache, verbose=verbose,
                                     page_size=page_size, max_rows=max_rows,
                                     filter=filter, orderby=orderby,
                                     select=select, tipo=type)

get_siope_indicadores 

get_siope_indicadores(
    ano,
    periodo,
    uf,
    use_cache=True,
    verbose=False,
    page_size=1000,
    max_rows=INF,
    filter=None,
    orderby=None,
    select=None,
    tipo=None,
)

Get SIOPE education indicators (e.g. % of revenue applied to education).

Source code in src/tesouropy/siope.py 
159
160
161
162
163
164
def get_siope_indicadores(ano, periodo, uf, use_cache=True, verbose=False,
                          page_size=1000, max_rows=INF, filter=None,
                          orderby=None, select=None, tipo=None):
    """Get SIOPE education indicators (e.g. % of revenue applied to education)."""
    return _siope("Indicadores_Siope", ano, periodo, uf, use_cache, verbose,
                  page_size, max_rows, filter, orderby, select, tipo)

get_siope_indicators 

get_siope_indicators(
    year,
    period,
    state,
    use_cache=True,
    verbose=False,
    page_size=1000,
    max_rows=INF,
    filter=None,
    orderby=None,
    select=None,
    type=None,
)

English alias for :func:get_siope_indicadores.

Source code in src/tesouropy/siope.py 
167
168
169
170
171
172
173
174
def get_siope_indicators(year, period, state, use_cache=True, verbose=False,
                         page_size=1000, max_rows=INF, filter=None, orderby=None,
                         select=None, type=None):
    """English alias for :func:`get_siope_indicadores`."""
    return get_siope_indicadores(ano=year, periodo=period, uf=state,
                                 use_cache=use_cache, verbose=verbose,
                                 page_size=page_size, max_rows=max_rows,
                                 filter=filter, orderby=orderby, select=select, tipo=type)

get_siope_info_complementares 

get_siope_info_complementares(
    ano,
    periodo,
    uf,
    use_cache=True,
    verbose=False,
    page_size=1000,
    max_rows=INF,
    filter=None,
    orderby=None,
    select=None,
    tipo=None,
)

Get SIOPE supplementary information from declarations.

Source code in src/tesouropy/siope.py 
177
178
179
180
181
182
183
def get_siope_info_complementares(ano, periodo, uf, use_cache=True,
                                  verbose=False, page_size=1000, max_rows=INF,
                                  filter=None, orderby=None, select=None, tipo=None):
    """Get SIOPE supplementary information from declarations."""
    return _siope("Informacoes_Complementares_Siope", ano, periodo, uf,
                  use_cache, verbose, page_size, max_rows, filter, orderby,
                  select, tipo)

get_siope_supplementary 

get_siope_supplementary(
    year,
    period,
    state,
    use_cache=True,
    verbose=False,
    page_size=1000,
    max_rows=INF,
    filter=None,
    orderby=None,
    select=None,
    type=None,
)

English alias for :func:get_siope_info_complementares.

Source code in src/tesouropy/siope.py 
186
187
188
189
190
191
192
193
194
def get_siope_supplementary(year, period, state, use_cache=True, verbose=False,
                            page_size=1000, max_rows=INF, filter=None,
                            orderby=None, select=None, type=None):
    """English alias for :func:`get_siope_info_complementares`."""
    return get_siope_info_complementares(ano=year, periodo=period, uf=state,
                                         use_cache=use_cache, verbose=verbose,
                                         page_size=page_size, max_rows=max_rows,
                                         filter=filter, orderby=orderby,
                                         select=select, tipo=type)

get_siope_receitas 

get_siope_receitas(
    ano,
    periodo,
    uf,
    use_cache=True,
    verbose=False,
    page_size=1000,
    max_rows=INF,
    filter=None,
    orderby=None,
    select=None,
    tipo=None,
)

Get SIOPE education revenue data (tax revenues, transfers, FUNDEB).

Source code in src/tesouropy/siope.py 
197
198
199
200
201
202
def get_siope_receitas(ano, periodo, uf, use_cache=True, verbose=False,
                       page_size=1000, max_rows=INF, filter=None, orderby=None,
                       select=None, tipo=None):
    """Get SIOPE education revenue data (tax revenues, transfers, FUNDEB)."""
    return _siope("Receita_Siope", ano, periodo, uf, use_cache, verbose,
                  page_size, max_rows, filter, orderby, select, tipo)

get_siope_revenues 

get_siope_revenues(
    year,
    period,
    state,
    use_cache=True,
    verbose=False,
    page_size=1000,
    max_rows=INF,
    filter=None,
    orderby=None,
    select=None,
    type=None,
)

English alias for :func:get_siope_receitas.

Source code in src/tesouropy/siope.py 
205
206
207
208
209
210
211
212
def get_siope_revenues(year, period, state, use_cache=True, verbose=False,
                       page_size=1000, max_rows=INF, filter=None, orderby=None,
                       select=None, type=None):
    """English alias for :func:`get_siope_receitas`."""
    return get_siope_receitas(ano=year, periodo=period, uf=state,
                              use_cache=use_cache, verbose=verbose,
                              page_size=page_size, max_rows=max_rows,
                              filter=filter, orderby=orderby, select=select, tipo=type)

get_siope_remuneracao 

get_siope_remuneracao(
    ano,
    periodo,
    mes,
    uf,
    use_cache=True,
    verbose=False,
    page_size=1000,
    max_rows=INF,
    filter=None,
    orderby=None,
    select=None,
    tipo=None,
)

Get SIOPE staff compensation data. Requires an extra mes (month).

Source code in src/tesouropy/siope.py 
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
def get_siope_remuneracao(ano, periodo, mes, uf, use_cache=True, verbose=False,
                          page_size=1000, max_rows=INF, filter=None,
                          orderby=None, select=None, tipo=None):
    """Get SIOPE staff compensation data. Requires an extra ``mes`` (month)."""
    check_required(ano=ano, periodo=periodo, mes=mes, uf=uf)
    params = {
        "Ano_Declaracao": ano,
        "Num_Peri": periodo,
        "Mes_Exercicio": mes,
        "Sig_UF": uf,
    }
    filter = _siope_tipo_filter(tipo, filter)
    return siope_fetch("Remuneracao_Siope", params, use_cache=use_cache,
                       verbose=verbose, page_size=page_size, max_rows=max_rows,
                       filter=filter, orderby=orderby, select=select)

get_siope_compensation 

get_siope_compensation(
    year,
    period,
    month,
    state,
    use_cache=True,
    verbose=False,
    page_size=1000,
    max_rows=INF,
    filter=None,
    orderby=None,
    select=None,
    type=None,
)

English alias for :func:get_siope_remuneracao.

Source code in src/tesouropy/siope.py 
232
233
234
235
236
237
238
239
def get_siope_compensation(year, period, month, state, use_cache=True,
                           verbose=False, page_size=1000, max_rows=INF,
                           filter=None, orderby=None, select=None, type=None):
    """English alias for :func:`get_siope_remuneracao`."""
    return get_siope_remuneracao(ano=year, periodo=period, mes=month, uf=state,
                                 use_cache=use_cache, verbose=verbose,
                                 page_size=page_size, max_rows=max_rows,
                                 filter=filter, orderby=orderby, select=select, tipo=type)

RREO tidy layer

rreo_tidy

RREO tidy layer — handles SICONFI's drifting labels across years.

SICONFI's RREO appendix names, account labels, and column suffixes drift across fiscal years. The package ships a small reference table (data/rreo_layout.csv) mapping (topic, regime, year_range) to the correct appendix and account-matching key, and uses it to assemble layout-stable indicators across years.

rreo_layout 

rreo_layout() -> pl.DataFrame

Return the bundled RREO layout reference table.

Columns: topic, regime, first_year, last_year, co_esfera, no_anexo, conta_match, cod_conta_match, indicador. Each rule matches either on a cleaned account label (conta_match) or on SICONFI's stable semantic account code (cod_conta_match); exactly one of the two is non-empty per row.

Source code in src/tesouropy/rreo_tidy.py 
59
60
61
62
63
64
65
66
67
68
def rreo_layout() -> pl.DataFrame:
    """Return the bundled RREO layout reference table.

    Columns: ``topic``, ``regime``, ``first_year``, ``last_year``,
    ``co_esfera``, ``no_anexo``, ``conta_match``, ``cod_conta_match``,
    ``indicador``. Each rule matches either on a cleaned account label
    (``conta_match``) or on SICONFI's stable semantic account code
    (``cod_conta_match``); exactly one of the two is non-empty per row.
    """
    return _load_rreo_layout()

rreo_normalize_columns 

rreo_normalize_columns(data: DataFrame) -> pl.DataFrame

Normalize the coluna field of an RREO DataFrame across years.

Appends two columns:

  • coluna_padrao: the column label with any trailing / YYYY or EM YYYY suffix removed (whitespace squished).
  • coluna_ano: the year that appeared in the suffix (Int64), or null when no year was present.
Source code in src/tesouropy/rreo_tidy.py 
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
def rreo_normalize_columns(data: pl.DataFrame) -> pl.DataFrame:
    """Normalize the ``coluna`` field of an RREO DataFrame across years.

    Appends two columns:

    * ``coluna_padrao``: the column label with any trailing ``/ YYYY`` or
      ``EM YYYY`` suffix removed (whitespace squished).
    * ``coluna_ano``: the year that appeared in the suffix (Int64), or null when
      no year was present.
    """
    if "coluna" not in data.columns:
        raise TesouroError("Input must have a `coluna` column.")

    colunas = data["coluna"].to_list()
    anos: list[int | None] = []
    padroes: list[str] = []
    for value in colunas:
        value = value if value is not None else ""
        if _YEAR_SUFFIX_RE.search(value):
            match = _TRAILING_YEAR_RE.search(value)
            anos.append(int(match.group(1)) if match else None)
        else:
            anos.append(None)
        padrao = _YEAR_SUFFIX_RE.sub("", value)
        padroes.append(re.sub(r"\s+", " ", padrao).strip())

    return data.with_columns(
        pl.Series("coluna_padrao", padroes),
        pl.Series("coluna_ano", anos, dtype=pl.Int64),
    )

tidy_rreo 

tidy_rreo(
    data: DataFrame, topic: str, regime=None
) -> pl.DataFrame

Tidy an RREO DataFrame by topic, reconciling layout drift across years.

Filters data (typically from :func:tesouropy.get_rreo_ufs) to the rows matching a known indicator for topic (and optionally regime), using the rules in :func:rreo_layout. Accounts are matched on a year-stable, accent-folded key — or, where the free-text label is ambiguous, on SICONFI's stable semantic account code (cod_conta) — so the same call returns a coherent series across years even when SICONFI relabelled the appendix or account.

Currently supported topics:

  • "previdencia" — federal RGPS / RPPS civis / FCDF / militares inativos (União sphere, Anexos 04.x).
  • "rcl" — Receita Corrente Líquida (Anexo 03), all spheres; regimes "total" (2015+) plus "ajustada_endividamento" and "ajustada_pessoal" (states/municipalities, 2020+).
  • "balanco" — Balanço Orçamentário (Anexo 01), all spheres, 2015+, matched on cod_conta: revenue/expenditure subtotals, current and capital categories, superávit and déficit.
  • "resultado" — primary and nominal results (Anexo 06) across the three label eras (2015-2017, 2018-2022, 2023+), matched on cod_conta, including the 2023+ com/sem RPPS split for states and municipalities. The nominal series starts in 2018.

When data carries an anexo column (the raw SICONFI output always does), rows only match the rule for their own appendix — Anexo 14 repeats accounts from other appendices under identical labels. Topics matched on cod_conta require that column in the input.

Source code in src/tesouropy/rreo_tidy.py 
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
154
155
156
157
158
159
160
161
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
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
def tidy_rreo(data: pl.DataFrame, topic: str, regime=None) -> pl.DataFrame:
    """Tidy an RREO DataFrame by topic, reconciling layout drift across years.

    Filters ``data`` (typically from :func:`tesouropy.get_rreo_ufs`) to the rows
    matching a known indicator for ``topic`` (and optionally ``regime``), using
    the rules in :func:`rreo_layout`. Accounts are matched on a year-stable,
    accent-folded key — or, where the free-text label is ambiguous, on
    SICONFI's stable semantic account code (``cod_conta``) — so the same call
    returns a coherent series across years even when SICONFI relabelled the
    appendix or account.

    Currently supported topics:

    * ``"previdencia"`` — federal RGPS / RPPS civis / FCDF / militares
      inativos (União sphere, Anexos 04.x).
    * ``"rcl"`` — Receita Corrente Líquida (Anexo 03), all spheres; regimes
      ``"total"`` (2015+) plus ``"ajustada_endividamento"`` and
      ``"ajustada_pessoal"`` (states/municipalities, 2020+).
    * ``"balanco"`` — Balanço Orçamentário (Anexo 01), all spheres, 2015+,
      matched on ``cod_conta``: revenue/expenditure subtotals, current and
      capital categories, superávit and déficit.
    * ``"resultado"`` — primary and nominal results (Anexo 06) across the
      three label eras (2015-2017, 2018-2022, 2023+), matched on
      ``cod_conta``, including the 2023+ com/sem RPPS split for states and
      municipalities. The nominal series starts in 2018.

    When ``data`` carries an ``anexo`` column (the raw SICONFI output always
    does), rows only match the rule for their own appendix — Anexo 14
    repeats accounts from other appendices under identical labels. Topics
    matched on ``cod_conta`` require that column in the input.
    """
    required = ("exercicio", "conta", "coluna", "valor")
    missing = [c for c in required if c not in data.columns]
    if missing:
        raise TesouroError(
            f"Input is missing required column(s): {', '.join(missing)}. "
            "Did you pass the raw output of get_rreo_ufs()?"
        )

    layout = _load_rreo_layout().filter(pl.col("topic") == topic)
    if regime is not None:
        regimes = [regime] if isinstance(regime, str) else list(regime)
        layout = layout.filter(pl.col("regime").is_in(regimes))
    if layout.height == 0:
        extra = "" if regime is None else f", regime={regime}"
        raise TesouroError(
            f"No layout entry for topic={topic!r}{extra}. Run rreo_layout() to "
            "inspect supported topics/regimes."
        )

    uses_cod = layout["cod_conta_match"].str.len_chars().gt(0).any()
    if uses_cod and "cod_conta" not in data.columns:
        raise TesouroError(
            f"Topic {topic!r} matches on cod_conta, but the input has no such "
            "column. Pass the raw output of get_rreo_ufs(), which carries it."
        )

    data = rreo_normalize_columns(data)
    data = data.with_columns(
        pl.col("conta")
        .map_elements(_clean_conta, return_dtype=pl.Utf8)
        .alias("_match_key"),
        pl.col("exercicio").cast(pl.Int64, strict=False).alias("_exercicio"),
    )
    has_anexo = "anexo" in data.columns

    matched = []
    for rule in layout.iter_rows(named=True):
        pick = (
            pl.col("_exercicio").is_not_null()
            & (pl.col("_exercicio") >= rule["first_year"])
            & (pl.col("_exercicio") <= rule["last_year"])
        )
        if rule["cod_conta_match"]:
            pick = pick & (pl.col("cod_conta") == rule["cod_conta_match"])
        else:
            pick = pick & (pl.col("_match_key") == rule["conta_match"])
        if has_anexo:
            # Anexo 14 repeats accounts from other appendices, same labels
            pick = pick & (pl.col("anexo") == rule["no_anexo"])
        rows = data.filter(pick)
        if rows.height:
            rows = rows.with_columns(
                pl.lit(rule["indicador"]).alias("indicador"),
                pl.lit(rule["regime"]).alias("regime"),
            )
            matched.append(rows)

    if not matched:
        # warn-and-return-empty, mirroring the R behaviour
        import logging

        logging.getLogger("tesouropy").warning(
            "No rows matched topic=%r in the supplied data.", topic
        )
        return pl.DataFrame()

    result = pl.concat(matched, how="diagonal_relaxed").drop(
        "_match_key", "_exercicio"
    )

    lead = ["indicador", "regime"]
    for col in ("exercicio", "instituicao", "cod_ibge", "uf"):
        if col in result.columns:
            lead.append(col)
    rest = [c for c in result.columns if c not in lead]
    return result.select(lead + rest)

Deprecated names

Renamed in 0.2.0; these still work but emit a DeprecationWarning and forward to the new names. See the SICONFI section above for the replacements.

deprecated

Deprecated function names.

In 0.2.0 the SICONFI report getters were renamed to make their scope explicit: the single-entity getters gained the _ufs suffix and the state-wide sweeps (every municipality of a UF) moved from _for_state to _municipios / _municipalities. The old names below still work but emit a :class:DeprecationWarning and forward to the new names. They are kept for at least one release cycle for backward compatibility.