agrobr 0.1.2__py3-none-any.whl → 0.5.0__py3-none-any.whl

agrobr/contracts/__init__.py

@@ -0,0 +1,186 @@
+"""Stability Contracts para garantia de schema e compatibilidade."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import StrEnum
+from typing import Any
+
+import pandas as pd
+
+
+class ColumnType(StrEnum):
+    """Tipos de dados suportados nos contratos."""
+
+    DATE = "date"
+    DATETIME = "datetime"
+    STRING = "str"
+    INTEGER = "int"
+    FLOAT = "float"
+    DECIMAL = "Decimal"
+    BOOLEAN = "bool"
+
+
+class BreakingChangePolicy(StrEnum):
+    """Politica para mudancas que quebram contrato."""
+
+    MAJOR_VERSION = "major"
+    NEVER = "never"
+    DEPRECATE_FIRST = "deprecate"
+
+
+@dataclass
+class Column:
+    """Definicao de uma coluna no contrato."""
+
+    name: str
+    type: ColumnType
+    nullable: bool = False
+    unit: str | None = None
+    description: str = ""
+    stable: bool = True
+    deprecated: bool = False
+    deprecated_in: str | None = None
+    removed_in: str | None = None
+
+    def validate(self, series: pd.Series) -> list[str]:
+        """Valida uma serie contra esta definicao."""
+        errors = []
+
+        if not self.nullable and series.isna().any():
+            null_count = series.isna().sum()
+            errors.append(f"Column '{self.name}' has {null_count} null values but nullable=False")
+
+        if self.type == ColumnType.DATE:
+            if not pd.api.types.is_datetime64_any_dtype(series):
+                try:
+                    pd.to_datetime(series.dropna())
+                except Exception:
+                    errors.append(f"Column '{self.name}' cannot be converted to date")
+
+        elif self.type == ColumnType.INTEGER:
+            if not pd.api.types.is_integer_dtype(series):
+                non_null = series.dropna()
+                if len(non_null) > 0:
+                    try:
+                        non_null.astype(int)
+                    except (ValueError, TypeError):
+                        errors.append(f"Column '{self.name}' contains non-integer values")
+
+        elif self.type in (
+            ColumnType.FLOAT,
+            ColumnType.DECIMAL,
+        ) and not pd.api.types.is_numeric_dtype(series):
+            errors.append(f"Column '{self.name}' is not numeric")
+
+        return errors
+
+
+@dataclass
+class Contract:
+    """Contrato de estabilidade para um dataset."""
+
+    name: str
+    version: str
+    columns: list[Column]
+    guarantees: list[str] = field(default_factory=list)
+    breaking_policy: BreakingChangePolicy = BreakingChangePolicy.MAJOR_VERSION
+    effective_from: str = ""
+
+    def validate(self, df: pd.DataFrame) -> tuple[bool, list[str]]:
+        """
+        Valida DataFrame contra o contrato.
+
+        Args:
+            df: DataFrame a validar
+
+        Returns:
+            Tupla (valido, lista de erros)
+        """
+        errors = []
+
+        required_cols = [c.name for c in self.columns if not c.nullable and c.stable]
+        missing = set(required_cols) - set(df.columns)
+        if missing:
+            errors.append(f"Missing required columns: {missing}")
+
+        for col_def in self.columns:
+            if col_def.name in df.columns:
+                col_errors = col_def.validate(df[col_def.name])
+                errors.extend(col_errors)
+
+        return len(errors) == 0, errors
+
+    def get_column(self, name: str) -> Column | None:
+        """Retorna definicao de uma coluna pelo nome."""
+        for col in self.columns:
+            if col.name == name:
+                return col
+        return None
+
+    def list_columns(self, stable_only: bool = False) -> list[str]:
+        """Lista nomes das colunas."""
+        if stable_only:
+            return [c.name for c in self.columns if c.stable]
+        return [c.name for c in self.columns]
+
+    def to_markdown(self) -> str:
+        """Gera documentacao Markdown do contrato."""
+        lines = [
+            f"# Contract: {self.name}",
+            f"**Version:** {self.version}",
+            f"**Effective from:** {self.effective_from}",
+            f"**Breaking policy:** {self.breaking_policy.value}",
+            "",
+            "## Columns",
+            "",
+            "| Column | Type | Nullable | Unit | Stable | Description |",
+            "|--------|------|----------|------|--------|-------------|",
+        ]
+
+        for col in self.columns:
+            stable = "Yes" if col.stable else "No"
+            nullable = "Yes" if col.nullable else "No"
+            unit = col.unit or "-"
+            desc = col.description or "-"
+            deprecated = " (deprecated)" if col.deprecated else ""
+            lines.append(
+                f"| {col.name}{deprecated} | {col.type.value} | {nullable} | {unit} | {stable} | {desc} |"
+            )
+
+        if self.guarantees:
+            lines.extend(["", "## Guarantees", ""])
+            for g in self.guarantees:
+                lines.append(f"- {g}")
+
+        return "\n".join(lines)
+
+    def to_dict(self) -> dict[str, Any]:
+        """Converte contrato para dicionario."""
+        return {
+            "name": self.name,
+            "version": self.version,
+            "effective_from": self.effective_from,
+            "breaking_policy": self.breaking_policy.value,
+            "columns": [
+                {
+                    "name": c.name,
+                    "type": c.type.value,
+                    "nullable": c.nullable,
+                    "unit": c.unit,
+                    "stable": c.stable,
+                    "deprecated": c.deprecated,
+                    "description": c.description,
+                }
+                for c in self.columns
+            ],
+            "guarantees": self.guarantees,
+        }
+
+
+__all__ = [
+    "Column",
+    "ColumnType",
+    "Contract",
+    "BreakingChangePolicy",
+]

agrobr/contracts/cepea.py

@@ -0,0 +1,80 @@
+"""Contratos de estabilidade para dados CEPEA."""
+
+from agrobr.contracts import BreakingChangePolicy, Column, ColumnType, Contract
+
+CEPEA_INDICADOR_V1 = Contract(
+    name="cepea.indicador",
+    version="1.0",
+    effective_from="0.3.0",
+    columns=[
+        Column(
+            name="data",
+            type=ColumnType.DATE,
+            nullable=False,
+            stable=True,
+            description="Data do indicador",
+        ),
+        Column(
+            name="produto",
+            type=ColumnType.STRING,
+            nullable=False,
+            stable=True,
+            description="Nome do produto (soja, milho, etc)",
+        ),
+        Column(
+            name="praca",
+            type=ColumnType.STRING,
+            nullable=True,
+            stable=True,
+            description="Praca de referencia",
+        ),
+        Column(
+            name="valor",
+            type=ColumnType.FLOAT,
+            nullable=False,
+            unit="BRL",
+            stable=True,
+            description="Preco em reais",
+        ),
+        Column(
+            name="unidade",
+            type=ColumnType.STRING,
+            nullable=False,
+            stable=True,
+            description="Unidade do preco (BRL/sc60kg, BRL/@, etc)",
+        ),
+        Column(
+            name="fonte",
+            type=ColumnType.STRING,
+            nullable=False,
+            stable=True,
+            description="Fonte dos dados",
+        ),
+        Column(
+            name="metodologia",
+            type=ColumnType.STRING,
+            nullable=True,
+            stable=False,
+            description="Descricao da metodologia",
+        ),
+        Column(
+            name="anomalies",
+            type=ColumnType.STRING,
+            nullable=True,
+            stable=False,
+            description="Lista de anomalias detectadas",
+        ),
+    ],
+    guarantees=[
+        "Column names never change (additions only)",
+        "Types only widen (int -> float, str -> categorical)",
+        "Dates always in local timezone (Sao Paulo)",
+        "Units explicit in 'unidade' column",
+        "'valor' is always positive",
+        "'data' is always a valid business day",
+    ],
+    breaking_policy=BreakingChangePolicy.MAJOR_VERSION,
+)
+
+
+__all__ = ["CEPEA_INDICADOR_V1"]

agrobr/contracts/conab.py

@@ -0,0 +1,181 @@
+"""Contratos de estabilidade para dados CONAB."""
+
+from agrobr.contracts import BreakingChangePolicy, Column, ColumnType, Contract
+
+CONAB_SAFRA_V1 = Contract(
+    name="conab.safras",
+    version="1.0",
+    effective_from="0.3.0",
+    columns=[
+        Column(
+            name="fonte",
+            type=ColumnType.STRING,
+            nullable=False,
+            stable=True,
+            description="Fonte dos dados (conab)",
+        ),
+        Column(
+            name="produto",
+            type=ColumnType.STRING,
+            nullable=False,
+            stable=True,
+            description="Nome do produto",
+        ),
+        Column(
+            name="safra",
+            type=ColumnType.STRING,
+            nullable=False,
+            stable=True,
+            description="Safra no formato YYYY/YY",
+        ),
+        Column(
+            name="uf",
+            type=ColumnType.STRING,
+            nullable=True,
+            stable=True,
+            description="Sigla da UF",
+        ),
+        Column(
+            name="area_plantada",
+            type=ColumnType.FLOAT,
+            nullable=True,
+            unit="mil_ha",
+            stable=True,
+            description="Area plantada em mil hectares",
+        ),
+        Column(
+            name="area_colhida",
+            type=ColumnType.FLOAT,
+            nullable=True,
+            unit="mil_ha",
+            stable=True,
+            description="Area colhida em mil hectares",
+        ),
+        Column(
+            name="produtividade",
+            type=ColumnType.FLOAT,
+            nullable=True,
+            unit="kg/ha",
+            stable=True,
+            description="Produtividade em kg/ha",
+        ),
+        Column(
+            name="producao",
+            type=ColumnType.FLOAT,
+            nullable=True,
+            unit="mil_ton",
+            stable=True,
+            description="Producao em mil toneladas",
+        ),
+        Column(
+            name="levantamento",
+            type=ColumnType.INTEGER,
+            nullable=False,
+            stable=True,
+            description="Numero do levantamento (1-12)",
+        ),
+        Column(
+            name="data_publicacao",
+            type=ColumnType.DATE,
+            nullable=False,
+            stable=True,
+            description="Data de publicacao do levantamento",
+        ),
+    ],
+    guarantees=[
+        "Column names never change (additions only)",
+        "'safra' always matches pattern YYYY/YY",
+        "'uf' is always a valid Brazilian state code",
+        "'levantamento' is between 1 and 12",
+        "Numeric values are always >= 0",
+    ],
+    breaking_policy=BreakingChangePolicy.MAJOR_VERSION,
+)
+
+CONAB_BALANCO_V1 = Contract(
+    name="conab.balanco",
+    version="1.0",
+    effective_from="0.3.0",
+    columns=[
+        Column(
+            name="produto",
+            type=ColumnType.STRING,
+            nullable=False,
+            stable=True,
+            description="Nome do produto",
+        ),
+        Column(
+            name="safra",
+            type=ColumnType.STRING,
+            nullable=False,
+            stable=True,
+            description="Safra de referencia",
+        ),
+        Column(
+            name="estoque_inicial",
+            type=ColumnType.FLOAT,
+            nullable=True,
+            unit="mil_ton",
+            stable=True,
+            description="Estoque inicial",
+        ),
+        Column(
+            name="producao",
+            type=ColumnType.FLOAT,
+            nullable=True,
+            unit="mil_ton",
+            stable=True,
+            description="Producao",
+        ),
+        Column(
+            name="importacao",
+            type=ColumnType.FLOAT,
+            nullable=True,
+            unit="mil_ton",
+            stable=True,
+            description="Importacao",
+        ),
+        Column(
+            name="suprimento",
+            type=ColumnType.FLOAT,
+            nullable=True,
+            unit="mil_ton",
+            stable=True,
+            description="Suprimento total",
+        ),
+        Column(
+            name="consumo",
+            type=ColumnType.FLOAT,
+            nullable=True,
+            unit="mil_ton",
+            stable=True,
+            description="Consumo interno",
+        ),
+        Column(
+            name="exportacao",
+            type=ColumnType.FLOAT,
+            nullable=True,
+            unit="mil_ton",
+            stable=True,
+            description="Exportacao",
+        ),
+        Column(
+            name="estoque_final",
+            type=ColumnType.FLOAT,
+            nullable=True,
+            unit="mil_ton",
+            stable=True,
+            description="Estoque final",
+        ),
+    ],
+    guarantees=[
+        "Column names never change (additions only)",
+        "All numeric values represent thousands of tons",
+        "suprimento = estoque_inicial + producao + importacao",
+        "estoque_final = suprimento - consumo - exportacao",
+    ],
+    breaking_policy=BreakingChangePolicy.MAJOR_VERSION,
+)
+
+
+__all__ = ["CONAB_SAFRA_V1", "CONAB_BALANCO_V1"]

agrobr/contracts/ibge.py

@@ -0,0 +1,146 @@
+"""Contratos de estabilidade para dados IBGE."""
+
+from agrobr.contracts import BreakingChangePolicy, Column, ColumnType, Contract
+
+IBGE_PAM_V1 = Contract(
+    name="ibge.pam",
+    version="1.0",
+    effective_from="0.3.0",
+    columns=[
+        Column(
+            name="ano",
+            type=ColumnType.INTEGER,
+            nullable=False,
+            stable=True,
+            description="Ano de referencia",
+        ),
+        Column(
+            name="localidade",
+            type=ColumnType.STRING,
+            nullable=True,
+            stable=True,
+            description="Nome da localidade (UF ou municipio)",
+        ),
+        Column(
+            name="produto",
+            type=ColumnType.STRING,
+            nullable=False,
+            stable=True,
+            description="Nome do produto",
+        ),
+        Column(
+            name="area_plantada",
+            type=ColumnType.FLOAT,
+            nullable=True,
+            unit="ha",
+            stable=True,
+            description="Area plantada em hectares",
+        ),
+        Column(
+            name="area_colhida",
+            type=ColumnType.FLOAT,
+            nullable=True,
+            unit="ha",
+            stable=True,
+            description="Area colhida em hectares",
+        ),
+        Column(
+            name="producao",
+            type=ColumnType.FLOAT,
+            nullable=True,
+            unit="ton",
+            stable=True,
+            description="Quantidade produzida em toneladas",
+        ),
+        Column(
+            name="rendimento",
+            type=ColumnType.FLOAT,
+            nullable=True,
+            unit="kg/ha",
+            stable=True,
+            description="Rendimento medio em kg/ha",
+        ),
+        Column(
+            name="valor_producao",
+            type=ColumnType.FLOAT,
+            nullable=True,
+            unit="mil_reais",
+            stable=True,
+            description="Valor da producao em mil reais",
+        ),
+        Column(
+            name="fonte",
+            type=ColumnType.STRING,
+            nullable=False,
+            stable=True,
+            description="Fonte dos dados (ibge_pam)",
+        ),
+    ],
+    guarantees=[
+        "Column names never change (additions only)",
+        "'ano' is always a valid year (>= 1974)",
+        "Numeric values are always >= 0",
+        "'fonte' is always 'ibge_pam'",
+    ],
+    breaking_policy=BreakingChangePolicy.MAJOR_VERSION,
+)
+
+IBGE_LSPA_V1 = Contract(
+    name="ibge.lspa",
+    version="1.0",
+    effective_from="0.3.0",
+    columns=[
+        Column(
+            name="ano",
+            type=ColumnType.INTEGER,
+            nullable=False,
+            stable=True,
+            description="Ano de referencia",
+        ),
+        Column(
+            name="mes",
+            type=ColumnType.INTEGER,
+            nullable=True,
+            stable=True,
+            description="Mes de referencia (1-12)",
+        ),
+        Column(
+            name="produto",
+            type=ColumnType.STRING,
+            nullable=False,
+            stable=True,
+            description="Nome do produto",
+        ),
+        Column(
+            name="variavel",
+            type=ColumnType.STRING,
+            nullable=True,
+            stable=False,
+            description="Nome da variavel",
+        ),
+        Column(
+            name="valor",
+            type=ColumnType.FLOAT,
+            nullable=True,
+            stable=False,
+            description="Valor da variavel",
+        ),
+        Column(
+            name="fonte",
+            type=ColumnType.STRING,
+            nullable=False,
+            stable=True,
+            description="Fonte dos dados (ibge_lspa)",
+        ),
+    ],
+    guarantees=[
+        "Column names never change (additions only)",
+        "'ano' is always a valid year",
+        "'mes' is between 1 and 12 when present",
+        "'fonte' is always 'ibge_lspa'",
+    ],
+    breaking_policy=BreakingChangePolicy.MAJOR_VERSION,
+)
+
+
+__all__ = ["IBGE_PAM_V1", "IBGE_LSPA_V1"]