vercel-queue 0.7.0__py3-none-any.whl

vercel/queue/_internal/typeutils.py

@@ -0,0 +1,203 @@
+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

vercel/queue/devserver.py

@@ -0,0 +1,24 @@
+"""Standalone queue development server."""
+
+from __future__ import annotations
+
+from ._internal.devserver import (
+    EmbeddedQueueDevServer,
+    QueueClientAsgiDevServer,
+    embedded_queue_dev_server,
+    main,
+    queue_client_asgi_dev_server,
+)
+
+# Only add public symbols to __all__; internal helpers must stay unexported.
+__all__ = (
+    "EmbeddedQueueDevServer",
+    "QueueClientAsgiDevServer",
+    "embedded_queue_dev_server",
+    "main",
+    "queue_client_asgi_dev_server",
+)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

vercel/queue/embedded.py

@@ -0,0 +1,50 @@
+"""Embedded local queue server for in-process Queue API development.
+
+This module provides a dependency-light Queue API implementation for embedded
+local runtime code. It preserves the same client and push-delivery path as the
+hosted service: callers send through ``QueueClient``, messages are stored
+in a local server, visible messages are leased, and a dispatcher invokes
+subscribers through ``accept_and_handle`` with synthetic Vercel Queue push
+headers. Successful handlers are acknowledged by the normal client follow-up
+path, and failures retry through lease expiry or explicit visibility changes.
+
+Use this for embedded, single-process local mode and tests.
+
+Run an embedded queue server in a test and use a client that sends to
+it directly:
+
+    import anyio
+    import vercel.queue as vq
+    import vercel.queue.embedded as vq_embedded
+
+    @vq.subscribe(topic="jobs*", consumer_group="just-testing")
+    async def handle_job(message: vq.Message[dict[str, object]]) -> None:
+        print(message.payload)
+
+    async def main() -> None:
+        async with vq_embedded.embedded_queue_service() as service:
+            client = service.get_async_client()
+            await client.send("email", {"subject": "hi"})
+
+    anyio.run(main)
+
+
+Enable the pytest fixture and use it in tests:
+
+    pytest_plugins = ["vercel.queue.testing.pytest"]
+
+    async def test_queue(embedded_queue_server):
+        client = embedded_queue_server.get_async_client()
+        message_id = await client.send("emails", {"subject": "hi"}, retention=60)
+"""
+
+from ._internal.embedded import (
+    create_embedded_queue_app,
+    embedded_queue_service,
+)
+
+# Only add public symbols to __all__; internal helpers must stay unexported.
+__all__ = (
+    "create_embedded_queue_app",
+    "embedded_queue_service",
+)

vercel/queue/py.typed

@@ -0,0 +1 @@
+

vercel/queue/sync.py

@@ -0,0 +1,8 @@
+"""Synchronous Vercel Queue client APIs."""
+# ruff: noqa: F403
+
+from ._internal import api_common as _api_common, api_sync as _api_sync
+from ._internal.api_common import *
+from ._internal.api_sync import *
+
+__all__ = _api_common.__all__ + _api_sync.__all__

vercel/queue/testing/__init__.py

@@ -0,0 +1,14 @@
+"""Testing helpers for Vercel Queue."""
+
+from .state import (
+    clear_subscriptions,
+    reset_default_async_queue_clients,
+    reset_default_queue_clients,
+)
+
+# Only add public symbols to __all__; internal helpers must stay unexported.
+__all__ = (
+    "clear_subscriptions",
+    "reset_default_async_queue_clients",
+    "reset_default_queue_clients",
+)

vercel/queue/testing/pytest.py

@@ -0,0 +1,42 @@
+"""Pytest fixtures for the embedded queue server."""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+
+import pytest
+
+from vercel.queue.devserver import EmbeddedQueueDevServer, embedded_queue_dev_server
+
+
+@pytest.fixture(scope="session")
+def _embedded_queue_server_session() -> Iterator[EmbeddedQueueDevServer]:
+    """Run one embedded queue server process for the test session."""
+    with embedded_queue_dev_server() as server:
+        yield server
+
+
+@pytest.fixture
+def embedded_queue_server(
+    _embedded_queue_server_session: EmbeddedQueueDevServer,
+) -> Iterator[EmbeddedQueueDevServer]:
+    """Return an isolated embedded queue server state for a test."""
+    _embedded_queue_server_session.reset()
+    try:
+        yield _embedded_queue_server_session
+    finally:
+        _embedded_queue_server_session.reset()
+
+
+@pytest.fixture
+def eqs(embedded_queue_server: EmbeddedQueueDevServer) -> EmbeddedQueueDevServer:
+    """Alias for the embedded queue server fixture."""
+    return embedded_queue_server
+
+
+# Only add public symbols to __all__; internal helpers must stay unexported.
+__all__ = (
+    "EmbeddedQueueDevServer",
+    "embedded_queue_server",
+    "eqs",
+)

vercel/queue/testing/state.py

@@ -0,0 +1,32 @@
+"""Queue test state helpers."""
+
+from __future__ import annotations
+
+from .._internal import subscribers as queue_subscribers
+from .._internal.http import (
+    reset_async_http_client_pool_for_tests,
+    reset_http_client_pools_for_tests,
+)
+
+
+def reset_default_queue_clients() -> None:
+    """Reset cached default Queue clients for tests."""
+    reset_http_client_pools_for_tests()
+
+
+async def reset_default_async_queue_clients() -> None:
+    """Reset cached default asynchronous Queue clients for tests."""
+    await reset_async_http_client_pool_for_tests()
+
+
+def clear_subscriptions() -> None:
+    """Clear registered subscribers and embedded dispatchers for tests."""
+    queue_subscribers.clear_subscriptions_for_tests()
+
+
+# Only add public symbols to __all__; internal helpers must stay unexported.
+__all__ = (
+    "clear_subscriptions",
+    "reset_default_async_queue_clients",
+    "reset_default_queue_clients",
+)

vercel/queue/version.py

@@ -0,0 +1,3 @@
+"""Package version metadata."""
+
+__version__ = "0.7.0"