Reference

Queries

transferegovpy.get(module, table, *, select=None, order=None, limit=MAX_PAGE, offset=0, page_size=MAX_PAGE, params=None, progress=None, cache=None, base_url=None, filters=None, **kwargs)

Retrieve rows from a TransfereGov table.

Parameters:

Name	Type	Description	Default
module	str	"transferenciasespeciais", "fundoafundo" or "ted". Aliases such as "fundo_a_fundo" are accepted.	required
table	str	A table name from :func:~transferegovpy.tables.	required
select	Sequence[str] | None	Columns to return. None returns every column. Selecting fewer columns makes large queries markedly faster.	None
order	Sequence[str] | str | None	Sort order, as column names optionally suffixed with .asc or .desc. None uses the table's primary key where the API declares one, and its identifier columns otherwise.	None
limit	float	Maximum number of rows to return. math.inf for every matching row. Counts rows, not requests: anything above 1000 is collected page by page.	MAX_PAGE
offset	int	Rows to skip before the first one returned.	0
page_size	int	Rows per request, between 1 and 1000.	MAX_PAGE
params	dict | None	Extra query parameters passed to the API verbatim, the escape hatch for 'PostgREST' features this package does not model.	None
progress	bool | None	Show a progress bar while collecting pages. None shows one when more than one page is needed and the session is interactive.	None
cache	bool | None	Serve the request from the response cache. None follows :func:~transferegovpy.cache_enabled.	None
base_url	str | None	The API base URL.	None
filters	dict | None	Filters as a mapping, for columns whose names collide with the keyword arguments above.	None
**kwargs	Any	Filters, named after the columns they apply to.	{}

Returns:

Type	Description
DataFrame	Typed from the API's own schema. :func:metadata reports the totals the API gave and how many pages were fetched.

Examples:

>>> get("ted", "plano_acao", aa_ano_plano_acao=gte(2024), limit=50)

transferegovpy.count(module, table, *, params=None, cache=None, base_url=None, filters=None, **kwargs)

Count the rows a query matches, without retrieving them.

Worth doing before a large :func:get: the biggest table in these APIs holds over a million rows, which is more than a thousand requests.

transferegovpy.ted(table, **kwargs)

Query the decentralized credit module.

transferegovpy.fundo_a_fundo(table, **kwargs)

Query the fund-to-fund module.

transferegovpy.transferencias_especiais(table, **kwargs)

Query the special transfers module.

transferegovpy.metadata

Discovery: what the APIs publish, without making a request.

modules()

List the TransfereGov API modules.

Returns:

Type	Description
DataFrame	One row per module: its name, the label used in this documentation, the number of tables it publishes, and its API base URL.

tables(module=None, counts=False)

List the tables a module publishes.

Parameters:

Name	Type	Description	Default
module	str | None	A module name from :func:modules. Aliases such as "fundo_a_fundo" are accepted. None lists the tables of every module.	None
counts	bool	Add a rows column with the number of rows each table currently holds. This is the only part of this function that needs a network connection: it makes one request per table, so tables(counts=True) with no module makes forty-eight. Responses are cached.	False

Returns:

Type	Description
DataFrame	One row per table: its module, name, number of columns, the primary key when the API declares one, and the description published in the schema.

fields(module, table)

List the columns of a table.

Every column name may be used as a filter in :func:~transferegovpy.get and :func:~transferegovpy.count, in select, and in order. Column names and categorical values stay in Portuguese because they are the API's own contract.

Returns:

Type	Description
DataFrame	One row per column: its name, the pandas dtype the package coerces it to, the Postgres type the API reports, whether it is part of the declared primary key, and its description.

schema_date()

When the packaged schema was taken from the APIs.

The package validates filters and types columns against a copy of the APIs' OpenAPI documents taken on this date. A column added upstream since then is still returned, but is typed by inspection rather than from the schema.

Discovery

transferegovpy.modules()

List the TransfereGov API modules.

Returns:

Type	Description
DataFrame	One row per module: its name, the label used in this documentation, the number of tables it publishes, and its API base URL.

transferegovpy.tables(module=None, counts=False)

List the tables a module publishes.

Parameters:

Name	Type	Description	Default
module	str | None	A module name from :func:modules. Aliases such as "fundo_a_fundo" are accepted. None lists the tables of every module.	None
counts	bool	Add a rows column with the number of rows each table currently holds. This is the only part of this function that needs a network connection: it makes one request per table, so tables(counts=True) with no module makes forty-eight. Responses are cached.	False

Returns:

Type	Description
DataFrame	One row per table: its module, name, number of columns, the primary key when the API declares one, and the description published in the schema.

transferegovpy.fields(module, table)

List the columns of a table.

Every column name may be used as a filter in :func:~transferegovpy.get and :func:~transferegovpy.count, in select, and in order. Column names and categorical values stay in Portuguese because they are the API's own contract.

Returns:

Type	Description
DataFrame	One row per column: its name, the pandas dtype the package coerces it to, the Postgres type the API reports, whether it is part of the declared primary key, and its description.

transferegovpy.schema_date()

When the packaged schema was taken from the APIs.

The package validates filters and types columns against a copy of the APIs' OpenAPI documents taken on this date. A column added upstream since then is still returned, but is typed by inspection rather than from the schema.

Filters

transferegovpy.filters

Comparison operators for the 'PostgREST' services behind the TransfereGov APIs.

A filter is a query parameter whose name is the column and whose value is operator.operand. These builders produce that value while keeping the escaping rules in one place.

Pass them as keyword arguments to :func:~transferegovpy.get and :func:~transferegovpy.count, where the keyword is the column being filtered::

get("ted", "plano_acao", aa_ano_plano_acao=gte(2024))

A bare value is shorthand for :func:eq, and a bare list or tuple is shorthand for :func:in_. Pass a list of operators to apply several conditions to the same column, which the API combines with AND::

get("ted", "plano_acao",
    dt_inicio_vigencia=[gte("2024-01-01"), lt("2025-01-01")])

eq(value)

Equals.

neq(value)

Does not equal.

gt(value)

Greater than.

gte(value)

Greater than or equal to.

lt(value)

Less than.

lte(value)

Less than or equal to.

like(pattern)

Matches a pattern, case sensitive. The wildcard is * or %.

ilike(pattern)

Matches a pattern, case insensitive. The wildcard is * or %.

re_match(pattern)

Matches a POSIX regular expression, case sensitive.

re_imatch(pattern)

Matches a POSIX regular expression, case insensitive.

in_(values)

Is one of values.

is_null()

Is null.

is_true()

Is true.

is_false()

Is false.

not_(filter_)

Negates another operator.

operators()

List the available filter operators.

Returns:

Type	Description
DataFrame	The exported operator, the 'PostgREST' operator it sends, and what it means.

Configuration

transferegovpy.configure(**options)

Set connection options for the session, or read them back.

transferegovpy.cache_dir(path=None)

Where cached responses are stored.

Called with no argument, reports the directory in use. Called with a path, switches to it for the rest of the session and creates it.

By default responses are cached in the session's temporary directory, so they are discarded when the process exits. To keep them between sessions, pass a persistent path or set TRANSFEREGOVPY_CACHE_DIR.

transferegovpy.cache_clear()

Delete cached responses. Returns how many files were removed.

Errors

transferegovpy._errors

Exceptions raised by transferegovpy.

Every error the package raises inherits from :class:TransferegovError, so a caller can catch the whole family with one except. The subclasses exist so that a caller can tell a bad query from a bad connection without parsing messages.

TransferegovError

Bases: Exception

Base class for every error this package raises.

SchemaError

Bases: TransferegovError

An unknown module, table or column.

FilterError

Bases: TransferegovError

A filter that cannot be turned into a query parameter.

URLTooLongError

Bases: TransferegovError

A request URL beyond what the service accepts.

Usually a filter built with :func:~transferegovpy.in_ over a long vector.

ResponseError

Bases: TransferegovError

A response the package cannot make sense of.

HTTPError

Bases: TransferegovError

A non-success HTTP status.

Attributes:

Name	Type	Description
status		The HTTP status code.
detail		The message, details and hint fields of the PostgREST error body, when it sent one.

IncompleteResultWarning

Bases: UserWarning

Fewer rows were collected than the API reported as matching.

ColumnTypeWarning

Bases: UserWarning

A column could not be coerced to the type the schema declares.