taskq-py 0.1.0__py3-none-any.whl

taskq/_di/types.py

@@ -0,0 +1,121 @@
+"""DI type vocabulary for the solver engine."""
+
+from collections.abc import AsyncIterator, Awaitable, Callable, Iterator
+from dataclasses import dataclass, field
+from enum import Enum, IntEnum
+from typing import Literal, Protocol, runtime_checkable
+
+from taskq._di.scope import Scope
+
+type Factory[T] = (
+    Callable[..., T]
+    | Callable[..., Awaitable[T]]
+    | Callable[..., AsyncIterator[T]]
+    | Callable[..., Iterator[T]]
+)
+
+
+class FactoryShape(IntEnum):
+    """Classification of factory shapes for resolution-time dispatch."""
+
+    SYNC_CALLABLE = 0
+    ASYNC_CALLABLE = 1
+    ASYNC_GENERATOR = 2
+    SYNC_GENERATOR = 3
+    VALUE = 4
+    CLASS = 5
+
+
+class ProviderLifecycle(Enum):
+    """Provider lifecycle shapes for resolution-time dispatch."""
+
+    Plain = "plain"
+    AsyncContextManager = "acm"
+    AsyncCloseable = "acloseable"
+    SyncCloseable = "scloseable"
+    AsyncGenerator = "asyncgen"
+    SyncGenerator = "syncgen"
+    PlainFactory = "plainfactory"
+
+
+@dataclass(frozen=True, slots=True)
+class ProviderEntry[T]:
+    """One registered provider for type T.
+
+    Field-to-shape mapping (canonical):
+      kind="value"   → factory_shape == FactoryShape.VALUE
+      kind="factory" → factory_shape ∈ {SYNC_CALLABLE, ASYNC_CALLABLE,
+                                       ASYNC_GENERATOR, SYNC_GENERATOR}
+      kind="class"   → factory_shape == FactoryShape.CLASS
+    ``register_value/factory/class`` methods are the single point that
+    constructs ``ProviderEntry`` and MUST honour this table.
+    """
+
+    type_: type[T]
+    scope: Scope
+    kind: Literal["value", "factory", "class"]
+    impl: object  # Why: heterogeneous (Factory[T] | type[T] | T) — erasure documented
+    factory_shape: FactoryShape
+    lifecycle: ProviderLifecycle | None = field(default=None)
+
+
+@runtime_checkable
+class ProviderRegistry(Protocol):
+    """Read-only registry surface consumed by the solver engine.
+
+    The full implementation (register_value / register_factory /
+    register_class / validate / has_provider) is owned by the container
+    implementation. The engine only needs the lookup surface defined here.
+    """
+
+    @property
+    def providers(self) -> dict[type, ProviderEntry[object]]: ...
+
+    # Why: runtime_checkable Protocol cannot express per-method type
+    # parameters (PEP 695 + runtime_checkable limitation under pyright).
+    # The signature is erased from the published shape
+    # ``get[T](type_: type[T]) -> ProviderEntry[T]`` to ``type[object] /
+    # ProviderEntry[object]``. This is the sanctioned DI erasure boundary.
+    def get(self, type_: type[object]) -> ProviderEntry[object]:
+        """Return the registered ProviderEntry for type_.
+
+        Raises:
+            MissingProvider: if type_ has no registered provider.
+
+        The engine relies on this contract: when a parameter has no
+        registered provider and is not in passthrough_kwargs, the
+        MissingProvider raised by this lookup is allowed to propagate.
+        Any test double or alternative implementation MUST match this
+        raises-contract — returning None or a sentinel breaks the solver.
+        """
+        ...
+
+
+@runtime_checkable
+class ScopeContainer(Protocol):
+    """One scope-lifetime container; owns its own AsyncExitStack.
+
+    The container is responsible for ALL factory invocation, caching,
+    and teardown registration. The solver engine NEVER calls a factory
+    directly and NEVER touches an AsyncExitStack — every resolution
+    goes through ``get_or_create``.
+    """
+
+    async def get_or_create(
+        self,
+        type_: type[object],
+        entry: ProviderEntry[object],
+    ) -> object:
+        """Return a resolved instance for type_, creating it if needed."""
+        ...
+
+    @property
+    def last_cache_hit(self) -> bool:
+        """Whether the most recent ``get_or_create`` served a cached value."""
+        ...
+
+    async def aclose(self) -> None:
+        """Close the container's internal AsyncExitStack with the
+        log-and-continue policy.
+        """
+        ...

taskq/_dsn.py

@@ -0,0 +1,18 @@
+"""Credential-safe DSN host extraction for logging.
+
+Single-purpose tiny module — same pattern as :mod:`taskq._json`.
+The leading underscore on the module name signals "internal to taskq."
+"""
+
+from urllib.parse import urlparse
+
+__all__ = ["dsn_host"]
+
+
+def dsn_host(dsn: object) -> str:
+    """Extract host from a DSN for safe logging (no credentials)."""
+    try:
+        parsed = urlparse(str(dsn))
+        return parsed.hostname or "unknown"
+    except Exception:
+        return "unknown"

taskq/_ids.py

@@ -0,0 +1,128 @@
+"""UUID and base62 generation helpers for TaskQ.
+
+Uses UUIDv7 (time-ordered) so job and worker IDs are monotonically
+increasing, which improves B-tree locality for PostgreSQL index inserts
+and makes IDs naturally sortable by creation time.
+
+Also provides :func:`new_base62` for short identifiers where a full UUID
+is overkill.  Three precision modes are available:
+
+- ``"random"`` — pure random, no timestamp.  Good for test bucket names
+  and other labels where sortability doesn't matter.
+- ``"second"`` — timestamp with second precision + random suffix.
+  IDs generated in different seconds sort correctly; within the same
+  second, order is arbitrary but IDs are still unique.
+- ``"millisecond"`` — timestamp with millisecond precision + random suffix.
+  Finer-grained sortability at the cost of more timestamp characters.
+"""
+
+from __future__ import annotations
+
+import os
+import time as _time
+from enum import Enum
+from uuid import UUID
+
+import uuid_utils
+
+from taskq.backend._protocol import JobId
+
+__all__ = ["new_base62", "new_job_id", "new_uuid"]
+
+_BASE62 = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz"
+_BASE62_LEN = len(_BASE62)
+
+_TS_CHARS_SECOND = 6
+_TS_CHARS_MILLISECOND = 8
+_MIN_LEN_SECOND = _TS_CHARS_SECOND + 1
+_MIN_LEN_MILLISECOND = _TS_CHARS_MILLISECOND + 1
+_MIN_LEN_RANDOM = 1
+
+
+class _Precision(Enum):
+    RANDOM = "random"
+    SECOND = "second"
+    MILLISECOND = "millisecond"
+
+
+def _encode_int(value: int, width: int) -> str:
+    out: list[str] = []
+    for _ in range(width):
+        out.append(_BASE62[value % _BASE62_LEN])
+        value //= _BASE62_LEN
+    if value:
+        raise ValueError(f"value {value} does not fit in {width} base62 characters")
+    return "".join(reversed(out))
+
+
+def _random_base62(count: int) -> str:
+    n = _BASE62_LEN**count
+    rand = int.from_bytes(os.urandom((n.bit_length() + 7) // 8), "big") % n
+    return _encode_int(rand, count)
+
+
+def new_base62(
+    length: int = 8,
+    *,
+    precision: str = "random",
+    _now: float | None = None,
+) -> str:
+    """Return a base62 identifier of *length* characters.
+
+    Three *precision* modes control the timestamp prefix:
+
+    ``"random"``
+        Pure random — no timestamp.  Minimum length 1.
+        Good for test bucket names and labels.
+
+    ``"second"``
+        Leading chars encode the current Unix timestamp at second
+        precision; remaining chars are random.  IDs from different
+        seconds sort correctly (same B-tree locality benefit as UUIDv7).
+        Minimum length 7 (6 timestamp + 1 random).
+
+    ``"millisecond"``
+        Same as ``"second"`` but with millisecond timestamp precision.
+        Minimum length 9 (8 timestamp + 1 random).
+
+    :param length: total character count (must be >= minimum for *precision*).
+    :param precision: ``"random"``, ``"second"``, or ``"millisecond"``.
+    :param _now: override the current time as a Unix timestamp (seconds).
+        For testing only; production callers should omit this parameter.
+    :raises ValueError: if *length* is below the minimum for *precision*.
+    """
+    prec = _Precision(precision)
+
+    if prec is _Precision.RANDOM:
+        if length < _MIN_LEN_RANDOM:
+            raise ValueError(
+                f"length must be >= {_MIN_LEN_RANDOM} for random precision, got {length}"
+            )
+        return _random_base62(length)
+
+    now = _now if _now is not None else _time.time()
+
+    if prec is _Precision.SECOND:
+        ts_chars = _TS_CHARS_SECOND
+        ts_val = int(now)
+        min_len = _MIN_LEN_SECOND
+    else:
+        ts_chars = _TS_CHARS_MILLISECOND
+        ts_val = int(now * 1000)
+        min_len = _MIN_LEN_MILLISECOND
+
+    if length < min_len:
+        raise ValueError(f"length must be >= {min_len} for {precision} precision, got {length}")
+
+    rand_chars = length - ts_chars
+    return _encode_int(ts_val, ts_chars) + _random_base62(rand_chars)
+
+
+def new_uuid() -> UUID:
+    """Return a new UUIDv7 as a stdlib :class:`~uuid.UUID`."""
+    return UUID(bytes=uuid_utils.uuid7().bytes)
+
+
+def new_job_id() -> JobId:
+    """Return a new UUIDv7 wrapped as a :data:`JobId`."""
+    return JobId(new_uuid())

taskq/_json.py

@@ -0,0 +1,105 @@
+"""orjson-backed JSON helpers.
+
+The library never imports stdlib ``json`` directly. Use ``dumps`` / ``loads``
+from this module so behaviour is consistent (UUID, datetime, numpy support
+where compiled) and the serialization hot path stays fast.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any, cast
+from uuid import UUID
+
+import orjson
+
+__all__ = ["dumps", "dumps_str", "loads", "structlog_serializer"]
+
+_UUID_RE = re.compile(
+    r"\A[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\Z",
+    re.IGNORECASE,
+)
+
+
+def _revive_uuids(value: Any) -> Any:
+    """Recursively convert UUID-like strings back to :class:`uuid.UUID`.
+
+    orjson serializes :class:`uuid.UUID` to the canonical 36-character hex
+    string but deserializes it back as a plain ``str``.  This helper walks
+    dict values and list items (not dict keys) and converts any string that
+    looks like a UUID back to a :class:`uuid.UUID` instance so that the
+    round-trip through PostgreSQL jsonb columns is transparent.
+    """
+    if isinstance(value, str):
+        if len(value) == 36 and _UUID_RE.match(value):
+            try:
+                return UUID(value)
+            except ValueError:
+                pass
+        return value
+    if isinstance(value, dict):
+        d = cast(dict[object, Any], value)
+        return {k: _revive_uuids(v) for k, v in d.items()}
+    if isinstance(value, list):
+        lst = cast(list[Any], value)
+        return [_revive_uuids(v) for v in lst]
+    return value
+
+
+def _orjson_fallback(obj: Any) -> Any:
+    """Convert types orjson can't serialize natively to a JSON-safe form.
+
+    Only reached when *obj* is not a type orjson handles (UUID, datetime,
+    str, int, float, bool, None, list, dict).  Kept fast-path: the vast
+    majority of values never hit this function.
+    """
+    cls: type[Any] = type(obj)  # pyright: ignore[reportUnknownVariableType]  # Why: obj is Any from orjson's default function; type() always returns a valid type object.
+    mod = cls.__module__
+    name = cls.__qualname__
+
+    # asyncpg protocol-level UUID — raw record access can leak these into
+    # structlog event dicts; convert to standard UUID string form.
+    if mod.startswith("asyncpg") and "UUID" in name:
+        return str(obj)
+
+    # bytes in a log event dict — decode with replacement.
+    if isinstance(obj, (bytes, bytearray)):
+        return obj.decode("utf-8", errors="replace")
+
+    raise TypeError(f"Type is not JSON serializable: {mod}.{name}")
+
+
+def dumps(value: Any, /) -> bytes:
+    """Serialize to bytes. Uses orjson defaults (UTC datetimes, UUID, etc.)."""
+    return orjson.dumps(
+        value,
+        default=_orjson_fallback,
+        option=orjson.OPT_NAIVE_UTC | orjson.OPT_UTC_Z | orjson.OPT_NON_STR_KEYS,
+    )
+
+
+def dumps_str(value: Any, /) -> str:
+    """Serialize to ``str``. Use only when the consumer demands text (e.g.,
+    asyncpg jsonb codec). Prefer :func:`dumps` for everything else."""
+    return dumps(value).decode("utf-8")
+
+
+def loads(data: bytes | bytearray | memoryview | str, /) -> Any:
+    """Deserialize bytes or text to a Python value.
+
+    UUID strings produced by :func:`dumps` / :func:`dumps_str` are revived
+    back to :class:`uuid.UUID` instances so that PostgreSQL jsonb columns,
+    NOTIFY payloads, event details, and other JSON-serialised state round-trip
+    correctly.
+    """
+    return _revive_uuids(orjson.loads(data))
+
+
+def structlog_serializer(value: Any, /, **_kwargs: Any) -> str:
+    """Serialize to ``str`` for structlog's ``JSONRenderer(serializer=...)``.
+
+    Accepts and ignores ``**_kwargs`` (e.g. ``default``) that structlog passes
+    internally — orjson handles all types we encounter natively and does not
+    use the ``default`` fallback that stdlib ``json`` requires.
+    """
+    return dumps_str(value)

taskq/_scope.py

@@ -0,0 +1,39 @@
+"""DI scope enum and lifecycle warning — zero-dependency leaf module.
+
+Extracted from ``taskq._di.scope`` so that ``taskq.exceptions`` can import
+:class:`Scope` without triggering ``taskq._di.__init__`` (which loads
+``taskq._di.scopes`` → ``taskq.context`` → circular import).
+
+This module MUST NOT import from any other ``taskq`` submodule.
+"""
+
+from enum import IntEnum
+
+__all__ = ["LifecycleDetectionWarning", "Scope"]
+
+
+class Scope(IntEnum):
+    """DI scope lifetime. Higher value = narrower scope.
+
+    PROCESS:   worker process startup -> exit (singletons).
+    THREAD:    worker thread spawn -> thread close (placeholder for multi-thread worker).
+    LOOP:      worker loop start -> loop close (pools, long-lived clients).
+    TRANSIENT: fresh per injection point - no cache.
+    """
+
+    PROCESS = 0
+    THREAD = 1
+    LOOP = 2
+    TRANSIENT = 3
+
+
+class LifecycleDetectionWarning(UserWarning):
+    """Emitted for DI usage hazards detected during DI operations.
+
+     Specific timing varies per emission site and is documented at
+     each emission. Fires for redundant call-site Scope overrides
+    , sync close detection on registered
+     classes, and other drift-prone API patterns. Subclass
+     of UserWarning so pytest captures it under default filters via
+     pytest.warns(LifecycleDetectionWarning).
+    """