vercel-queue-bundle 0.7.3__tar.gz → 0.8.0__tar.gz

{vercel_queue_bundle-0.7.3 → vercel_queue_bundle-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: vercel-queue-bundle
-Version: 0.7.3
+Version: 0.8.0
 Summary: Vercel Queue client for Python
 License-Expression: MIT
 License-File: LICENSE

{vercel_queue_bundle-0.7.3 → vercel_queue_bundle-0.8.0}/vercel/queue/_internal/api_common.py

@@ -35,6 +35,7 @@ StrContainer = _types.StrContainer
 TextBufferTransport = _transports.TextBufferTransport
 TextStreamTransport = _transports.TextStreamTransport
 Topic = _types.Topic
+TopicPattern = _types.TopicPattern
 TypedJsonTransport = _transports.TypedJsonTransport
 __version__ = _version.__version__
 asgi_app = _asgi.asgi_app
@@ -93,6 +94,7 @@ __all__ = (
     "ThrottledError",
     "TokenResolutionError",
     "Topic",
+    "TopicPattern",
     "TypedJsonTransport",
     "UnauthorizedError",
     "UnhandledMessageError",

{vercel_queue_bundle-0.7.3 → vercel_queue_bundle-0.8.0}/vercel/queue/_internal/subscribers.py

@@ -40,9 +40,11 @@ from .transports import (
     is_untyped_payload_annotation,
     payload_transport_kind,
     reject_invalid_payload_annotation,
+    topic_payload_annotation,
     transport_for_kind,
 )
 from .types import (
+    BaseTopic,
     Duration,
     Message,
     MessageMetadata,
@@ -50,12 +52,15 @@ from .types import (
     RetryAfter,
     StrContainer,
     Topic,
+    TopicPattern,
     Transport,
     duration_to_seconds,
 )
 
 _Subscriber: TypeAlias = Callable[..., Any | Awaitable[Any]]
 _SubscriberRef: TypeAlias = weakref.ReferenceType[_Subscriber]
+_SubscriptionTopic: TypeAlias = "str | SanitizedName | Topic[Any] | TopicPattern[Any]"
+"""Anything ``subscribe()`` accepts: one topic, or a pattern matching several."""
 P = ParamSpec("P")
 R = TypeVar("R")
 R_co = TypeVar("R_co", covariant=True)
@@ -66,6 +71,14 @@ class PayloadAdapter(Protocol):
     def validate_python(self, value: Any, /) -> Any: ...
 
 
+class _TransportPayloadAdapter:
+    def __init__(self, validate_payload: Callable[[Any], Any]) -> None:
+        self._validate_payload = validate_payload
+
+    def validate_python(self, value: Any, /) -> Any:
+        return self._validate_payload(value)
+
+
 class EmbeddedDispatcher(Protocol):
     def register_subscription(
         self,
@@ -107,6 +120,7 @@ class InvocationPlan:
     payload_adapter: PayloadAdapter | None
     mode: InvocationMode
     transport_kind: TransportKind
+    transport: Transport[Any] | None = None
 
     def prepare_payload(self, payload: Any) -> Any:
         if self.payload_adapter is None:
@@ -120,6 +134,33 @@ class InvocationPlan:
             raise
 
 
+class _TransportOrKind:
+    def __init__(self, plan: InvocationPlan) -> None:
+        self.transport_kind = plan.transport_kind
+        self.transport = plan.transport
+
+    def __hash__(self) -> int:
+        return hash(self.transport_kind) if self.transport is None else id(self.transport)
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, _TransportOrKind):
+            return NotImplemented
+        if self.transport is None and other.transport is None:
+            return self.transport_kind == other.transport_kind
+        # Two instances of the same class can decode differently
+        return self.transport is other.transport
+
+    def __repr__(self) -> str:
+        if self.transport is None:
+            return self.transport_kind
+        return repr(self.transport)
+
+    def get_transport(self) -> Transport[Any]:
+        if self.transport is None:
+            return _transport_for_kind(self.transport_kind)
+        return self.transport
+
+
 @dataclass(frozen=True, kw_only=True)
 class _Subscription:
     func_ref: _SubscriberRef
@@ -314,23 +355,17 @@ def _message_payload_annotation(annotation: Any) -> Any:
     return message_args[0]
 
 
-def _topic_payload_annotation(topic: str | SanitizedName | Topic[Any]) -> Any:
-    if not isinstance(topic, Topic):
-        return inspect.Signature.empty
-    if getattr(type(topic), "__topic_origin__", None) is not Topic:
-        return inspect.Signature.empty
-    return type(topic).__topic_payload_type__
-
-
-def _normalize_subscription_topic(topic: str | SanitizedName | Topic[Any]) -> str:
+def _normalize_subscription_topic(topic: _SubscriptionTopic) -> str:
     if isinstance(topic, SanitizedName):
         return str(topic)
     if isinstance(topic, str):
         validate_subscription_pattern(topic)
         return topic
+    if isinstance(topic, TopicPattern):
+        return str(topic.name)
     if isinstance(topic, Topic):
         return validate_topic_name(topic)
-    raise TypeError("topic must be a string or Topic")
+    raise TypeError("topic must be a string, Topic, or TopicPattern")
 
 
 def _resolve_invocation_payload_annotation(
@@ -356,7 +391,11 @@ def _payload_adapter(
     annotation: Any,
     *,
     localns: dict[str, Any] | None = None,
+    transport: Transport[Any] | None = None,
 ) -> PayloadAdapter | None:
+    validate_payload = getattr(transport, "validate_payload", None)
+    if callable(validate_payload):
+        return _TransportPayloadAdapter(validate_payload)
     annotation = strip_annotated(annotation)
     if is_untyped_payload_annotation(annotation):
         return None
@@ -407,6 +446,7 @@ def _build_invocation_plan(
     func: _Subscriber,
     *,
     topic_payload_annotation: Any = inspect.Signature.empty,
+    transport: Transport[Any] | None = None,
 ) -> InvocationPlan:
     signature = inspect.signature(func)
     input_params: list[inspect.Parameter] = []
@@ -446,9 +486,11 @@ def _build_invocation_plan(
         payload_adapter=_payload_adapter(
             payload_annotation,
             localns=resolved_annotation.localns,
+            transport=transport,
         ),
         mode=mode,
         transport_kind=_transport_kind(payload_annotation),
+        transport=transport,
     )
 
 
@@ -593,13 +635,13 @@ def infer_subscriber_transport(metadata: MessageMetadata) -> Transport[Any]:
     if not matching:
         raise _no_matching_subscriptions_error(metadata.topic)
 
-    kinds = {matched.subscription.invocation.transport_kind for matched in matching}
-    if len(kinds) != 1:
+    tks = {_TransportOrKind(matched.subscription.invocation) for matched in matching}
+    if len(tks) != 1:
         raise SubscriptionError(
             "matching queue subscribers require incompatible payload transports: "
-            + ", ".join(sorted(kinds))
+            + ", ".join(sorted(map(repr, tks)))
         )
-    return _transport_for_kind(kinds.pop())
+    return tks.pop().get_transport()
 
 
 async def _maybe_await_result(result: Any) -> Any:
@@ -702,14 +744,14 @@ def _register_subscription(
     func: Callable[P, R],
     *,
     consumer_group: str | SanitizedName | None = None,
-    topic: str | SanitizedName | Topic[Any],
+    topic: _SubscriptionTopic,
     retry_after: Duration | None = None,
     initial_delay: Duration | None = None,
     max_concurrency: int | None = None,
     max_attempts: int | None = None,
 ) -> QueueSubscriber[P, R]:
     topic_name = _normalize_subscription_topic(topic)
-    topic_payload_annotation = _topic_payload_annotation(topic)
+    payload_annotation = topic_payload_annotation(topic)
 
     resolved_consumer_group = (
         _default_consumer_group(func)
@@ -725,7 +767,10 @@ def _register_subscription(
         consumer_group=resolved_consumer_group,
         invocation=_build_invocation_plan(
             cast("_Subscriber", func),
-            topic_payload_annotation=topic_payload_annotation,
+            topic_payload_annotation=payload_annotation,
+            # This is not receive_transport_for_topic() because we are doing
+            # more than that in _build_invocation_plan()
+            transport=topic.transport if isinstance(topic, BaseTopic) else None,
         ),
         topic=topic_name,
         retry_after_seconds=_optional_bounded_duration(
@@ -769,7 +814,12 @@ def subscribe(
 
 
 @overload
-def subscribe(func: Callable[[T], R], /, *, topic: Topic[T]) -> QueueSubscriber[[T], R]: ...
+def subscribe(
+    func: Callable[[T], R],
+    /,
+    *,
+    topic: Topic[T] | TopicPattern[T],
+) -> QueueSubscriber[[T], R]: ...
 
 
 @overload
@@ -777,7 +827,7 @@ def subscribe(
     func: Callable[[Message[T]], R],
     /,
     *,
-    topic: Topic[T],
+    topic: Topic[T] | TopicPattern[T],
 ) -> QueueSubscriber[[Message[T]], R]: ...
 
 
@@ -808,7 +858,7 @@ def subscribe(
 @overload
 def subscribe(
     *,
-    topic: Topic[T],
+    topic: Topic[T] | TopicPattern[T],
     consumer_group: str | SanitizedName | None = None,
     retry_after: Duration | None = None,
     initial_delay: Duration | None = None,
@@ -850,7 +900,7 @@ def subscribe(
     func: None,
     /,
     *,
-    topic: Topic[T],
+    topic: Topic[T] | TopicPattern[T],
     consumer_group: str | SanitizedName | None = None,
     retry_after: Duration | None = None,
     initial_delay: Duration | None = None,
@@ -863,7 +913,7 @@ def subscribe(
     func: _Subscriber | None = None,
     /,
     *,
-    topic: str | SanitizedName | Topic[Any],
+    topic: _SubscriptionTopic,
     consumer_group: str | SanitizedName | None = None,
     retry_after: Duration | None = None,
     initial_delay: Duration | None = None,

{vercel_queue_bundle-0.7.3 → vercel_queue_bundle-0.8.0}/vercel/queue/_internal/transports.py

@@ -27,8 +27,10 @@ from .streams import (
     SyncTextStreamPayload,
 )
 from .types import (
+    BaseTopic,
     RequestContent,
     Topic,
+    TopicPattern,
     Transport,
 )
 
@@ -304,14 +306,24 @@ def receive_transport_for_annotation(annotation: Any) -> Transport[Any]:
     return transport_for_kind(kind)
 
 
+def topic_payload_annotation(topic: object) -> Any:
+    """Return the payload type ``topic`` was specialized with, if any.
+
+    A bare name, an unspecialized topic, and a user subclass all report "no
+    annotation": none of them carries a payload type we put there.
+    """
+    origin = getattr(type(topic), "__topic_origin__", None)
+    if origin is not Topic and origin is not TopicPattern:
+        return inspect.Signature.empty
+    return getattr(type(topic), "__topic_payload_type__", inspect.Signature.empty)
+
+
 def receive_transport_for_topic(topic: object) -> Transport[Any]:
-    if not isinstance(topic, Topic):
+    if not isinstance(topic, BaseTopic):
         return RawJsonTransport[Any]()
     if topic.transport is not None:
         return topic.transport
-    if getattr(type(topic), "__topic_origin__", None) is not Topic:
-        return RawJsonTransport[Any]()
-    return receive_transport_for_annotation(type(topic).__topic_payload_type__)
+    return receive_transport_for_annotation(topic_payload_annotation(topic))
 
 
 def send_transport_for_topic(topic: object) -> Transport[Any] | None:
@@ -360,5 +372,6 @@ __all__ = (
     "receive_transport_for_topic",
     "reject_invalid_payload_annotation",
     "send_transport_for_topic",
+    "topic_payload_annotation",
     "transport_for_kind",
 )

{vercel_queue_bundle-0.7.3 → vercel_queue_bundle-0.8.0}/vercel/queue/_internal/types.py

@@ -12,8 +12,15 @@ from collections.abc import (
 from dataclasses import dataclass
 from datetime import datetime, timedelta
 
+from vercel._internal.core.polyfills import Self
+
 from .constants import DEFAULT_RETRY_AFTER_SECONDS
-from .names import SanitizedName, validate_name, validate_topic_name
+from .names import (
+    SanitizedName,
+    validate_name,
+    validate_subscription_pattern,
+    validate_topic_name,
+)
 
 T = TypeVar("T")
 _TYPE_VAR_TYPE = type(T)
@@ -62,47 +69,62 @@ def duration_to_float_seconds(duration: Duration) -> float:
 
 
 @dataclass(frozen=True, kw_only=True, eq=False)
-class Topic(Generic[T]):
-    """A named Vercel Queues topic.
+class BaseTopic(Generic[T]):
+    """Shared behaviour of :class:`Topic` and :class:`TopicPattern`.
 
-    Topics identify the stream that messages are sent to and received from.
+    Use ``Topic`` to name one topic and ``TopicPattern`` to match several; the
+    two are separate types so that a pattern cannot reach an operation that
+    needs a single, concrete topic.
     """
 
-    name: SanitizedName
-    """Topic name to send to or receive from."""
+    name: SanitizedName | str
+    """The topic name, or the pattern that selects topic names.
+
+    A pattern is a plain ``str``: ``SanitizedName`` means "safe to put in a
+    request path", which a pattern is not.
+    """
 
     transport: Transport[Any] | None = None
-    """Optional transport used when sending to or polling this topic."""
+    """Optional transport used when sending to, polling, or subscribing to this topic."""
 
-    __topic_origin__: ClassVar[type[Topic[Any]] | None] = None
+    __topic_origin__: ClassVar[type[BaseTopic[Any]] | None] = None
     __topic_payload_type__: ClassVar[Any] = None
-    _specializations: ClassVar[dict[Any, type[Topic[Any]]]] = {}
-
-    def __class_getitem__(cls, params: Any) -> type[Topic[Any]]:
+    _specializations: ClassVar[dict[Any, type[BaseTopic[Any]]]] = {}
+
+    def __init_subclass__(cls, **kwargs: Any) -> None:
+        super().__init_subclass__(**kwargs)
+        # `Topic` and `TopicPattern` each need their own cache, or the first
+        # `Topic[bytes]` would be handed back for `TopicPattern[bytes]`. A
+        # specialization (the only thing carrying `__topic_origin__` in its
+        # own namespace) keeps sharing the cache of the class it came from.
+        if "__topic_origin__" not in cls.__dict__:
+            cls._specializations = {}
+
+    def __class_getitem__(cls, params: Any) -> type[Self]:
         if isinstance(params, tuple):
             if len(params) != 1:
-                raise TypeError("Topic expects exactly one type argument")
+                raise TypeError(f"{cls.__name__} expects exactly one type argument")
             params = params[0]
         if isinstance(params, _TYPE_VAR_TYPE):
-            return cast("type[Topic[Any]]", cls)
+            return cls
 
         try:
-            return cls._specializations[params]
+            return cast("type[Self]", cls._specializations[params])
         except KeyError:
             pass
 
         payload_repr = _topic_payload_type_repr(params)
         specialization = type(
-            f"Topic[{payload_repr}]",
+            f"{cls.__name__}[{payload_repr}]",
             (cls,),
             {
                 "__module__": cls.__module__,
-                "__topic_origin__": Topic,
+                "__topic_origin__": cls,
                 "__topic_payload_type__": params,
             },
         )
         cls._specializations[params] = specialization
-        return cast("type[Topic[Any]]", specialization)
+        return cast("type[Self]", specialization)
 
     def __init__(
         self,
@@ -110,14 +132,22 @@ class Topic(Generic[T]):
         *,
         transport: Transport[Any] | None = None,
     ) -> None:
-        object.__setattr__(self, "name", SanitizedName(validate_topic_name(name)))
+        object.__setattr__(self, "name", self._validated_name(name))
         object.__setattr__(self, "transport", transport)
 
+    @staticmethod
+    def _validated_name(name: str | SanitizedName) -> SanitizedName | str:
+        raise NotImplementedError
+
     def __repr__(self) -> str:
-        return f"Topic(name={self.name!r})"
+        # Report the class the user named, not the synthesized specialization.
+        cls = type(self)
+        return f"{(cls.__topic_origin__ or cls).__name__}(name={self.name!r})"
 
     def __eq__(self, other: object) -> bool:
-        if not isinstance(other, Topic):
+        # A pattern always ends in `*`, which a topic name can never contain,
+        # so comparing names is enough to keep the two kinds apart.
+        if not isinstance(other, BaseTopic):
             return NotImplemented
         return self.name == other.name
 
@@ -125,6 +155,36 @@ class Topic(Generic[T]):
         return hash(self.name)
 
 
+class Topic(BaseTopic[T]):
+    """A named Vercel Queues topic.
+
+    Topics identify the stream that messages are sent to and received from.
+    """
+
+    name: SanitizedName
+    """Topic name to send to, poll, or subscribe to."""
+
+    @staticmethod
+    def _validated_name(name: str | SanitizedName) -> SanitizedName | str:
+        return SanitizedName(validate_topic_name(name))
+
+
+class TopicPattern(BaseTopic[T]):
+    """A pattern selecting every Vercel Queues topic it matches.
+
+    ``"*"`` matches every topic and a prefix ending in ``*`` matches by
+    prefix. A pattern can only be subscribed to: sending and polling name one
+    topic, so they take a :class:`Topic`.
+    """
+
+    name: str
+    """The pattern this subscription matches topics with."""
+
+    @staticmethod
+    def _validated_name(name: str | SanitizedName) -> SanitizedName | str:
+        return validate_subscription_pattern(str(name))
+
+
 def _topic_payload_type_repr(payload_type: object) -> str:
     name = getattr(payload_type, "__qualname__", None)
     if isinstance(name, str):
@@ -297,4 +357,5 @@ __all__: tuple[str, ...] = (
     "RetryAfter",
     "StrContainer",
     "Topic",
+    "TopicPattern",
 )

{vercel_queue_bundle-0.7.3 → vercel_queue_bundle-0.8.0}/vercel/queue/version.py

@@ -1,3 +1,3 @@
 """Package version metadata."""
 
-__version__ = "0.7.3"
+__version__ = "0.8.0"