encore-dev 2.0.0a7__py3-none-any.whl

encore/__init__.py

@@ -0,0 +1,43 @@
+"""Encore SDK for Python — infrastructure resources.
+
+Declare infrastructure (SQL databases, pub/sub, object storage, Redis, cron jobs,
+metrics, secrets) as module-level variables; Encore's parser discovers them for
+provisioning and wiring, and this package's runtime binding (``encore_sdk_core`` over
+PyO3) connects them to the provisioned infrastructure at run time.
+
+Services are declared by the language-agnostic ``encore.service.json`` file, not in
+Python — this SDK is infrastructure-only.
+
+After importing resource declarations, call ``await encore.start()`` once from
+your async main or framework startup hook. This starts all registered subscription
+handlers on the application's loop and returns so the application can serve.
+
+    from encore import pubsub, secrets
+    from encore.storage import postgres
+
+    db = postgres.Database("orders", migrations="./migrations")
+    events = pubsub.Topic("order-events")
+    api_key = secrets.Secret("ApiKey")
+"""
+
+from __future__ import annotations
+
+from . import cron, meta, metrics, pubsub, secrets, shutdown, storage
+from .internal.runtime import EncoreError, run_forever, version
+from .internal.startup import start
+from .meta import app_meta
+
+__all__ = [
+    "storage",
+    "pubsub",
+    "cron",
+    "meta",
+    "metrics",
+    "secrets",
+    "shutdown",
+    "EncoreError",
+    "app_meta",
+    "run_forever",
+    "start",
+    "version",
+]

encore/cron/__init__.py

@@ -0,0 +1,50 @@
+"""Cron jobs.
+
+Typical usage example:
+
+    from encore import cron
+
+    _ = cron.Job("cleanup", path="/internal/cleanup", title="Nightly cleanup", every="24h")
+
+A cron job is a parse-time declaration: the parser discovers it and, when the
+job is due, the platform sends a ``POST`` request for ``path`` to the service
+that declares the job. There is no runtime client.
+"""
+
+from __future__ import annotations
+
+
+class Job:
+    """A scheduled HTTP request declared at module scope."""
+
+    def __init__(
+        self,
+        name: str,
+        *,
+        path: str,
+        title: str | None = None,
+        every: str | None = None,
+        schedule: str | None = None,
+    ) -> None:
+        """Declare a cron job with exactly one scheduling option.
+
+        Args:
+            name: The cron job's resource name.
+            path: The service path to call with POST, starting with a slash.
+            title: An optional human-readable title.
+            every: The interval between calls, such as "24h". Excludes schedule.
+            schedule: A cron expression. Excludes every.
+
+        Raises:
+            ValueError: Both or neither scheduling options are set, or path does
+                not start with a slash.
+        """
+        if (every is None) == (schedule is None):
+            raise ValueError("set exactly one of `every` or `schedule`")
+        if not path.startswith("/"):
+            raise ValueError("`path` must start with `/`")
+        self._name = name
+        self._path = path
+        self._title = title
+        self._every = every
+        self._schedule = schedule

encore/internal/__init__.py

@@ -0,0 +1 @@
+"""Internal plumbing for the Encore SDK. Not part of the public API."""

encore/internal/_loader.py

@@ -0,0 +1,79 @@
+"""Loading the native extension without starting the runtime.
+
+The log handler uses _encore_runtime for encoding before runtime startup.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import os
+from pathlib import Path
+import sys
+import sysconfig
+from typing import TYPE_CHECKING
+
+
+def _runtime_relative_path() -> Path:
+    """Select the runtime directory using the interpreter ABI.
+
+    A free-threaded build uses its own ABI even when its GIL is enabled.
+    """
+    if sysconfig.get_config_var("Py_GIL_DISABLED"):
+        variant = f"cp{sys.version_info.major}{sys.version_info.minor}t"
+        filename = (
+            "_encore_runtime.pyd" if sys.platform == "win32" else "_encore_runtime.so"
+        )
+        return Path(variant) / filename
+    return Path(
+        "_encore_runtime.pyd" if sys.platform == "win32" else "_encore_runtime.abi3.so"
+    )
+
+
+def _load_native():
+    explicit = os.environ.get("ENCORE_PYTHON_RUNTIME_LIB")
+    root = os.environ.get("ENCORE_PYTHON_RUNTIME_DIR")
+    relative = _runtime_relative_path()
+    if explicit:
+        path = Path(explicit)
+    elif root:
+        path = Path(root) / relative
+    else:
+        # Deployment builds preserve an explicit library override separately.
+        override = (
+            "_encore_runtime_override.pyd"
+            if sys.platform == "win32"
+            else "_encore_runtime_override.so"
+        )
+        path = next(
+            (
+                candidate
+                for directory in Path(__file__).resolve().parents
+                for base in (directory, directory / "dist")
+                for candidate in (base / override, base / relative)
+                if candidate.is_file()
+            ),
+            None,
+        )
+    if path is None or not path.is_file():
+        raise ImportError(
+            f"Could not find the Encore Python runtime for {relative}"
+            + (f" at {path}" if path is not None else "")
+            + ". Run through the Encore CLI, set ENCORE_PYTHON_RUNTIME_DIR to a "
+            "directory containing the matching ABI, or set ENCORE_PYTHON_RUNTIME_LIB "
+            "to the native library. For SDK development, run "
+            "`cargo xtask build-py-runtime` with the matching --python-runtime."
+        )
+    spec = importlib.util.spec_from_file_location("_encore_runtime", path)
+    if spec is None or spec.loader is None:
+        raise ImportError(f"Cannot load the Encore Python runtime from {path}")
+    native = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(native)
+    sys.modules[spec.name] = native
+    return native
+
+
+if TYPE_CHECKING:
+    # Stub-only module; the implementation is loaded dynamically below.
+    from . import _native  # pyright: ignore[reportMissingModuleSource]
+else:
+    _native = _load_native()