vercel-queue 0.7.2__tar.gz → 0.7.3__tar.gz

{vercel_queue-0.7.2 → vercel_queue-0.7.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: vercel-queue
-Version: 0.7.2
+Version: 0.7.3
 Summary: Vercel Queue client for Python
 License-Expression: MIT
 License-File: LICENSE
@@ -10,7 +10,8 @@ Requires-Dist: httpx[http2]>=0.27.0
 Requires-Dist: python-multipart>=0.0.20
 Requires-Dist: typing-extensions>=4.0.0
 Requires-Dist: vercel-headers>=0.7.1
-Requires-Dist: vercel-oidc>=0.7.1
+Requires-Dist: vercel-internal-core<0.2.0,>=0.1.2
+Requires-Dist: vercel-oidc>=0.8.0
 Provides-Extra: devserver
 Requires-Dist: uvicorn; extra == 'devserver'
 Provides-Extra: trio
@@ -67,35 +68,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
@@ -163,42 +158,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
@@ -285,7 +284,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-0.7.2 → vercel_queue-0.7.3}/README.md

@@ -46,35 +46,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
@@ -142,42 +136,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
@@ -264,7 +262,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-0.7.2 → vercel_queue-0.7.3}/_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-0.7.2 → vercel_queue-0.7.3}/pyproject.toml

@@ -21,6 +21,7 @@ dependencies = [
     "python-multipart>=0.0.20",
     "typing_extensions>=4.0.0",
     "vercel-headers>=0.6.0",
+    "vercel-internal-core>=0.1.0,<0.2.0",
     "vercel-oidc>=0.6.0",
 ]
 
@@ -32,6 +33,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"
@@ -63,6 +65,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-0.7.2 → vercel_queue-0.7.3}/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,
@@ -44,14 +53,6 @@ from .types import (
     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]

{vercel_queue-0.7.2 → vercel_queue-0.7.3}/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 (
@@ -20,16 +31,6 @@ from .types import (
     Topic,
     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")
 

{vercel_queue-0.7.2 → vercel_queue-0.7.3}/vercel/queue/version.py

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

vercel_queue-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