agrobr 0.1.0__py3-none-any.whl

agrobr/normalize/dates.py

@@ -0,0 +1,303 @@
+"""
+Utilitários para datas de safra agrícola.
+
+No Brasil, a safra agrícola não coincide com o ano civil:
+- Safra de verão (soja, milho 1ª): plantio Set-Dez, colheita Jan-Abr
+- Safra de inverno (milho 2ª, trigo): plantio Fev-Mar, colheita Jun-Set
+
+Notação: "2024/25" significa plantio em 2024 e colheita em 2025.
+"""
+
+from __future__ import annotations
+
+import re
+from datetime import date
+from typing import Literal
+
+MesSafra = Literal[
+    "jan", "fev", "mar", "abr", "mai", "jun", "jul", "ago", "set", "out", "nov", "dez"
+]
+
+REGEX_SAFRA_COMPLETA = re.compile(r"^(\d{4})/(\d{2})$")
+REGEX_SAFRA_CURTA = re.compile(r"^(\d{2})/(\d{2})$")
+REGEX_SAFRA_BARRA = re.compile(r"^(\d{4})/(\d{4})$")
+
+INICIO_SAFRA_MES = 7
+
+
+def safra_atual(data: date | None = None) -> str:
+    """
+    Retorna a safra agrícola atual no formato '2024/25'.
+
+    A safra é determinada pelo mês:
+    - Jul a Dez: safra do ano atual / próximo ano
+    - Jan a Jun: safra do ano anterior / ano atual
+
+    Args:
+        data: Data de referência (default: hoje)
+
+    Returns:
+        String no formato '2024/25'
+
+    Examples:
+        >>> safra_atual(date(2024, 10, 15))
+        '2024/25'
+        >>> safra_atual(date(2025, 3, 15))
+        '2024/25'
+    """
+    if data is None:
+        data = date.today()
+
+    ano_inicio = data.year if data.month >= INICIO_SAFRA_MES else data.year - 1
+
+    ano_fim = ano_inicio + 1
+    return f"{ano_inicio}/{str(ano_fim)[-2:]}"
+
+
+def validar_safra(safra: str) -> bool:
+    """
+    Valida se string está no formato de safra válido.
+
+    Formatos aceitos:
+    - '2024/25' (padrão)
+    - '24/25' (curto)
+    - '2024/2025' (completo)
+
+    Args:
+        safra: String a validar
+
+    Returns:
+        True se válido, False caso contrário
+    """
+    if REGEX_SAFRA_COMPLETA.match(safra):
+        return True
+    if REGEX_SAFRA_CURTA.match(safra):
+        return True
+    return bool(REGEX_SAFRA_BARRA.match(safra))
+
+
+def normalizar_safra(safra: str) -> str:
+    """
+    Normaliza safra para formato padrão '2024/25'.
+
+    Args:
+        safra: Safra em qualquer formato aceito
+
+    Returns:
+        Safra no formato '2024/25'
+
+    Raises:
+        ValueError: Se formato inválido
+
+    Examples:
+        >>> normalizar_safra('24/25')
+        '2024/25'
+        >>> normalizar_safra('2024/2025')
+        '2024/25'
+    """
+    match_completa = REGEX_SAFRA_COMPLETA.match(safra)
+    if match_completa:
+        return safra
+
+    match_curta = REGEX_SAFRA_CURTA.match(safra)
+    if match_curta:
+        ano_inicio = int(match_curta.group(1))
+        ano_fim = match_curta.group(2)
+        ano_inicio = 1900 + ano_inicio if ano_inicio >= 50 else 2000 + ano_inicio
+        return f"{ano_inicio}/{ano_fim}"
+
+    match_barra = REGEX_SAFRA_BARRA.match(safra)
+    if match_barra:
+        ano_inicio_str = match_barra.group(1)
+        ano_fim_str = match_barra.group(2)[-2:]
+        return f"{ano_inicio_str}/{ano_fim_str}"
+
+    raise ValueError(f"Formato de safra inválido: '{safra}'")
+
+
+def safra_para_anos(safra: str) -> tuple[int, int]:
+    """
+    Converte safra para anos de início e fim.
+
+    Args:
+        safra: Safra no formato '2024/25'
+
+    Returns:
+        Tupla (ano_inicio, ano_fim)
+
+    Examples:
+        >>> safra_para_anos('2024/25')
+        (2024, 2025)
+    """
+    safra_norm = normalizar_safra(safra)
+    match = REGEX_SAFRA_COMPLETA.match(safra_norm)
+
+    if match is None:
+        raise ValueError(f"Formato de safra inválido: '{safra}'")
+
+    ano_inicio = int(match.group(1))
+    ano_fim_curto = int(match.group(2))
+
+    seculo = (ano_inicio // 100) * 100
+    ano_fim = seculo + ano_fim_curto
+
+    if ano_fim < ano_inicio:
+        ano_fim += 100
+
+    return ano_inicio, ano_fim
+
+
+def anos_para_safra(ano_inicio: int, ano_fim: int | None = None) -> str:
+    """
+    Converte anos para formato de safra.
+
+    Args:
+        ano_inicio: Ano de início (plantio)
+        ano_fim: Ano de fim (colheita). Se None, assume ano_inicio + 1
+
+    Returns:
+        Safra no formato '2024/25'
+
+    Examples:
+        >>> anos_para_safra(2024)
+        '2024/25'
+        >>> anos_para_safra(2024, 2025)
+        '2024/25'
+    """
+    if ano_fim is None:
+        ano_fim = ano_inicio + 1
+
+    return f"{ano_inicio}/{str(ano_fim)[-2:]}"
+
+
+def safra_anterior(safra: str, n: int = 1) -> str:
+    """
+    Retorna a safra N anos antes.
+
+    Args:
+        safra: Safra de referência
+        n: Número de safras anteriores (default: 1)
+
+    Returns:
+        Safra anterior
+
+    Examples:
+        >>> safra_anterior('2024/25')
+        '2023/24'
+        >>> safra_anterior('2024/25', 3)
+        '2021/22'
+    """
+    ano_inicio, _ = safra_para_anos(safra)
+    return anos_para_safra(ano_inicio - n)
+
+
+def safra_posterior(safra: str, n: int = 1) -> str:
+    """
+    Retorna a safra N anos depois.
+
+    Args:
+        safra: Safra de referência
+        n: Número de safras posteriores (default: 1)
+
+    Returns:
+        Safra posterior
+
+    Examples:
+        >>> safra_posterior('2024/25')
+        '2025/26'
+    """
+    ano_inicio, _ = safra_para_anos(safra)
+    return anos_para_safra(ano_inicio + n)
+
+
+def lista_safras(inicio: str, fim: str) -> list[str]:
+    """
+    Gera lista de safras entre início e fim (inclusive).
+
+    Args:
+        inicio: Safra inicial
+        fim: Safra final
+
+    Returns:
+        Lista de safras
+
+    Examples:
+        >>> lista_safras('2020/21', '2024/25')
+        ['2020/21', '2021/22', '2022/23', '2023/24', '2024/25']
+    """
+    ano_inicio, _ = safra_para_anos(inicio)
+    ano_fim, _ = safra_para_anos(fim)
+
+    return [anos_para_safra(ano) for ano in range(ano_inicio, ano_fim + 1)]
+
+
+def data_para_safra(data: date) -> str:
+    """
+    Determina a safra de uma data.
+
+    Args:
+        data: Data
+
+    Returns:
+        Safra correspondente
+    """
+    return safra_atual(data)
+
+
+def periodo_safra(safra: str) -> tuple[date, date]:
+    """
+    Retorna período aproximado da safra (Jul a Jun).
+
+    Args:
+        safra: Safra no formato '2024/25'
+
+    Returns:
+        Tupla (data_inicio, data_fim)
+    """
+    ano_inicio, ano_fim = safra_para_anos(safra)
+
+    data_inicio = date(ano_inicio, INICIO_SAFRA_MES, 1)
+    data_fim = date(ano_fim, 6, 30)
+
+    return data_inicio, data_fim
+
+
+def mes_para_numero(mes: str | MesSafra) -> int:
+    """
+    Converte nome do mês para número.
+
+    Args:
+        mes: Nome do mês (pt-BR, 3 letras)
+
+    Returns:
+        Número do mês (1-12)
+    """
+    meses = {
+        "jan": 1,
+        "fev": 2,
+        "mar": 3,
+        "abr": 4,
+        "mai": 5,
+        "jun": 6,
+        "jul": 7,
+        "ago": 8,
+        "set": 9,
+        "out": 10,
+        "nov": 11,
+        "dez": 12,
+    }
+    return meses[mes.lower()[:3]]
+
+
+def numero_para_mes(numero: int) -> str:
+    """
+    Converte número do mês para nome.
+
+    Args:
+        numero: Número do mês (1-12)
+
+    Returns:
+        Nome do mês (3 letras)
+    """
+    meses = ["jan", "fev", "mar", "abr", "mai", "jun", "jul", "ago", "set", "out", "nov", "dez"]
+    return meses[numero - 1]

agrobr/normalize/encoding.py

@@ -0,0 +1,102 @@
+"""Tratamento de encoding com fallback chain."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+import chardet
+import structlog
+
+logger = structlog.get_logger()
+
+ENCODING_CHAIN: Sequence[str] = (
+    "utf-8",
+    "iso-8859-1",
+    "windows-1252",
+    "utf-16",
+    "ascii",
+)
+
+
+def decode_content(
+    content: bytes,
+    declared_encoding: str | None = None,
+    source: str | None = None,
+) -> tuple[str, str]:
+    """
+    Decodifica bytes com fallback chain inteligente.
+
+    Args:
+        content: Bytes a decodificar
+        declared_encoding: Encoding declarado pelo servidor (Content-Type)
+        source: Nome da fonte para logging
+
+    Returns:
+        tuple[str, str]: (texto decodificado, encoding usado)
+    """
+    if declared_encoding:
+        try:
+            decoded = content.decode(declared_encoding)
+            logger.debug(
+                "encoding_success",
+                source=source,
+                encoding=declared_encoding,
+                method="declared",
+            )
+            return decoded, declared_encoding
+        except (UnicodeDecodeError, LookupError):
+            logger.debug(
+                "encoding_declared_failed",
+                source=source,
+                declared=declared_encoding,
+            )
+
+    for encoding in ENCODING_CHAIN:
+        try:
+            decoded = content.decode(encoding)
+            if encoding != "utf-8":
+                logger.info(
+                    "encoding_fallback",
+                    source=source,
+                    declared=declared_encoding,
+                    actual=encoding,
+                    method="chain",
+                )
+            return decoded, encoding
+        except UnicodeDecodeError:
+            continue
+
+    detected = chardet.detect(content)
+    if detected["encoding"] and detected["confidence"] > 0.7:
+        try:
+            decoded = content.decode(detected["encoding"])
+            logger.info(
+                "encoding_fallback",
+                source=source,
+                declared=declared_encoding,
+                actual=detected["encoding"],
+                confidence=detected["confidence"],
+                method="chardet",
+            )
+            return decoded, detected["encoding"]
+        except (UnicodeDecodeError, LookupError):
+            pass
+
+    logger.warning(
+        "encoding_forced",
+        source=source,
+        declared=declared_encoding,
+        chardet_result=detected,
+    )
+    return content.decode("utf-8", errors="replace"), "utf-8-replaced"
+
+
+def detect_encoding(content: bytes) -> tuple[str, float]:
+    """
+    Detecta encoding provável do conteúdo.
+
+    Returns:
+        tuple[str, float]: (encoding, confidence 0-1)
+    """
+    result = chardet.detect(content)
+    return result["encoding"] or "utf-8", result["confidence"] or 0.0

agrobr/normalize/regions.py

@@ -0,0 +1,308 @@
+"""
+Padronização de regiões, UFs e municípios brasileiros.
+"""
+
+from __future__ import annotations
+
+import re
+import unicodedata
+from typing import Literal
+
+UF = Literal[
+    "AC",
+    "AL",
+    "AP",
+    "AM",
+    "BA",
+    "CE",
+    "DF",
+    "ES",
+    "GO",
+    "MA",
+    "MT",
+    "MS",
+    "MG",
+    "PA",
+    "PB",
+    "PR",
+    "PE",
+    "PI",
+    "RJ",
+    "RN",
+    "RS",
+    "RO",
+    "RR",
+    "SC",
+    "SP",
+    "SE",
+    "TO",
+]
+
+Regiao = Literal["Norte", "Nordeste", "Centro-Oeste", "Sudeste", "Sul"]
+
+UFS: dict[str, dict[str, str | int]] = {
+    "AC": {"nome": "Acre", "regiao": "Norte", "ibge": 12},
+    "AL": {"nome": "Alagoas", "regiao": "Nordeste", "ibge": 27},
+    "AP": {"nome": "Amapá", "regiao": "Norte", "ibge": 16},
+    "AM": {"nome": "Amazonas", "regiao": "Norte", "ibge": 13},
+    "BA": {"nome": "Bahia", "regiao": "Nordeste", "ibge": 29},
+    "CE": {"nome": "Ceará", "regiao": "Nordeste", "ibge": 23},
+    "DF": {"nome": "Distrito Federal", "regiao": "Centro-Oeste", "ibge": 53},
+    "ES": {"nome": "Espírito Santo", "regiao": "Sudeste", "ibge": 32},
+    "GO": {"nome": "Goiás", "regiao": "Centro-Oeste", "ibge": 52},
+    "MA": {"nome": "Maranhão", "regiao": "Nordeste", "ibge": 21},
+    "MT": {"nome": "Mato Grosso", "regiao": "Centro-Oeste", "ibge": 51},
+    "MS": {"nome": "Mato Grosso do Sul", "regiao": "Centro-Oeste", "ibge": 50},
+    "MG": {"nome": "Minas Gerais", "regiao": "Sudeste", "ibge": 31},
+    "PA": {"nome": "Pará", "regiao": "Norte", "ibge": 15},
+    "PB": {"nome": "Paraíba", "regiao": "Nordeste", "ibge": 25},
+    "PR": {"nome": "Paraná", "regiao": "Sul", "ibge": 41},
+    "PE": {"nome": "Pernambuco", "regiao": "Nordeste", "ibge": 26},
+    "PI": {"nome": "Piauí", "regiao": "Nordeste", "ibge": 22},
+    "RJ": {"nome": "Rio de Janeiro", "regiao": "Sudeste", "ibge": 33},
+    "RN": {"nome": "Rio Grande do Norte", "regiao": "Nordeste", "ibge": 24},
+    "RS": {"nome": "Rio Grande do Sul", "regiao": "Sul", "ibge": 43},
+    "RO": {"nome": "Rondônia", "regiao": "Norte", "ibge": 11},
+    "RR": {"nome": "Roraima", "regiao": "Norte", "ibge": 14},
+    "SC": {"nome": "Santa Catarina", "regiao": "Sul", "ibge": 42},
+    "SP": {"nome": "São Paulo", "regiao": "Sudeste", "ibge": 35},
+    "SE": {"nome": "Sergipe", "regiao": "Nordeste", "ibge": 28},
+    "TO": {"nome": "Tocantins", "regiao": "Norte", "ibge": 17},
+}
+
+REGIOES: dict[str, list[str]] = {
+    "Norte": ["AC", "AP", "AM", "PA", "RO", "RR", "TO"],
+    "Nordeste": ["AL", "BA", "CE", "MA", "PB", "PE", "PI", "RN", "SE"],
+    "Centro-Oeste": ["DF", "GO", "MT", "MS"],
+    "Sudeste": ["ES", "MG", "RJ", "SP"],
+    "Sul": ["PR", "RS", "SC"],
+}
+
+
+def remover_acentos(texto: str) -> str:
+    """Remove acentos de uma string."""
+    nfkd = unicodedata.normalize("NFKD", texto)
+    return "".join(c for c in nfkd if not unicodedata.combining(c))
+
+
+NOMES_PARA_UF: dict[str, str] = {
+    remover_acentos(str(info["nome"]).lower()): uf for uf, info in UFS.items()
+} | {uf.lower(): uf for uf in UFS}
+
+
+def normalizar_uf(entrada: str) -> str | None:
+    """
+    Normaliza entrada para sigla UF.
+
+    Args:
+        entrada: Sigla ou nome do estado
+
+    Returns:
+        Sigla UF ou None se não encontrado
+
+    Examples:
+        >>> normalizar_uf('mato grosso')
+        'MT'
+        >>> normalizar_uf('SP')
+        'SP'
+        >>> normalizar_uf('são paulo')
+        'SP'
+    """
+    entrada_norm = remover_acentos(entrada.strip().lower())
+
+    if entrada_norm.upper() in UFS:
+        return entrada_norm.upper()
+
+    if entrada_norm in NOMES_PARA_UF:
+        return NOMES_PARA_UF[entrada_norm]
+
+    for nome, uf in NOMES_PARA_UF.items():
+        if nome in entrada_norm or entrada_norm in nome:
+            return uf
+
+    return None
+
+
+def uf_para_nome(uf: str) -> str:
+    """
+    Retorna nome completo da UF.
+
+    Args:
+        uf: Sigla da UF
+
+    Returns:
+        Nome completo
+
+    Raises:
+        KeyError: Se UF inválida
+    """
+    return str(UFS[uf.upper()]["nome"])
+
+
+def uf_para_regiao(uf: str) -> str:
+    """
+    Retorna região da UF.
+
+    Args:
+        uf: Sigla da UF
+
+    Returns:
+        Nome da região
+    """
+    return str(UFS[uf.upper()]["regiao"])
+
+
+def uf_para_ibge(uf: str) -> int:
+    """
+    Retorna código IBGE da UF.
+
+    Args:
+        uf: Sigla da UF
+
+    Returns:
+        Código IBGE (2 dígitos)
+    """
+    return int(UFS[uf.upper()]["ibge"])
+
+
+def ibge_para_uf(codigo: int) -> str:
+    """
+    Converte código IBGE para sigla UF.
+
+    Args:
+        codigo: Código IBGE
+
+    Returns:
+        Sigla UF
+    """
+    for uf, info in UFS.items():
+        if info["ibge"] == codigo:
+            return uf
+    raise ValueError(f"Código IBGE inválido: {codigo}")
+
+
+def listar_ufs(regiao: str | None = None) -> list[str]:
+    """
+    Lista UFs, opcionalmente filtradas por região.
+
+    Args:
+        regiao: Filtrar por região
+
+    Returns:
+        Lista de siglas UF
+    """
+    if regiao:
+        return REGIOES.get(regiao, [])
+    return list(UFS.keys())
+
+
+def listar_regioes() -> list[str]:
+    """Retorna lista de regiões."""
+    return list(REGIOES.keys())
+
+
+def normalizar_municipio(nome: str) -> str:
+    """
+    Normaliza nome de município.
+
+    Remove acentos, converte para title case, trata casos especiais.
+
+    Args:
+        nome: Nome do município
+
+    Returns:
+        Nome normalizado
+    """
+    nome = nome.strip()
+
+    nome = re.sub(r"\s+", " ", nome)
+
+    palavras_minusculas = {"de", "da", "do", "das", "dos", "e"}
+
+    partes = nome.lower().split()
+    resultado = []
+
+    for i, parte in enumerate(partes):
+        if i == 0 or parte not in palavras_minusculas:
+            resultado.append(parte.capitalize())
+        else:
+            resultado.append(parte)
+
+    return " ".join(resultado)
+
+
+def extrair_uf_municipio(texto: str) -> tuple[str | None, str | None]:
+    """
+    Extrai UF e município de texto no formato "Município - UF" ou "Município/UF".
+
+    Args:
+        texto: Texto com município e UF
+
+    Returns:
+        Tupla (uf, municipio) ou (None, None) se não identificado
+    """
+    padrao = re.compile(r"^(.+?)[\s]*[-/][\s]*([A-Za-z]{2})$")
+    match = padrao.match(texto.strip())
+
+    if match:
+        municipio = normalizar_municipio(match.group(1))
+        uf = normalizar_uf(match.group(2))
+        return uf, municipio
+
+    return None, None
+
+
+def validar_uf(uf: str) -> bool:
+    """Verifica se UF é válida."""
+    return uf.upper() in UFS
+
+
+def validar_regiao(regiao: str) -> bool:
+    """Verifica se região é válida."""
+    return regiao in REGIOES
+
+
+PRACAS_CEPEA: dict[str, dict[str, str]] = {
+    "soja": {
+        "paranagua": "PR",
+        "rio grande": "RS",
+        "santos": "SP",
+    },
+    "milho": {
+        "campinas": "SP",
+        "cascavel": "PR",
+        "rio verde": "GO",
+    },
+    "boi_gordo": {
+        "sao paulo": "SP",
+        "araçatuba": "SP",
+        "presidente prudente": "SP",
+    },
+    "cafe": {
+        "sao paulo": "SP",
+        "mogiana": "SP",
+        "sul de minas": "MG",
+    },
+}
+
+
+def normalizar_praca(praca: str, produto: str | None = None) -> str:
+    """
+    Normaliza nome de praça de comercialização.
+
+    Args:
+        praca: Nome da praça
+        produto: Produto (para contexto)
+
+    Returns:
+        Nome normalizado
+    """
+    praca_norm = remover_acentos(praca.lower().strip())
+
+    if produto and produto.lower() in PRACAS_CEPEA:
+        pracas_produto = PRACAS_CEPEA[produto.lower()]
+        for praca_padrao in pracas_produto:
+            if praca_padrao in praca_norm or praca_norm in praca_padrao:
+                return praca_padrao.title()
+
+    return normalizar_municipio(praca)