anvisa 0.1.0__py3-none-any.whl

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/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/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}")

anvisa/client.py

@@ -0,0 +1,231 @@
+"""The HTTP client and the API domains: `fila`, `udi` and `assunto`."""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Iterator
+from typing import Any, Protocol, TypeVar
+
+import httpx
+
+from . import __version__, models
+from .auth import Credentials, TokenAuth
+from .errors import InvalidPageError, MissingFilterError, raise_for_response
+from .throttle import Throttle
+
+BASE_URL = "https://api-gateway.prd.apps.anvisa.gov.br/consultas-externas-api"
+USER_AGENT = f"anvisa-python/{__version__} (+https://github.com/vasfvitor/anvisa-api)"
+
+
+class Client:
+    """Sync client. Use as a context manager or call `close()`.
+
+    >>> with Client.from_env() as anvisa:
+    ...     anvisa.fila.areas()
+    """
+
+    def __init__(
+        self,
+        credentials: Credentials | None = None,
+        *,
+        user_agent: str = USER_AGENT,
+        base_url: str = BASE_URL,
+        timeout: float = 30.0,
+        transport: httpx.BaseTransport | None = None,
+        throttle: Throttle | None = None,
+    ) -> None:
+        self.credentials = credentials or Credentials.from_env()
+        self.throttle = throttle or Throttle()
+        self._http = httpx.Client(
+            base_url=base_url,
+            timeout=timeout,
+            transport=transport,
+            headers={"User-Agent": user_agent, "Accept": "application/json"},
+            auth=TokenAuth(self.credentials),
+        )
+        self.fila = Fila(self)
+        self.udi = Udi(self)
+        self.assunto = Assunto(self)
+
+    @classmethod
+    def from_env(cls, **kwargs: Any) -> Client:
+        return cls(Credentials.from_env(), **kwargs)
+
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> Client:
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
+
+    def get(self, path: str) -> Any:
+        return self._send(self._http.build_request("GET", path))
+
+    def post(self, path: str, body: dict[str, Any]) -> Any:
+        return self._send(self._http.build_request("POST", path, json=body))
+
+    def _send(self, request: httpx.Request) -> Any:
+        self.throttle.before()
+        response = self._http.send(request)
+        self.throttle.after(response.headers)
+        raise_for_response(response)
+        return response.json()
+
+
+def page_body(
+    page: int, size: int, sort: dict[str, str] | None, filters: dict[str, Any]
+) -> dict[str, Any]:
+    """Build ANVISA's `PaginationBuilder` body. Pages are 1-based on the wire."""
+    if page < 1:
+        raise InvalidPageError(f"page must be >= 1 (got {page}); ANVISA pages are 1-based")
+    return {"page": page, "size": size, "sorting": dict(sort or {}), "filter": dict(filters)}
+
+
+T = TypeVar("T")
+
+
+class PageLike(Protocol[T]):
+    content: list[T] | None
+    number: int | None
+    last: bool | None
+
+
+def iterate_pages(fetch: Callable[[int], PageLike[T]]) -> Iterator[T]:
+    """Yield items across pages. `fetch` takes a 1-based page; responses report 0-based `number`."""
+    page_number = 1
+    while True:
+        page = fetch(page_number)
+        yield from page.content or []
+        if page.last or not page.content:
+            return
+        page_number = (page.number or 0) + 2
+
+
+class Fila:
+    """Fila de análise: which processes are queued, in which order, per subqueue."""
+
+    def __init__(self, client: Client) -> None:
+        self._client = client
+
+    def areas(self) -> list[models.TipoProduto]:
+        """Áreas de interesse (Medicamento=1, Dispositivos Médicos=8, ...)."""
+        return [
+            models.TipoProduto.model_validate(x) for x in self._client.get("/api/v1/fila/areafila")
+        ]
+
+    def grupos(self, area_id: int) -> list[models.ChaveValorLong]:
+        """Grupos de fila of an area (Registros, Alterações, Revalidações, ...)."""
+        data = self._client.get(f"/api/v1/fila/{area_id}/fila")
+        return [models.ChaveValorLong.model_validate(x) for x in data]
+
+    def subfilas(self, grupo_id: int) -> list[models.ChaveValorInteger]:
+        """Subfilas of a grupo; their ids are what `consulta` takes."""
+        data = self._client.get(f"/api/v1/fila/{grupo_id}/subfila")
+        return [models.ChaveValorInteger.model_validate(x) for x in data]
+
+    def consulta(self, subfila_id: int) -> list[models.FilaCalculadaDTO]:
+        """The whole calculated queue of a subfila, in order. Not paginated by the API."""
+        data = self._client.post("/api/v1/fila/consulta", {"filter": {"subfila": subfila_id}})
+        return [models.FilaCalculadaDTO.model_validate(x) for x in data]
+
+
+class Udi:
+    """UDI (Unique Device Identification) of medical devices, plus GMDN terms."""
+
+    def __init__(self, client: Client) -> None:
+        self._client = client
+
+    def search(
+        self,
+        page: int = 1,
+        size: int = 20,
+        sort: dict[str, str] | None = None,
+        **filters: Any,
+    ) -> models.PageUdiDTO:
+        """One page of devices. At least one filter is required (`nomeComercial` is verified;
+        `udiDi`, `cnpjDetentora`, `codigoGmdn`, `nuRegistro`, ... come from ANVISA's example)."""
+        if not filters:
+            raise MissingFilterError(
+                "udi.search needs at least one filter, e.g. nomeComercial='cateter'"
+            )
+        data = self._client.post("/api/v1/udi", page_body(page, size, sort, filters))
+        return models.PageUdiDTO.model_validate(data)
+
+    def iter_search(
+        self, size: int = 100, sort: dict[str, str] | None = None, **filters: Any
+    ) -> Iterator[models.UdiDTO]:
+        """Every device matching the filters, across pages."""
+        return iterate_pages(lambda page: self.search(page, size, sort, **filters))
+
+    def get(self, id: int) -> models.DetalheDispositivoDTO:
+        return models.DetalheDispositivoDTO.model_validate(self._client.get(f"/api/v1/udi/{id}"))
+
+    def get_historico(self, id_dispositivo: int, id_historico: int) -> models.DetalheDispositivoDTO:
+        data = self._client.get(f"/api/v1/udi/{id_dispositivo}/{id_historico}")
+        return models.DetalheDispositivoDTO.model_validate(data)
+
+    def historicos(self) -> list[models.HistoricoUdiDTO]:
+        data = self._client.get("/api/v1/udi/historico")
+        return [models.HistoricoUdiDTO.model_validate(x) for x in data]
+
+    def termos_gmdn(
+        self,
+        page: int = 1,
+        size: int = 20,
+        sort: dict[str, str] | None = None,
+        **filters: Any,
+    ) -> models.PageTermoGMDNDTO:
+        data = self._client.post("/api/v1/udi/termoGmdn", page_body(page, size, sort, filters))
+        return models.PageTermoGMDNDTO.model_validate(data)
+
+    def termo_gmdn(self, codigo: str) -> models.TermoGMDNDTO:
+        return models.TermoGMDNDTO.model_validate(
+            self._client.get(f"/api/v1/udi/termoGmdn/{codigo}")
+        )
+
+
+class Assunto:
+    """Assuntos de peticionamento: subject codes, and per code the required documents,
+    forms, legal basis and fees. `lista` and `detalhe` are verified live; the catalogs and
+    `busca` come from the spec only."""
+
+    def __init__(self, client: Client) -> None:
+        self._client = client
+
+    def lista(self) -> list[models.AssuntoDTO]:
+        """Every subject code with its description (~2,600 entries, one request)."""
+        data = self._client.get("/api/v1/assunto/assuntos")
+        return [models.AssuntoDTO.model_validate(x) for x in data]
+
+    def detalhe(self, codigo: int | str) -> models.DetalheAssunto:
+        """Full detail of one subject: system, services, forms, checklist, fees by company size."""
+        return models.DetalheAssunto.model_validate(self._client.get(f"/api/v1/assunto/{codigo}"))
+
+    def tipos_solicitacao(self) -> list[models.TipoSolicitacaoDTO]:
+        data = self._client.get("/api/v1/assunto/tiposSolicitacao")
+        return [models.TipoSolicitacaoDTO.model_validate(x) for x in data]
+
+    def tipos_produto(self) -> list[models.TipoProdutoDTO]:
+        data = self._client.get("/api/v1/assunto/tiposProduto")
+        return [models.TipoProdutoDTO.model_validate(x) for x in data]
+
+    def sistemas(self) -> list[models.SistemaDTO]:
+        data = self._client.get("/api/v1/assunto/sistemas")
+        return [models.SistemaDTO.model_validate(x) for x in data]
+
+    def servicos(self) -> list[models.ServicoDTO]:
+        data = self._client.get("/api/v1/assunto/servicos")
+        return [models.ServicoDTO.model_validate(x) for x in data]
+
+    def busca(
+        self,
+        page: int = 1,
+        size: int = 20,
+        sort: dict[str, str] | None = None,
+        **filters: Any,
+    ) -> models.PageConsultaAssunto:
+        """Paginated search. Filter keys from ANVISA's example, unverified: `codigosAssunto`,
+        `servicos`, `sistemas`, `tiposProduto`, `tiposSolicitacao`."""
+        data = self._client.post("/api/v1/assunto/", page_body(page, size, sort, filters))
+        return models.PageConsultaAssunto.model_validate(data)