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

agrobr/config.py

@@ -0,0 +1,137 @@
+"""Configuracao global do agrobr."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import date
+from pathlib import Path
+from typing import Literal
+
+_config: AgrobrConfig | None = None
+
+
+@dataclass
+class AgrobrConfig:
+    """Configuracao global do agrobr."""
+
+    mode: Literal["normal", "deterministic"] = "normal"
+    snapshot_date: date | None = None
+    snapshot_path: Path | None = None
+
+    cache_enabled: bool = True
+    cache_path: Path | None = None
+
+    network_enabled: bool = True
+    timeout_seconds: int = 30
+
+    browser_fallback: bool = False
+    alternative_source: bool = True
+
+    log_level: str = "INFO"
+
+    def is_deterministic(self) -> bool:
+        """Verifica se esta em modo deterministico."""
+        return self.mode == "deterministic"
+
+    def get_snapshot_dir(self) -> Path:
+        """Retorna diretorio de snapshots."""
+        if self.snapshot_path:
+            return self.snapshot_path
+        return Path.home() / ".agrobr" / "snapshots"
+
+    def get_current_snapshot_path(self) -> Path | None:
+        """Retorna caminho do snapshot atual."""
+        if not self.snapshot_date:
+            return None
+        return self.get_snapshot_dir() / self.snapshot_date.isoformat()
+
+
+def set_mode(
+    mode: Literal["normal", "deterministic"],
+    snapshot: str | date | None = None,
+    snapshot_path: str | Path | None = None,
+) -> None:
+    """
+    Define modo de operacao do agrobr.
+
+    Args:
+        mode: "normal" ou "deterministic"
+        snapshot: Data do snapshot (YYYY-MM-DD ou date)
+        snapshot_path: Caminho customizado para snapshots
+
+    Example:
+        agrobr.set_mode("normal")
+        agrobr.set_mode("deterministic", snapshot="2025-12-31")
+    """
+    global _config
+
+    if isinstance(snapshot, str):
+        snapshot = date.fromisoformat(snapshot)
+
+    if isinstance(snapshot_path, str):
+        snapshot_path = Path(snapshot_path)
+
+    _config = AgrobrConfig(
+        mode=mode,
+        snapshot_date=snapshot,
+        snapshot_path=snapshot_path,
+        network_enabled=(mode == "normal"),
+    )
+
+
+def get_config() -> AgrobrConfig:
+    """Retorna configuracao atual."""
+    global _config
+    if _config is None:
+        _config = AgrobrConfig()
+    return _config
+
+
+def reset_config() -> None:
+    """Reseta para configuracao padrao."""
+    global _config
+    _config = None
+
+
+def configure(
+    cache_enabled: bool | None = None,
+    cache_path: str | Path | None = None,
+    timeout_seconds: int | None = None,
+    browser_fallback: bool | None = None,
+    alternative_source: bool | None = None,
+    log_level: str | None = None,
+) -> None:
+    """
+    Configura opcoes do agrobr.
+
+    Args:
+        cache_enabled: Habilitar/desabilitar cache
+        cache_path: Caminho customizado para cache
+        timeout_seconds: Timeout para requisicoes HTTP
+        browser_fallback: Usar browser como fallback
+        alternative_source: Usar fontes alternativas
+        log_level: Nivel de log (DEBUG, INFO, WARNING, ERROR)
+    """
+    config = get_config()
+
+    if cache_enabled is not None:
+        config.cache_enabled = cache_enabled
+    if cache_path is not None:
+        config.cache_path = Path(cache_path) if isinstance(cache_path, str) else cache_path
+    if timeout_seconds is not None:
+        config.timeout_seconds = timeout_seconds
+    if browser_fallback is not None:
+        config.browser_fallback = browser_fallback
+    if alternative_source is not None:
+        config.alternative_source = alternative_source
+    if log_level is not None:
+        config.log_level = log_level
+
+
+__all__ = [
+    "AgrobrConfig",
+    "set_mode",
+    "get_config",
+    "reset_config",
+    "configure",
+]

agrobr/constants.py

@@ -12,7 +12,7 @@ class Fonte(StrEnum):
     CEPEA = "cepea"
     CONAB = "conab"
     IBGE = "ibge"
-    NOTICIAS_AGRICOLAS = "noticias_agricolas"  # Fonte alternativa para CEPEA
+    NOTICIAS_AGRICOLAS = "noticias_agricolas"
 
 
 URLS = {
@@ -35,7 +35,6 @@ URLS = {
     },
 }
 
-# Mapeamento de produtos para URLs do Notícias Agrícolas (indicadores CEPEA)
 NOTICIAS_AGRICOLAS_PRODUTOS = {
     "soja": "soja/soja-indicador-cepea-esalq-porto-paranagua",
     "soja_parana": "soja/indicador-cepea-esalq-soja-parana",

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