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

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

@@ -1,14 +1,15 @@
 Metadata-Version: 2.4
 Name: vercel-queue-bundle
-Version: 0.7.2
+Version: 0.8.0
 Summary: Vercel Queue client for Python
 License-Expression: MIT
 License-File: LICENSE
 License-File: vercel/queue/_vendor/LICENSE.python-multipart.txt
 Requires-Python: >=3.10
 Requires-Dist: vercel-headers-bundle>=0.7.1
+Requires-Dist: vercel-internal-core-bundle<0.2.0,>=0.1.2
 Requires-Dist: vercel-internal-shared-vendored-deps>=0.1.1
-Requires-Dist: vercel-oidc-bundle>=0.7.1
+Requires-Dist: vercel-oidc-bundle>=0.8.0
 Provides-Extra: devserver
 Requires-Dist: uvicorn; extra == 'devserver'
 Provides-Extra: trio
@@ -69,35 +70,29 @@ from vercel.queue import send
 message_id = await send("my-topic", {"message": "Hello world"})
 ```
 
-**3. Handle incoming messages with an API route function:**
+**3. Handle incoming messages in a subscriber module:**
 
 ```python
-# api/queue.py
-from vercel.queue import asgi_app, subscribe
+# worker.py
+from vercel.queue import subscribe
 
 
-@subscribe(topic="my-topic", consumer_group="api/queue.py")
+@subscribe(topic="my-topic")
 async def process_message(message):
     print("Processing:", message)
-
-
-# An ASGI app instance that converts incoming message callbacks
-# sent by Vercel Queues and routes them to handlers.
-app = asgi_app()
 ```
 
-**4. Configure `vercel.json`:**
+**4. Declare the subscriber in `pyproject.toml`:**
 
-```json
-{
-    "functions": {
-        "api/queue.py": {
-            "experimentalTriggers": [{ "type": "queue/v2beta", "topic": "my-topic" }]
-        }
-    }
-}
+```toml
+[[tool.vercel.subscribers]]
+entrypoint = "worker:process_message"
 ```
 
+The Vercel build introspects the entrypoint module's registered
+subscriptions and compiles it into a queue-triggered function. No
+`vercel.json` trigger configuration is needed.
+
 **5. Deploy:**
 
 ```bash
@@ -165,42 +160,46 @@ and running polling loops on other infrastructure.
 
 ### Auto-scaled push-mode on Vercel
 
-The recommended way of deploying queue subscribers is to deploy them as Vercel Functions
-
-**Vercel Function (plain `/api` directory):**
+The recommended way of deploying queue subscribers is to declare them in
+`pyproject.toml` with `[[tool.vercel.subscribers]]`. Each entry points at a
+module that registers subscriptions with `@subscribe`:
 
 ```python
-# api/handle_orders.py
-from vercel.queue import asgi_app, subscribe
+# worker.py
+from vercel.queue import subscribe
 
 
-@subscribe(topic="orders", consumer_group="api/handle_orders.py")
+@subscribe(topic="orders", retry_after=60)
 async def handle_order(message):
     print("Processing:", message)
+```
 
+**pyproject.toml**:
 
-# An ASGI app instance that converts incoming message callbacks
-# sent by Vercel Queues and routes them to handlers.
-app = asgi_app()
+```toml
+[[tool.vercel.subscribers]]
+entrypoint = "worker:handle_order"
 ```
 
-**vercel.json**:
-
-```json
-{
-    "functions": {
-        "api/queue/orders.py": {
-            "experimentalTriggers": [
-                {
-                    "type": "queue/v2beta",
-                    "topic": "orders",
-                    "retryAfterSeconds": 60,
-                    "initialDelaySeconds": 0
-                }
-            ]
-        }
-    }
-}
+At build time, Vercel imports the entrypoint module, introspects every
+subscription it registers, and compiles the subscriber into its own
+queue-triggered function. Delivery tuning lives on the `@subscribe`
+decorator (`retry_after`, `initial_delay`, `max_concurrency`,
+`max_attempts`, `consumer_group`), so no `vercel.json` configuration is
+needed.
+
+A subscriber consumes every subscription registered by its entrypoint
+module. Add an optional `topics` filter to split subscriptions across
+several subscriber functions:
+
+```toml
+[[tool.vercel.subscribers]]
+entrypoint = "worker:handle_order"
+topics = ["orders"]
+
+[[tool.vercel.subscribers]]
+entrypoint = "worker:handle_refund"
+topics = ["refunds"]
 ```
 
 ### Automatic Polling Loop
@@ -287,7 +286,7 @@ polling, because it can distribute messages across regions unpredictably.
 ## Retry and Backoff
 
 When a topic handler raises, the message is not acknowledged and becomes available for redelivery
-after the `retryAfterSeconds` interval configured in `vercel.json`. Retries continue until the
+after the `retry_after` interval configured on the subscriber. Retries continue until the
 handler succeeds or the message expires.
 
 For finer control over retry timing, raise `RetryAfter` from a subscriber:

{vercel_queue_bundle-0.7.2 → vercel_queue_bundle-0.8.0}/README.md

@@ -50,35 +50,29 @@ from vercel.queue import send
 message_id = await send("my-topic", {"message": "Hello world"})
 ```
 
-**3. Handle incoming messages with an API route function:**
+**3. Handle incoming messages in a subscriber module:**
 
 ```python
-# api/queue.py
-from vercel.queue import asgi_app, subscribe
+# worker.py
+from vercel.queue import subscribe
 
 
-@subscribe(topic="my-topic", consumer_group="api/queue.py")
+@subscribe(topic="my-topic")
 async def process_message(message):
     print("Processing:", message)
-
-
-# An ASGI app instance that converts incoming message callbacks
-# sent by Vercel Queues and routes them to handlers.
-app = asgi_app()
 ```
 
-**4. Configure `vercel.json`:**
+**4. Declare the subscriber in `pyproject.toml`:**
 
-```json
-{
-    "functions": {
-        "api/queue.py": {
-            "experimentalTriggers": [{ "type": "queue/v2beta", "topic": "my-topic" }]
-        }
-    }
-}
+```toml
+[[tool.vercel.subscribers]]
+entrypoint = "worker:process_message"
 ```
 
+The Vercel build introspects the entrypoint module's registered
+subscriptions and compiles it into a queue-triggered function. No
+`vercel.json` trigger configuration is needed.
+
 **5. Deploy:**
 
 ```bash
@@ -146,42 +140,46 @@ and running polling loops on other infrastructure.
 
 ### Auto-scaled push-mode on Vercel
 
-The recommended way of deploying queue subscribers is to deploy them as Vercel Functions
-
-**Vercel Function (plain `/api` directory):**
+The recommended way of deploying queue subscribers is to declare them in
+`pyproject.toml` with `[[tool.vercel.subscribers]]`. Each entry points at a
+module that registers subscriptions with `@subscribe`:
 
 ```python
-# api/handle_orders.py
-from vercel.queue import asgi_app, subscribe
+# worker.py
+from vercel.queue import subscribe
 
 
-@subscribe(topic="orders", consumer_group="api/handle_orders.py")
+@subscribe(topic="orders", retry_after=60)
 async def handle_order(message):
     print("Processing:", message)
+```
 
+**pyproject.toml**:
 
-# An ASGI app instance that converts incoming message callbacks
-# sent by Vercel Queues and routes them to handlers.
-app = asgi_app()
+```toml
+[[tool.vercel.subscribers]]
+entrypoint = "worker:handle_order"
 ```
 
-**vercel.json**:
-
-```json
-{
-    "functions": {
-        "api/queue/orders.py": {
-            "experimentalTriggers": [
-                {
-                    "type": "queue/v2beta",
-                    "topic": "orders",
-                    "retryAfterSeconds": 60,
-                    "initialDelaySeconds": 0
-                }
-            ]
-        }
-    }
-}
+At build time, Vercel imports the entrypoint module, introspects every
+subscription it registers, and compiles the subscriber into its own
+queue-triggered function. Delivery tuning lives on the `@subscribe`
+decorator (`retry_after`, `initial_delay`, `max_concurrency`,
+`max_attempts`, `consumer_group`), so no `vercel.json` configuration is
+needed.
+
+A subscriber consumes every subscription registered by its entrypoint
+module. Add an optional `topics` filter to split subscriptions across
+several subscriber functions:
+
+```toml
+[[tool.vercel.subscribers]]
+entrypoint = "worker:handle_order"
+topics = ["orders"]
+
+[[tool.vercel.subscribers]]
+entrypoint = "worker:handle_refund"
+topics = ["refunds"]
 ```
 
 ### Automatic Polling Loop
@@ -268,7 +266,7 @@ polling, because it can distribute messages across regions unpredictably.
 ## Retry and Backoff
 
 When a topic handler raises, the message is not acknowledged and becomes available for redelivery
-after the `retryAfterSeconds` interval configured in `vercel.json`. Retries continue until the
+after the `retry_after` interval configured on the subscriber. Retries continue until the
 handler succeeds or the message expires.
 
 For finer control over retry timing, raise `RetryAfter` from a subscriber:

{vercel_queue_bundle-0.7.2 → vercel_queue_bundle-0.8.0}/_vercel_hatch_build.py

@@ -8,6 +8,7 @@ from typing import Any
 
 from hatchling.metadata.plugin.interface import MetadataHookInterface
 from packaging.requirements import Requirement
+from packaging.specifiers import SpecifierSet
 
 try:
     import tomllib
@@ -29,8 +30,10 @@ class WorkspaceDependenciesMetadataHook(MetadataHookInterface):
         }
         workspace_root = _find_workspace_root(Path(self.root))
 
+        package = pyproject.get("project", {}).get("name", str(self.root))
+
         metadata["dependencies"] = [
-            _rewrite_dependency(requirement, workspace_names, workspace_root)
+            _rewrite_dependency(requirement, workspace_names, workspace_root, package)
             for requirement in dependency_table.get("dependencies", [])
         ]
 
@@ -55,24 +58,56 @@ def _rewrite_dependency(
     requirement: str,
     workspace_names: set[str],
     workspace_root: Path | None,
+    package: str,
 ) -> str:
     parsed = Requirement(requirement)
     normalized = parsed.name.lower().replace("_", "-")
     if normalized not in workspace_names or workspace_root is None:
         return requirement
-    return _with_lower_bound(parsed, _read_workspace_version(workspace_root, normalized))
+    version = _read_workspace_version(workspace_root, normalized)
+    return _with_lower_bound(parsed, version, requirement, package)
 
 
-def _with_lower_bound(requirement: Requirement, version: str) -> str:
+def _with_lower_bound(requirement: Requirement, version: str, declared: str, package: str) -> str:
     extras = f"[{','.join(sorted(requirement.extras))}]" if requirement.extras else ""
     specifiers = [
         str(specifier) for specifier in requirement.specifier if specifier.operator != ">="
     ]
     specifier_text = ",".join([f">={version}", *specifiers])
+    _reject_unsatisfiable(package, requirement.name, declared, specifier_text, version)
     marker = f" ; {requirement.marker}" if requirement.marker else ""
     return f"{requirement.name}{extras}{specifier_text}{marker}"
 
 
+def _reject_unsatisfiable(
+    package: str, dependency: str, declared: str, specifier_text: str, version: str
+) -> None:
+    """Refuse to publish a bound that no version of *dependency* can satisfy.
+
+    The lower bound is generated from the sibling's current version while the
+    rest of the specifier is whatever the package declared, so a hand-written
+    upper bound that the sibling has since reached produces something like
+    ``>=0.3.0,<0.3.0``. Nothing rejects that later: the wheel builds, uploads,
+    and only fails when someone tries to install it. Fail the build instead --
+    CI builds every package, so the bump that crosses the bound is caught by
+    its own pull request.
+
+    The test is that the sibling version *being released* satisfies the bound,
+    which is narrower than the range being non-empty: `>=0.7.1,!=0.7.1` leaves
+    room for a later version, but says the release under way is unusable.
+    """
+    # `prereleases=True` so a workspace version like `0.4.0b1` is judged
+    # against its own bound rather than excluded for being a prerelease.
+    if SpecifierSet(specifier_text).contains(version, prereleases=True):
+        return
+    raise RuntimeError(
+        f"{package} declares {declared!r}, but {dependency} is at {version} in "
+        f"the workspace, so publishing would pin {dependency}{specifier_text} — "
+        f"which excludes {version} itself, the version being released. "
+        f"Raise the upper bound in [tool.vercel.release.dependencies] of {package}."
+    )
+
+
 def _read_workspace_version(workspace_root: Path, package_name: str) -> str:
     for pattern in ("src/*/pyproject.toml", "integrations/*/pyproject.toml"):
         for pyproject_path in workspace_root.glob(pattern):

{vercel_queue_bundle-0.7.2 → vercel_queue_bundle-0.8.0}/pyproject.toml

@@ -21,7 +21,8 @@ path = "hatch_build.py"
 [tool.vercel.release.dependencies]
 dependencies = [
     "vercel-headers-bundle>=0.7.1",
-    "vercel-oidc-bundle>=0.7.1",
+    "vercel-internal-core-bundle>=0.1.2,<0.2.0",
+    "vercel-oidc-bundle>=0.8.0",
     "vercel-internal-shared-vendored-deps>=0.1.1",
 ]
 
@@ -33,6 +34,7 @@ trio = ["anyio[trio]>=4.0.0"]
 [tool.uv.sources]
 vercel-oidc = { workspace = true }
 vercel-headers = { workspace = true }
+vercel-internal-core = { workspace = true }
 
 [tool.hatch.version]
 path = "vercel/queue/version.py"
@@ -65,6 +67,10 @@ exclude = [
 extend = "../../pyproject.toml"
 cache-dir = "../../.ruff_cache"
 preview = true
+# `vercel` is a PEP 420 namespace package split across workspace members, so
+# `vercel._internal.core` is this package's own shared internals rather than
+# another project's privates. import-private-name needs telling.
+namespace-packages = ["vercel"]
 
 [tool.ruff.lint]
 extend-select = [

{vercel_queue_bundle-0.7.2 → 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.2 → vercel_queue_bundle-0.8.0}/vercel/queue/_internal/subscribers.py

@@ -12,6 +12,15 @@ from importlib import import_module
 from itertools import count
 from types import MappingProxyType
 
+from vercel._internal.core.typeutils import (
+    ResolvedAnnotation,
+    TypeAnnotationResolutionError,
+    args,
+    origin_is,
+    resolve_annotation_with_namespace_from_call_stack,
+    strip_annotated,
+)
+
 from .errors import (
     DuplicateSubscriptionError,
     PayloadValidationError,
@@ -31,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,
@@ -41,20 +52,15 @@ from .types import (
     RetryAfter,
     StrContainer,
     Topic,
+    TopicPattern,
     Transport,
     duration_to_seconds,
 )
-from .typeutils import (
-    ResolvedAnnotation,
-    TypeAnnotationResolutionError,
-    args,
-    origin_is,
-    resolve_annotation_with_namespace_from_call_stack,
-    strip_annotated,
-)
 
 _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)
@@ -65,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,
@@ -106,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:
@@ -119,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
@@ -313,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(
@@ -355,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
@@ -406,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] = []
@@ -445,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,
     )
 
 
@@ -592,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:
@@ -701,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)
@@ -724,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(
@@ -768,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
@@ -776,7 +827,7 @@ def subscribe(
     func: Callable[[Message[T]], R],
     /,
     *,
-    topic: Topic[T],
+    topic: Topic[T] | TopicPattern[T],
 ) -> QueueSubscriber[[Message[T]], R]: ...
 
 
@@ -807,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,
@@ -849,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,
@@ -862,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.2 → vercel_queue_bundle-0.8.0}/vercel/queue/_internal/transports.py

@@ -7,6 +7,17 @@ import json
 from collections.abc import AsyncIterable, AsyncIterator, Callable, Iterable
 from importlib import import_module
 
+from vercel._internal.core.typeutils import (
+    annotation_needs_resolution,
+    args,
+    is_classvar,
+    is_final,
+    is_type_var,
+    is_union_type,
+    origin_is,
+    strip_annotated,
+)
+
 from .constants import CONTENT_TYPE_JSON, CONTENT_TYPE_OCTET_STREAM, CONTENT_TYPE_TEXT
 from .errors import SubscriptionError
 from .streams import (
@@ -16,20 +27,12 @@ from .streams import (
     SyncTextStreamPayload,
 )
 from .types import (
+    BaseTopic,
     RequestContent,
     Topic,
+    TopicPattern,
     Transport,
 )
-from .typeutils import (
-    annotation_needs_resolution,
-    args,
-    is_classvar,
-    is_final,
-    is_type_var,
-    is_union_type,
-    origin_is,
-    strip_annotated,
-)
 
 T = TypeVar("T")
 
@@ -303,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:
@@ -359,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.2 → 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.2 → vercel_queue_bundle-0.8.0}/vercel/queue/version.py

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

vercel_queue_bundle-0.7.2/vercel/queue/_internal/typeutils.py

@@ -1,203 +0,0 @@
-from __future__ import annotations
-
-from typing import (
-    Annotated,
-    Any,
-    ClassVar,
-    Final,
-    ForwardRef,
-    Literal,
-    TypeVar,
-    Union,
-    get_args,
-    get_origin,
-    get_type_hints,
-)
-
-import inspect
-import types
-from dataclasses import dataclass
-from types import FrameType
-
-_T = TypeVar("_T")
-_TYPE_VAR_TYPE = type(_T)
-
-
-class TypeAnnotationResolutionError(TypeError):
-    """Raised when a runtime annotation cannot be resolved."""
-
-
-@dataclass(frozen=True)
-class ResolvedAnnotation:
-    annotation: Any
-    localns: dict[str, Any] | None = None
-
-
-def is_generic_alias(tp: Any) -> bool:
-    return get_origin(tp) is not None
-
-
-def is_annotated(tp: Any) -> bool:
-    return get_origin(tp) is Annotated
-
-
-def strip_annotated(tp: Any) -> Any:
-    while is_annotated(tp):
-        tp = get_args(tp)[0]
-    return tp
-
-
-def is_type_var(tp: Any) -> bool:
-    return isinstance(tp, _TYPE_VAR_TYPE)
-
-
-def is_classvar(tp: Any) -> bool:
-    return get_origin(tp) is ClassVar
-
-
-def is_final(tp: Any) -> bool:
-    return get_origin(tp) is Final
-
-
-def is_union_type(tp: Any) -> bool:
-    return get_origin(tp) in {Union, types.UnionType}
-
-
-def origin_is(tp: Any, *origins: Any) -> bool:
-    return get_origin(tp) in origins
-
-
-def args(tp: Any) -> tuple[Any, ...]:
-    return get_args(tp)
-
-
-def annotation_needs_resolution(annotation: Any) -> bool:
-    if isinstance(annotation, str | ForwardRef):
-        return True
-    if is_type_var(annotation):
-        return False
-    if origin_is(annotation, Literal):
-        return False
-    if origin_is(annotation, Annotated):
-        annotation_args = args(annotation)
-        return bool(annotation_args) and annotation_needs_resolution(annotation_args[0])
-    return any(annotation_needs_resolution(item) for item in args(annotation))
-
-
-def _normalize_forward_refs(annotation: Any) -> Any:
-    if isinstance(annotation, str):
-        return ForwardRef(annotation)
-    if isinstance(annotation, ForwardRef) or is_type_var(annotation):
-        return annotation
-
-    annotation_args = args(annotation)
-    if not annotation_args or origin_is(annotation, Literal):
-        return annotation
-
-    origin = get_origin(annotation)
-    if origin is Annotated:
-        first_arg = _normalize_forward_refs(annotation_args[0])
-        if first_arg is annotation_args[0]:
-            return annotation
-        return Annotated.__class_getitem__((first_arg, *annotation_args[1:]))
-
-    normalized_args = tuple(_normalize_forward_refs(item) for item in annotation_args)
-    if normalized_args == annotation_args:
-        return annotation
-
-    if isinstance(annotation, types.GenericAlias):
-        return origin[normalized_args]
-    copy_with = getattr(annotation, "copy_with", None)
-    if copy_with is not None:
-        return copy_with(normalized_args)
-    return annotation
-
-
-def _resolve_annotation_fully(
-    annotation: Any,
-    *,
-    globalns: dict[str, Any],
-    localns: dict[str, Any] | None = None,
-) -> ResolvedAnnotation:
-    resolved = resolve_annotation(annotation, globalns=globalns, localns=localns)
-    if not annotation_needs_resolution(resolved):
-        return ResolvedAnnotation(resolved, localns)
-
-    normalized = _normalize_forward_refs(resolved)
-    return ResolvedAnnotation(
-        resolve_annotation(normalized, globalns=globalns, localns=localns),
-        localns,
-    )
-
-
-def _call_stack_localns() -> dict[str, Any]:
-    frame: FrameType | None = inspect.currentframe()
-    localns: dict[str, Any] = {}
-    try:
-        frame = frame.f_back if frame is not None else None
-        while frame is not None:
-            localns = {**frame.f_locals, **localns}
-            frame = frame.f_back
-    finally:
-        del frame
-    return localns
-
-
-def resolve_annotation(
-    annotation: Any,
-    *,
-    globalns: dict[str, Any],
-    localns: dict[str, Any] | None = None,
-) -> Any:
-    class AnnotationShim:
-        pass
-
-    AnnotationShim.__annotations__ = {"value": annotation}
-    return get_type_hints(
-        AnnotationShim,
-        globalns=globalns,
-        localns=localns,
-        include_extras=True,
-    )["value"]
-
-
-def resolve_annotation_from_call_stack(
-    annotation: Any,
-    *,
-    globalns: dict[str, Any],
-) -> Any:
-    return resolve_annotation_with_namespace_from_call_stack(
-        annotation,
-        globalns=globalns,
-    ).annotation
-
-
-def resolve_annotation_with_namespace_from_call_stack(
-    annotation: Any,
-    *,
-    globalns: dict[str, Any],
-) -> ResolvedAnnotation:
-    if annotation is Any or not annotation_needs_resolution(annotation):
-        return ResolvedAnnotation(annotation, _call_stack_localns())
-
-    resolution_error: BaseException | None = None
-    try:
-        return _resolve_annotation_fully(annotation, globalns=globalns)
-    except (NameError, TypeError, AttributeError) as exc:
-        resolution_error = exc
-
-    localns = _call_stack_localns()
-
-    try:
-        return _resolve_annotation_fully(
-            annotation,
-            globalns=globalns,
-            localns=localns,
-        )
-    except (NameError, TypeError, AttributeError) as exc:
-        resolution_error = exc
-
-    if not annotation_needs_resolution(annotation):
-        return ResolvedAnnotation(annotation)
-
-    raise TypeAnnotationResolutionError from resolution_error