fleetpull 0.1.0__py3-none-any.whl

fleetpull/timing/clock.py

@@ -0,0 +1,192 @@
+# src/fleetpull/timing/clock.py
+"""Time abstraction for fleetpull.
+
+Provides an injectable clock interface to avoid scattered
+``datetime.now()`` calls and enable deterministic time in tests.
+Anything in fleetpull that needs the current time — rate-limiter token
+refill, watermark computation, fetch-window resolution, run-ledger
+timestamps — takes a clock rather than calling the standard library
+directly. ``Clock`` is the Protocol defining the time-provider
+interface; ``SystemClock`` is the production implementation backed by
+system time; ``FrozenClock`` is the test implementation fixed at a
+specific moment.
+"""
+
+import time
+from dataclasses import dataclass
+from datetime import UTC, date, datetime, timedelta
+from typing import Protocol, runtime_checkable
+
+from fleetpull.timing.canon import require_utc
+
+__all__: list[str] = [
+    'Clock',
+    'FrozenClock',
+    'SystemClock',
+]
+
+
+@runtime_checkable
+class Clock(Protocol):
+    """
+    Interface for time providers in fleetpull.
+
+    Centralizes time access (no scattered ``datetime.now()`` calls),
+    enables deterministic time in tests, and enforces timezone-aware
+    UTC timestamps internally. All implementations must return
+    timezone-aware UTC datetimes.
+    """
+
+    def now_utc(self) -> datetime:
+        """
+        Return the current time as a timezone-aware UTC datetime.
+
+        Returns:
+            Timezone-aware datetime in UTC.
+        """
+        ...
+
+    def today_utc(self) -> date:
+        """
+        Return today's date in UTC.
+
+        Returns:
+            Current UTC date.
+        """
+        ...
+
+    def monotonic_seconds(self) -> float:
+        """
+        Return a monotonic timestamp for duration measurement.
+
+        Monotonic clocks are unaffected by NTP adjustments or DST changes,
+        making them suitable for measuring elapsed time.
+
+        Returns:
+            Monotonic time in seconds.
+        """
+        ...
+
+
+@dataclass(frozen=True, slots=True)
+class SystemClock:
+    """
+    Production clock backed by system wall-clock and monotonic timer.
+
+    Returns timezone-aware UTC datetimes. This is the default clock
+    for production use.
+    """
+
+    def now_utc(self) -> datetime:
+        """Return current UTC time."""
+        return datetime.now(tz=UTC)
+
+    def today_utc(self) -> date:
+        """Return current UTC date."""
+        return self.now_utc().date()
+
+    def monotonic_seconds(self) -> float:
+        """
+        Return monotonic time from ``time.perf_counter()``.
+
+        The invariant is monotonic, never wall clock.
+        ``time.perf_counter()`` is the deliberate choice over
+        ``time.monotonic()``: on Windows under CPython 3.12,
+        ``monotonic()`` is GetTickCount64 with roughly 15.6 ms
+        resolution, while ``perf_counter()`` is
+        QueryPerformanceCounter — and the test convention of real
+        threads with tiny waits needs the finer clock on exactly that
+        platform.
+        """
+        return time.perf_counter()
+
+
+class FrozenClock:
+    """
+    Deterministic clock for tests and reproducible runs.
+
+    Starts at a fixed UTC datetime and only advances when explicitly
+    mutated via ``advance()`` or ``set_time()``. Not thread-safe: keep
+    usage test-scoped or wrap externally.
+
+    Example:
+        >>> clock = FrozenClock(start_time_utc=datetime(2026, 1, 23, 12, tzinfo=UTC))
+        >>> clock.now_utc()
+        datetime.datetime(2026, 1, 23, 12, 0, tzinfo=datetime.timezone.utc)
+        >>> clock.advance(timedelta(hours=1))
+        >>> clock.now_utc().hour
+        13
+    """
+
+    __slots__ = ('_current_monotonic_seconds', '_current_time_utc')
+
+    def __init__(
+        self,
+        *,
+        start_time_utc: datetime,
+        start_monotonic_seconds: float = 0.0,
+    ) -> None:
+        """
+        Initialize a frozen clock.
+
+        Args:
+            start_time_utc: Initial time (must be timezone-aware UTC).
+            start_monotonic_seconds: Initial monotonic value (non-negative).
+
+        Raises:
+            ValueError: If start_time_utc is naive or not UTC (the
+                ``require_utc`` canonical-UTC guard).
+            ValueError: If start_monotonic_seconds is negative.
+        """
+        if start_monotonic_seconds < 0.0:
+            raise ValueError('start_monotonic_seconds must be non-negative')
+
+        self._current_time_utc: datetime = require_utc(start_time_utc)
+        self._current_monotonic_seconds: float = start_monotonic_seconds
+
+    def now_utc(self) -> datetime:
+        """Return the frozen UTC time."""
+        return self._current_time_utc
+
+    def today_utc(self) -> date:
+        """Return the frozen UTC date."""
+        return self._current_time_utc.date()
+
+    def monotonic_seconds(self) -> float:
+        """Return the frozen monotonic value."""
+        return self._current_monotonic_seconds
+
+    def advance(self, delta: timedelta) -> None:
+        """
+        Advance the clock by a duration.
+
+        Advances wall-clock and monotonic time together, keeping them
+        correlated the way real time behaves.
+
+        Args:
+            delta: Time to advance (must be non-negative).
+
+        Raises:
+            ValueError: If delta is negative.
+        """
+        if delta.total_seconds() < 0:
+            raise ValueError('delta must be non-negative')
+
+        self._current_time_utc += delta
+        self._current_monotonic_seconds += delta.total_seconds()
+
+    def set_time(self, new_time_utc: datetime) -> None:
+        """
+        Set the clock to a specific UTC time.
+
+        Does not adjust the monotonic counter — use ``advance()`` for
+        correlated wall/monotonic changes.
+
+        Args:
+            new_time_utc: New time (must be timezone-aware UTC).
+
+        Raises:
+            ValueError: If new_time_utc is naive or not UTC (the
+                ``require_utc`` canonical-UTC guard).
+        """
+        self._current_time_utc = require_utc(new_time_utc)

fleetpull/timing/codec.py

@@ -0,0 +1,122 @@
+# src/fleetpull/timing/codec.py
+"""Pure conversions between UTC datetimes and their wire/storage string forms.
+
+A leaf: stdlib plus the sibling ``canon`` module, nothing internal beyond
+this package. Converts our own outbound and persisted values — request
+parameters and DateWatermark state — between ``datetime`` and string. It
+never parses a provider response body; response timestamps are cast
+vectorized in the records layer.
+
+UTC discipline, enforced both directions (the canonical-UTC doctrine,
+``canon.py``):
+    - Encoders reject a naive or non-UTC datetime via ``require_utc`` — a
+      non-UTC value reaching here missed an ingress and is a bug, failed
+      loud.
+    - ``from_iso8601`` normalizes any offset to UTC and rejects a naive
+      result — an ISO string with no offset is ambiguous, never assumed UTC.
+      It is the string-ingress twin of ``canon.ensure_utc``.
+
+Because every internal timestamp is UTC end to end, DST and ambiguous-local
+bugs are structurally impossible.
+
+Bad input raises stdlib ``ValueError`` — a bad value is a caller bug or
+malformed input, never a ``FleetpullError``. The consuming boundary
+translates when it wants a typed failure (the config loader maps a user's
+bad date to ``ConfigurationError``). Keeping the raise stdlib is what lets
+``timing`` import nothing internal.
+
+The epoch encoders (``to_unix_seconds`` / ``to_unix_millis``) are
+deliberately absent still: the first epoch-consuming endpoint (Samsara
+trips, epoch milliseconds, captured 2026-07-20) keeps its conversion at
+the leaf as a single-consumer fact (exact integer arithmetic in
+``endpoints/samsara/trips.py``); the codec takes the function when a
+second epoch consumer lands (the rule of two).
+"""
+
+from datetime import UTC, datetime
+
+from fleetpull.timing.canon import require_utc
+
+__all__: list[str] = [
+    'from_iso8601',
+    'to_iso8601',
+    'to_utc_date_string',
+]
+
+
+def to_iso8601(moment: datetime) -> str:
+    """
+    Render a UTC datetime as a seconds-precision ISO-8601 'Z' string.
+
+    The form GeoTab's ``fromDate`` and DateWatermark persistence use, e.g.
+    ``'2026-06-01T00:00:00Z'``. Sub-second precision is dropped: window
+    parameters are second-granular and persisted watermarks read cleaner
+    without it.
+
+    Args:
+        moment: A timezone-aware UTC datetime.
+
+    Returns:
+        The ISO-8601 string with a trailing ``Z``.
+
+    Raises:
+        ValueError: If ``moment`` is naive or not UTC.
+    """
+    validated_moment: datetime = require_utc(moment)
+    # isoformat emits '+00:00' for a UTC datetime; swap for the 'Z' form
+    # providers expect. The offset is the only '+00:00' a validated-UTC ISO
+    # string can contain, so the suffix strip is unambiguous.
+    iso_with_offset: str = validated_moment.isoformat(timespec='seconds')
+    return iso_with_offset.removesuffix('+00:00') + 'Z'
+
+
+def to_utc_date_string(moment: datetime) -> str:
+    """
+    Render the UTC calendar date of a datetime as ``'YYYY-MM-DD'``.
+
+    Used for hive partition keys (``date=YYYY-MM-DD``) and date-only request
+    parameters. The date is the UTC date, since ``moment`` is UTC.
+
+    Args:
+        moment: A timezone-aware UTC datetime.
+
+    Returns:
+        The UTC date in ISO ``'YYYY-MM-DD'`` form.
+
+    Raises:
+        ValueError: If ``moment`` is naive or not UTC.
+    """
+    validated_moment: datetime = require_utc(moment)
+    return validated_moment.date().isoformat()
+
+
+def from_iso8601(text: str) -> datetime:
+    """
+    Parse an ISO-8601 datetime string into a timezone-aware UTC datetime.
+
+    Accepts any offset form ``datetime.fromisoformat`` handles on 3.12 (``Z``,
+    ``+HH:MM``, fractional seconds) and normalizes it to UTC. A string with no
+    offset — including a date-only string — is ambiguous and rejected; this
+    module never assumes UTC for an unzoned value.
+
+    Consumers: reading a persisted DateWatermark back, and parsing a
+    user-supplied date from YAML config. The config path is untrusted, so a
+    malformed value raises here and the config loader translates it.
+
+    Args:
+        text: An ISO-8601 datetime string carrying a UTC offset.
+
+    Returns:
+        The instant as a timezone-aware UTC datetime (tzinfo is
+        ``datetime.UTC``).
+
+    Raises:
+        ValueError: If ``text`` is not parseable ISO-8601, or carries no
+            offset (naive).
+    """
+    parsed_moment: datetime = datetime.fromisoformat(text)
+    if parsed_moment.tzinfo is None:
+        raise ValueError(
+            f'ISO-8601 datetime must carry a UTC offset; got naive {text!r}'
+        )
+    return parsed_moment.astimezone(UTC)

fleetpull/timing/sleeper.py

@@ -0,0 +1,65 @@
+# src/fleetpull/timing/sleeper.py
+"""Injectable sleep seam for backoff waiting.
+
+A one-method seam kept separate from ``Clock``: ``Clock`` reads time
+(``now_utc`` / ``today_utc`` / ``monotonic_seconds``) and never consumes it.
+Code that must pause — the transport client's TRANSIENT backoff — takes a
+``Sleeper`` so tests substitute a recording double and never wait real time,
+exactly as ``Clock`` is injected to make time deterministic.
+"""
+
+import time
+from dataclasses import dataclass
+from typing import Protocol, runtime_checkable
+
+__all__: list[str] = [
+    'Sleeper',
+    'SystemSleeper',
+]
+
+
+@runtime_checkable
+class Sleeper(Protocol):
+    """
+    Interface for sleep providers.
+
+    One capability — pause the calling thread for a duration — so the seam is
+    a single method (the ``Clock`` / ``RandomFractionGenerator`` precedent).
+    Tests inject a recording double; production injects ``SystemSleeper``.
+    """
+
+    def sleep(self, seconds: float) -> None:
+        """
+        Block the calling thread for ``seconds``.
+
+        Args:
+            seconds: Non-negative duration to sleep. Behavior on a negative
+                value is the implementation's (``SystemSleeper`` defers to
+                ``time.sleep``, which raises ``ValueError``).
+        """
+        ...
+
+
+@dataclass(frozen=True, slots=True)
+class SystemSleeper:
+    """
+    Production sleeper backed by ``time.sleep``.
+
+    Frozen and stateless, so one shared instance is safe to inject anywhere
+    (the ``SystemClock`` precedent).
+    """
+
+    def sleep(self, seconds: float) -> None:
+        """
+        Sleep via ``time.sleep``.
+
+        Args:
+            seconds: Non-negative duration to sleep.
+
+        Side Effects:
+            Blocks the calling thread for ``seconds``.
+
+        Raises:
+            ValueError: If ``seconds`` is negative (raised by ``time.sleep``).
+        """
+        time.sleep(seconds)

fleetpull/vocabulary/__init__.py

@@ -0,0 +1,16 @@
+# src/fleetpull/vocabulary/__init__.py
+"""Shared, dependency-free package vocabulary."""
+
+from fleetpull.vocabulary.json_types import JsonObject, JsonScalar, JsonValue
+from fleetpull.vocabulary.provider import Provider
+from fleetpull.vocabulary.quota_scope import QuotaScope
+from fleetpull.vocabulary.response_category import ResponseCategory
+
+__all__: list[str] = [
+    'JsonObject',
+    'JsonScalar',
+    'JsonValue',
+    'Provider',
+    'QuotaScope',
+    'ResponseCategory',
+]

fleetpull/vocabulary/json_types.py

@@ -0,0 +1,20 @@
+# src/fleetpull/vocabulary/json_types.py
+"""JSON type vocabulary: the recursive shape of a JSON document.
+
+The package-wide aliases for JSON data -- spoken by the network contract
+(request bodies, response envelopes, page decoding), the records layer (raw
+record dicts entering validation), and the orchestrator (batch plumbing).
+Homed in ``vocabulary`` because the concept is generic JSON, not a network
+contract: three layers speak it, so it lives in the dependency-free leaf
+they all sit above, not in the transport package one of them happens to be.
+"""
+
+__all__: list[str] = ['JsonObject', 'JsonScalar', 'JsonValue']
+
+# The actual type of a JSON document, recursively. Used for JSON-RPC
+# bodies and response envelopes; available to every layer.
+type JsonScalar = str | int | float | bool | None
+type JsonValue = JsonScalar | list[JsonValue] | dict[str, JsonValue]
+# A single JSON object -- the shape one extracted record takes; the endpoints
+# layer types the record extractor's output as ``list[JsonObject]``.
+type JsonObject = dict[str, JsonValue]

fleetpull/vocabulary/provider.py

@@ -0,0 +1,29 @@
+# src/fleetpull/vocabulary/provider.py
+"""
+The closed set of telematics providers fleetpull extracts from.
+
+Shared, dependency-free package vocabulary, sibling to ``ResponseCategory``:
+an endpoint declares the provider it belongs to, and the composition root
+keys per-provider auth and response classification on it. Homed in the leaf
+that imports nothing internal so every layer can name a provider without
+forming a cycle.
+"""
+
+from enum import StrEnum
+
+__all__: list[str] = ['Provider']
+
+
+class Provider(StrEnum):
+    """
+    Closed set of telematics providers.
+
+    String values are the lowercase provider keys used in logging and
+    quota-scope naming. A provider earns a member only when fleetpull
+    implements its auth and response classification — which all three
+    already have.
+    """
+
+    GEOTAB = 'geotab'
+    MOTIVE = 'motive'
+    SAMSARA = 'samsara'

fleetpull/vocabulary/quota_scope.py

@@ -0,0 +1,47 @@
+# src/fleetpull/vocabulary/quota_scope.py
+"""
+The closed set of quota scopes an endpoint definition declares.
+
+Shared, dependency-free package vocabulary, sibling to ``Provider`` and
+``ResponseCategory`` in the leaf. A ``QuotaScope`` is which token bucket an
+endpoint spends from — the type of ``endpoint.quota_scope`` — not which
+provider it belongs to. The two are separate vocabularies on purpose — folding
+both into one type would be exactly the conflation this avoids — and they
+diverged when GeoTab metered its endpoints apart from the rest (the
+method-class scopes below; the §13 Samsara ``vehicle_locations`` case would
+add another ``QuotaScope`` member while the ``Provider`` stays ``SAMSARA``).
+
+GeoTab meters per method class, not per provider (§8, captured 2026-07-09),
+so its scopes are method-class members: ``GEOTAB_GET`` is the Get-class data
+scope endpoint definitions declare, ``GEOTAB_FEED`` is the GetFeed-class
+scope the feed endpoints declare (its own ~60/min budget, proven by the
+2026-07-21 header-decrement probe — distinct from the ~650/min Get class),
+and ``GEOTAB_AUTHENTICATE`` is the dedicated Authenticate scope —
+auth-internal, never an endpoint declaration; the composition root passes it
+to the authenticator factory by name.
+"""
+
+from enum import StrEnum
+
+__all__: list[str] = ['QuotaScope']
+
+
+class QuotaScope(StrEnum):
+    """
+    Closed set of quota scopes (which token bucket an endpoint spends from).
+
+    String values are the lowercase scope keys the ``RateLimiterRegistry`` is
+    already keyed on (matching the provider-derived scope strings in use today),
+    so a ``QuotaScope`` member passes to ``QuotaScopeLimiter(quota_scope: str)``
+    transparently — it is a ``str``.
+
+    Membership vs. limits: scope *membership* is this closed architectural set
+    (code); scope *limits* are config (§7). Adding a scope is therefore a code
+    change (a new member) plus a config change (its limits) — not config-only.
+    """
+
+    GEOTAB_AUTHENTICATE = 'geotab_authenticate'
+    GEOTAB_FEED = 'geotab_feed'
+    GEOTAB_GET = 'geotab_get'
+    MOTIVE = 'motive'
+    SAMSARA = 'samsara'

fleetpull/vocabulary/response_category.py

@@ -0,0 +1,32 @@
+# src/fleetpull/vocabulary/response_category.py
+"""
+The closed response-classification vocabulary.
+
+Shared, dependency-free package vocabulary: the classification layer
+produces it, the client dispatches on it, the retry layer takes it as
+input, and ``RetriesExhaustedError`` carries it on a public field.
+Homed in a leaf that imports nothing internal so every layer — root
+exceptions included — can depend on it without forming a cycle.
+"""
+
+from enum import StrEnum
+
+__all__: list[str] = ['ResponseCategory']
+
+
+class ResponseCategory(StrEnum):
+    """
+    Closed vocabulary of "what the client does next."
+
+    Each member earns its slot by demanding a distinct client action.
+    Closure invariant (DESIGN.md §8): a new category is admissible only
+    if it arrives with a new client action.
+    """
+
+    SUCCESS = 'success'  # parse and yield records
+    TRANSIENT = 'transient'  # retry with backoff
+    RATE_LIMITED = 'rate_limited'  # penalize the shared quota scope, then retry
+    AUTH_FAILURE = (
+        'auth_failure'  # ask the auth strategy whether one retry is worthwhile
+    )
+    FATAL = 'fatal'  # raise