agrobr 0.1.0__py3-none-any.whl

agrobr/conab/api.py

@@ -0,0 +1,239 @@
+"""API pública do módulo CONAB."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import pandas as pd
+import structlog
+
+from agrobr import constants
+from agrobr.conab import client
+from agrobr.conab.parsers.v1 import ConabParserV1
+
+logger = structlog.get_logger()
+
+
+async def safras(
+    produto: str,
+    safra: str | None = None,
+    uf: str | None = None,
+    levantamento: int | None = None,
+    as_polars: bool = False,
+) -> pd.DataFrame:
+    """
+    Obtém dados de safra por produto.
+
+    Args:
+        produto: Nome do produto (soja, milho, arroz, feijao, algodao, trigo, etc)
+        safra: Safra no formato "2024/25" (default: mais recente)
+        uf: Filtrar por UF (ex: "MT", "PR")
+        levantamento: Número do levantamento (default: mais recente)
+        as_polars: Se True, retorna polars.DataFrame
+
+    Returns:
+        DataFrame com dados de safra por UF
+
+    Example:
+        >>> df = await conab.safras('soja', safra='2025/26')
+        >>> df = await conab.safras('milho', uf='MT')
+    """
+    logger.info(
+        "conab_safras_request",
+        produto=produto,
+        safra=safra,
+        uf=uf,
+        levantamento=levantamento,
+    )
+
+    xlsx, metadata = await client.fetch_safra_xlsx(safra=safra, levantamento=levantamento)
+
+    parser = ConabParserV1()
+    safra_list = parser.parse_safra_produto(
+        xlsx=xlsx,
+        produto=produto,
+        safra_ref=safra or metadata["safra"],
+        levantamento=metadata.get("levantamento"),
+    )
+
+    if uf:
+        safra_list = [s for s in safra_list if s.uf == uf.upper()]
+
+    if not safra_list:
+        logger.warning(
+            "conab_safras_empty",
+            produto=produto,
+            safra=safra,
+            uf=uf,
+        )
+        return pd.DataFrame()
+
+    df = pd.DataFrame([s.model_dump() for s in safra_list])
+
+    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(
+        "conab_safras_success",
+        produto=produto,
+        records=len(df),
+    )
+
+    return df
+
+
+async def balanco(
+    produto: str | None = None,
+    safra: str | None = None,
+    as_polars: bool = False,
+) -> pd.DataFrame:
+    """
+    Obtém dados de balanço de oferta e demanda.
+
+    Args:
+        produto: Filtrar por produto (soja, milho, etc). None para todos.
+        safra: Safra de referência para o levantamento (default: mais recente)
+        as_polars: Se True, retorna polars.DataFrame
+
+    Returns:
+        DataFrame com balanço de oferta/demanda
+
+    Example:
+        >>> df = await conab.balanco('soja')
+        >>> df = await conab.balanco()  # Todos os produtos
+    """
+    logger.info(
+        "conab_balanco_request",
+        produto=produto,
+        safra=safra,
+    )
+
+    xlsx, metadata = await client.fetch_safra_xlsx(safra=safra)
+
+    parser = ConabParserV1()
+    suprimentos = parser.parse_suprimento(xlsx=xlsx, produto=produto)
+
+    if not suprimentos:
+        logger.warning(
+            "conab_balanco_empty",
+            produto=produto,
+        )
+        return pd.DataFrame()
+
+    df = pd.DataFrame(suprimentos)
+
+    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(
+        "conab_balanco_success",
+        produto=produto,
+        records=len(df),
+    )
+
+    return df
+
+
+async def brasil_total(
+    safra: str | None = None,
+    as_polars: bool = False,
+) -> pd.DataFrame:
+    """
+    Obtém totais do Brasil por produto.
+
+    Args:
+        safra: Safra de referência (default: mais recente)
+        as_polars: Se True, retorna polars.DataFrame
+
+    Returns:
+        DataFrame com totais por produto
+
+    Example:
+        >>> df = await conab.brasil_total()
+        >>> df = await conab.brasil_total(safra='2025/26')
+    """
+    logger.info(
+        "conab_brasil_total_request",
+        safra=safra,
+    )
+
+    xlsx, metadata = await client.fetch_safra_xlsx(safra=safra)
+
+    parser = ConabParserV1()
+    totais = parser.parse_brasil_total(xlsx=xlsx, safra_ref=safra)
+
+    if not totais:
+        logger.warning("conab_brasil_total_empty", safra=safra)
+        return pd.DataFrame()
+
+    df = pd.DataFrame(totais)
+
+    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(
+        "conab_brasil_total_success",
+        records=len(df),
+    )
+
+    return df
+
+
+async def levantamentos() -> list[dict[str, Any]]:
+    """
+    Lista levantamentos de safra disponíveis.
+
+    Returns:
+        Lista de dicts com informações dos levantamentos
+
+    Example:
+        >>> levs = await conab.levantamentos()
+        >>> for lev in levs[:5]:
+        ...     print(f"{lev['safra']} - {lev['levantamento']}º levantamento")
+    """
+    return await client.list_levantamentos()
+
+
+async def produtos() -> list[str]:
+    """
+    Lista produtos disponíveis.
+
+    Returns:
+        Lista de nomes de produtos
+
+    Example:
+        >>> prods = await conab.produtos()
+        >>> print(prods)
+        ['soja', 'milho', 'arroz', 'feijao', ...]
+    """
+    return list(constants.CONAB_PRODUTOS.keys())
+
+
+async def ufs() -> list[str]:
+    """
+    Lista UFs disponíveis.
+
+    Returns:
+        Lista de siglas de UF
+
+    Example:
+        >>> estados = await conab.ufs()
+        >>> print(estados)
+        ['AC', 'AL', 'AM', ...]
+    """
+    return constants.CONAB_UFS.copy()

agrobr/conab/client.py

@@ -0,0 +1,219 @@
+"""Cliente HTTP para download de dados da CONAB."""
+
+from __future__ import annotations
+
+import re
+from io import BytesIO
+from typing import Any
+
+import structlog
+from playwright.async_api import async_playwright
+
+from agrobr import constants
+from agrobr.exceptions import SourceUnavailableError
+from agrobr.http.rate_limiter import RateLimiter
+from agrobr.http.user_agents import UserAgentRotator
+
+logger = structlog.get_logger()
+
+
+async def fetch_boletim_page() -> str:
+    """
+    Busca página do boletim de safras de grãos da CONAB.
+
+    Returns:
+        HTML da página com lista de levantamentos
+    """
+    url = constants.URLS[constants.Fonte.CONAB]["boletim_graos"]
+
+    logger.info("conab_fetch_boletim_page", url=url)
+
+    async with RateLimiter.acquire(constants.Fonte.CONAB), async_playwright() as p:
+        browser = await p.chromium.launch(headless=True)
+        page = await browser.new_page(
+            user_agent=UserAgentRotator.get_random(),
+            viewport={"width": 1920, "height": 1080},
+        )
+
+        await page.goto(url, timeout=60000)
+        await page.wait_for_timeout(3000)
+
+        html: str = await page.content()
+        await browser.close()
+
+        logger.info(
+            "conab_fetch_boletim_success",
+            content_length=len(html),
+        )
+
+        return html
+
+
+async def list_levantamentos(html: str | None = None) -> list[dict[str, Any]]:
+    """
+    Lista levantamentos disponíveis na página do boletim.
+
+    Args:
+        html: HTML da página (se None, busca automaticamente)
+
+    Returns:
+        Lista de dicts com informações dos levantamentos
+    """
+    if html is None:
+        html = await fetch_boletim_page()
+
+    levantamentos = []
+
+    pattern = r'href="([^"]+/(\d+)o-levantamento-safra-(\d{4})-(\d{2})/[^"]*\.xlsx)"[^>]*>([^<]*Tabela[^<]*)'
+
+    for match in re.finditer(pattern, html, re.IGNORECASE):
+        url = match.group(1)
+        num_levantamento = int(match.group(2))
+        ano_inicio = int(match.group(3))
+        ano_fim = int(match.group(4))
+
+        levantamentos.append(
+            {
+                "url": url,
+                "levantamento": num_levantamento,
+                "safra": f"{ano_inicio}/{ano_fim}",
+                "ano_inicio": ano_inicio,
+                "ano_fim": ano_fim,
+            }
+        )
+
+    levantamentos.sort(key=lambda x: (x["ano_inicio"], x["levantamento"]), reverse=True)
+
+    logger.info(
+        "conab_levantamentos_found",
+        count=len(levantamentos),
+    )
+
+    return levantamentos
+
+
+async def download_xlsx(url: str) -> BytesIO:
+    """
+    Baixa arquivo XLSX da CONAB.
+
+    Args:
+        url: URL do arquivo XLSX
+
+    Returns:
+        BytesIO com conteúdo do arquivo
+
+    Raises:
+        SourceUnavailableError: Se não conseguir baixar
+    """
+    logger.info("conab_download_xlsx", url=url)
+
+    async with RateLimiter.acquire(constants.Fonte.CONAB), async_playwright() as p:
+        browser = await p.chromium.launch(headless=True)
+        context = await browser.new_context(accept_downloads=True)
+        page = await context.new_page()
+
+        try:
+            async with page.expect_download(timeout=60000) as download_info:
+                await page.evaluate(f'() => {{ window.location.href = "{url}" }}')
+
+            download = await download_info.value
+
+            path = await download.path()
+            if path:
+                with open(path, "rb") as f:
+                    content = f.read()
+
+                logger.info(
+                    "conab_download_success",
+                    url=url,
+                    size_bytes=len(content),
+                )
+
+                return BytesIO(content)
+            else:
+                raise SourceUnavailableError(
+                    source="conab",
+                    url=url,
+                    last_error="Download path not available",
+                )
+
+        except Exception as e:
+            logger.error(
+                "conab_download_failed",
+                url=url,
+                error=str(e),
+            )
+            raise SourceUnavailableError(
+                source="conab",
+                url=url,
+                last_error=str(e),
+            ) from e
+
+        finally:
+            await browser.close()
+
+
+async def fetch_latest_safra_xlsx() -> tuple[BytesIO, dict[str, Any]]:
+    """
+    Baixa planilha do levantamento mais recente.
+
+    Returns:
+        tuple: (BytesIO com arquivo, metadata do levantamento)
+    """
+    levantamentos = await list_levantamentos()
+
+    if not levantamentos:
+        raise SourceUnavailableError(
+            source="conab",
+            url=constants.URLS[constants.Fonte.CONAB]["boletim_graos"],
+            last_error="No levantamentos found",
+        )
+
+    latest = levantamentos[0]
+    xlsx = await download_xlsx(latest["url"])
+
+    return xlsx, latest
+
+
+async def fetch_safra_xlsx(
+    safra: str | None = None,
+    levantamento: int | None = None,
+) -> tuple[BytesIO, dict[str, Any]]:
+    """
+    Baixa planilha de safra específica.
+
+    Args:
+        safra: Safra no formato "2024/25" (default: mais recente)
+        levantamento: Número do levantamento (default: mais recente)
+
+    Returns:
+        tuple: (BytesIO com arquivo, metadata do levantamento)
+    """
+    levantamentos = await list_levantamentos()
+
+    if not levantamentos:
+        raise SourceUnavailableError(
+            source="conab",
+            url=constants.URLS[constants.Fonte.CONAB]["boletim_graos"],
+            last_error="No levantamentos found",
+        )
+
+    filtered = levantamentos
+
+    if safra:
+        filtered = [lev for lev in filtered if lev["safra"] == safra]
+
+    if levantamento:
+        filtered = [lev for lev in filtered if lev["levantamento"] == levantamento]
+
+    if not filtered:
+        raise SourceUnavailableError(
+            source="conab",
+            url=constants.URLS[constants.Fonte.CONAB]["boletim_graos"],
+            last_error=f"No levantamento found for safra={safra}, levantamento={levantamento}",
+        )
+
+    target = filtered[0]
+    xlsx = await download_xlsx(target["url"])
+
+    return xlsx, target

agrobr/conab/parsers/__init__.py

@@ -0,0 +1,7 @@
+"""Parsers CONAB."""
+
+from __future__ import annotations
+
+from agrobr.conab.parsers.v1 import ConabParserV1
+
+__all__ = ["ConabParserV1"]