API pública¶

Esta página diz o que o agrobr garante entre versões. O que está listado aqui segue o SemVer: nome, parâmetros, tipo de retorno e exceções só quebram em versão major, com a mudança no CHANGELOG e no guia de migração. O resto do pacote é interno e pode mudar em qualquer versão, inclusive minor ou patch. Quem usa um nome interno deve fixar a versão do agrobr.

A regra é uma só: o que a documentação ensina a importar é público, e esta página nomeia cada caso.

Raiz do pacote¶

Os nomes do agrobr.__all__:

os módulos das fontes, datasets, contracts e deterministic;
as exceções AgrobrError, CacheMigrationError, ContractViolationError, InvalidParameterError, ParseError, ResourceLimitError, SnapshotError, SourceUnavailableError e UnknownNameError;
MetaInfo e __version__.

Fontes¶

Tudo o que está no __all__ do módulo da fonte. O caminho público é o do módulo (agrobr.<fonte> ou agrobr.alt.<fonte>); os submódulos e subpacotes dentro de uma fonte (client, parser, models, parsers, cache, agrobr.conab.progresso, agrobr.incra.andamento...) são internos, mesmo quando expõem a mesma função.

Módulo	Página
`agrobr.abiove`	ABIOVE
`agrobr.acervo_fundiario`	Acervo Fundiário
`agrobr.alt.anp_diesel`	ANP Diesel
`agrobr.alt.antt_pedagio`	ANTT Pedágio
`agrobr.alt.mapa_psr`	MAPA PSR
`agrobr.alt.sicar`	SICAR
`agrobr.ana`	ANA
`agrobr.anda`	ANDA
`agrobr.anec`	ANEC
`agrobr.antaq`	ANTAQ
`agrobr.b3`	B3
`agrobr.bcb`	BCB e séries econômicas
`agrobr.bruto`	Coleta bruta: arquivos e páginas originais com manifesto
`agrobr.cepea`	CEPEA
`agrobr.cftc`	CFTC
`agrobr.cnuc`	CNUC
`agrobr.comexstat`	ComexStat
`agrobr.comtrade`	UN Comtrade
`agrobr.conab`	CONAB, progresso e CEASA
`agrobr.defensivos`	Defensivos
`agrobr.deral`	DERAL
`agrobr.desmatamento`	Desmatamento
`agrobr.embrapa_solos`	Embrapa Solos
`agrobr.funai`	FUNAI
`agrobr.ibama`	IBAMA
`agrobr.ibge`	IBGE
`agrobr.icmbio`	ICMBio
`agrobr.imea`	IMEA
`agrobr.incra`	INCRA
`agrobr.inmet`	INMET
`agrobr.lista_suja`	Lista Suja
`agrobr.mapbiomas`	MapBiomas
`agrobr.mapbiomas_alerta`	MapBiomas Alerta
`agrobr.nasa_power`	NASA POWER
`agrobr.noticias_agricolas`	Notícias Agrícolas
`agrobr.queimadas`	Queimadas
`agrobr.rio_verde`	Fundação Rio Verde
`agrobr.rnc`	RNC
`agrobr.sfb`	SFB
`agrobr.unica`	UNICA
`agrobr.usda`	USDA
`agrobr.zarc`	ZARC

agrobr.alt é o espaço dos 4 módulos alt.

Datasets, contratos, exceções e normalização¶

Módulo	O que é público
`agrobr.datasets`	o `__all__`: os datasets (visão geral) e o catálogo (`list_datasets`, `list_products`, `info`, `describe`, `describe_all`, `get_dataset`), `deterministic`, `is_deterministic` e `get_snapshot`
`agrobr.contracts`	o `__all__`: `get_contract`, `list_contracts`, `has_contract`, `validate_dataset`, `register_contract`, `generate_json_schemas`, `Contract`, `Column`, `ColumnType` e `BreakingChangePolicy`
`agrobr.exceptions`	o `__all__`: as exceções da raiz e `FingerprintMismatchError`, `NetworkError`, `ValidationError`, `SourceFallbackWarning` e `StaleDataWarning`
`agrobr.models`	`MetaInfo` e `Fingerprint`
`agrobr.normalize`	o `__all__` (normalização)

O caminho público de um contrato é o nome registrado: contracts.get_contract("<nome>"). As constantes que a documentação ensina a importar também são públicas: BCB_FOCUS_V2 (agrobr.contracts.bcb_focus), BCB_PTAX_V2 e BCB_PTAX_MOEDAS_V1 (agrobr.contracts.bcb_ptax), BCB_SGS_V3 (agrobr.contracts.bcb_sgs), CLIMA_V3 (agrobr.contracts.clima), COMERCIO_INTERNACIONAL_V3 (agrobr.contracts.comtrade), CONAB_CUSTOS_V3 (agrobr.contracts.conab_custos), LISTA_SUJA_EMPREGADORES_V2 (agrobr.contracts.lista_suja) e POSICIONAMENTO_FUNDOS_COLUNAS_V2 (agrobr.contracts.datasets). As demais constantes *_V<n> citadas nas páginas de contrato identificam a versão; leia o contrato pelo get_contract. As constantes históricas que o guia de migração cita não são públicas; as que mudaram de nome (como agrobr.contracts.datasets.CLIMA_V2) emitem DeprecationWarning.

Síncrono, snapshots e configuração¶

Nome	O que é público	Página
`agrobr.sync`	o espelho síncrono de toda função pública das fontes e de `datasets` (`agrobr.sync.<fonte>.<função>`, `agrobr.sync.alt.<fonte>.<função>`)	Async
`agrobr.snapshots`	o `__all__`: `create_snapshot`, `list_snapshots`, `get_snapshot`, `load_from_snapshot`, `delete_snapshot`, `SnapshotInfo` e `SnapshotManifest`	Snapshots
`agrobr.config`	`set_mode`, `get_config` e `reset_config`	Snapshots
`deterministic_decorator`	o decorator, importado de `agrobr.datasets.deterministic`	Reprodutibilidade

Outros nomes ensinados na documentação¶

Fora dos módulos acima, só estes:

agrobr.http.get_timeout (resiliência);
agrobr.validators.sanity.PRICE_RULES (resiliência);
agrobr.defensivos.cache.invalidate (defensivos);
agrobr.normalize.dates.converter_datas (normalização);
agrobr.normalize.dates.normalizar_safra, o mesmo objeto de normalize.normalizar_safra (guia de migração).

CLI e variáveis de ambiente¶

Os comandos e as opções da CLI são públicos, e o código de saída também. As variáveis de ambiente são públicas, menos as AGROBR_ALERT_*.

Interno¶

Sem garantia de SemVer:

agrobr.alerts, agrobr.benchmark, agrobr.cache, agrobr.health, agrobr.utils e agrobr.constants;
agrobr.http, agrobr.validators, agrobr.models e agrobr.config, menos os nomes listados acima;
os submódulos das fontes, de agrobr.normalize, de agrobr.contracts e de agrobr.datasets, menos os nomes listados acima;
todo nome que começa com _.

Nomes internos aparecem no __all__ de alguns pacotes e às vezes em exemplos de páginas avançadas, para diagnóstico. Use à vontade, mas fixe a versão: eles podem mudar sem aviso de depreciação.