wolfzbr 0.4.0__py3-none-any.whl

wolfz/__init__.py

@@ -0,0 +1,22 @@
+"""WolfzBR: limpeza de planilhas brasileiras com receitas reproduzíveis.
+
+API pública mínima para uso em notebook e scripts::
+
+    import wolfz
+
+    receita = wolfz.load_recipe("vendas.wolfz.json")
+    df = wolfz.run(receita, "vendas_jan.csv")
+"""
+
+from importlib.metadata import PackageNotFoundError, version
+
+from wolfz.core.engine import StepError
+from wolfz.core.engine import run_file as run
+from wolfz.core.recipe import RecipeError, load_recipe
+
+try:
+    __version__ = version("wolfzbr")
+except PackageNotFoundError:  # rodando do código-fonte sem instalar
+    __version__ = "0.0.0+desconhecida"
+
+__all__ = ["RecipeError", "StepError", "__version__", "load_recipe", "run"]

wolfz/api/__init__.py

@@ -0,0 +1 @@
+"""API FastAPI local: transporte, token de sessão e servir a SPA. Sem regra de negócio."""

wolfz/api/app.py

@@ -0,0 +1,58 @@
+"""Aplicação FastAPI: rotas em ``/api``, a SPA compilada na raiz."""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+
+from fastapi import FastAPI
+from fastapi.responses import HTMLResponse
+from fastapi.staticfiles import StaticFiles
+
+import wolfz.ops  # noqa: F401  (registra o catálogo de operações)
+from wolfz import __version__
+from wolfz.api import problems, security
+from wolfz.api.projetos import Projetos
+from wolfz.api.rotas import router
+from wolfz.api.security import Settings
+
+_SEM_INTERFACE = """<!doctype html>
+<html lang="pt-BR"><head><meta charset="utf-8"><title>WolfzBR</title></head>
+<body style="font-family: system-ui, sans-serif; max-width: 40rem; margin: 4rem auto">
+<h1>WolfzBR</h1>
+<p>A API está no ar, mas a interface ainda não foi compilada neste pacote.</p>
+</body></html>
+"""
+
+
+def create_app(settings: Settings) -> FastAPI:
+    projetos = Projetos(settings.workspace, settings.port)
+
+    @asynccontextmanager
+    async def ciclo(app: FastAPI) -> AsyncIterator[None]:
+        yield
+        projetos.fechar_todos()  # libera os locks ao encerrar
+
+    app = FastAPI(
+        title="WolfzBR Local API",
+        version=__version__,
+        lifespan=ciclo,
+        docs_url="/api/docs" if settings.dev else None,
+        redoc_url=None,
+        openapi_url="/api/openapi.json" if settings.dev else None,
+    )
+    app.state.settings = settings
+    app.state.projetos = projetos
+    problems.install(app)
+    security.install(app, settings)
+    app.include_router(router(settings, projetos))
+
+    if (settings.static_dir / "index.html").is_file():
+        app.mount("/", StaticFiles(directory=settings.static_dir, html=True), name="spa")
+    else:
+
+        @app.get("/", include_in_schema=False)
+        def sem_interface() -> HTMLResponse:
+            return HTMLResponse(_SEM_INTERFACE)
+
+    return app

wolfz/api/modelos.py

@@ -0,0 +1,148 @@
+"""Modelos das respostas da API. Existem para o OpenAPI: o cliente
+TypeScript da interface é gerado a partir dele (F1.H1). Os handlers
+continuam devolvendo dicionários; o FastAPI valida contra estes modelos.
+
+A receita fica como objeto livre (``dict``): o formato dela é o JSON
+Schema da receita (``wolfz schema``), e os parâmetros de cada passo vêm de
+``GET /ops``."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class _Resposta(BaseModel):
+    # Campo a mais no dicionário passa adiante: a resposta não perde
+    # informação se o núcleo ganhar um campo antes do modelo.
+    model_config = ConfigDict(extra="allow")
+
+
+class Aba(_Resposta):
+    index: int
+    name: str
+    visibility: str
+    hidden: bool
+    rows: int | None = None
+    columns: int | None = None
+
+
+class Deteccao(_Resposta):
+    """Estrutura detectada, em linhas e letras do Excel."""
+
+    cabecalho: list[int] | None = None
+    dados: list[int]
+    colunas: list[str]
+    totais: list[int] = []
+    fill_down: list[str] = []
+    titulo: list[str] = []
+    notas: list[str] = []
+
+
+class Fonte(_Resposta):
+    name: str
+    format: str
+    size: int
+    sheet: str | None = None
+    path: str | None = None
+    uploaded: bool = False
+
+
+class Raw(_Resposta):
+    rows: int
+    columns: list[str]
+
+
+class Projeto(_Resposta):
+    id: str
+    name: str
+    created_at: str
+    source: Fonte
+    sheets: list[Aba] = []
+    raw: Raw
+    recipe: dict[str, Any]
+    etag: str
+
+
+class ProjetoCriado(Projeto):
+    reused_raw: bool
+    detection: Deteccao | None = None
+
+
+class ProjetoResumo(_Resposta):
+    id: str
+    name: str | None = None
+    created_at: str | None = None
+    format: str | None = None
+    sheet: str | None = None
+    rows: int | None = None
+    open_here: bool
+    open_elsewhere: bool
+
+
+class Estrutura(_Resposta):
+    structure: dict[str, Any]
+    detection: Deteccao | None = None
+
+
+class FormaValor(_Resposta):
+    shape: str
+    count: int
+
+
+class PerfilColuna(_Resposta):
+    name: str
+    inferred_type: str
+    type_rate: float
+    rows: int
+    nulls: int
+    null_markers: int
+    distinct: int
+    top_shapes: list[FormaValor]
+    examples: list[str]
+    minimum: float | str | None = None
+    maximum: float | str | None = None
+    null_pct: float
+    null_marker_pct: float
+
+
+class Perfil(_Resposta):
+    total_rows: int
+    sampled_rows: int
+    is_sample: bool
+    columns: list[PerfilColuna]
+
+
+class ColunaPreview(_Resposta):
+    name: str
+    dtype: str
+
+
+class Pagina(_Resposta):
+    columns: list[ColunaPreview]
+    rows: list[list[Any]]
+    total_rows: int
+    offset: int
+
+
+class ReceitaSalva(_Resposta):
+    etag: str
+    recipe: dict[str, Any]
+
+
+class Exportacao(_Resposta):
+    files: list[str]
+    rows: int | None = None
+    # Células de texto que começam com =, +, -, @… (None: só código exportado).
+    formula_cells: int | None = None
+    neutralized: bool = False
+
+
+class Operacao(_Resposta):
+    op: str
+    doc: str
+    # "schema" é nome de método antigo do BaseModel; o campo usa alias.
+    schema_: dict[str, Any] = Field(alias="schema")
+    full_checkpoint: bool
+    examples: list[dict[str, Any]]

wolfz/api/problems.py

@@ -0,0 +1,102 @@
+"""Erros no formato Problem Details (RFC 9457, §5.4 do design).
+
+Toda resposta de erro da API tem o mesmo corpo: ``type``, ``title``,
+``status``, ``detail`` e ``instance``, mais ``step_id`` e
+``available_columns`` quando o erro é de um passo da receita. É o mesmo
+texto que a CLI mostra, porque vem das mesmas exceções do núcleo.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from fastapi import FastAPI, Request
+from fastapi.exceptions import RequestValidationError
+from fastapi.responses import JSONResponse
+from starlette.exceptions import HTTPException as StarletteHTTPException
+
+from wolfz.core.engine import StepError
+from wolfz.core.ingest import IngestError
+from wolfz.core.recipe import RecipeError
+
+PROBLEM_JSON = "application/problem+json"
+log = logging.getLogger("wolfz.api")
+
+_TITULOS = {
+    400: "Requisição inválida",
+    401: "Token de sessão ausente ou inválido",
+    403: "Acesso negado",
+    404: "Não encontrado",
+    405: "Método não permitido",
+    409: "Conflito",
+    413: "Arquivo grande demais",
+    415: "Formato não suportado",
+    422: "Dados inválidos",
+    423: "Projeto aberto em outra instância",
+    428: "Cabeçalho If-Match obrigatório",
+    500: "Erro interno",
+}
+
+
+class Problem(Exception):
+    """Erro da API com status e texto para o usuário."""
+
+    def __init__(self, status: int, detail: str, title: str | None = None, **extra: Any):
+        self.status = status
+        self.detail = detail
+        self.title = title or _TITULOS.get(status, "Erro")
+        self.extra = extra
+        super().__init__(detail)
+
+
+def problem_response(request: Request, status: int, title: str, detail: str, **extra: Any) -> JSONResponse:
+    corpo = {
+        "type": "about:blank",
+        "title": title,
+        "status": status,
+        "detail": detail,
+        "instance": request.url.path,
+        **extra,
+    }
+    return JSONResponse(corpo, status_code=status, media_type=PROBLEM_JSON)
+
+
+def install(app: FastAPI) -> None:
+    """Registra os tradutores de exceção da aplicação."""
+
+    @app.exception_handler(Problem)
+    async def _problem(request: Request, exc: Problem) -> JSONResponse:
+        return problem_response(request, exc.status, exc.title, exc.detail, **exc.extra)
+
+    @app.exception_handler(StepError)
+    async def _step(request: Request, exc: StepError) -> JSONResponse:
+        corpo = exc.to_problem(status=422, instance=request.url.path)
+        return JSONResponse(corpo, status_code=422, media_type=PROBLEM_JSON)
+
+    @app.exception_handler(IngestError)
+    async def _ingest(request: Request, exc: IngestError) -> JSONResponse:
+        corpo = exc.to_problem(instance=request.url.path)
+        return JSONResponse(corpo, status_code=exc.status, media_type=PROBLEM_JSON)
+
+    @app.exception_handler(RecipeError)
+    async def _recipe(request: Request, exc: RecipeError) -> JSONResponse:
+        detalhe = "; ".join(exc.errors) if exc.errors else str(exc)
+        return problem_response(request, 422, "Receita inválida", detalhe, errors=exc.errors)
+
+    @app.exception_handler(RequestValidationError)
+    async def _validation(request: Request, exc: RequestValidationError) -> JSONResponse:
+        erros = [f"{'.'.join(str(p) for p in e['loc'])}: {e['msg']}" for e in exc.errors()]
+        return problem_response(request, 422, _TITULOS[422], "; ".join(erros), errors=erros)
+
+    @app.exception_handler(StarletteHTTPException)
+    async def _http(request: Request, exc: StarletteHTTPException) -> JSONResponse:
+        titulo = _TITULOS.get(exc.status_code, "Erro")
+        return problem_response(request, exc.status_code, titulo, str(exc.detail))
+
+    @app.exception_handler(Exception)
+    async def _inesperado(request: Request, exc: Exception) -> JSONResponse:
+        # Sem detalhe da exceção na resposta nem no log: a mensagem pode
+        # conter valor de célula (§12.1).
+        log.error("erro não tratado em %s: %s", request.url.path, type(exc).__name__)
+        return problem_response(request, 500, _TITULOS[500], "Erro inesperado. Veja o log do WolfzBR.")

wolfz/api/projetos.py

@@ -0,0 +1,97 @@
+"""Projetos abertos nesta instância: lock por projeto e serialização do preview.
+
+Lock (§9 do design, F0.A8): lock de arquivo do sistema operacional em
+``<projeto>/.lock`` (pacote ``filelock``), adquirido ao criar ou abrir o
+projeto e mantido até fechar o projeto ou encerrar o processo. Se o processo
+morre, o SO libera sozinho. Ao lado, ``.lock.json`` com pid, porta e hora,
+só para a mensagem de erro ("aberto em outra janela, em http://…").
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import threading
+from datetime import UTC, datetime
+from pathlib import Path
+
+from filelock import FileLock, Timeout
+
+from wolfz.api.problems import Problem
+from wolfz.core.engine.cache import projeto_travado
+from wolfz.core.workspace import PROJECT_FILE, Workspace
+
+LOCK_META = ".lock.json"
+
+
+class Projetos:
+    def __init__(self, workspace: Workspace, port: int):
+        self.workspace = workspace
+        self.port = port
+        self._locks: dict[str, FileLock] = {}
+        self._previews: dict[str, threading.Lock] = {}
+        self._mutex = threading.Lock()
+
+    def pasta(self, project_id: str) -> Path:
+        """Pasta do projeto; 404 se o id é inválido ou não existe."""
+        try:
+            pasta = self.workspace.project_dir(project_id)
+        except ValueError as exc:
+            raise Problem(404, f"Projeto {project_id!r} não existe.") from exc
+        if not (pasta / PROJECT_FILE).is_file():
+            raise Problem(404, f"Projeto {project_id!r} não existe.")
+        return pasta
+
+    def abrir(self, project_id: str) -> Path:
+        """Abre o projeto nesta instância (idempotente); 423 se ele está aberto
+        em outra."""
+        pasta = self.pasta(project_id)
+        with self._mutex:
+            if project_id in self._locks:
+                return pasta
+            lock = FileLock(pasta / ".lock")
+            try:
+                lock.acquire(timeout=0)
+            except Timeout as exc:
+                raise Problem(
+                    423,
+                    "Este projeto já está aberto em outra janela do WolfzBR" + self._onde(pasta) + ".",
+                ) from exc
+            meta = {"pid": os.getpid(), "port": self.port, "opened_at": datetime.now(UTC).isoformat()}
+            (pasta / LOCK_META).write_text(json.dumps(meta), encoding="utf-8")
+            self._locks[project_id] = lock
+        return pasta
+
+    def _onde(self, pasta: Path) -> str:
+        try:
+            meta = json.loads((pasta / LOCK_META).read_text(encoding="utf-8"))
+            return f", em http://127.0.0.1:{int(meta['port'])}"
+        except (OSError, ValueError, KeyError, TypeError):
+            return ""
+
+    def aberto_aqui(self, project_id: str) -> bool:
+        return project_id in self._locks
+
+    def aberto_em_outra(self, project_id: str, pasta: Path) -> bool:
+        return not self.aberto_aqui(project_id) and projeto_travado(pasta)
+
+    def fechar(self, project_id: str) -> None:
+        with self._mutex:
+            lock = self._locks.pop(project_id, None)
+            self._previews.pop(project_id, None)
+        if lock is not None:
+            pasta = Path(lock.lock_file).parent
+            (pasta / LOCK_META).unlink(missing_ok=True)
+            lock.release()
+
+    def fechar_todos(self) -> None:
+        for project_id in list(self._locks):
+            self.fechar(project_id)
+
+    def lock_preview(self, project_id: str) -> threading.Lock:
+        """Um preview por projeto por vez (§11.5): o segundo espera o primeiro."""
+        with self._mutex:
+            return self._previews.setdefault(project_id, threading.Lock())
+
+    def abertos(self) -> set[Path]:
+        return {Path(lock.lock_file).parent for lock in self._locks.values()}