anvisa 0.1.0__tar.gz

anvisa-0.1.0/.gitignore

@@ -0,0 +1,13 @@
+# python
+__pycache__/
+*.pyc
+.venv/
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+
+# never commit credentials
+credentials.env
+.env

anvisa-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vitor
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

anvisa-0.1.0/PKG-INFO

@@ -0,0 +1,58 @@
+Metadata-Version: 2.5
+Name: anvisa
+Version: 0.1.0
+Summary: Client and CLI for ANVISA's official Consultas Externas API (fila de análise, UDI, assuntos)
+Project-URL: Repository, https://github.com/vasfvitor/anvisa-api
+Author: Vitor
+License-Expression: MIT
+License-File: LICENSE
+Keywords: anvisa,brazil,health,regulatory,udi
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Healthcare Industry
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Requires-Dist: httpx<1,>=0.27
+Requires-Dist: pydantic<3,>=2.7
+Requires-Dist: typer>=0.12
+Description-Content-Type: text/markdown
+
+# anvisa
+
+Python client and CLI for ANVISA's official **Consultas Externas** API
+(fila de análise, UDI de dispositivos médicos, termos GMDN, assuntos de peticionamento).
+
+```bash
+uv tool install anvisa   # or: pipx install anvisa
+```
+
+Credentials come from https://api.anvisa.gov.br/ (login Gov.br → Client ID / Client Secret).
+Write them to `~/.config/anvisa/credentials.env` (`CLIENT_ID=...`, `CLIENT_SECRET=...`, chmod 600)
+or export `ANVISA_CLIENT_ID` / `ANVISA_CLIENT_SECRET`.
+
+```bash
+anvisa fila areas
+anvisa fila consulta 167
+anvisa udi search --nome cateter
+anvisa --format json udi get 377
+anvisa assunto lista --busca bioequival
+```
+
+```python
+from anvisa import Client
+
+with Client.from_env() as anvisa:
+    queue = anvisa.fila.consulta(167)
+    page = anvisa.udi.search(nomeComercial="cateter", size=50)
+```
+
+What the library handles for you, because ANVISA's spec doesn't say so: a User-Agent that
+Cloudflare accepts, token caching and renewal (29-minute tokens, no refresh token), a mirror
+of the gateway's rate limit (burst 25, 1 request/s) so loops never hit 429, 1-based request
+pages against 0-based responses, required filter keys, and typed exceptions for the
+validation errors ANVISA reports as HTTP 500.
+
+Full write-up, spec overlay and recorded fixtures: https://github.com/vasfvitor/anvisa-api

anvisa-0.1.0/README.md

@@ -0,0 +1,36 @@
+# anvisa
+
+Python client and CLI for ANVISA's official **Consultas Externas** API
+(fila de análise, UDI de dispositivos médicos, termos GMDN, assuntos de peticionamento).
+
+```bash
+uv tool install anvisa   # or: pipx install anvisa
+```
+
+Credentials come from https://api.anvisa.gov.br/ (login Gov.br → Client ID / Client Secret).
+Write them to `~/.config/anvisa/credentials.env` (`CLIENT_ID=...`, `CLIENT_SECRET=...`, chmod 600)
+or export `ANVISA_CLIENT_ID` / `ANVISA_CLIENT_SECRET`.
+
+```bash
+anvisa fila areas
+anvisa fila consulta 167
+anvisa udi search --nome cateter
+anvisa --format json udi get 377
+anvisa assunto lista --busca bioequival
+```
+
+```python
+from anvisa import Client
+
+with Client.from_env() as anvisa:
+    queue = anvisa.fila.consulta(167)
+    page = anvisa.udi.search(nomeComercial="cateter", size=50)
+```
+
+What the library handles for you, because ANVISA's spec doesn't say so: a User-Agent that
+Cloudflare accepts, token caching and renewal (29-minute tokens, no refresh token), a mirror
+of the gateway's rate limit (burst 25, 1 request/s) so loops never hit 429, 1-based request
+pages against 0-based responses, required filter keys, and typed exceptions for the
+validation errors ANVISA reports as HTTP 500.
+
+Full write-up, spec overlay and recorded fixtures: https://github.com/vasfvitor/anvisa-api

anvisa-0.1.0/pyproject.toml

@@ -0,0 +1,65 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "anvisa"
+version = "0.1.0"
+description = "Client and CLI for ANVISA's official Consultas Externas API (fila de análise, UDI, assuntos)"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [{ name = "Vitor" }]
+keywords = ["anvisa", "udi", "regulatory", "brazil", "health"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "Intended Audience :: Healthcare Industry",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+  "httpx>=0.27,<1",
+  "pydantic>=2.7,<3",
+  "typer>=0.12",
+]
+
+[project.urls]
+Repository = "https://github.com/vasfvitor/anvisa-api"
+
+[project.scripts]
+anvisa = "anvisa.cli:app"
+
+[dependency-groups]
+dev = [
+  "pytest>=8",
+  "datamodel-code-generator>=0.30",
+  "jsonpath-ng>=1.6",
+  "pyyaml>=6",
+  "ruff>=0.6",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/anvisa"]
+
+[tool.hatch.build.targets.sdist]
+# tests and scripts need ../../fixtures and ../../spec from the repo, so they are not shipped
+only-include = ["src/anvisa", "README.md", "LICENSE", "pyproject.toml"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-m 'not live'"
+markers = ["live: hits the real ANVISA API (needs credentials; run with -m live)"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+extend-exclude = ["src/anvisa/models.py"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM"]
+
+[tool.ruff.lint.per-file-ignores]
+"src/anvisa/cli.py" = ["B008"]  # typer.Option() in defaults is the typer idiom

anvisa-0.1.0/src/anvisa/__init__.py

@@ -0,0 +1,38 @@
+"""Client for ANVISA's official Consultas Externas API."""
+
+__version__ = "0.1.0"
+
+from .auth import Credentials  # noqa: E402  (client.py reads __version__ at import time)
+from .client import Client  # noqa: E402
+from .errors import (  # noqa: E402
+    AnvisaError,
+    ApiError,
+    AuthError,
+    BlockedError,
+    CredentialsError,
+    InvalidPageError,
+    MalformedRequestError,
+    MissingFilterError,
+    NotFoundError,
+    RateLimitError,
+    RequestRejectedError,
+)
+from .throttle import Throttle  # noqa: E402
+
+__all__ = [
+    "AnvisaError",
+    "ApiError",
+    "AuthError",
+    "BlockedError",
+    "Client",
+    "Credentials",
+    "CredentialsError",
+    "InvalidPageError",
+    "MalformedRequestError",
+    "MissingFilterError",
+    "NotFoundError",
+    "RateLimitError",
+    "RequestRejectedError",
+    "Throttle",
+    "__version__",
+]

anvisa-0.1.0/src/anvisa/auth.py

@@ -0,0 +1,119 @@
+"""Credentials and the OAuth2 client-credentials flow against ANVISA's Keycloak.
+
+Tokens last 1740 s and there is no refresh token, so `TokenAuth` simply requests a new
+one when the cached token is within `margin` seconds of expiring, or after a 401.
+"""
+
+from __future__ import annotations
+
+import os
+import time
+from collections.abc import Callable, Generator, Mapping
+from dataclasses import dataclass
+from pathlib import Path
+
+import httpx
+
+from .errors import AuthError, CredentialsError
+
+TOKEN_URL = (
+    "https://acesso.prd.apps.anvisa.gov.br/auth/realms/externo/protocol/openid-connect/token"
+)
+CREDENTIALS_FILE = Path("~/.config/anvisa/credentials.env")
+
+
+@dataclass(frozen=True)
+class Credentials:
+    client_id: str
+    client_secret: str
+    token_url: str = TOKEN_URL
+
+    @classmethod
+    def from_env(
+        cls,
+        env: Mapping[str, str] | None = None,
+        path: Path = CREDENTIALS_FILE,
+    ) -> Credentials:
+        """From ANVISA_CLIENT_ID/ANVISA_CLIENT_SECRET, else CLIENT_ID=/CLIENT_SECRET= in `path`."""
+        env = os.environ if env is None else env
+        file_values = read_env_file(path.expanduser())
+        client_id = env.get("ANVISA_CLIENT_ID") or file_values.get("CLIENT_ID")
+        client_secret = env.get("ANVISA_CLIENT_SECRET") or file_values.get("CLIENT_SECRET")
+        if not (client_id and client_secret):
+            raise CredentialsError(
+                "no ANVISA credentials: set ANVISA_CLIENT_ID and ANVISA_CLIENT_SECRET, "
+                f"or write CLIENT_ID=... and CLIENT_SECRET=... to {path} (chmod 600). "
+                "Credentials come from https://api.anvisa.gov.br/ (login Gov.br)."
+            )
+        return cls(client_id, client_secret)
+
+    def __repr__(self) -> str:  # never print the secret
+        return f"Credentials(client_id={self.client_id!r}, client_secret='***')"
+
+
+def read_env_file(path: Path) -> dict[str, str]:
+    """Parse `KEY=VALUE` lines (comments, blank lines, `export` and quotes allowed)."""
+    if not path.is_file():
+        return {}
+    values: dict[str, str] = {}
+    for raw in path.read_text(encoding="utf-8").splitlines():
+        line = raw.strip()
+        if not line or line.startswith("#") or "=" not in line:
+            continue
+        key, _, value = line.removeprefix("export ").partition("=")
+        values[key.strip()] = value.strip().strip("'\"")
+    return values
+
+
+class TokenAuth(httpx.Auth):
+    """httpx auth hook: fetches and caches the bearer token, retries once on 401."""
+
+    requires_response_body = True
+
+    def __init__(
+        self,
+        credentials: Credentials,
+        *,
+        margin: float = 60.0,
+        clock: Callable[[], float] = time.time,
+    ) -> None:
+        self.credentials = credentials
+        self.margin = margin
+        self._clock = clock
+        self._token: str | None = None
+        self._expires_at = 0.0
+
+    @property
+    def token_valid(self) -> bool:
+        return self._token is not None and self._clock() < self._expires_at - self.margin
+
+    def auth_flow(self, request: httpx.Request) -> Generator[httpx.Request, httpx.Response, None]:
+        if not self.token_valid:
+            yield from self._fetch_token(request)
+        request.headers["Authorization"] = f"Bearer {self._token}"
+        response = yield request
+        if response.status_code == 401:
+            yield from self._fetch_token(request)
+            request.headers["Authorization"] = f"Bearer {self._token}"
+            yield request
+
+    def _fetch_token(
+        self, original: httpx.Request
+    ) -> Generator[httpx.Request, httpx.Response, None]:
+        token_request = httpx.Request(
+            "POST",
+            self.credentials.token_url,
+            data={
+                "grant_type": "client_credentials",
+                "client_id": self.credentials.client_id,
+                "client_secret": self.credentials.client_secret,
+            },
+            # the token endpoint sits behind the same Cloudflare rules: reuse the caller's UA
+            headers={"User-Agent": original.headers.get("User-Agent", "anvisa-python")},
+        )
+        response = yield token_request
+        if response.status_code != 200:
+            raise AuthError(f"token request failed: HTTP {response.status_code}")
+        body = response.json()
+        self._token = body["access_token"]
+        self._expires_at = self._clock() + float(body.get("expires_in", 0))

anvisa-0.1.0/src/anvisa/cli.py

@@ -0,0 +1,252 @@
+"""`anvisa` command line: fila de análise, UDI and assunto lookups."""
+
+from __future__ import annotations
+
+import json
+import sys
+from collections.abc import Iterator
+from contextlib import contextmanager
+from datetime import datetime
+from enum import Enum
+from typing import Any
+
+import typer
+from pydantic import BaseModel
+from rich.console import Console
+from rich.table import Table
+
+from . import __version__
+from .client import Client
+from .errors import AnvisaError, CredentialsError
+
+try:
+    from zoneinfo import ZoneInfo
+
+    BRT = ZoneInfo("America/Sao_Paulo")
+except Exception:  # no tz database available
+    BRT = None
+
+
+class Format(str, Enum):
+    json = "json"
+    table = "table"
+
+
+app = typer.Typer(
+    help="ANVISA Consultas Externas: fila de análise, UDI de dispositivos médicos e assuntos.",
+    no_args_is_help=True,
+)
+fila_app = typer.Typer(
+    help="Fila de análise (posição dos processos por subfila).", no_args_is_help=True
+)
+udi_app = typer.Typer(help="UDI de dispositivos médicos e termos GMDN.", no_args_is_help=True)
+assunto_app = typer.Typer(
+    help="Assuntos de peticionamento (documentos, formulários, taxas).", no_args_is_help=True
+)
+app.add_typer(fila_app, name="fila")
+app.add_typer(udi_app, name="udi")
+app.add_typer(assunto_app, name="assunto")
+
+
+def _version(value: bool) -> None:
+    if value:
+        typer.echo(f"anvisa {__version__}")
+        raise typer.Exit()
+
+
+@app.callback()
+def main(
+    ctx: typer.Context,
+    format: Format | None = typer.Option(
+        None,
+        "--format",
+        "-f",
+        help="json or table (default: table on a terminal, json when piped).",
+    ),
+    version: bool = typer.Option(
+        False, "--version", callback=_version, is_eager=True, help="Print the version and exit."
+    ),
+) -> None:
+    ctx.obj = format or (Format.table if sys.stdout.isatty() else Format.json)
+
+
+def make_client() -> Client:
+    """Separate so tests can swap in a client with a mocked transport."""
+    return Client.from_env()
+
+
+@contextmanager
+def handle_errors() -> Iterator[None]:
+    try:
+        yield
+    except CredentialsError as exc:
+        typer.echo(f"error: {exc}", err=True)
+        raise typer.Exit(2) from None
+    except AnvisaError as exc:
+        typer.echo(f"error: {exc}", err=True)
+        raise typer.Exit(1) from None
+
+
+def emit(ctx: typer.Context, data: BaseModel | list[BaseModel], title: str = "") -> None:
+    rows = data if isinstance(data, list) else [data]
+    console = Console()  # created per call so COLUMNS/TTY are read at run time
+    if ctx.obj == Format.json:
+        payload = [r.model_dump(mode="json") for r in rows]
+        typer.echo(
+            json.dumps(
+                payload if isinstance(data, list) else payload[0], ensure_ascii=False, indent=2
+            )
+        )
+        return
+    if not rows:
+        console.print("(nenhum resultado)")
+        return
+    if isinstance(data, list):
+        table = Table(title=title or None)
+        columns = list(rows[0].model_dump())
+        for column in columns:
+            table.add_column(column)
+        for row in rows:
+            values = row.model_dump()
+            table.add_row(*(render(values[c]) for c in columns))
+    else:
+        table = Table(title=title or None, show_header=False)
+        for key, value in rows[0].model_dump().items():
+            table.add_row(key, render(value))
+    console.print(table)
+
+
+def render(value: Any) -> str:
+    if value is None:
+        return ""
+    if isinstance(value, datetime):
+        local = value.astimezone(BRT) if BRT else value
+        return (
+            local.strftime("%Y-%m-%d")
+            if (local.hour, local.minute) == (0, 0)
+            else local.strftime("%Y-%m-%d %H:%M")
+        )
+    if isinstance(value, Enum):
+        return str(value.value)
+    if isinstance(value, dict | list):
+        return json.dumps(value, ensure_ascii=False, default=str)
+    return str(value)
+
+
+# --- fila -------------------------------------------------------------------
+
+
+@fila_app.command("areas")
+def fila_areas(ctx: typer.Context) -> None:
+    """Áreas de interesse (Medicamento=1, Dispositivos Médicos=8, ...)."""
+    with handle_errors(), make_client() as client:
+        emit(ctx, client.fila.areas(), "Áreas")
+
+
+@fila_app.command("grupos")
+def fila_grupos(
+    ctx: typer.Context, area_id: int = typer.Argument(help="id from `anvisa fila areas`")
+) -> None:
+    """Grupos de fila de uma área."""
+    with handle_errors(), make_client() as client:
+        emit(ctx, client.fila.grupos(area_id), f"Grupos da área {area_id}")
+
+
+@fila_app.command("subfilas")
+def fila_subfilas(
+    ctx: typer.Context, grupo_id: int = typer.Argument(help="id from `anvisa fila grupos`")
+) -> None:
+    """Subfilas de um grupo."""
+    with handle_errors(), make_client() as client:
+        emit(ctx, client.fila.subfilas(grupo_id), f"Subfilas do grupo {grupo_id}")
+
+
+@fila_app.command("consulta")
+def fila_consulta(
+    ctx: typer.Context, subfila_id: int = typer.Argument(help="id from `anvisa fila subfilas`")
+) -> None:
+    """A fila calculada completa de uma subfila, em ordem."""
+    with handle_errors(), make_client() as client:
+        emit(ctx, client.fila.consulta(subfila_id), f"Fila da subfila {subfila_id}")
+
+
+# --- udi --------------------------------------------------------------------
+
+
+@udi_app.command("search")
+def udi_search(
+    ctx: typer.Context,
+    nome: str | None = typer.Option(None, "--nome", "-n", help="nomeComercial (verified filter)"),
+    udi_di: str | None = typer.Option(None, "--udi-di", help="udiDi (unverified)"),
+    cnpj: str | None = typer.Option(None, "--cnpj", help="cnpjDetentora (unverified)"),
+    gmdn: str | None = typer.Option(None, "--gmdn", help="codigoGmdn (unverified)"),
+    registro: str | None = typer.Option(None, "--registro", help="nuRegistro (unverified)"),
+    page: int = typer.Option(1, "--page", min=1),
+    size: int = typer.Option(20, "--size", min=1),
+    all_pages: bool = typer.Option(
+        False, "--all", help="iterate every page (respects the rate limit)"
+    ),
+) -> None:
+    """Busca de dispositivos por UDI. Pelo menos um filtro é obrigatório."""
+    filters = {
+        k: v
+        for k, v in {
+            "nomeComercial": nome,
+            "udiDi": udi_di,
+            "cnpjDetentora": cnpj,
+            "codigoGmdn": gmdn,
+            "nuRegistro": registro,
+        }.items()
+        if v
+    }
+    with handle_errors(), make_client() as client:
+        if all_pages:
+            emit(ctx, list(client.udi.iter_search(size=size, **filters)), "UDI")
+        else:
+            result = client.udi.search(page=page, size=size, **filters)
+            total = f" (página {page} de {result.totalPages}, {result.totalElements} no total)"
+            emit(ctx, result.content or [], "UDI" + total)
+
+
+@udi_app.command("get")
+def udi_get(ctx: typer.Context, id: int) -> None:
+    """Detalhe de um dispositivo (id interno, de `udi search`)."""
+    with handle_errors(), make_client() as client:
+        emit(ctx, client.udi.get(id), f"UDI {id}")
+
+
+@udi_app.command("historico")
+def udi_historico(ctx: typer.Context, id_dispositivo: int, id_historico: int) -> None:
+    """Uma versão histórica de um dispositivo."""
+    with handle_errors(), make_client() as client:
+        emit(ctx, client.udi.get_historico(id_dispositivo, id_historico), "UDI (histórico)")
+
+
+@udi_app.command("gmdn")
+def udi_gmdn(ctx: typer.Context, codigo: str) -> None:
+    """Termo GMDN por código."""
+    with handle_errors(), make_client() as client:
+        emit(ctx, client.udi.termo_gmdn(codigo), f"GMDN {codigo}")
+
+
+# --- assunto ----------------------------------------------------------------
+
+
+@assunto_app.command("lista")
+def assunto_lista(
+    ctx: typer.Context,
+    busca: str | None = typer.Option(None, "--busca", "-b", help="filter locally by text"),
+) -> None:
+    """Todos os códigos de assunto de peticionamento (uma requisição, ~2.600 linhas)."""
+    with handle_errors(), make_client() as client:
+        rows = client.assunto.lista()
+        if busca:
+            rows = [r for r in rows if busca.lower() in (r.descricao or "").lower()]
+        emit(ctx, rows, "Assuntos")
+
+
+@assunto_app.command("get")
+def assunto_get(ctx: typer.Context, codigo: int) -> None:
+    """Detalhe de um assunto: sistema, serviços, formulários, checklist e taxas por porte."""
+    with handle_errors(), make_client() as client:
+        emit(ctx, client.assunto.detalhe(codigo), f"Assunto {codigo}")