alpr-sdk 0.1.0__py3-none-any.whl

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/_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/_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/_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/_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/_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)
+

alpr/_upload.py

@@ -0,0 +1,57 @@
+from __future__ import annotations
+
+import secrets
+
+
+def image_type(data: bytes) -> tuple[str, str]:
+    """The content type and file name of a photo: JPEG and PNG are what the API reads,
+    and anything else goes as bytes for the API to refuse."""
+    if data.startswith(b"\xff\xd8\xff"):
+        return "image/jpeg", "photo.jpg"
+    if data.startswith(b"\x89PNG\r\n\x1a\n"):
+        return "image/png", "photo.png"
+    return "application/octet-stream", "photo"
+
+
+def field_text(value: str | int | float | bool) -> str:
+    """A value as the text of a multipart field: floats in the shortest decimal form (0.5, 1)."""
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    if isinstance(value, float):
+        text = repr(value)
+        return text[:-2] if text.endswith(".0") else text
+    return str(value)
+
+
+def _escape(name: str) -> str:
+    return name.replace("\\", "\\\\").replace('"', '\\"').replace("\r", "%0D").replace("\n", "%0A")
+
+
+class Form:
+    """A multipart/form-data body: one file and the text fields beside it."""
+
+    def __init__(self) -> None:
+        self._parts: list[tuple[str, bytes | None, str]] = []
+
+    def text(self, name: str, value: str | int | float | bool) -> None:
+        """Adds a text field."""
+        self._parts.append((name, None, field_text(value)))
+
+    def file(self, name: str, data: bytes) -> None:
+        """Adds the photo, named and typed by what its first bytes say it is."""
+        self._parts.append((name, bytes(data), ""))
+
+    def encode(self) -> tuple[bytes, str]:
+        """The body and its Content-Type, boundary included."""
+        boundary = secrets.token_hex(24)
+        out = bytearray()
+        for name, data, value in self._parts:
+            out += f"--{boundary}\r\n".encode()
+            if data is None:
+                out += f'Content-Disposition: form-data; name="{_escape(name)}"\r\n\r\n'.encode() + value.encode() + b"\r\n"
+                continue
+            kind, filename = image_type(data)
+            out += f'Content-Disposition: form-data; name="{_escape(name)}"; filename="{filename}"\r\nContent-Type: {kind}\r\n\r\n'.encode()
+            out += data + b"\r\n"
+        out += f"--{boundary}--\r\n".encode()
+        return bytes(out), f"multipart/form-data; boundary={boundary}"

alpr/_version.py

@@ -0,0 +1,10 @@
+# Code generated by sdk/generator. DO NOT EDIT.
+
+VERSION = "0.1.0"
+"""This SDK's version."""
+
+API_VERSION = "1.0.0"
+"""The contract this SDK was generated from."""
+
+DEFAULT_BASE_URL = "https://alpr.sh"
+"""Alpr.sh's API. The workspace is the API key's: alpr_live_…."""

alpr/models.py

@@ -0,0 +1,388 @@
+# Code generated by sdk/generator. DO NOT EDIT.
+"""The resources Alpr.sh's API answers and the bodies its writes take."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Literal, NotRequired, Self, TypedDict
+
+
+@dataclass(frozen=True)
+class Camera:
+    """Camera is a resource of Alpr.sh's API."""
+
+    created_at: str
+    enabled: bool
+    id: str
+    location: str
+    """O endereço da câmera como texto; vazio se não foi informado."""
+    name: str
+    protocol: Literal["rtsp", "rtmp", "hls", "http", "hikconnect", "hikcloud", "rtmppush"]
+    """Como a câmera é lida. Nunca traz o endereço do stream, usuário nem senha."""
+    reading_area: ReadingArea | None
+    """Nulo quando a câmera lê a imagem inteira."""
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> Self:
+        """Reads the object the API answered; the JSON names are the API's, the attributes snake_case."""
+        return cls(
+            created_at=data["createdAt"],
+            enabled=data["enabled"],
+            id=data["id"],
+            location=data["location"],
+            name=data["name"],
+            protocol=data["protocol"],
+            reading_area=None if data.get("readingArea") is None else ReadingArea.from_dict(data["readingArea"]),
+        )
+
+
+@dataclass(frozen=True)
+class DetectedPlate:
+    """DetectedPlate is a resource of Alpr.sh's API."""
+
+    conf: float
+    """Confiança do detector, de 0 a 100, com uma casa."""
+    coordinate_bottom: int
+    coordinate_left: int
+    coordinate_right: int
+    coordinate_top: int
+    created_at: str
+    plate_type: Literal["car"]
+    time: str
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> Self:
+        """Reads the object the API answered; the JSON names are the API's, the attributes snake_case."""
+        return cls(
+            conf=float(data["conf"]),
+            coordinate_bottom=data["coordinateBottom"],
+            coordinate_left=data["coordinateLeft"],
+            coordinate_right=data["coordinateRight"],
+            coordinate_top=data["coordinateTop"],
+            created_at=data["createdAt"],
+            plate_type=data["plateType"],
+            time=data["time"],
+        )
+
+
+@dataclass(frozen=True)
+class DetectionImageLink:
+    """DetectionImageLink is a resource of Alpr.sh's API."""
+
+    detection_id: str
+    expires_in: int
+    """Segundos de validade do link (300)."""
+    image_url: str
+    """Endereço absoluto de GET /api/v1/detections/{id}/image/file, assinado; abra-o como veio."""
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> Self:
+        """Reads the object the API answered; the JSON names are the API's, the attributes snake_case."""
+        return cls(
+            detection_id=data["detectionId"],
+            expires_in=data["expiresIn"],
+            image_url=data["imageUrl"],
+        )
+
+
+@dataclass(frozen=True)
+class PhotoDetection:
+    """PhotoDetection is a resource of Alpr.sh's API."""
+
+    image_height: int
+    image_width: int
+    plates: list[DetectedPlate]
+    """Onde há placa, sem o texto; o detector não filtra pelo formato brasileiro. Sem placa, []."""
+    processing_time_ms: int
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> Self:
+        """Reads the object the API answered; the JSON names are the API's, the attributes snake_case."""
+        return cls(
+            image_height=data["imageHeight"],
+            image_width=data["imageWidth"],
+            plates=[DetectedPlate.from_dict(item0) for item0 in data["plates"]],
+            processing_time_ms=data["processingTimeMs"],
+        )
+
+
+@dataclass(frozen=True)
+class PhotoRecognition:
+    """PhotoRecognition is a resource of Alpr.sh's API."""
+
+    credits_remaining: int
+    """Créditos que sobraram depois desta leitura."""
+    image_height: int
+    image_width: int
+    plates: list[RecognizedPlate]
+    """Só as placas válidas no Brasil (ABC1234 ou ABC1D23); sem placa, []."""
+    processing_time_ms: int
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> Self:
+        """Reads the object the API answered; the JSON names are the API's, the attributes snake_case."""
+        return cls(
+            credits_remaining=data["creditsRemaining"],
+            image_height=data["imageHeight"],
+            image_width=data["imageWidth"],
+            plates=[RecognizedPlate.from_dict(item0) for item0 in data["plates"]],
+            processing_time_ms=data["processingTimeMs"],
+        )
+
+
+@dataclass(frozen=True)
+class PlateReading:
+    """PlateReading is a resource of Alpr.sh's API."""
+
+    confidence: float
+    """Confiança da leitura, de 0 a 1 com quatro casas (nas outras rotas conf vai de 0 a 100)."""
+    credits_remaining: int
+    """Créditos que sobraram depois desta leitura."""
+    detection_id: str | None
+    """Hoje sempre nulo: a leitura de uma placa recortada não é guardada."""
+    latency_ms: int
+    plate: str
+    """O texto lido, sem hífen, maiúsculo; não é validado pelo formato brasileiro."""
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> Self:
+        """Reads the object the API answered; the JSON names are the API's, the attributes snake_case."""
+        return cls(
+            confidence=float(data["confidence"]),
+            credits_remaining=data["creditsRemaining"],
+            detection_id=data.get("detectionId"),
+            latency_ms=data["latencyMs"],
+            plate=data["plate"],
+        )
+
+
+@dataclass(frozen=True)
+class ReadingArea:
+    """ReadingArea is a resource of Alpr.sh's API."""
+
+    box: ReadingAreaBox
+    """A caixa envolvente, em frações da imagem (0 a 1); é o que o motor lê."""
+    points: list[list[float]]
+    """Os cantos do polígono, de 3 a 16 pares [x, y] em frações da imagem; um retângulo traz os quatro cantos. Placas fora dele são ignoradas."""
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> Self:
+        """Reads the object the API answered; the JSON names are the API's, the attributes snake_case."""
+        return cls(
+            box=ReadingAreaBox.from_dict(data["box"]),
+            points=[[float(item1) for item1 in item0] for item0 in data["points"]],
+        )
+
+
+@dataclass(frozen=True)
+class ReadingAreaBox:
+    """A caixa envolvente, em frações da imagem (0 a 1); é o que o motor lê."""
+
+    height: float
+    width: float
+    x: float
+    y: float
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> Self:
+        """Reads the object the API answered; the JSON names are the API's, the attributes snake_case."""
+        return cls(
+            height=float(data["height"]),
+            width=float(data["width"]),
+            x=float(data["x"]),
+            y=float(data["y"]),
+        )
+
+
+@dataclass(frozen=True)
+class Recognition:
+    """Recognition is a resource of Alpr.sh's API."""
+
+    camera_id: str | None
+    """Nulo numa leitura feita pela API por foto."""
+    captured_at: str
+    """Com o deslocamento do fuso do Alpr.sh."""
+    conf: float
+    """De 0 a 100, com uma casa."""
+    id: str
+    plate: str
+    source: Literal["camera", "api"]
+    """camera: lida por uma câmera; api: enviada por foto."""
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> Self:
+        """Reads the object the API answered; the JSON names are the API's, the attributes snake_case."""
+        return cls(
+            camera_id=data.get("cameraId"),
+            captured_at=data["capturedAt"],
+            conf=float(data["conf"]),
+            id=data["id"],
+            plate=data["plate"],
+            source=data["source"],
+        )
+
+
+@dataclass(frozen=True)
+class RecognizedPlate:
+    """RecognizedPlate is a resource of Alpr.sh's API."""
+
+    char_confs: str
+    """Confiança de cada caractere, de 0 a 1 com duas casas, separadas por ponto e vírgula (\"0.99;0.98\")."""
+    conf: float
+    """Confiança da placa, de 0 a 100, com uma casa."""
+    coordinate_bottom: int
+    """Pixels da foto enviada."""
+    coordinate_left: int
+    coordinate_right: int
+    coordinate_top: int
+    created_at: str
+    """Igual a time."""
+    plate: str
+    """Sete caracteres, maiúsculos: ABC1234 ou ABC1D23 (Mercosul)."""
+    plate_type: Literal["car"]
+    """Sempre car; a API não informa país nem formato."""
+    time: str
+    """Instante da leitura, com o deslocamento do fuso do Alpr.sh."""
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> Self:
+        """Reads the object the API answered; the JSON names are the API's, the attributes snake_case."""
+        return cls(
+            char_confs=data["charConfs"],
+            conf=float(data["conf"]),
+            coordinate_bottom=data["coordinateBottom"],
+            coordinate_left=data["coordinateLeft"],
+            coordinate_right=data["coordinateRight"],
+            coordinate_top=data["coordinateTop"],
+            created_at=data["createdAt"],
+            plate=data["plate"],
+            plate_type=data["plateType"],
+            time=data["time"],
+        )
+
+
+@dataclass(frozen=True)
+class WebhookAlertTriggered:
+    """WebhookAlertTriggered is a resource of Alpr.sh's API."""
+
+    camera_id: str | None
+    """Ausente se a leitura não veio de uma câmera."""
+    captured_at: str
+    confidence: float
+    """De 0 a 1."""
+    event: Literal["alert.triggered"]
+    id: str
+    """O id do disparo."""
+    plate: str
+    recognition_id: str
+    """A leitura que disparou o alerta."""
+    rule_id: str
+    rule_name: str
+    skip: list[str] | None
+    """Os destinos que as listas de permitidos e de bloqueados excluíram deste disparo (internal, channel:<id>, partner:<id>). Presente só quando algum foi excluído; é informação, não há o que fazer com ela."""
+    tenant_id: str
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> Self:
+        """Reads the object the API answered; the JSON names are the API's, the attributes snake_case."""
+        return cls(
+            camera_id=data.get("camera_id"),
+            captured_at=data["captured_at"],
+            confidence=float(data["confidence"]),
+            event=data["event"],
+            id=data["id"],
+            plate=data["plate"],
+            recognition_id=data["recognition_id"],
+            rule_id=data["rule_id"],
+            rule_name=data["rule_name"],
+            skip=data.get("skip"),
+            tenant_id=data["tenant_id"],
+        )
+
+
+@dataclass(frozen=True)
+class WebhookRecognitionCreated:
+    """WebhookRecognitionCreated is a resource of Alpr.sh's API."""
+
+    camera_id: str | None
+    """Ausente numa leitura enviada por foto."""
+    captured_at: str
+    """UTC, com fração de segundo."""
+    confidence: float
+    """De 0 a 1 (na API de chave, conf vai de 0 a 100)."""
+    event: Literal["recognition.created"]
+    id: str
+    """O id da leitura; é o mesmo id de GET /api/v1/recognitions e de GET /api/v1/detections/{id}/image."""
+    plate: str
+    source: Literal["camera", "api"]
+    """camera: lida por uma câmera; api: enviada por foto."""
+    tenant_id: str
+    """O espaço de trabalho dono da leitura."""
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> Self:
+        """Reads the object the API answered; the JSON names are the API's, the attributes snake_case."""
+        return cls(
+            camera_id=data.get("camera_id"),
+            captured_at=data["captured_at"],
+            confidence=float(data["confidence"]),
+            event=data["event"],
+            id=data["id"],
+            plate=data["plate"],
+            source=data["source"],
+            tenant_id=data["tenant_id"],
+        )
+
+
+@dataclass(frozen=True)
+class WebhookTest:
+    """WebhookTest is a resource of Alpr.sh's API."""
+
+    event: Literal["webhook.test"]
+    id: str
+    sent_at: str
+    tenant_id: str
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> Self:
+        """Reads the object the API answered; the JSON names are the API's, the attributes snake_case."""
+        return cls(
+            event=data["event"],
+            id=data["id"],
+            sent_at=data["sent_at"],
+            tenant_id=data["tenant_id"],
+        )
+
+
+class PhotosDetectParams(TypedDict):
+    """The body of photos:detect."""
+
+    image: bytes
+    """A foto, JPEG ou PNG."""
+    image_mode: NotRequired[Literal["NONE"]]
+    """Só NONE é aceito."""
+    lpr_confidence: NotRequired[float]
+    """Piso de confiança do detector de placas."""
+    min_ocr_confidence: NotRequired[float]
+    """Piso de confiança da leitura dos caracteres."""
+
+
+class PhotosOCRParams(TypedDict):
+    """The body of photos:ocr."""
+
+    image: bytes
+    """A imagem da placa já recortada, JPEG ou PNG."""
+
+
+class PhotosRecognizeParams(TypedDict):
+    """The body of photos:recognize."""
+
+    image: bytes
+    """A foto, JPEG ou PNG."""
+    image_mode: NotRequired[Literal["NONE"]]
+    """Só NONE é aceito."""
+    lpr_confidence: NotRequired[float]
+    """Piso de confiança do detector de placas."""
+    min_ocr_confidence: NotRequired[float]
+    """Piso de confiança da leitura dos caracteres."""
+

alpr/webhooks.py

@@ -0,0 +1,162 @@
+# Code generated by sdk/generator. DO NOT EDIT.
+"""Verifying the webhooks Alpr.sh sends."""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import json
+import re
+import time
+from collections.abc import Iterable, Mapping
+from dataclasses import dataclass
+from typing import Any, TypeAlias
+
+from .models import WebhookAlertTriggered, WebhookRecognitionCreated, WebhookTest
+
+WEBHOOK_TOLERANCE_SECONDS = 300
+"""How far from now a webhook's timestamp may be."""
+
+_MAX_SIGNATURES = 6
+"""How many signatures a request may list: one for the secret in use and one for each secret still signing during a rotation."""
+
+_SIGNATURE = re.compile(r"sha256=[0-9a-fA-F]{64}")
+
+HeadersLike: TypeAlias = Mapping[str, str] | Iterable[tuple[str, str]]
+"""The request's headers: a mapping, or the (name, value) pairs of a web stack that repeats a header."""
+
+
+class WebhookVerificationError(Exception):
+    """A request Alpr.sh did not sign, or signed too long ago."""
+
+    def __init__(self, message: str = "alpr: webhook signature does not verify") -> None:
+        super().__init__(message)
+
+
+@dataclass(frozen=True)
+class AlertTriggeredWebhookEvent(WebhookAlertTriggered):
+    """The payload of
+    - ``alert.triggered``
+
+    The fields are the payload's, flat: there is no ``data`` wrapper.
+    """
+
+
+@dataclass(frozen=True)
+class RecognitionCreatedWebhookEvent(WebhookRecognitionCreated):
+    """The payload of
+    - ``recognition.created``
+
+    The fields are the payload's, flat: there is no ``data`` wrapper.
+    """
+
+
+@dataclass(frozen=True)
+class TestWebhookEvent(WebhookTest):
+    """The payload of
+    - ``webhook.test``
+
+    The fields are the payload's, flat: there is no ``data`` wrapper.
+    """
+
+
+@dataclass(frozen=True)
+class UnknownWebhookEvent:
+    """An event of a name this SDK does not know yet; its body is kept as it was sent."""
+
+    event: str
+    """The event's name."""
+    id: str
+    """The id the body carries, or empty."""
+    body: dict[str, Any]
+    """The whole body, decoded."""
+
+
+WebhookEvent: TypeAlias = (
+    AlertTriggeredWebhookEvent
+    | RecognitionCreatedWebhookEvent
+    | TestWebhookEvent
+    | UnknownWebhookEvent
+)
+"""A webhook Alpr.sh sent, verified: one class a payload, told apart with ``match``
+or ``isinstance``, or ``UnknownWebhookEvent`` for an event this SDK does not know yet."""
+
+
+def _event(raw: bytes) -> WebhookEvent:
+    try:
+        body = json.loads(raw)
+    except ValueError as error:
+        raise ValueError(f"alpr: the webhook body is not an event: {error}") from None
+    if not isinstance(body, dict) or not isinstance(body.get("event"), str) or not body["event"]:
+        raise ValueError("alpr: the webhook body is not an event")
+    name: str = body["event"]
+    try:
+        if name in ("alert.triggered",):
+            return AlertTriggeredWebhookEvent.from_dict(body)
+        if name in ("recognition.created",):
+            return RecognitionCreatedWebhookEvent.from_dict(body)
+        if name in ("webhook.test",):
+            return TestWebhookEvent.from_dict(body)
+    except (KeyError, TypeError, ValueError, AttributeError) as error:
+        raise ValueError(f"alpr: the webhook body is not a {name} event: {error!r}") from None
+    sent = body.get("id")
+    return UnknownWebhookEvent(event=name, id=sent if isinstance(sent, str) else "", body=body)
+
+
+def _header(headers: HeadersLike, name: str) -> list[str]:
+    pairs = headers.items() if isinstance(headers, Mapping) else headers
+    return [value for key, value in pairs if key.lower() == name]
+
+
+def verify_webhook(secret: str, headers: HeadersLike, body: bytes | str) -> WebhookEvent:
+    """Checks a webhook Alpr.sh sent and answers its event.
+
+    Alpr.sh signs the headers ``X-Alprsh-Timestamp`` and ``X-Alprsh-Delivery-Id``
+    and the body: ``X-Alprsh-Signature`` carries ``sha256=`` and the hex
+    HMAC-SHA256 of ``{timestamp}.{delivery-id}.{body}`` under the endpoint's
+    secret (the whole ``whsec_…`` text, as it is), and more than one signature
+    while a secret is rotated: one matching is enough. Pass the body exactly as
+    it arrived, before parsing it, and deduplicate by the ``X-Alprsh-Delivery-Id``
+    header. A signature that does not verify raises ``WebhookVerificationError``;
+    an empty secret raises ``ValueError``; so does a body that is not an event.
+    """
+    return _verify_webhook_at(secret, headers, body, time.time())
+
+
+def verify_webhook_signature(secret: str, headers: HeadersLike, body: bytes | str) -> None:
+    """Checks a webhook's signature as :func:`verify_webhook` does, without reading its body."""
+    _verify_webhook_signature_at(secret, headers, body, time.time())
+
+
+def _verify_webhook_at(secret: str, headers: HeadersLike, body: bytes | str, now: float) -> WebhookEvent:
+    raw = body.encode() if isinstance(body, str) else body
+    _verify_webhook_signature_at(secret, headers, raw, now)
+    return _event(raw)
+
+
+def _verify_webhook_signature_at(secret: str, headers: HeadersLike, body: bytes | str, now: float) -> None:
+    if not secret:
+        raise ValueError("alpr: the webhook secret is empty")
+    raw = body.encode() if isinstance(body, str) else body
+    ids, stamps = _header(headers, "x-alprsh-delivery-id"), _header(headers, "x-alprsh-timestamp")
+    delivery_id, stamp = (ids[0] if ids else ""), (stamps[0] if stamps else "")
+    # Only ASCII digits: int() would also take a sign, spaces, underscores and other scripts' digits.
+    if not delivery_id or not (stamp.isascii() and stamp.isdigit()) or len(stamp) > 15:
+        raise WebhookVerificationError()
+    if abs(now - int(stamp)) > WEBHOOK_TOLERANCE_SECONDS:
+        raise WebhookVerificationError()
+    expected = hmac.new(secret.encode(), f"{stamp}.{delivery_id}.".encode() + raw, hashlib.sha256).digest()
+    listed = ",".join(_header(headers, "x-alprsh-signature")).split(",")
+    if len(listed) > _MAX_SIGNATURES:
+        raise WebhookVerificationError()
+    matched = False
+    for entry in listed:
+        entry = entry.strip()
+        # One malformed signature refuses the request. Every listed signature is
+        # compared, in constant time.
+        if not _SIGNATURE.fullmatch(entry):
+            raise WebhookVerificationError()
+        if hmac.compare_digest(bytes.fromhex(entry[len("sha256=") :]), expected):
+            matched = True
+    if not matched:
+        raise WebhookVerificationError()

alpr_sdk-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,14 @@
+alpr/__init__.py,sha256=3QL7b1frGZ8RxPMR6NibGNnfT5o_ExTPy52vGD0oBy4,1825
+alpr/_client.py,sha256=girLmeh_3b6ei6-oozNzGB_PDoQNGqXuK5b_HqOM3Pk,4629
+alpr/_core.py,sha256=1H12QXc5yChvxryMokPTyuEZnNTAsq1uZzz1h3dBfBA,524
+alpr/_errors.py,sha256=jftl3gVBIOYVw97tPUNeo5L41Jp31EaNaaSX58DD2UA,1847
+alpr/_pagination.py,sha256=PoCA8vXAvHHtWCevjBuTLstJgMe-sZW5sJp3idiU0N8,1291
+alpr/_services.py,sha256=XsbF1YZfaDcokycafRAS6SDXKosPEId7jWRB-GuAj_A,4111
+alpr/_upload.py,sha256=TNso4Q17KQn3vdoFBLHPcWnb3S6nX8uvOLyIZkZTfWM,2295
+alpr/_version.py,sha256=34t9pqk6kZ2sQcidaGGP4oBYT-niOFl_PfDvIQt-m4s,270
+alpr/models.py,sha256=nNtdoAzq7hTkSsDubO3ML3Rw4YJ2vJXruxySci1e3pg,13064
+alpr/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+alpr/webhooks.py,sha256=0V7BBxB7_4z3b_k0CK0aEJTRsrw4qvUnp9_PkXYOPlk,6378
+alpr_sdk-0.1.0.dist-info/METADATA,sha256=P4JojXdWhyfeyiw90iwcB6bnP5iF98iJaBm62VlcZEI,6580
+alpr_sdk-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+alpr_sdk-0.1.0.dist-info/RECORD,,

alpr_sdk-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any