justrouting 0.1.0__py3-none-any.whl

justrouting/__init__.py

@@ -0,0 +1,129 @@
+"""JustRouting Python client.
+
+Official Python client for the JustRouting API — routing, distance
+matrices, and vehicle routing optimization across Southeast Asia.
+
+    client = justrouting.Client("YOUR_API_KEY")
+
+    route = client.routes.get(justrouting.RouteRequest(
+        origin=[103.8198, 1.3521],
+        destination=[103.9915, 1.3644],
+    ))
+    print(f"Distance: {route.distance / 1000:.1f} km")
+
+Coordinates are always [longitude, latitude], the order used by GeoJSON,
+OSRM and VROOM. Failed calls raise a subclass of [justrouting.Error] —
+see [justrouting.NoRouteError] and friends.
+
+The package has no dependencies outside the standard library.
+"""
+
+from .client import Client
+from .consts import DEFAULT_BASE_URL, DEFAULT_PROFILE, VERSION
+from .error import (
+    CrossCountryError,
+    DecodeError,
+    Error,
+    InvalidCoordinatesError,
+    InvalidRequestError,
+    JustRoutingError,
+    NoRouteError,
+    PlanLimitExceededError,
+    QuotaExceededError,
+    RateLimitedError,
+    TransportError,
+    UnauthorizedError,
+    UpstreamUnavailableError,
+)
+from .geo import Geometry, LineString, Point, Waypoint
+from .health import Health, HealthService
+from .matrix import MatrixRequest, MatrixResponse, MatrixService
+from .optimization import (
+    Job,
+    OptimizationOptions,
+    OptimizationRequest,
+    OptimizationService,
+    RouteStep,
+    Shipment,
+    ShipmentStep,
+    Solution,
+    Summary,
+    TimeWindow,
+    Unassigned,
+    Vehicle,
+    VehicleRoute,
+)
+from .routes import (
+    Annotation,
+    Intersection,
+    Lane,
+    Leg,
+    Maneuver,
+    Route,
+    RouteRequest,
+    RouteResponse,
+    RoutesService,
+    Step,
+)
+
+__version__ = VERSION
+
+__all__ = [
+    # Client
+    "Client",
+    "VERSION",
+    "DEFAULT_BASE_URL",
+    "DEFAULT_PROFILE",
+    # Errors
+    "JustRoutingError",
+    "Error",
+    "UnauthorizedError",
+    "RateLimitedError",
+    "QuotaExceededError",
+    "PlanLimitExceededError",
+    "CrossCountryError",
+    "InvalidCoordinatesError",
+    "NoRouteError",
+    "UpstreamUnavailableError",
+    "InvalidRequestError",
+    "TransportError",
+    "DecodeError",
+    # Geo
+    "Point",
+    "Geometry",
+    "LineString",
+    "Waypoint",
+    # Services
+    "RoutesService",
+    "MatrixService",
+    "OptimizationService",
+    "HealthService",
+    # Routes
+    "RouteRequest",
+    "RouteResponse",
+    "Route",
+    "Leg",
+    "Step",
+    "Maneuver",
+    "Intersection",
+    "Lane",
+    "Annotation",
+    # Matrix
+    "MatrixRequest",
+    "MatrixResponse",
+    # Optimization
+    "OptimizationRequest",
+    "OptimizationOptions",
+    "TimeWindow",
+    "Vehicle",
+    "Job",
+    "ShipmentStep",
+    "Shipment",
+    "Solution",
+    "Summary",
+    "VehicleRoute",
+    "RouteStep",
+    "Unassigned",
+    # Health
+    "Health",
+]

justrouting/client.py

@@ -0,0 +1,139 @@
+"""The JustRouting client.
+
+A client is created with an API key and, optionally, keyword options::
+
+    client = justrouting.Client("YOUR_API_KEY")
+
+    route = client.routes.get(justrouting.RouteRequest(
+        origin=[103.8198, 1.3521],
+        destination=[103.9915, 1.3644],
+    ))
+    print(f"Distance: {route.distance / 1000:.1f} km")
+
+Coordinates are always [longitude, latitude], the order used by GeoJSON,
+OSRM and VROOM. Every call accepts an optional ``timeout`` argument in
+seconds that bounds the whole retry sequence, like a context deadline in
+the Go client.
+
+Failed calls raise a subclass of [justrouting.Error]. Use ``except`` clauses
+for control flow and [justrouting.Error] when the status code or raw body is
+needed::
+
+    try:
+        route = client.routes.get(req)
+    except justrouting.RateLimitedError:
+        # back off and retry later
+
+Unlike the Go client, invalid constructor options raise ``ValueError``
+immediately — Python constructors can fail, so there is no need to defer
+the error to the first request.
+
+The package has no dependencies outside the standard library.
+"""
+
+from __future__ import annotations
+
+import urllib.parse
+from typing import Callable, Optional
+
+from .consts import DEFAULT_BASE_URL, DEFAULT_PROFILE, VERSION
+from .health import HealthService
+from .matrix import MatrixService
+from .optimization import OptimizationService
+from .routes import RoutesService
+from .transport import Transport, default_backoff
+
+__all__ = [
+    "Client",
+    "VERSION",
+    "DEFAULT_BASE_URL",
+    "DEFAULT_PROFILE",
+]
+
+_DEFAULT_MAX_RETRIES = 2
+_DEFAULT_TIMEOUT = 30.0
+
+
+def _validate_base_url(raw: str) -> str:
+    raw = raw.strip()
+    if not raw:
+        raise ValueError("justrouting: base_url must not be empty")
+    parts = urllib.parse.urlsplit(raw)
+    if not parts.scheme or not parts.netloc:
+        raise ValueError(f"justrouting: base_url {raw!r} is not an absolute URL")
+    return raw
+
+
+class Client:
+    """A JustRouting API client.
+
+    It is safe for concurrent use by multiple threads, and should be created
+    once and reused.
+
+    Args:
+        api_key: The API key, sent as an ``Authorization: Bearer`` header on
+            every request that needs it. An empty key is allowed but only
+            [HealthService.get] will work; every other call fails with
+            [UnauthorizedError] before any request is sent.
+        base_url: The API endpoint, default [DEFAULT_BASE_URL]. Target a
+            local or staging server with ``base_url="http://localhost:8080"``.
+            Any path is kept as a prefix for every request.
+        user_agent: Override the User-Agent header. Identifying your
+            application helps when diagnosing traffic against the API.
+        max_retries: How many times a failed request is retried, on top of
+            the initial attempt. The default is 2. Pass 0 to disable
+            retries. Only rate-limit (429), server (5xx) and transport
+            errors are retried; other 4xx responses are returned immediately.
+        backoff: Callable(attempt: int) -> float returning the delay in
+            seconds before retry ``attempt`` (1 for the first retry, 2 for
+            the second, and so on). The default is exponential backoff with
+            jitter, starting at 500ms and capped at 8s. A Retry-After
+            response header, when present, takes precedence.
+        timeout: Seconds allowed for a single HTTP attempt, like
+            ``http.Client.Timeout`` in Go. The default is 30. Use the
+            per-call ``timeout`` argument instead to bound the whole retry
+            sequence.
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        user_agent: Optional[str] = None,
+        max_retries: int = _DEFAULT_MAX_RETRIES,
+        backoff: Optional[Callable[[int], float]] = None,
+        timeout: Optional[float] = _DEFAULT_TIMEOUT,
+    ) -> None:
+        if max_retries < 0:
+            raise ValueError(
+                f"justrouting: max_retries must not be negative, got {max_retries}"
+            )
+        if user_agent is not None and not user_agent.strip():
+            raise ValueError("justrouting: user_agent must not be empty")
+        if backoff is not None and not callable(backoff):
+            raise ValueError("justrouting: backoff must be a callable")
+        if timeout is not None and timeout <= 0:
+            raise ValueError("justrouting: timeout must be positive or None")
+
+        self._transport = Transport(
+            api_key=api_key.strip(),
+            base_url=_validate_base_url(base_url),
+            user_agent=user_agent or f"justrouting-py/{VERSION}",
+            max_retries=max_retries,
+            backoff=backoff or default_backoff,
+            timeout=timeout,
+        )
+
+        # Routes computes routes between two or more coordinates.
+        self.routes = RoutesService(self._transport)
+        # Matrix computes duration and distance matrices.
+        self.matrix = MatrixService(self._transport)
+        # Optimization solves vehicle routing problems.
+        self.optimization = OptimizationService(self._transport)
+        # Health reports API and upstream availability.
+        self.health = HealthService(self._transport)
+
+    def base_url(self) -> str:
+        """The API endpoint the client sends requests to."""
+        return self._transport.base_url

justrouting/consts.py

@@ -0,0 +1,30 @@
+"""Package constants, in a leaf module so services and the client can both
+import them without a cycle."""
+
+from __future__ import annotations
+
+import urllib.parse
+
+__all__ = [
+    "VERSION",
+    "DEFAULT_BASE_URL",
+    "DEFAULT_PROFILE",
+    "profile_or_default",
+]
+
+# VERSION is the client version, reported in the User-Agent header.
+VERSION = "0.1.0"
+
+# DEFAULT_BASE_URL is the hosted JustRouting API endpoint.
+DEFAULT_BASE_URL = "https://api.justrouting.tech"
+
+# DEFAULT_PROFILE is the routing profile used when a request leaves
+# Profile empty.
+DEFAULT_PROFILE = "driving"
+
+
+def profile_or_default(profile: str) -> str:
+    """The profile to use in a request path, with URL path escaping."""
+    if not profile:
+        return DEFAULT_PROFILE
+    return urllib.parse.quote(profile, safe="")

justrouting/error.py

@@ -0,0 +1,269 @@
+"""Errors raised by the JustRouting client.
+
+The Go client classifies failures with sentinel errors and ``errors.Is``.
+Python expresses the same classification as an exception hierarchy, so
+callers use ``except`` clauses instead of string matching::
+
+    try:
+        route = client.routes.get(req)
+    except justrouting.QuotaExceededError:
+        # daily allowance used up — retrying will not help
+    except justrouting.RateLimitedError:
+        # throttled; the client already retried
+    except justrouting.CrossCountryError:
+        # coordinates span more than one country
+    except justrouting.NoRouteError:
+        # no road connects these points
+
+``QuotaExceededError`` is a subclass of ``RateLimitedError``, mirroring how
+the Go client reports a daily-quota response as both
+``ErrQuotaExceeded`` and ``ErrRateLimited``.
+
+Every API failure — non-2xx responses and in-body engine failures alike —
+raises an ``Error`` (or one of its subclasses). Catch it when the status
+code, engine code, or raw body is needed::
+
+    except justrouting.Error as e:
+        log("HTTP %d: %s\n%s", e.status_code, e.message, e.body)
+
+``Error`` carries the same fields as the Go ``*Error`` struct. Failures
+that never produced an API response (local validation, transport, decoding)
+raise ``InvalidRequestError``, ``TransportError`` or ``DecodeError``
+instead, which are *not* subclasses of ``Error``.
+"""
+
+import http.client
+import json
+
+__all__ = [
+    "JustRoutingError",
+    "Error",
+    "UnauthorizedError",
+    "RateLimitedError",
+    "QuotaExceededError",
+    "PlanLimitExceededError",
+    "CrossCountryError",
+    "InvalidCoordinatesError",
+    "NoRouteError",
+    "UpstreamUnavailableError",
+    "InvalidRequestError",
+    "TransportError",
+    "DecodeError",
+]
+
+# maxErrorBodyBytes bounds how much of a response body is retained on an
+# Error, so that a large or misbehaving upstream cannot balloon a log line.
+_MAX_ERROR_BODY_BYTES = 8 << 10
+
+
+class JustRoutingError(Exception):
+    """Base class of every error raised by this package."""
+
+
+class Error(JustRoutingError):
+    """A failed API call.
+
+    It is raised whenever the API responds with a non-2xx status, and also
+    when a 2xx response carries an in-body failure code — the routing and
+    optimization engines can both report errors alongside HTTP 200.
+
+    Attributes:
+        status_code: The HTTP status of the response. Zero for errors that
+            were produced without an HTTP response, such as local validation.
+        message: The human-readable reason reported by the API.
+        osrm_code: The routing engine's status code, such as ``"NoRoute"``
+            or ``"InvalidValue"``. Empty when the error did not come from
+            the routing engine.
+        vroom_code: The optimization engine's non-zero status code. Zero
+            when the error did not come from the optimization engine.
+        body: The raw response body, truncated to a sane limit. Useful for
+            logging responses this package does not model.
+    """
+
+    def __init__(
+        self,
+        message: str = "",
+        *,
+        status_code: int = 0,
+        osrm_code: str = "",
+        vroom_code: int = 0,
+        body: bytes = b"",
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.status_code = status_code
+        self.osrm_code = osrm_code
+        self.vroom_code = vroom_code
+        self.body = body
+
+    def __str__(self) -> str:
+        # A zero status means the error was produced without an HTTP
+        # response; the message then already carries the full text.
+        if self.status_code == 0:
+            return self.message
+        parts = ["justrouting: "]
+        parts.append(f"HTTP {self.status_code}")
+        if self.osrm_code:
+            parts.append(f" ({self.osrm_code})")
+        elif self.vroom_code:
+            parts.append(f" (optimization code {self.vroom_code})")
+        if self.message:
+            parts.append(f": {self.message}")
+        return "".join(parts)
+
+
+class UnauthorizedError(Error):
+    """The API key is missing, invalid or revoked."""
+
+
+class RateLimitedError(Error):
+    """The request was throttled (per-second limit or daily quota)."""
+
+
+class QuotaExceededError(RateLimitedError):
+    """The plan's daily request quota is used up.
+
+    Retrying before the quota resets will not help. Subclasses
+    ``RateLimitedError`` because quota exhaustion is a form of throttling.
+    """
+
+
+class PlanLimitExceededError(Error):
+    """The request is larger than the plan allows — too many matrix
+    coordinates, jobs, or vehicles."""
+
+
+class CrossCountryError(Error):
+    """The coordinates span more than one country.
+
+    Every coordinate in a request must fall within a single country.
+    """
+
+
+class InvalidCoordinatesError(Error):
+    """A coordinate was malformed, out of range, or could not be parsed."""
+
+
+class NoRouteError(Error):
+    """No route exists between the given coordinates."""
+
+
+class UpstreamUnavailableError(Error):
+    """The routing engine behind the API could not be reached.
+
+    This is usually transient.
+    """
+
+
+class InvalidRequestError(Error):
+    """The request was rejected before being sent because required fields
+    were missing or inconsistent.
+
+    These errors carry no HTTP status; the message holds the reason.
+    """
+
+
+class TransportError(JustRoutingError):
+    """A network-level failure while contacting the API.
+
+    The original exception is available as ``__cause__``. Transport errors
+    are transient and are retried like 429 and 5xx responses.
+    """
+
+
+class DecodeError(JustRoutingError):
+    """A successful response could not be decoded.
+
+    The original exception is available as ``__cause__``.
+    """
+
+
+def _truncate(body: bytes, max_bytes: int) -> bytes:
+    if len(body) <= max_bytes:
+        return body
+    return body[:max_bytes]
+
+
+def osrm_status_error(code: str, message: str) -> "Error | None":
+    """Convert a routing engine status code into an Error, or None when the
+    response was successful."""
+    if not code or code.lower() == "ok":
+        return None
+    if not message:
+        message = f"routing engine returned {code}"
+    cls = _classify_error(http.client.OK, message, code)
+    return cls(status_code=http.client.OK, osrm_code=code, message=message)
+
+
+def error_from_response(status_code: int, body: bytes) -> "Error":
+    """Build the right Error subclass for an HTTP error response.
+
+    Bodies are classified by shape rather than Content-Type: some API
+    handlers emit a JSON body while leaving the header set to text/plain.
+    """
+    message, osrm_code, vroom_code = "", "", 0
+
+    payload = None
+    try:
+        stripped = body.strip()
+        if stripped:
+            payload = json.loads(stripped)
+    except ValueError:
+        payload = None
+
+    if isinstance(payload, dict):
+        # {"error": ...}                       gateway errors
+        # {"code": "NoRoute", "message": ...}  routing engine (string code)
+        # {"code": 3, "error": ...}            optimization engine (int code)
+        message = payload.get("error") or payload.get("message") or ""
+        code = payload.get("code")
+        if isinstance(code, str) and code.lower() != "ok":
+            osrm_code = code
+        elif isinstance(code, int):
+            vroom_code = code
+
+    if not message:
+        message = _fallback_message(status_code, body)
+
+    cls = _classify_error(status_code, message, osrm_code)
+    return cls(
+        status_code=status_code,
+        message=message,
+        osrm_code=osrm_code,
+        vroom_code=vroom_code,
+        body=_truncate(body, _MAX_ERROR_BODY_BYTES),
+    )
+
+
+def _classify_error(status_code: int, message: str, osrm_code: str):
+    """Pick the exception class for a failure, in the same priority order
+    the Go client's Error.Is uses."""
+    msg = message.lower()
+    if status_code == http.client.UNAUTHORIZED:
+        return UnauthorizedError
+    if status_code == http.client.TOO_MANY_REQUESTS:
+        if "daily quota" in msg:
+            return QuotaExceededError
+        return RateLimitedError
+    if status_code == http.client.BAD_GATEWAY or "upstream unavailable" in msg:
+        return UpstreamUnavailableError
+    if "cross-country" in msg:
+        return CrossCountryError
+    if "exceeds plan limit" in msg or "too many jobs" in msg or "too many vehicles" in msg:
+        return PlanLimitExceededError
+    if osrm_code.lower() == "noroute":
+        return NoRouteError
+    if "cannot parse coordinates" in msg or "invalid coordinates" in msg:
+        return InvalidCoordinatesError
+    return Error
+
+
+def _fallback_message(status_code: int, body: bytes) -> str:
+    """Produce a message for responses with no recognisable error field,
+    such as an HTML error page from an intermediary proxy."""
+    s = body.decode("utf-8", errors="replace").strip()
+    if s and not s.startswith("{") and not s.startswith("<") and len(s) <= 200:
+        return s
+    if text := http.client.responses.get(status_code, ""):
+        return text.lower()
+    return "unexpected response"