alpr-sdk 0.1.0__tar.gz

alpr_sdk-0.1.0/.gitignore

@@ -0,0 +1,5 @@
+__pycache__/
+*.egg-info/
+dist/
+.venv/
+.mypy_cache/

alpr_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,131 @@
+Metadata-Version: 2.5
+Name: alpr-sdk
+Version: 0.1.0
+Summary: Alpr.sh's SDK for Python: license-plate recognition on photos, readings, cameras and webhooks.
+Project-URL: Homepage, https://alpr.sh
+Project-URL: Repository, https://github.com/alpr-sh/sdk
+License-Expression: MIT
+Classifier: Programming Language :: Python :: 3
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# Alpr.sh SDK para Python
+
+SDK oficial da API da Alpr.sh para Python 3.11+, sem dependências. É gerado a partir do contrato da API (`openapi.json`, na raiz de [alpr-sh/sdk](https://github.com/alpr-sh/sdk)) por `generator/`. Não edite os arquivos desta pasta: regenere.
+
+```sh
+pip install alpr-sdk
+```
+
+## Começando
+
+A chave de API (`alpr_live_…`) é a do espaço de trabalho: ela diz de quem são as leituras e quais escopos a chamada pode usar. Não há ambiente de teste.
+
+```python
+import os
+from alpr import Alpr
+
+alpr = Alpr(os.environ["ALPR_API_KEY"])
+
+# Lê as placas de uma foto.
+with open("portaria.jpg", "rb") as file:
+    result = alpr.photos.recognize({"image": file.read(), "lpr_confidence": 0.5})
+for plate in result.plates:
+    print(plate.plate, plate.conf, plate.plate_type)
+
+# Percorre as leituras, da mais nova para a mais antiga, com filtros.
+for reading in alpr.recognitions.list_iter(plate="BRA", source="camera"):
+    print(reading.id, reading.plate, reading.captured_at)
+
+# Lista as câmeras.
+for camera in alpr.cameras.list():
+    print(camera.id, camera.name, camera.enabled)
+
+# O link temporário da imagem de uma leitura.
+image = alpr.recognitions.image("det_123")
+print(image.image_url, image.expires_in)
+```
+
+`Alpr(api_key, base_url=…, timeout=30, transport=…)`: o endereço-base é `https://alpr.sh`; `http` só é aceito para `localhost`, `127.0.0.0/8` e `::1`, e qualquer outro endereço levanta `ValueError` antes de qualquer envio, para a chave nunca cruzar a rede em texto claro. A chamada que precisa de outra chave aceita `api_key=`. Redirecionamentos nunca são seguidos (a chave não viaja): um 3xx é um `AlprError`. O SDK não repete chamadas sozinho.
+
+## A foto
+
+Passe os **bytes** da foto (`bytes`). O SDK envia `multipart/form-data` no campo `image`, com o nome e o tipo definidos pelos primeiros bytes: JPEG (`FF D8 FF`) vira `photo.jpg` (`image/jpeg`), PNG vira `photo.png` (`image/png`) e qualquer outra coisa vai como `photo` (`application/octet-stream`), para a API recusar. As opções `lpr_confidence` e `min_ocr_confidence` (de 0 a 1) são opcionais e só são enviadas quando você as passa; `ocr` aceita apenas `image`.
+
+## Páginas
+
+`alpr.recognitions.list(before=…, plate=…, camera=…, source=…)` busca uma página e devolve `Page` com `items` e `next`, o cursor da página seguinte (`None` na última). `list_iter(...)` é um gerador que percorre todas as páginas, começando do cursor `before` que você passar (sem ele, da mais nova), e termina no primeiro erro ou quando o cursor deixa de andar.
+
+## Recursos
+
+| Serviço | Métodos |
+|---|---|
+| `alpr.cameras` | `list` |
+| `alpr.photos` | `detect`, `ocr`, `recognize` |
+| `alpr.recognitions` | `image`, `list`, `list_iter` |
+
+## Erros
+
+Uma recusa da API levanta `AlprError`, com `status`, `code`, `message`, `fields` (vazio, a menos que a resposta traga o problema de cada campo) e, num 429, `retry_after` em segundos (do cabeçalho `Retry-After`). Uma resposta de erro que não é JSON continua sendo um erro, só com o `status`. Os códigos:
+
+| Status | `code` |
+|---|---|
+| 400 | `missing image`, `invalid_image`, `invalid_option` |
+| 401 | `invalid_api_key` |
+| 402 | `insufficient_credits` |
+| 403 | `insufficient_scope` |
+| 404 | `not_found`, `image_unavailable` |
+| 413 | `image_too_large` |
+| 422 | `no_plate` |
+| 429 | `rate_limited` |
+| 503 | `engine_unavailable`, `storage_unavailable` |
+
+```python
+from alpr import AlprError
+
+try:
+    alpr.photos.recognize({"image": photo})
+except AlprError as error:
+    if error.code == "rate_limited":
+        time.sleep(error.retry_after or 1)
+```
+
+## Webhooks
+
+A Alpr.sh envia os eventos para o endereço que você cadastrou, assinados. Os cabeçalhos:
+
+- `X-Alprsh-Delivery-Id`: o id da entrega. **Deduplique as entregas por ele**: o `id` do corpo é o da leitura ou do alerta, não o da entrega.
+- `X-Alprsh-Timestamp`: segundos desde 1970 (só dígitos ASCII).
+- `X-Alprsh-Signature`: `sha256=` e os 64 caracteres hexadecimais do HMAC-SHA256 de `timestamp + "." + delivery-id + "." + corpo`, com o segredo do endpoint (`whsec_…`) usado como está, em UTF-8, sem decodificar.
+
+```python
+from alpr import (
+    AlertTriggeredWebhookEvent,
+    RecognitionCreatedWebhookEvent,
+    UnknownWebhookEvent,
+    WebhookVerificationError,
+    verify_webhook,
+)
+
+try:
+    event = verify_webhook(os.environ["ALPR_WEBHOOK_SECRET"], request.headers, request.get_data())
+except WebhookVerificationError:
+    return "assinatura inválida", 400
+
+match event:
+    case RecognitionCreatedWebhookEvent(plate=plate, camera_id=camera_id):
+        print(event.event, plate, camera_id, event.captured_at)
+    case AlertTriggeredWebhookEvent(rule_name=rule_name):
+        print(rule_name, event.recognition_id)
+    case UnknownWebhookEvent():
+        pass  # um evento que esta versão do SDK ainda não conhece: event.body é o JSON
+```
+
+Passe o corpo cru, exatamente como chegou, e verifique antes de interpretar. Os cabeçalhos podem ser um dicionário (a busca ignora maiúsculas) ou uma lista de pares `(nome, valor)`, para os frameworks que repetem um cabeçalho. A tolerância do relógio é de `WEBHOOK_TOLERANCE_SECONDS` (300 segundos, para os dois lados; exatamente 300 passa, 301 não).
+
+Durante a rotação do segredo o cabeçalho de assinatura traz mais de uma, numa linha separada por vírgulas ou em linhas repetidas (até 6); basta uma conferir, mas uma assinatura malformada recusa a requisição inteira. `verify_webhook_signature` só confere a assinatura. Uma assinatura que não confere levanta `WebhookVerificationError`; um segredo vazio é um erro de configuração (`ValueError`), não de assinatura.
+
+O evento é tipado: um tipo por carga (`RecognitionCreatedWebhookEvent`, `AlertTriggeredWebhookEvent`, `TestWebhookEvent`), com os campos da carga na raiz (`event`, `id`, `tenant_id`, `plate`…), sem `data` nem `type`. Um nome de evento que esta versão do SDK não conhece chega como `UnknownWebhookEvent` (`event`, `id` e o `body` inteiro), e não é um erro. Um corpo que não é um objeto com `event` levanta `ValueError`.
+
+Versão do SDK: 0.1.0 · contrato da API: 1.0.0

alpr_sdk-0.1.0/README.md

@@ -0,0 +1,119 @@
+# Alpr.sh SDK para Python
+
+SDK oficial da API da Alpr.sh para Python 3.11+, sem dependências. É gerado a partir do contrato da API (`openapi.json`, na raiz de [alpr-sh/sdk](https://github.com/alpr-sh/sdk)) por `generator/`. Não edite os arquivos desta pasta: regenere.
+
+```sh
+pip install alpr-sdk
+```
+
+## Começando
+
+A chave de API (`alpr_live_…`) é a do espaço de trabalho: ela diz de quem são as leituras e quais escopos a chamada pode usar. Não há ambiente de teste.
+
+```python
+import os
+from alpr import Alpr
+
+alpr = Alpr(os.environ["ALPR_API_KEY"])
+
+# Lê as placas de uma foto.
+with open("portaria.jpg", "rb") as file:
+    result = alpr.photos.recognize({"image": file.read(), "lpr_confidence": 0.5})
+for plate in result.plates:
+    print(plate.plate, plate.conf, plate.plate_type)
+
+# Percorre as leituras, da mais nova para a mais antiga, com filtros.
+for reading in alpr.recognitions.list_iter(plate="BRA", source="camera"):
+    print(reading.id, reading.plate, reading.captured_at)
+
+# Lista as câmeras.
+for camera in alpr.cameras.list():
+    print(camera.id, camera.name, camera.enabled)
+
+# O link temporário da imagem de uma leitura.
+image = alpr.recognitions.image("det_123")
+print(image.image_url, image.expires_in)
+```
+
+`Alpr(api_key, base_url=…, timeout=30, transport=…)`: o endereço-base é `https://alpr.sh`; `http` só é aceito para `localhost`, `127.0.0.0/8` e `::1`, e qualquer outro endereço levanta `ValueError` antes de qualquer envio, para a chave nunca cruzar a rede em texto claro. A chamada que precisa de outra chave aceita `api_key=`. Redirecionamentos nunca são seguidos (a chave não viaja): um 3xx é um `AlprError`. O SDK não repete chamadas sozinho.
+
+## A foto
+
+Passe os **bytes** da foto (`bytes`). O SDK envia `multipart/form-data` no campo `image`, com o nome e o tipo definidos pelos primeiros bytes: JPEG (`FF D8 FF`) vira `photo.jpg` (`image/jpeg`), PNG vira `photo.png` (`image/png`) e qualquer outra coisa vai como `photo` (`application/octet-stream`), para a API recusar. As opções `lpr_confidence` e `min_ocr_confidence` (de 0 a 1) são opcionais e só são enviadas quando você as passa; `ocr` aceita apenas `image`.
+
+## Páginas
+
+`alpr.recognitions.list(before=…, plate=…, camera=…, source=…)` busca uma página e devolve `Page` com `items` e `next`, o cursor da página seguinte (`None` na última). `list_iter(...)` é um gerador que percorre todas as páginas, começando do cursor `before` que você passar (sem ele, da mais nova), e termina no primeiro erro ou quando o cursor deixa de andar.
+
+## Recursos
+
+| Serviço | Métodos |
+|---|---|
+| `alpr.cameras` | `list` |
+| `alpr.photos` | `detect`, `ocr`, `recognize` |
+| `alpr.recognitions` | `image`, `list`, `list_iter` |
+
+## Erros
+
+Uma recusa da API levanta `AlprError`, com `status`, `code`, `message`, `fields` (vazio, a menos que a resposta traga o problema de cada campo) e, num 429, `retry_after` em segundos (do cabeçalho `Retry-After`). Uma resposta de erro que não é JSON continua sendo um erro, só com o `status`. Os códigos:
+
+| Status | `code` |
+|---|---|
+| 400 | `missing image`, `invalid_image`, `invalid_option` |
+| 401 | `invalid_api_key` |
+| 402 | `insufficient_credits` |
+| 403 | `insufficient_scope` |
+| 404 | `not_found`, `image_unavailable` |
+| 413 | `image_too_large` |
+| 422 | `no_plate` |
+| 429 | `rate_limited` |
+| 503 | `engine_unavailable`, `storage_unavailable` |
+
+```python
+from alpr import AlprError
+
+try:
+    alpr.photos.recognize({"image": photo})
+except AlprError as error:
+    if error.code == "rate_limited":
+        time.sleep(error.retry_after or 1)
+```
+
+## Webhooks
+
+A Alpr.sh envia os eventos para o endereço que você cadastrou, assinados. Os cabeçalhos:
+
+- `X-Alprsh-Delivery-Id`: o id da entrega. **Deduplique as entregas por ele**: o `id` do corpo é o da leitura ou do alerta, não o da entrega.
+- `X-Alprsh-Timestamp`: segundos desde 1970 (só dígitos ASCII).
+- `X-Alprsh-Signature`: `sha256=` e os 64 caracteres hexadecimais do HMAC-SHA256 de `timestamp + "." + delivery-id + "." + corpo`, com o segredo do endpoint (`whsec_…`) usado como está, em UTF-8, sem decodificar.
+
+```python
+from alpr import (
+    AlertTriggeredWebhookEvent,
+    RecognitionCreatedWebhookEvent,
+    UnknownWebhookEvent,
+    WebhookVerificationError,
+    verify_webhook,
+)
+
+try:
+    event = verify_webhook(os.environ["ALPR_WEBHOOK_SECRET"], request.headers, request.get_data())
+except WebhookVerificationError:
+    return "assinatura inválida", 400
+
+match event:
+    case RecognitionCreatedWebhookEvent(plate=plate, camera_id=camera_id):
+        print(event.event, plate, camera_id, event.captured_at)
+    case AlertTriggeredWebhookEvent(rule_name=rule_name):
+        print(rule_name, event.recognition_id)
+    case UnknownWebhookEvent():
+        pass  # um evento que esta versão do SDK ainda não conhece: event.body é o JSON
+```
+
+Passe o corpo cru, exatamente como chegou, e verifique antes de interpretar. Os cabeçalhos podem ser um dicionário (a busca ignora maiúsculas) ou uma lista de pares `(nome, valor)`, para os frameworks que repetem um cabeçalho. A tolerância do relógio é de `WEBHOOK_TOLERANCE_SECONDS` (300 segundos, para os dois lados; exatamente 300 passa, 301 não).
+
+Durante a rotação do segredo o cabeçalho de assinatura traz mais de uma, numa linha separada por vírgulas ou em linhas repetidas (até 6); basta uma conferir, mas uma assinatura malformada recusa a requisição inteira. `verify_webhook_signature` só confere a assinatura. Uma assinatura que não confere levanta `WebhookVerificationError`; um segredo vazio é um erro de configuração (`ValueError`), não de assinatura.
+
+O evento é tipado: um tipo por carga (`RecognitionCreatedWebhookEvent`, `AlertTriggeredWebhookEvent`, `TestWebhookEvent`), com os campos da carga na raiz (`event`, `id`, `tenant_id`, `plate`…), sem `data` nem `type`. Um nome de evento que esta versão do SDK não conhece chega como `UnknownWebhookEvent` (`event`, `id` e o `body` inteiro), e não é um erro. Um corpo que não é um objeto com `event` levanta `ValueError`.
+
+Versão do SDK: 0.1.0 · contrato da API: 1.0.0

alpr_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,23 @@
+[build-system]
+requires = ["hatchling>=1.33"]
+build-backend = "hatchling.build"
+
+[project]
+name = "alpr-sdk"
+version = "0.1.0"
+description = "Alpr.sh's SDK for Python: license-plate recognition on photos, readings, cameras and webhooks."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.11"
+dependencies = []
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Typing :: Typed",
+]
+
+[project.urls]
+Homepage = "https://alpr.sh"
+Repository = "https://github.com/alpr-sh/sdk"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/alpr"]

alpr_sdk-0.1.0/src/alpr/__init__.py

@@ -0,0 +1,61 @@
+# Code generated by sdk/generator. DO NOT EDIT.
+"""Alpr.sh's SDK for Python, generated from Alpr.sh's API contract."""
+
+from ._client import Alpr, Transport, urllib_transport
+from ._errors import AlprError
+from ._pagination import Page
+from ._services import CamerasService, PhotosService, RecognitionsService
+from ._version import API_VERSION, DEFAULT_BASE_URL, VERSION
+from .models import Camera, DetectedPlate, DetectionImageLink, PhotoDetection, PhotoRecognition, PhotosDetectParams, PhotosOCRParams, PhotosRecognizeParams, PlateReading, ReadingArea, ReadingAreaBox, Recognition, RecognizedPlate, WebhookAlertTriggered, WebhookRecognitionCreated, WebhookTest
+from .webhooks import (
+    WEBHOOK_TOLERANCE_SECONDS,
+    AlertTriggeredWebhookEvent,
+    RecognitionCreatedWebhookEvent,
+    TestWebhookEvent,
+    HeadersLike,
+    UnknownWebhookEvent,
+    WebhookEvent,
+    WebhookVerificationError,
+    verify_webhook,
+    verify_webhook_signature,
+)
+
+__all__ = [
+    "API_VERSION",
+    "DEFAULT_BASE_URL",
+    "VERSION",
+    "WEBHOOK_TOLERANCE_SECONDS",
+    "Alpr",
+    "AlprError",
+    "HeadersLike",
+    "Page",
+    "Transport",
+    "UnknownWebhookEvent",
+    "WebhookEvent",
+    "WebhookVerificationError",
+    "urllib_transport",
+    "verify_webhook",
+    "verify_webhook_signature",
+    "AlertTriggeredWebhookEvent",
+    "RecognitionCreatedWebhookEvent",
+    "TestWebhookEvent",
+    "CamerasService",
+    "PhotosService",
+    "RecognitionsService",
+    "Camera",
+    "DetectedPlate",
+    "DetectionImageLink",
+    "PhotoDetection",
+    "PhotoRecognition",
+    "PhotosDetectParams",
+    "PhotosOCRParams",
+    "PhotosRecognizeParams",
+    "PlateReading",
+    "ReadingArea",
+    "ReadingAreaBox",
+    "Recognition",
+    "RecognizedPlate",
+    "WebhookAlertTriggered",
+    "WebhookRecognitionCreated",
+    "WebhookTest",
+]

alpr_sdk-0.1.0/src/alpr/_client.py

@@ -0,0 +1,107 @@
+# Code generated by sdk/generator. DO NOT EDIT.
+
+from __future__ import annotations
+
+import ipaddress
+import json
+import urllib.error
+import urllib.request
+from collections.abc import Callable
+from typing import Any
+from urllib.parse import urlencode, urlsplit
+
+from ._errors import AlprError
+from ._services import CamerasService, PhotosService, RecognitionsService
+from ._upload import Form
+from ._version import DEFAULT_BASE_URL, VERSION
+
+Transport = Callable[[str, str, dict[str, str], "bytes | None", float], "tuple[int, dict[str, str], bytes]"]
+"""Sends one request: (method, url, headers, body, timeout) -> (status, headers in lower case, body)."""
+
+
+class _RefuseRedirects(urllib.request.HTTPRedirectHandler):
+    """The API never redirects, and a redirect would carry the key to wherever it points."""
+
+    def redirect_request(self, req: Any, fp: Any, code: int, msg: str, headers: Any, newurl: str) -> Any:
+        raise AlprError(code, "redirect_refused", "the server answered a redirect; the SDK does not follow redirects, so the API key is never sent elsewhere")
+
+
+_OPENER = urllib.request.build_opener(_RefuseRedirects)
+
+
+def urllib_transport(method: str, url: str, headers: dict[str, str], body: bytes | None, timeout: float) -> tuple[int, dict[str, str], bytes]:
+    """The standard library's HTTP, so the SDK depends on nothing. It refuses redirects."""
+    request = urllib.request.Request(url, data=body, headers=headers, method=method)
+    try:
+        with _OPENER.open(request, timeout=timeout) as response:
+            return response.status, {key.lower(): value for key, value in response.headers.items()}, response.read()
+    except urllib.error.HTTPError as error:
+        with error:
+            return error.code, {key.lower(): value for key, value in error.headers.items()}, error.read()
+
+
+def _check_base_url(base_url: str) -> None:
+    """Raises ValueError unless base_url is https, or http to localhost, 127.0.0.0/8 or ::1."""
+    try:
+        parts = urlsplit(base_url)
+        host = (parts.hostname or "").lower()
+    except ValueError:
+        raise ValueError("alpr: the base URL must be https (http is accepted only for localhost, 127.0.0.0/8 and ::1), so the API key is never sent in clear text") from None
+    try:
+        loopback = host == "localhost" or ipaddress.ip_address(host).is_loopback
+    except ValueError:
+        loopback = False
+    secure = parts.scheme.lower() == "https" or (parts.scheme.lower() == "http" and loopback)
+    if not host or not secure:
+        raise ValueError("alpr: the base URL must be https (http is accepted only for localhost, 127.0.0.0/8 and ::1), so the API key is never sent in clear text")
+
+
+class Alpr:
+    """Alpr.sh's API with one workspace's API key.
+
+    The key (``alpr_live_…``) says the workspace and the scopes the calls may use.
+
+        alpr = Alpr(os.environ["ALPR_API_KEY"])
+        result = alpr.photos.recognize({"image": photo})
+        for reading in alpr.recognitions.list_iter(plate="BRA"):
+            ...
+    """
+
+    def __init__(self, api_key: str, *, base_url: str = DEFAULT_BASE_URL, timeout: float = 30.0, transport: Transport | None = None) -> None:
+        self._api_key = api_key
+        self._base_url = base_url.rstrip("/")
+        _check_base_url(self._base_url)
+        self._timeout = timeout
+        self._transport = transport or urllib_transport
+        self.cameras = CamerasService(self)
+        self.photos = PhotosService(self)
+        self.recognitions = RecognitionsService(self)
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        query: dict[str, Any] | None = None,
+        form: Form | None = None,
+        api_key: str | None = None,
+    ) -> Any:
+        """Calls the API and answers its decoded JSON body (None for a 204); a refusal raises AlprError."""
+        url = self._base_url + path
+        values = {name: str(value) for name, value in (query or {}).items() if value is not None and value != ""}
+        if values:
+            url += "?" + urlencode(values)
+        headers = {
+            "Authorization": f"Bearer {api_key or self._api_key}",
+            "Accept": "application/json",
+            "User-Agent": f"alpr-python/{VERSION}",
+        }
+        data = None
+        if form is not None:
+            data, headers["Content-Type"] = form.encode()
+        status, response_headers, raw = self._transport(method, url, headers, data, self._timeout)
+        if status >= 300:
+            raise AlprError.from_response(status, response_headers, raw)
+        if status == 204 or not raw:
+            return None
+        return json.loads(raw)

alpr_sdk-0.1.0/src/alpr/_core.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+from typing import Any, Protocol
+from urllib.parse import quote
+
+from ._upload import Form
+
+
+class Requester(Protocol):
+    """What a service calls the API through."""
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        query: dict[str, Any] | None = None,
+        form: Form | None = None,
+        api_key: str | None = None,
+    ) -> Any: ...
+
+
+def segment(value: str) -> str:
+    """A path parameter, escaped."""
+    return quote(value, safe="")

alpr_sdk-0.1.0/src/alpr/_errors.py

@@ -0,0 +1,44 @@
+from __future__ import annotations
+
+import json
+from collections.abc import Mapping
+from typing import Any
+
+
+class AlprError(Exception):
+    """A request the API refused.
+
+    ``code`` is the API's: invalid_api_key, insufficient_scope,
+    insufficient_credits, missing image, invalid_image, invalid_option,
+    image_too_large, no_plate, not_found, image_unavailable, rate_limited,
+    engine_unavailable or storage_unavailable. ``fields`` says, when the API
+    names them, what is wrong with each field. ``retry_after`` is how many
+    seconds to wait on a 429.
+    """
+
+    def __init__(self, status: int, code: str, message: str = "", fields: dict[str, list[str]] | None = None, retry_after: int | None = None) -> None:
+        super().__init__(f"alpr: {status} {code}: {message}" if message else f"alpr: {status} {code}")
+        self.status = status
+        self.code = code
+        self.message = message
+        self.fields = fields or {}
+        self.retry_after = retry_after
+
+    @classmethod
+    def from_response(cls, status: int, headers: Mapping[str, str], body: bytes) -> AlprError:
+        data: dict[str, Any] = {}
+        try:
+            loaded = json.loads(body or b"{}")
+            if isinstance(loaded, dict):
+                data = loaded
+        except ValueError:
+            pass  # A refusal without a JSON body is still a refusal.
+        code, message, fields = data.get("error"), data.get("message"), data.get("fields")
+        retry_after = headers.get("retry-after", "").strip()
+        return cls(
+            status,
+            code if isinstance(code, str) else "",
+            message if isinstance(message, str) else "",
+            fields if isinstance(fields, dict) else None,
+            int(retry_after) if retry_after.isascii() and retry_after.isdigit() and len(retry_after) < 10 else None,
+        )

alpr_sdk-0.1.0/src/alpr/_pagination.py

@@ -0,0 +1,34 @@
+from __future__ import annotations
+
+from collections.abc import Callable, Iterator
+from dataclasses import dataclass
+from typing import Any, Generic, TypeVar
+
+T = TypeVar("T")
+
+
+@dataclass(frozen=True)
+class Page(Generic[T]):
+    """One page of a list: its items, and the cursor of the next page."""
+
+    items: list[T]
+    next: str | None
+    """The cursor to ask the next page with; None on the last page."""
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any], item: Callable[[dict[str, Any]], T], next_field: str) -> Page[T]:
+        cursor = data.get(next_field)
+        return cls(items=[item(each) for each in data.get("data") or []], next=cursor if isinstance(cursor, str) and cursor else None)
+
+
+def iterate(fetch: Callable[[str | None], Page[T]], first: str | None = None) -> Iterator[T]:
+    """Walks pages from the cursor ``first`` (the newest page when None) until the last one,
+    yielding every item. It ends at the first error, which it raises, and when the next cursor
+    is the one just used: a cursor that does not move would ask for the same page forever."""
+    cursor = first
+    while True:
+        result = fetch(cursor)
+        yield from result.items
+        if not result.next or result.next == cursor:
+            return
+        cursor = result.next

alpr_sdk-0.1.0/src/alpr/_services.py

@@ -0,0 +1,88 @@
+# Code generated by sdk/generator. DO NOT EDIT.
+
+from __future__ import annotations
+
+import builtins
+from collections.abc import Iterator
+
+from . import models
+from ._core import Requester, segment
+from ._pagination import Page, iterate
+from ._upload import Form
+
+
+class CamerasService:
+    """The API's cameras."""
+
+    def __init__(self, client: Requester) -> None:
+        self._client = client
+
+    def list(self, *, api_key: str | None = None) -> builtins.list[models.Camera]:
+        """Listar as câmeras."""
+        data = self._client.request("GET", "/api/v1/cameras", api_key=api_key)
+        return [models.Camera.from_dict(item) for item in data.get("data") or []]
+
+
+class PhotosService:
+    """The API's photos."""
+
+    def __init__(self, client: Requester) -> None:
+        self._client = client
+
+    def detect(self, params: models.PhotosDetectParams, *, api_key: str | None = None) -> models.PhotoDetection:
+        """Localizar as placas de uma foto."""
+        form = Form()
+        form.file("image", params["image"])
+        if params.get("image_mode") is not None:
+            form.text("image_mode", params["image_mode"])
+        if params.get("lpr_confidence") is not None:
+            form.text("lpr_confidence", params["lpr_confidence"])
+        if params.get("min_ocr_confidence") is not None:
+            form.text("min_ocr_confidence", params["min_ocr_confidence"])
+        data = self._client.request("POST", "/api/v1/detect", form=form, api_key=api_key)
+        return models.PhotoDetection.from_dict(data)
+
+    def ocr(self, params: models.PhotosOCRParams, *, api_key: str | None = None) -> models.PlateReading:
+        """Ler uma placa já recortada."""
+        form = Form()
+        form.file("image", params["image"])
+        data = self._client.request("POST", "/api/v1/ocr", form=form, api_key=api_key)
+        return models.PlateReading.from_dict(data)
+
+    def recognize(self, params: models.PhotosRecognizeParams, *, api_key: str | None = None) -> models.PhotoRecognition:
+        """Ler as placas de uma foto."""
+        form = Form()
+        form.file("image", params["image"])
+        if params.get("image_mode") is not None:
+            form.text("image_mode", params["image_mode"])
+        if params.get("lpr_confidence") is not None:
+            form.text("lpr_confidence", params["lpr_confidence"])
+        if params.get("min_ocr_confidence") is not None:
+            form.text("min_ocr_confidence", params["min_ocr_confidence"])
+        data = self._client.request("POST", "/api/v1/recognize", form=form, api_key=api_key)
+        return models.PhotoRecognition.from_dict(data)
+
+
+class RecognitionsService:
+    """The API's recognitions."""
+
+    def __init__(self, client: Requester) -> None:
+        self._client = client
+
+    def image(self, id: str, *, api_key: str | None = None) -> models.DetectionImageLink:
+        """Imagem de uma leitura."""
+        data = self._client.request("GET", "/api/v1/detections/" + segment(id) + "/image", api_key=api_key)
+        return models.DetectionImageLink.from_dict(data)
+
+    def list(self, *, before: str | None = None, plate: str | None = None, camera: str | None = None, source: str | None = None, api_key: str | None = None) -> Page[models.Recognition]:
+        """Listar as leituras. One page; ``list_iter`` walks every page.
+
+        ``before`` is the cursor the previous page answered as ``next``; None asks for the newest page.
+        """
+        data = self._client.request("GET", "/api/v1/recognitions", query={"before": before, "plate": plate, "camera": camera, "source": source}, api_key=api_key)
+        return Page.from_dict(data, models.Recognition.from_dict, "next")
+
+    def list_iter(self, *, before: str | None = None, plate: str | None = None, camera: str | None = None, source: str | None = None, api_key: str | None = None) -> Iterator[models.Recognition]:
+        """Walks every page of recognitions:list, item by item, from ``before`` (the newest when None)."""
+        return iterate(lambda cursor: self.list(before=cursor, plate=plate, camera=camera, source=source, api_key=api_key), before)
+