vercel-celery 0.7.0__tar.gz

vercel_celery-0.7.0/.gitignore

@@ -0,0 +1,130 @@
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstallerhave
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+.benchmarks/
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+.ruff_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Scrapy
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+.python-version
+
+# pipenv
+Pipfile.lock
+
+# poetry
+poetry.lock
+
+# PDM
+pdm.lock
+.pdm.toml
+
+# Hatch
+.hatch/
+
+# pyright/mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# pyre
+.pyre/
+
+# pytype
+.pytype/
+
+# Caches
+__pypackages__/
+
+# Editor/project files
+.DS_Store
+.idea/
+.vscode/
+.zed/
+*.swp
+*.swo
+
+# Virtual environments
+.env
+.venv
+.venv.*
+env/
+venv/
+**/.env
+**/.venv
+**/.venv.*
+**/env/
+**/venv/
+ENV/
+env.bak/
+venv.bak/
+
+# dotenv anywhere
+**/.env
+**/.env.*
+**/*.env
+
+.claude

vercel_celery-0.7.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Vercel Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

vercel_celery-0.7.0/PKG-INFO

@@ -0,0 +1,90 @@
+Metadata-Version: 2.4
+Name: vercel-celery
+Version: 0.7.0
+Summary: Celery integration for Vercel Queue and Runtime Cache
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: celery<6,>=5.3
+Requires-Dist: vercel-cache>=0.7.0
+Requires-Dist: vercel-queue>=0.7.0
+Description-Content-Type: text/markdown
+
+# vercel-celery
+
+Celery integration for Vercel Queue Service and Vercel Runtime Cache.
+
+This package provides a Celery broker transport backed by Vercel Queue Service
+and a Celery result backend backed by Vercel Runtime Cache.
+
+```python
+from vercel.integrations.celery import install_vercel_celery_integration
+
+install_vercel_celery_integration()
+```
+
+By default, named Celery apps publish to app-prefixed Vercel Queue topics. For
+example, `Celery("my_app")` maps Celery queue `emails` to the Vercel Queue topic
+`celery-my__app-emails` after Vercel Queue name sanitization. Apps with no name
+use unprefixed topics. To override this, set
+`broker_transport_options = {"queue_name_prefix": "jobs-"}`. Set
+`queue_name_prefix` to `""` to use Celery queue names as Vercel Queue topics.
+
+The broker's Vercel Queue consumer group defaults to `celery`. Workers sharing
+the same Vercel Queue topic and consumer group compete for tasks. Workers using
+the same topic with different consumer groups receive fan-out copies. To
+override it, set `broker_transport_options = {"consumer_group": "workers"}`.
+
+The installer sets Celery's default `broker_url` to `vercel://` when Celery has
+no broker default configured. Pass `set_default_broker=False` to opt out.
+It also sets Celery's default `result_backend` to `vercel-runtime-cache://`
+when Celery has no result backend configured. Pass
+`set_default_result_backend=False` to opt out.
+
+`vercel://` uses push delivery when `VERCEL` is truthy in the environment and
+poll delivery otherwise. Set `broker_url = "vercel-push://"` to force push
+delivery, or `broker_url = "vercel-poll://"` for forced polling workers, local
+workers, and background workers.
+
+Pass `register_queues=False` to skip automatic Vercel Queue trigger
+registration. When using that mode, manually register each Celery app whose
+queues should receive Vercel Queue push deliveries:
+
+```python
+from vercel.integrations.celery import register_celery_app_queues
+
+register_celery_app_queues(app)
+```
+
+To customize Celery task result storage in Vercel Runtime Cache, configure
+Celery's result backend transport options:
+
+```python
+result_backend_transport_options = {
+    "namespace": "celery-results",
+    "ttl": 3600,
+}
+```
+
+By default, named Celery apps use an app-scoped Runtime Cache namespace. For
+example, `Celery("my_app")` stores results under `celery-results-my_app`. Apps
+with no name use `celery-results`. If producers and workers use different
+Celery app names, configure a shared explicit `namespace`.
+
+The Runtime Cache backend uses `vercel.cache`, including its normal key hashing,
+namespacing, and local in-memory fallback when Runtime Cache is unavailable.
+Celery result backends are not required to retain results indefinitely; results
+may expire according to Celery's result expiration settings or the backend's own
+retention behavior. This backend is therefore an expiring, cache-backed result
+backend rather than durable result storage. Celery treats missing result entries
+as pending results. By default, stored results use Celery's `result_expires`
+value as their Runtime Cache TTL; set `result_backend_transport_options["ttl"]`
+to override that retention period.
+
+JSON result serialization works normally. Binary serializers, including
+`pickle`, are stored through an internal base64 wrapper so Runtime Cache only
+receives JSON-compatible values.
+
+Runtime Cache is a single-key cache API, so this backend does not provide native
+bulk result fetches or increment-backed chord counters. Result availability is
+limited by Runtime Cache retention and eviction behavior.

vercel_celery-0.7.0/README.md

@@ -0,0 +1,78 @@
+# vercel-celery
+
+Celery integration for Vercel Queue Service and Vercel Runtime Cache.
+
+This package provides a Celery broker transport backed by Vercel Queue Service
+and a Celery result backend backed by Vercel Runtime Cache.
+
+```python
+from vercel.integrations.celery import install_vercel_celery_integration
+
+install_vercel_celery_integration()
+```
+
+By default, named Celery apps publish to app-prefixed Vercel Queue topics. For
+example, `Celery("my_app")` maps Celery queue `emails` to the Vercel Queue topic
+`celery-my__app-emails` after Vercel Queue name sanitization. Apps with no name
+use unprefixed topics. To override this, set
+`broker_transport_options = {"queue_name_prefix": "jobs-"}`. Set
+`queue_name_prefix` to `""` to use Celery queue names as Vercel Queue topics.
+
+The broker's Vercel Queue consumer group defaults to `celery`. Workers sharing
+the same Vercel Queue topic and consumer group compete for tasks. Workers using
+the same topic with different consumer groups receive fan-out copies. To
+override it, set `broker_transport_options = {"consumer_group": "workers"}`.
+
+The installer sets Celery's default `broker_url` to `vercel://` when Celery has
+no broker default configured. Pass `set_default_broker=False` to opt out.
+It also sets Celery's default `result_backend` to `vercel-runtime-cache://`
+when Celery has no result backend configured. Pass
+`set_default_result_backend=False` to opt out.
+
+`vercel://` uses push delivery when `VERCEL` is truthy in the environment and
+poll delivery otherwise. Set `broker_url = "vercel-push://"` to force push
+delivery, or `broker_url = "vercel-poll://"` for forced polling workers, local
+workers, and background workers.
+
+Pass `register_queues=False` to skip automatic Vercel Queue trigger
+registration. When using that mode, manually register each Celery app whose
+queues should receive Vercel Queue push deliveries:
+
+```python
+from vercel.integrations.celery import register_celery_app_queues
+
+register_celery_app_queues(app)
+```
+
+To customize Celery task result storage in Vercel Runtime Cache, configure
+Celery's result backend transport options:
+
+```python
+result_backend_transport_options = {
+    "namespace": "celery-results",
+    "ttl": 3600,
+}
+```
+
+By default, named Celery apps use an app-scoped Runtime Cache namespace. For
+example, `Celery("my_app")` stores results under `celery-results-my_app`. Apps
+with no name use `celery-results`. If producers and workers use different
+Celery app names, configure a shared explicit `namespace`.
+
+The Runtime Cache backend uses `vercel.cache`, including its normal key hashing,
+namespacing, and local in-memory fallback when Runtime Cache is unavailable.
+Celery result backends are not required to retain results indefinitely; results
+may expire according to Celery's result expiration settings or the backend's own
+retention behavior. This backend is therefore an expiring, cache-backed result
+backend rather than durable result storage. Celery treats missing result entries
+as pending results. By default, stored results use Celery's `result_expires`
+value as their Runtime Cache TTL; set `result_backend_transport_options["ttl"]`
+to override that retention period.
+
+JSON result serialization works normally. Binary serializers, including
+`pickle`, are stored through an internal base64 wrapper so Runtime Cache only
+receives JSON-compatible values.
+
+Runtime Cache is a single-key cache API, so this backend does not provide native
+bulk result fetches or increment-backed chord counters. Result availability is
+limited by Runtime Cache retention and eviction behavior.

vercel_celery-0.7.0/_vercel_hatch_build.py

@@ -0,0 +1,116 @@
+"""Hatch metadata hook for publish-time workspace dependency bounds."""
+
+from __future__ import annotations
+
+import ast
+from pathlib import Path
+from typing import Any
+
+from hatchling.metadata.plugin.interface import MetadataHookInterface
+from packaging.requirements import Requirement
+
+try:
+    import tomllib
+except ModuleNotFoundError:  # pragma: no cover - Python < 3.11
+    import tomli as tomllib  # type: ignore[no-redef]
+
+
+class WorkspaceDependenciesMetadataHook(MetadataHookInterface):
+    """Generate package dependencies from the repo-owned dependency table."""
+
+    def update(self, metadata: dict[str, Any]) -> None:
+        """Populate dynamic dependencies for Hatchling metadata generation."""
+        pyproject = _load_pyproject(Path(self.root))
+        release = pyproject.get("tool", {}).get("vercel", {}).get("release", {})
+        dependency_table = release.get("dependencies", {})
+        workspace_sources = pyproject.get("tool", {}).get("uv", {}).get("sources", {})
+        workspace_names = {
+            name for name, source in workspace_sources.items() if source.get("workspace") is True
+        }
+        workspace_root = _find_workspace_root(Path(self.root))
+
+        metadata["dependencies"] = [
+            _rewrite_dependency(requirement, workspace_names, workspace_root)
+            for requirement in dependency_table.get("dependencies", [])
+        ]
+
+
+def _load_pyproject(path: Path) -> dict[str, Any]:
+    with (path / "pyproject.toml").open("rb") as fp:
+        return tomllib.load(fp)
+
+
+def _find_workspace_root(start: Path) -> Path | None:
+    for path in [start, *start.parents]:
+        pyproject = path / "pyproject.toml"
+        if not pyproject.exists():
+            continue
+        data = _load_pyproject(path)
+        if "workspace" in data.get("tool", {}).get("uv", {}):
+            return path
+    return None
+
+
+def _rewrite_dependency(
+    requirement: str,
+    workspace_names: set[str],
+    workspace_root: Path | None,
+) -> 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))
+
+
+def _with_lower_bound(requirement: Requirement, version: 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])
+    marker = f" ; {requirement.marker}" if requirement.marker else ""
+    return f"{requirement.name}{extras}{specifier_text}{marker}"
+
+
+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):
+            version = _version_from_pyproject(pyproject_path, package_name)
+            if version is not None:
+                return version
+    raise RuntimeError(f"unknown workspace dependency {package_name!r}")
+
+
+def _version_from_pyproject(pyproject_path: Path, package_name: str) -> str | None:
+    data = _load_pyproject(pyproject_path.parent)
+    if data.get("project", {}).get("name") != package_name:
+        return None
+    version_path = pyproject_path.parent / data["tool"]["hatch"]["version"]["path"]
+    module = ast.parse(version_path.read_text(encoding="utf-8"), filename=str(version_path))
+    for node in module.body:
+        value = _version_value(node)
+        if value is None:
+            continue
+        if isinstance(value, ast.Constant) and isinstance(value.value, str):
+            return value.value
+    raise RuntimeError(f"could not find __version__ in {version_path}")
+
+
+def _version_value(node: ast.stmt) -> ast.expr | None:
+    if isinstance(node, ast.Assign) and any(
+        isinstance(target, ast.Name) and target.id == "__version__" for target in node.targets
+    ):
+        return node.value
+    if (
+        isinstance(node, ast.AnnAssign)
+        and isinstance(node.target, ast.Name)
+        and node.target.id == "__version__"
+    ):
+        return node.value
+    return None
+
+
+def get_metadata_hook() -> type[MetadataHookInterface]:
+    """Return the hook class used by Hatchling's custom hook loader."""
+    return WorkspaceDependenciesMetadataHook

vercel_celery-0.7.0/hatch_build.py

@@ -0,0 +1,29 @@
+"""Load the shared Vercel Hatch metadata hook."""
+
+from __future__ import annotations
+
+from importlib.util import module_from_spec, spec_from_file_location
+from pathlib import Path
+from types import ModuleType
+
+from hatchling.metadata.plugin.interface import MetadataHookInterface
+
+
+def get_metadata_hook() -> type[MetadataHookInterface]:
+    """Return the shared workspace dependency metadata hook."""
+    return _load_shared_hook().get_metadata_hook()
+
+
+def _load_shared_hook() -> ModuleType:
+    root = Path(__file__).resolve().parent
+    candidates = [root / "../../scripts/hatch_build.py", root / "_vercel_hatch_build.py"]
+    for candidate in candidates:
+        path = candidate.resolve()
+        if path.exists():
+            spec = spec_from_file_location("_vercel_hatch_build", path)
+            if spec is None or spec.loader is None:
+                raise RuntimeError(f"could not load Hatch hook from {path}")
+            module = module_from_spec(spec)
+            spec.loader.exec_module(module)
+            return module
+    raise RuntimeError("could not find shared Vercel Hatch metadata hook")

vercel_celery-0.7.0/pyproject.toml

@@ -0,0 +1,64 @@
+[build-system]
+requires = ["hatchling>=1.27.0,<2"]
+build-backend = "hatchling.build"
+
+[project]
+name = "vercel-celery"
+dynamic = ["version", "dependencies"]
+description = "Celery integration for Vercel Queue and Runtime Cache"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE", "LICENSE.*"]
+
+[tool.hatch.metadata.hooks.custom]
+path = "hatch_build.py"
+
+[tool.vercel.release.dependencies]
+dependencies = [
+    "celery>=5.3,<6",
+    "vercel-cache>=0.6.0",
+    "vercel-queue>=0.6.0",
+]
+
+[tool.uv.sources]
+vercel-cache = { workspace = true }
+vercel-queue = { workspace = true }
+
+[tool.ruff]
+extend = "../ruff.toml"
+
+[tool.pytest.ini_options]
+addopts = "--no-header --capture=tee-sys"
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+[tool.hatch.version]
+path = "vercel/integrations/celery/version.py"
+
+[tool.hatch.build.targets.sdist]
+force-include = { "../../scripts/hatch_build.py" = "/_vercel_hatch_build.py" }
+include = [
+    "/vercel/integrations/celery/**/*.py",
+    "/vercel/integrations/celery/py.typed",
+    "/README.md",
+    "/pyproject.toml",
+    "/hatch_build.py",
+    "/LICENSE",
+]
+exclude = [
+    "/**/__pycache__",
+]
+
+[tool.hatch.build.targets.wheel]
+dev-mode-dirs = ["."]
+only-include = [
+    "/vercel/integrations/celery",
+]
+exclude = [
+    "/**/__pycache__",
+]
+
+[tool.poe]
+include = "../../scripts/poe/poe.toml"
+verbosity = -1

vercel_celery-0.7.0/vercel/integrations/celery/__init__.py

@@ -0,0 +1,141 @@
+"""Celery integration for Vercel Queue Service."""
+
+from kombu.transport import TRANSPORT_ALIASES, virtual
+
+from celery.app import backends as celery_backends
+from celery.app.defaults import DEFAULTS as CELERY_DEFAULTS
+from vercel.queue import CommunicationError, TokenResolutionError, UnauthorizedError
+
+from ._broker import (
+    AutoChannel,
+    PollChannel,
+    PushChannel,
+    _configure_existing_app_defaults,
+    _install_app_finalize_hook,
+    _install_connection_transport_options_hook,
+    _register_existing_app_queues,
+    _set_default_broker_set_by_installer,
+    register_celery_app_queues,
+)
+from ._result_backend import DEFAULT_RESULT_BACKEND_ALIAS, VercelRuntimeCacheBackend
+from .version import __version__
+
+_DEFAULT_CONNECTION_PARAMS = {"hostname": None, "port": None}
+# Token resolution depends on request-scoped OIDC context that may be
+# momentarily unavailable on Celery-owned threads (and refreshes with the next
+# push delivery). A cached token can also expire between local resolution and the
+# remote request, producing UnauthorizedError once before the next resolution
+# evicts it. CommunicationError is ordinary network trouble. Treat all three as
+# recoverable connection failures so the Celery consumer restarts instead of
+# shutting the worker down permanently. Kombu's own connection_errors use
+# amqp.exceptions.ConnectionError, not the builtin, so CommunicationError must be
+# listed explicitly.
+_CONNECTION_ERRORS = (
+    *virtual.Transport.connection_errors,
+    TokenResolutionError,
+    UnauthorizedError,
+    CommunicationError,
+)
+
+
+class VercelQueueTransport(virtual.Transport):
+    """Kombu transport that auto-selects Vercel Queue Service delivery mode.
+
+    The transport uses push delivery when running on Vercel and polling otherwise. It is registered
+    as ``vercel://`` by ``install_vercel_celery_integration``.
+    """
+
+    Channel = AutoChannel
+    driver_type = "vercel"
+    driver_name = "Vercel Queue Service"
+    default_connection_params = _DEFAULT_CONNECTION_PARAMS
+    connection_errors = _CONNECTION_ERRORS
+
+
+class VercelQueuePollTransport(virtual.Transport):
+    """Kombu transport that always polls Vercel Queue Service.
+
+    It is registered as ``vercel-poll://`` by ``install_vercel_celery_integration`` and is intended
+    for workers that cannot receive Vercel Queue push deliveries.
+    """
+
+    Channel = PollChannel
+    driver_type = "vercel"
+    driver_name = "Vercel Queue Service (poll)"
+    default_connection_params = _DEFAULT_CONNECTION_PARAMS
+    connection_errors = _CONNECTION_ERRORS
+
+
+class VercelQueuePushTransport(virtual.Transport):
+    """Kombu transport that receives Vercel Queue Service push deliveries.
+
+    It is registered as ``vercel-push://`` by ``install_vercel_celery_integration`` and requires the
+    app's queues to be registered as Vercel Queue topic subscribers.
+    """
+
+    Channel = PushChannel
+    driver_type = "vercel"
+    driver_name = "Vercel Queue Service (push)"
+    default_connection_params = _DEFAULT_CONNECTION_PARAMS
+    connection_errors = _CONNECTION_ERRORS
+
+
+def install_vercel_celery_integration(
+    *,
+    register_queues: bool = True,
+    set_default_broker: bool = True,
+    set_default_result_backend: bool = True,
+) -> None:
+    """Register Vercel Queue Service as a Celery broker integration.
+
+    Register ``vercel://``. ``vercel-poll://``, and ``vercel-push://`` as valid Kombu transport
+    aliases for automatic push/poll, always-poll, and always-push modes correspondingly. When
+    *set_default_broker* is ``True`` (default), also set Celery default broker URL to ``vercel://``
+    when no broker is configured already. When *set_default_result_backend* is ``True`` (default),
+    set Celery's default result backend to ``vercel-runtime-cache://`` when no result backend is
+    configured already. When *register_queues* is `True` (default), automatically register all
+    Celery queues as Vercel Queues topic subscribers.
+
+    This also registers ``vercel-runtime-cache://`` as the Vercel Runtime Cache result backend
+    alias.
+    """
+    TRANSPORT_ALIASES["vercel"] = (
+        f"{VercelQueueTransport.__module__}:{VercelQueueTransport.__name__}"
+    )
+    TRANSPORT_ALIASES["vercel-poll"] = (
+        f"{VercelQueuePollTransport.__module__}:{VercelQueuePollTransport.__name__}"
+    )
+    TRANSPORT_ALIASES["vercel-push"] = (
+        f"{VercelQueuePushTransport.__module__}:{VercelQueuePushTransport.__name__}"
+    )
+    celery_backends.BACKEND_ALIASES[DEFAULT_RESULT_BACKEND_ALIAS] = (
+        f"{VercelRuntimeCacheBackend.__module__}:{VercelRuntimeCacheBackend.__name__}"
+    )
+    default_broker_url = "vercel://" if set_default_broker else None
+    default_result_backend = (
+        f"{DEFAULT_RESULT_BACKEND_ALIAS}://" if set_default_result_backend else None
+    )
+    if set_default_broker and CELERY_DEFAULTS.get("broker_url") is None:
+        CELERY_DEFAULTS["broker_url"] = default_broker_url
+        _set_default_broker_set_by_installer(value=True)
+    if set_default_result_backend and CELERY_DEFAULTS.get("result_backend") is None:
+        CELERY_DEFAULTS["result_backend"] = default_result_backend
+    _install_connection_transport_options_hook()
+    _install_app_finalize_hook(register_queues=register_queues)
+    _configure_existing_app_defaults(
+        broker_url=default_broker_url,
+        result_backend=default_result_backend,
+    )
+    if register_queues:
+        _register_existing_app_queues()
+
+
+__all__ = [
+    "VercelQueuePollTransport",
+    "VercelQueuePushTransport",
+    "VercelQueueTransport",
+    "VercelRuntimeCacheBackend",
+    "__version__",
+    "install_vercel_celery_integration",
+    "register_celery_app_queues",
+]