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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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,
)

Get constitutional transfers for municipalities within states.

Note: this endpoint expects UPPERCASE parameter names upstream; the conversion is handled internally.

Source code in src/tesouropy/transferencias.py

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):
    """Get constitutional transfers for municipalities within states.

    Note: this endpoint expects UPPERCASE parameter names upstream; the
    conversion is handled internally.
    """
    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),
        "P_SN_DETALHAR": p_sn_detalhar,
    }
    return transferencias_fetch("/por_estado_municipio", params,
                                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,
)

English alias for :func:get_tc_por_municipio.

Source code in src/tesouropy/transferencias.py

def get_tc_by_municipality(state_code=None, municipality=None, year=None,
                           month=None, transfer_type=None, detailed=None,
                           use_cache=True, verbose=False):
    """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)

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.

Source code in src/tesouropy/transferencias.py

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."""
    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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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, indicador.

Source code in src/tesouropy/rreo_tidy.py

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``, ``indicador``.
    """
    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

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, 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).

Source code in src/tesouropy/rreo_tidy.py

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, 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).
    """
    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."
        )

    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"),
    )

    matched = []
    for rule in layout.iter_rows(named=True):
        rows = data.filter(
            pl.col("_exercicio").is_not_null()
            & (pl.col("_exercicio") >= rule["first_year"])
            & (pl.col("_exercicio") <= rule["last_year"])
            & (pl.col("_match_key") == rule["conta_match"])
        )
        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.