agrobr 0.1.0__py3-none-any.whl

agrobr/ibge/api.py

@@ -0,0 +1,273 @@
+"""API pública do módulo IBGE - PAM e LSPA."""
+
+from __future__ import annotations
+
+from typing import Literal
+
+import pandas as pd
+import structlog
+
+from agrobr.ibge import client
+
+logger = structlog.get_logger()
+
+
+async def pam(
+    produto: str,
+    ano: int | str | list[int] | None = None,
+    uf: str | None = None,
+    nivel: Literal["brasil", "uf", "municipio"] = "uf",
+    variaveis: list[str] | None = None,
+    as_polars: bool = False,
+) -> pd.DataFrame:
+    """
+    Obtém dados da Produção Agrícola Municipal (PAM).
+
+    Args:
+        produto: Nome do produto (soja, milho, arroz, feijao, trigo, etc)
+        ano: Ano ou lista de anos (default: último disponível)
+        uf: Filtrar por UF (ex: "MT", "PR"). Requer nivel="uf" ou "municipio"
+        nivel: Nível territorial ("brasil", "uf", "municipio")
+        variaveis: Lista de variáveis (area_plantada, area_colhida, producao, rendimento)
+        as_polars: Se True, retorna polars.DataFrame
+
+    Returns:
+        DataFrame com dados da PAM
+
+    Example:
+        >>> df = await ibge.pam('soja', ano=2023)
+        >>> df = await ibge.pam('milho', ano=[2020, 2021, 2022], uf='MT')
+    """
+    logger.info(
+        "ibge_pam_request",
+        produto=produto,
+        ano=ano,
+        uf=uf,
+        nivel=nivel,
+    )
+
+    # Mapeia produto para código SIDRA
+    produto_lower = produto.lower()
+    if produto_lower not in client.PRODUTOS_PAM:
+        raise ValueError(
+            f"Produto não suportado: {produto}. Disponíveis: {list(client.PRODUTOS_PAM.keys())}"
+        )
+
+    produto_cod = client.PRODUTOS_PAM[produto_lower]
+
+    # Mapeia variáveis
+    if variaveis is None:
+        variaveis = ["area_plantada", "area_colhida", "producao", "rendimento"]
+
+    var_codes = []
+    for var in variaveis:
+        if var in client.VARIAVEIS:
+            var_codes.append(client.VARIAVEIS[var])
+        else:
+            logger.warning(f"Variável desconhecida: {var}")
+
+    # Mapeia nível territorial
+    nivel_map = {
+        "brasil": "1",
+        "uf": "3",
+        "municipio": "6",
+    }
+    territorial_level = nivel_map.get(nivel, "3")
+
+    # Define código territorial
+    ibge_code = "all"
+    if uf and nivel in ("uf", "municipio"):
+        ibge_code = client.uf_to_ibge_code(uf)
+
+    # Define período
+    if ano is None:
+        period = "last"
+    elif isinstance(ano, list):
+        period = ",".join(str(a) for a in ano)
+    else:
+        period = str(ano)
+
+    # Busca dados
+    df = await client.fetch_sidra(
+        table_code=client.TABELAS["pam_nova"],
+        territorial_level=territorial_level,
+        ibge_territorial_code=ibge_code,
+        variable=",".join(var_codes) if var_codes else None,
+        period=period,
+        classifications={"782": produto_cod},
+    )
+
+    # Processa resposta
+    df = client.parse_sidra_response(df)
+
+    # Pivota para ter variáveis como colunas
+    if "variavel" in df.columns and "valor" in df.columns:
+        df_pivot = df.pivot_table(
+            index=["localidade", "ano"] if "localidade" in df.columns else ["ano"],
+            columns="variavel",
+            values="valor",
+            aggfunc="first",
+        ).reset_index()
+
+        # Renomeia colunas para nomes mais simples
+        rename_map = {
+            "Área plantada": "area_plantada",
+            "Área colhida": "area_colhida",
+            "Quantidade produzida": "producao",
+            "Rendimento médio da produção": "rendimento",
+            "Valor da produção": "valor_producao",
+        }
+        df_pivot = df_pivot.rename(columns=rename_map)
+        df = df_pivot
+
+    df["produto"] = produto_lower
+    df["fonte"] = "ibge_pam"
+
+    if as_polars:
+        try:
+            import polars as pl
+
+            return pl.from_pandas(df)  # type: ignore[no-any-return]
+        except ImportError:
+            logger.warning("polars_not_installed", fallback="pandas")
+
+    logger.info(
+        "ibge_pam_success",
+        produto=produto,
+        records=len(df),
+    )
+
+    return df
+
+
+async def lspa(
+    produto: str,
+    ano: int | str | None = None,
+    mes: int | str | None = None,
+    uf: str | None = None,
+    as_polars: bool = False,
+) -> pd.DataFrame:
+    """
+    Obtém dados do Levantamento Sistemático da Produção Agrícola (LSPA).
+
+    O LSPA fornece estimativas mensais de safra para os principais produtos.
+
+    Args:
+        produto: Nome do produto (soja, milho_1, milho_2, arroz, feijao_1, etc)
+        ano: Ano de referência (default: atual)
+        mes: Mês de referência (1-12). Se None, retorna todos os meses do ano.
+        uf: Filtrar por UF (ex: "MT", "PR")
+        as_polars: Se True, retorna polars.DataFrame
+
+    Returns:
+        DataFrame com estimativas LSPA
+
+    Example:
+        >>> df = await ibge.lspa('soja', ano=2024)
+        >>> df = await ibge.lspa('milho_1', ano=2024, mes=6, uf='PR')
+    """
+    logger.info(
+        "ibge_lspa_request",
+        produto=produto,
+        ano=ano,
+        mes=mes,
+        uf=uf,
+    )
+
+    # Mapeia produto para código SIDRA
+    produto_lower = produto.lower()
+    if produto_lower not in client.PRODUTOS_LSPA:
+        raise ValueError(
+            f"Produto não suportado: {produto}. Disponíveis: {list(client.PRODUTOS_LSPA.keys())}"
+        )
+
+    produto_cod = client.PRODUTOS_LSPA[produto_lower]
+
+    # Define período
+    if ano is None:
+        from datetime import date
+
+        ano = date.today().year
+
+    # Define período
+    period = f"{ano}{int(mes):02d}" if mes else ",".join(f"{ano}{m:02d}" for m in range(1, 13))
+
+    # Define nível territorial
+    territorial_level = "3" if uf else "1"
+    ibge_code = client.uf_to_ibge_code(uf) if uf else "all"
+
+    # Busca dados (não especifica variáveis - retorna todas)
+    df = await client.fetch_sidra(
+        table_code=client.TABELAS["lspa"],
+        territorial_level=territorial_level,
+        ibge_territorial_code=ibge_code,
+        period=period,
+        classifications={"48": produto_cod},
+    )
+
+    # Processa resposta
+    df = client.parse_sidra_response(df)
+
+    # Adiciona período da consulta
+    df["ano"] = ano
+    if mes:
+        df["mes"] = mes
+
+    df["produto"] = produto_lower
+    df["fonte"] = "ibge_lspa"
+
+    if as_polars:
+        try:
+            import polars as pl
+
+            return pl.from_pandas(df)  # type: ignore[no-any-return]
+        except ImportError:
+            logger.warning("polars_not_installed", fallback="pandas")
+
+    logger.info(
+        "ibge_lspa_success",
+        produto=produto,
+        records=len(df),
+    )
+
+    return df
+
+
+async def produtos_pam() -> list[str]:
+    """
+    Lista produtos disponíveis na PAM.
+
+    Returns:
+        Lista de nomes de produtos
+
+    Example:
+        >>> prods = await ibge.produtos_pam()
+        >>> print(prods)
+        ['soja', 'milho', 'arroz', ...]
+    """
+    return list(client.PRODUTOS_PAM.keys())
+
+
+async def produtos_lspa() -> list[str]:
+    """
+    Lista produtos disponíveis no LSPA.
+
+    Returns:
+        Lista de nomes de produtos
+
+    Example:
+        >>> prods = await ibge.produtos_lspa()
+        >>> print(prods)
+        ['soja', 'milho_1', 'milho_2', ...]
+    """
+    return list(client.PRODUTOS_LSPA.keys())
+
+
+async def ufs() -> list[str]:
+    """
+    Lista UFs disponíveis.
+
+    Returns:
+        Lista de siglas de UF
+    """
+    return list(client.get_uf_codes().keys())

agrobr/ibge/client.py

@@ -0,0 +1,256 @@
+"""Cliente para API SIDRA do IBGE usando sidrapy."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import pandas as pd
+import sidrapy
+import structlog
+
+from agrobr import constants
+from agrobr.http.rate_limiter import RateLimiter
+
+logger = structlog.get_logger()
+
+
+# Códigos das tabelas SIDRA
+TABELAS = {
+    # PAM - Produção Agrícola Municipal
+    "pam_temporarias": "1612",  # Lavouras temporárias (1974-2018)
+    "pam_permanentes": "1613",  # Lavouras permanentes (1974-2018)
+    "pam_nova": "5457",  # Nova série PAM (2018+)
+    # LSPA - Levantamento Sistemático da Produção Agrícola
+    "lspa": "6588",  # Série mensal (2006+)
+    "lspa_safra": "1618",  # Por ano de safra
+}
+
+# Variáveis disponíveis
+VARIAVEIS = {
+    # PAM 5457
+    "area_plantada": "214",
+    "area_colhida": "215",
+    "producao": "216",
+    "rendimento": "112",
+    "valor_producao": "215",
+    # PAM 1612 (lavouras temporárias)
+    "area_plantada_1612": "109",
+    "area_colhida_1612": "1000109",
+    "producao_1612": "214",
+    "rendimento_1612": "112",
+    "valor_1612": "215",
+    # LSPA 6588
+    "area_lspa": "109",
+    "producao_lspa": "216",
+    "rendimento_lspa": "112",
+}
+
+# Níveis territoriais
+NIVEIS_TERRITORIAIS = {
+    "brasil": "1",
+    "regiao": "2",
+    "uf": "3",
+    "mesorregiao": "7",
+    "microrregiao": "8",
+    "municipio": "6",
+}
+
+# Códigos de produtos agrícolas (classificação 782 para tabela 5457)
+PRODUTOS_PAM = {
+    "soja": "40124",
+    "milho": "40126",
+    "arroz": "40117",
+    "feijao": "40120",
+    "trigo": "40145",
+    "algodao": "40109",
+    "cafe": "40112",
+    "cana": "40114",
+    "mandioca": "40127",
+    "laranja": "40125",
+}
+
+# Códigos para LSPA (classificação 48 para tabela 6588)
+PRODUTOS_LSPA = {
+    "soja": "39443",
+    "milho_1": "39441",
+    "milho_2": "39442",
+    "arroz": "39432",
+    "feijao_1": "39436",
+    "feijao_2": "39437",
+    "feijao_3": "39438",
+    "trigo": "39447",
+    "algodao": "39433",
+    "cafe": "109194",
+    "amendoim_1": "109180",
+    "amendoim_2": "109181",
+    "aveia": "109179",
+    "batata_1": "39434",
+    "batata_2": "39435",
+    "cevada": "109182",
+    "mamona": "109183",
+    "sorgo": "109184",
+    "triticale": "109185",
+}
+
+
+async def fetch_sidra(
+    table_code: str,
+    territorial_level: str = "1",
+    ibge_territorial_code: str = "all",
+    variable: str | list[str] | None = None,
+    period: str | list[str] | None = None,
+    classifications: dict[str, str | list[str]] | None = None,
+    header: str = "n",
+) -> pd.DataFrame:
+    """
+    Busca dados do SIDRA/IBGE usando sidrapy.
+
+    Args:
+        table_code: Código da tabela SIDRA
+        territorial_level: Nível territorial (1=Brasil, 3=UF, 6=Município)
+        ibge_territorial_code: Código territorial IBGE ou "all"
+        variable: Código(s) da variável
+        period: Período (ex: "2023", "last 5", "2019-2023")
+        classifications: Classificações/filtros adicionais
+        header: "n" para header numérico, "y" para descritivo
+
+    Returns:
+        DataFrame com dados do SIDRA
+    """
+    logger.info(
+        "ibge_fetch_start",
+        table=table_code,
+        level=territorial_level,
+        period=period,
+    )
+
+    async with RateLimiter.acquire(constants.Fonte.IBGE):
+        # sidrapy é síncrono, então apenas chamamos diretamente
+        kwargs: dict[str, Any] = {
+            "table_code": table_code,
+            "territorial_level": territorial_level,
+            "ibge_territorial_code": ibge_territorial_code,
+            "header": header,
+        }
+
+        if variable:
+            if isinstance(variable, list):
+                kwargs["variable"] = ",".join(variable)
+            else:
+                kwargs["variable"] = variable
+
+        if period:
+            if isinstance(period, list):
+                kwargs["period"] = ",".join(period)
+            else:
+                kwargs["period"] = period
+
+        if classifications:
+            kwargs["classifications"] = classifications
+
+        try:
+            df = sidrapy.get_table(**kwargs)
+
+            # Remove primeira linha que é o header descritivo
+            if header == "n" and len(df) > 1:
+                df = df.iloc[1:].reset_index(drop=True)
+
+            logger.info(
+                "ibge_fetch_success",
+                table=table_code,
+                rows=len(df),
+            )
+
+            return pd.DataFrame(df)
+
+        except Exception as e:
+            logger.error(
+                "ibge_fetch_error",
+                table=table_code,
+                error=str(e),
+            )
+            raise
+
+
+def parse_sidra_response(
+    df: pd.DataFrame,
+    rename_columns: dict[str, str] | None = None,
+) -> pd.DataFrame:
+    """
+    Processa resposta do SIDRA para formato mais legível.
+
+    Args:
+        df: DataFrame retornado pelo sidrapy
+        rename_columns: Mapeamento de renomeação de colunas
+
+    Returns:
+        DataFrame processado
+    """
+    # Mapeamento padrão de colunas SIDRA
+    default_rename = {
+        "NC": "nivel_territorial_cod",
+        "NN": "nivel_territorial",
+        "MC": "localidade_cod",
+        "MN": "localidade",
+        "V": "valor",
+        "D1C": "ano_cod",
+        "D1N": "ano",
+        "D2C": "variavel_cod",
+        "D2N": "variavel",
+        "D3C": "produto_cod",
+        "D3N": "produto",
+        "D4C": "classificacao_cod",
+        "D4N": "classificacao",
+    }
+
+    if rename_columns:
+        default_rename.update(rename_columns)
+
+    # Renomeia apenas colunas que existem
+    rename_map = {k: v for k, v in default_rename.items() if k in df.columns}
+    df = df.rename(columns=rename_map)
+
+    # Converte valor para numérico
+    if "valor" in df.columns:
+        df["valor"] = pd.to_numeric(df["valor"], errors="coerce")
+
+    return df
+
+
+def get_uf_codes() -> dict[str, str]:
+    """Retorna mapeamento de sigla UF para código IBGE."""
+    return {
+        "RO": "11",
+        "AC": "12",
+        "AM": "13",
+        "RR": "14",
+        "PA": "15",
+        "AP": "16",
+        "TO": "17",
+        "MA": "21",
+        "PI": "22",
+        "CE": "23",
+        "RN": "24",
+        "PB": "25",
+        "PE": "26",
+        "AL": "27",
+        "SE": "28",
+        "BA": "29",
+        "MG": "31",
+        "ES": "32",
+        "RJ": "33",
+        "SP": "35",
+        "PR": "41",
+        "SC": "42",
+        "RS": "43",
+        "MS": "50",
+        "MT": "51",
+        "GO": "52",
+        "DF": "53",
+    }
+
+
+def uf_to_ibge_code(uf: str) -> str:
+    """Converte sigla UF para código IBGE."""
+    codes = get_uf_codes()
+    return codes.get(uf.upper(), uf)

agrobr/models.py

@@ -0,0 +1,85 @@
+"""Modelos Pydantic v2 do agrobr."""
+
+from __future__ import annotations
+
+from datetime import date, datetime
+from decimal import Decimal
+from typing import Any
+
+from pydantic import BaseModel, Field, field_validator
+
+from .constants import Fonte
+
+
+class Indicador(BaseModel):
+    fonte: Fonte
+    produto: str = Field(..., min_length=2)
+    praca: str | None = None
+    data: date
+    valor: Decimal = Field(..., gt=0)
+    unidade: str
+    metodologia: str | None = None
+    revisao: int = Field(default=0, ge=0)
+    meta: dict[str, Any] = Field(default_factory=dict)
+
+    parsed_at: datetime = Field(default_factory=datetime.utcnow)
+    parser_version: int = Field(default=1)
+    anomalies: list[str] = Field(default_factory=list)
+
+    @field_validator("produto")
+    @classmethod
+    def lowercase_produto(cls, v: str) -> str:
+        if isinstance(v, str):
+            return v.lower().strip()
+        return v
+
+
+class Safra(BaseModel):
+    fonte: Fonte
+    produto: str
+    safra: str = Field(..., pattern=r"^\d{4}/\d{2}$")
+    uf: str | None = Field(None, min_length=2, max_length=2)
+    area_plantada: Decimal | None = Field(None, ge=0)
+    producao: Decimal | None = Field(None, ge=0)
+    produtividade: Decimal | None = Field(None, ge=0)
+    unidade_area: str = Field(default="mil_ha")
+    unidade_producao: str = Field(default="mil_ton")
+    levantamento: int = Field(..., ge=1, le=12)
+    data_publicacao: date
+    meta: dict[str, Any] = Field(default_factory=dict)
+
+    parsed_at: datetime = Field(default_factory=datetime.utcnow)
+    parser_version: int = Field(default=1)
+    anomalies: list[str] = Field(default_factory=list)
+
+
+class CacheEntry(BaseModel):
+    key: str
+    data: bytes
+    created_at: datetime
+    expires_at: datetime
+    source: Fonte
+    version: int = 1
+    stale: bool = False
+    hit_count: int = 0
+
+
+class HistoryEntry(BaseModel):
+    key: str
+    data: bytes
+    source: Fonte
+    data_date: date
+    collected_at: datetime
+    parser_version: int
+    fingerprint_hash: str
+
+
+class Fingerprint(BaseModel):
+    source: Fonte
+    url: str
+    collected_at: datetime
+    table_classes: list[list[str]]
+    key_ids: list[str]
+    structure_hash: str
+    table_headers: list[list[str]]
+    element_counts: dict[str, int]

agrobr/normalize/__init__.py

@@ -0,0 +1,64 @@
+"""Normalização de dados - unidades, datas, regiões, encoding."""
+
+from __future__ import annotations
+
+from .dates import (
+    anos_para_safra,
+    lista_safras,
+    normalizar_safra,
+    periodo_safra,
+    safra_anterior,
+    safra_atual,
+    safra_para_anos,
+    safra_posterior,
+    validar_safra,
+)
+from .encoding import decode_content, detect_encoding
+from .regions import (
+    ibge_para_uf,
+    listar_regioes,
+    listar_ufs,
+    normalizar_municipio,
+    normalizar_praca,
+    normalizar_uf,
+    uf_para_ibge,
+    uf_para_nome,
+    uf_para_regiao,
+    validar_uf,
+)
+from .units import (
+    converter,
+    preco_saca_para_tonelada,
+    preco_tonelada_para_saca,
+    sacas_para_toneladas,
+    toneladas_para_sacas,
+)
+
+__all__: list[str] = [
+    "decode_content",
+    "detect_encoding",
+    "converter",
+    "preco_saca_para_tonelada",
+    "preco_tonelada_para_saca",
+    "sacas_para_toneladas",
+    "toneladas_para_sacas",
+    "safra_atual",
+    "validar_safra",
+    "normalizar_safra",
+    "safra_para_anos",
+    "anos_para_safra",
+    "safra_anterior",
+    "safra_posterior",
+    "lista_safras",
+    "periodo_safra",
+    "normalizar_uf",
+    "uf_para_nome",
+    "uf_para_regiao",
+    "uf_para_ibge",
+    "ibge_para_uf",
+    "listar_ufs",
+    "listar_regioes",
+    "normalizar_municipio",
+    "normalizar_praca",
+    "validar_uf",
+]