encore-dev 2.0.0a7__tar.gz → 2.0.0a8__tar.gz

{encore_dev-2.0.0a7 → encore_dev-2.0.0a8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: encore-dev
-Version: 2.0.0a7
+Version: 2.0.0a8
 Summary: Encore SDK for Python — infrastructure resources
 Author: Encore
 License: MPL-2.0
@@ -40,6 +40,24 @@ async def place_order(order):
     await events.publish({"id": order.id})
 ```
 
+## Service URLs
+
+Use `base_url` to look up a service's configured base URL:
+
+```python
+from encore.services import base_url
+
+order = f"{base_url('orders')}/orders/123"
+```
+
+The returned string has no trailing slash: a call's path goes after it. Unknown
+service names raise `ValueError`. Lookup reads the runtime configuration and
+makes no network request.
+
+Looking up a service's URL makes the calling service depend on it, which Encore
+reads from the code: pass the name as a string literal, call `base_url` directly
+rather than passing it around, and call it in a service.
+
 ## Postgres queries and handles
 
 Declare `postgres.Database("orders", migrations="./migrations")` at module scope.
@@ -73,9 +91,10 @@ select `read()`, `write()`, or `admin()` before handing it to another function.
 Direct database operations infer writer permissions. Reference creation records
 reader, writer, or admin permissions at that call site.
 
-Like the Rust SDK, access selection currently controls parser permission
-inference. Handles still share one runtime pool; per-handle privilege enforcement
-and replica routing (including the `read(primary=True)` preference) are pending.
+Like the Rust SDK, handles share the database's pool. A `read()` handle runs on
+read-only connections, so its writes fail with SQLSTATE 25006 and its
+transactions are read-only; it reads from the database's read-only pool on a
+replica if the runtime config has one, unless `primary=True` is set.
 
 ```python
 async def rename_order(order_id: int, name: str):
@@ -412,10 +431,12 @@ uv run --project sdk/py/infra ruff format --check sdk/py/infra
 The generated `_native.pyi` is excluded from linting and formatting because it
 is owned by the PyO3 stub generator. It is still checked by ty.
 
-## Numeric counters and label groups
+## Metrics
 
-Counters default to unsigned 64-bit integers. Use `Counter[float]` for fractional
-increments and `CounterGroup[Labels, float]` for labeled float counters:
+Metrics are OpenTelemetry instruments of the meter `encore`, declared at module
+scope in three scopes (`Counter`, `SharedCounter`, `GlobalCounter`, and so on
+for `UpDownCounter`, `Gauge` and `Histogram`), each with a `…Group` form whose
+labels are a `TypedDict` or a dataclass:
 
 ```python
 from dataclasses import dataclass
@@ -425,74 +446,43 @@ from encore import metrics
 
 @dataclass(frozen=True)
 class Labels:
-    operation: str
+    route: str
 
 
-requests = metrics.CounterGroup[Labels]("requests")
-usage = metrics.CounterGroup[Labels, float]("usage")
-cpu_time = metrics.Counter[float]("cpu_time")
+latency = metrics.HistogramGroup[Labels]("request_duration", unit="s")
 
-requests.with_labels(Labels("checkout")).increment()
-usage.with_labels(Labels("checkout")).increment(0.125)
-cpu_time.increment(0.025)
+latency.with_labels(Labels("/orders")).record(0.025)
 ```
 
-This syntax works on Python 3.9 and later. Put numeric type arguments on the
-constructor; a variable annotation alone does not select runtime storage.
-`with_labels()` returns `Counter[int]` or `Counter[float]` to the type checker.
-Existing `Counter(name)` and `CounterGroup[Labels](name)` keep their integer
-behavior. Gauge values already use floating-point storage.
-
-Float increments must be finite and nonnegative. An update that would overflow
-the total raises `ValueError` without changing it. Double-precision totals can
-incur rounding, including loss of integer precision above `2**53`. Integer and
-float counters cannot share a native series. Integer totals still wrap on 64-bit
-overflow. Calling `increment()` without a value adds one in either mode.
+A service's own metric (`Counter`, `HistogramGroup`, …) is exported as
+`<service>.<name>`: `request_duration` of the service `shop` is
+`shop.request_duration`. Shared and global ones keep their name, and are
+declared once: other modules import the declaration, and code in another
+language binds one by name, as in
+`metrics.CounterGroup[Labels].named("responses_total")`. Hand a metric to other
+code as a reference, `latency.ref()`.
 
-All metric groups accept dataclass instances as well as mappings, including
-TypedDicts. Fields must contain strings, booleans, or finite numbers. Nested
-objects are rejected. Numeric labels are rounded down to integer strings and
-booleans become `"true"` or `"false"`. Names are normalized to snake_case; `service`
-is reserved. The label values are captured when binding, so later mutation does
-not change an existing series. `GaugeGroup[Labels]` and `HistogramGroup[Labels]`
-also provide typed label arguments.
+Label keys are snake_case; values are strings, ints and bools, anything else a
+`TypeError`. `unit`, `description` and a histogram's `buckets` must be literals:
+Encore's parser reads them.
 
-## Histogram metrics
+## OpenTelemetry
 
-Declare histograms at module scope to record distributions such as request
-duration or payload size. Record one observation for each measurement:
+Encore records its spans and metrics through its own providers and installs no
+OpenTelemetry globals, leaving an app's own setup alone. For the app's spans
+and instruments, and instrumentation packages', install Encore's providers or
+pass them to an instrumentation:
 
 ```python
-from typing import TypedDict
-
-from encore import metrics
-
-
-class Labels(TypedDict):
-    route: str
+from opentelemetry import metrics, trace
 
+from encore.metrics import meter_provider
+from encore.tracing import tracer_provider
 
-latency = metrics.Histogram("request_duration", unit="seconds")
-sizes = metrics.HistogramGroup[Labels]("response_size", unit="bytes")
-
-latency.observe(0.025)
-sizes.with_labels({"route": "/orders"}).observe(512)
+trace.set_tracer_provider(tracer_provider())
+metrics.set_meter_provider(meter_provider())
 ```
 
-The runtime maintains count, sum, and automatic exponential buckets without
-keeping individual measurements. Bucket widths grow by at most 10%. `unit` is
-optional metadata, must be a string literal when supplied, and does not convert
-values. Histogram groups normalize and cache labels like counter groups. Use
-labels with a small set of values: each combination retains a series for the
-process lifetime.
-
-Prefer finite observations. As in Rust, NaN increments the count and makes the
-sum NaN without entering a bucket; infinities enter their own buckets.
-
-Prometheus remote write exports the bucket distribution for approximate
-percentile queries. AWS, GCP, and Datadog currently export only `<name>_count`
-and `<name>_sum`, which support averages but not percentiles.
-
 ## Documentation style
 
 Follow the [Google Python docstring guide](https://google.github.io/styleguide/pyguide.html#docstrings)

{encore_dev-2.0.0a7 → encore_dev-2.0.0a8}/README.md

@@ -27,6 +27,24 @@ async def place_order(order):
     await events.publish({"id": order.id})
 ```
 
+## Service URLs
+
+Use `base_url` to look up a service's configured base URL:
+
+```python
+from encore.services import base_url
+
+order = f"{base_url('orders')}/orders/123"
+```
+
+The returned string has no trailing slash: a call's path goes after it. Unknown
+service names raise `ValueError`. Lookup reads the runtime configuration and
+makes no network request.
+
+Looking up a service's URL makes the calling service depend on it, which Encore
+reads from the code: pass the name as a string literal, call `base_url` directly
+rather than passing it around, and call it in a service.
+
 ## Postgres queries and handles
 
 Declare `postgres.Database("orders", migrations="./migrations")` at module scope.
@@ -60,9 +78,10 @@ select `read()`, `write()`, or `admin()` before handing it to another function.
 Direct database operations infer writer permissions. Reference creation records
 reader, writer, or admin permissions at that call site.
 
-Like the Rust SDK, access selection currently controls parser permission
-inference. Handles still share one runtime pool; per-handle privilege enforcement
-and replica routing (including the `read(primary=True)` preference) are pending.
+Like the Rust SDK, handles share the database's pool. A `read()` handle runs on
+read-only connections, so its writes fail with SQLSTATE 25006 and its
+transactions are read-only; it reads from the database's read-only pool on a
+replica if the runtime config has one, unless `primary=True` is set.
 
 ```python
 async def rename_order(order_id: int, name: str):
@@ -399,10 +418,12 @@ uv run --project sdk/py/infra ruff format --check sdk/py/infra
 The generated `_native.pyi` is excluded from linting and formatting because it
 is owned by the PyO3 stub generator. It is still checked by ty.
 
-## Numeric counters and label groups
+## Metrics
 
-Counters default to unsigned 64-bit integers. Use `Counter[float]` for fractional
-increments and `CounterGroup[Labels, float]` for labeled float counters:
+Metrics are OpenTelemetry instruments of the meter `encore`, declared at module
+scope in three scopes (`Counter`, `SharedCounter`, `GlobalCounter`, and so on
+for `UpDownCounter`, `Gauge` and `Histogram`), each with a `…Group` form whose
+labels are a `TypedDict` or a dataclass:
 
 ```python
 from dataclasses import dataclass
@@ -412,74 +433,43 @@ from encore import metrics
 
 @dataclass(frozen=True)
 class Labels:
-    operation: str
+    route: str
 
 
-requests = metrics.CounterGroup[Labels]("requests")
-usage = metrics.CounterGroup[Labels, float]("usage")
-cpu_time = metrics.Counter[float]("cpu_time")
+latency = metrics.HistogramGroup[Labels]("request_duration", unit="s")
 
-requests.with_labels(Labels("checkout")).increment()
-usage.with_labels(Labels("checkout")).increment(0.125)
-cpu_time.increment(0.025)
+latency.with_labels(Labels("/orders")).record(0.025)
 ```
 
-This syntax works on Python 3.9 and later. Put numeric type arguments on the
-constructor; a variable annotation alone does not select runtime storage.
-`with_labels()` returns `Counter[int]` or `Counter[float]` to the type checker.
-Existing `Counter(name)` and `CounterGroup[Labels](name)` keep their integer
-behavior. Gauge values already use floating-point storage.
-
-Float increments must be finite and nonnegative. An update that would overflow
-the total raises `ValueError` without changing it. Double-precision totals can
-incur rounding, including loss of integer precision above `2**53`. Integer and
-float counters cannot share a native series. Integer totals still wrap on 64-bit
-overflow. Calling `increment()` without a value adds one in either mode.
+A service's own metric (`Counter`, `HistogramGroup`, …) is exported as
+`<service>.<name>`: `request_duration` of the service `shop` is
+`shop.request_duration`. Shared and global ones keep their name, and are
+declared once: other modules import the declaration, and code in another
+language binds one by name, as in
+`metrics.CounterGroup[Labels].named("responses_total")`. Hand a metric to other
+code as a reference, `latency.ref()`.
 
-All metric groups accept dataclass instances as well as mappings, including
-TypedDicts. Fields must contain strings, booleans, or finite numbers. Nested
-objects are rejected. Numeric labels are rounded down to integer strings and
-booleans become `"true"` or `"false"`. Names are normalized to snake_case; `service`
-is reserved. The label values are captured when binding, so later mutation does
-not change an existing series. `GaugeGroup[Labels]` and `HistogramGroup[Labels]`
-also provide typed label arguments.
+Label keys are snake_case; values are strings, ints and bools, anything else a
+`TypeError`. `unit`, `description` and a histogram's `buckets` must be literals:
+Encore's parser reads them.
 
-## Histogram metrics
+## OpenTelemetry
 
-Declare histograms at module scope to record distributions such as request
-duration or payload size. Record one observation for each measurement:
+Encore records its spans and metrics through its own providers and installs no
+OpenTelemetry globals, leaving an app's own setup alone. For the app's spans
+and instruments, and instrumentation packages', install Encore's providers or
+pass them to an instrumentation:
 
 ```python
-from typing import TypedDict
-
-from encore import metrics
-
-
-class Labels(TypedDict):
-    route: str
+from opentelemetry import metrics, trace
 
+from encore.metrics import meter_provider
+from encore.tracing import tracer_provider
 
-latency = metrics.Histogram("request_duration", unit="seconds")
-sizes = metrics.HistogramGroup[Labels]("response_size", unit="bytes")
-
-latency.observe(0.025)
-sizes.with_labels({"route": "/orders"}).observe(512)
+trace.set_tracer_provider(tracer_provider())
+metrics.set_meter_provider(meter_provider())
 ```
 
-The runtime maintains count, sum, and automatic exponential buckets without
-keeping individual measurements. Bucket widths grow by at most 10%. `unit` is
-optional metadata, must be a string literal when supplied, and does not convert
-values. Histogram groups normalize and cache labels like counter groups. Use
-labels with a small set of values: each combination retains a series for the
-process lifetime.
-
-Prefer finite observations. As in Rust, NaN increments the count and makes the
-sum NaN without entering a bucket; infinities enter their own buckets.
-
-Prometheus remote write exports the bucket distribution for approximate
-percentile queries. AWS, GCP, and Datadog currently export only `<name>_count`
-and `<name>_sum`, which support averages but not percentiles.
-
 ## Documentation style
 
 Follow the [Google Python docstring guide](https://google.github.io/styleguide/pyguide.html#docstrings)

{encore_dev-2.0.0a7 → encore_dev-2.0.0a8}/encore/__init__.py

@@ -1,7 +1,7 @@
 """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
+metrics, secrets, config) 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.
 
@@ -22,18 +22,20 @@ handlers on the application's loop and returns so the application can serve.
 
 from __future__ import annotations
 
-from . import cron, meta, metrics, pubsub, secrets, shutdown, storage
+from . import config, cron, env, metrics, pubsub, secrets, services, shutdown, storage
 from .internal.runtime import EncoreError, run_forever, version
 from .internal.startup import start
-from .meta import app_meta
+from .env import app_meta
 
 __all__ = [
+    "config",
     "storage",
     "pubsub",
     "cron",
-    "meta",
+    "env",
     "metrics",
     "secrets",
+    "services",
     "shutdown",
     "EncoreError",
     "app_meta",

encore_dev-2.0.0a8/encore/config/__init__.py

@@ -0,0 +1,268 @@
+"""Application config: typed values a service reads.
+
+Values are written in TOML or JSON files beside the code, and can change
+while the app runs.
+
+Typical usage example:
+
+    from dataclasses import dataclass
+    from datetime import timedelta
+    from typing import Annotated
+
+    from encore.config import Config, Max, Min
+    from encore.secrets import Secret
+
+
+    @dataclass
+    class Checkout:
+        max_items: Annotated[int, Min(1), Max(500)]
+        payment_timeout: timedelta = timedelta(seconds=90)
+        stripe_key: Secret[str] = Secret[str]("StripeKey")
+
+
+    checkout = Config[Checkout]("checkout")
+
+    limit = checkout.value.max_items
+
+Scope:
+    Which class a config is declared with says who it belongs to, as with
+    secrets. A Config belongs to the service that declares it, which holds
+    its own value for it, and must be declared inside a service. A
+    SharedConfig has one value for the whole app; each service that reads it
+    is recorded as using it. A GlobalConfig has one value for the whole app
+    and is available to every service without being recorded.
+
+Values:
+    A config's value is a snapshot of its type: ``value`` never fails, since
+    the runtime checked the value against the config's schema before the
+    service started. Encore derives that schema from the type: a dataclass,
+    a TypedDict or an Enum, built of str, int, float, bool, Literal, Optional,
+    list, dict[str, ...], typing.Any and datetime.timedelta (written as a
+    string such as "30s"). A dataclass field with a default, and an Optional
+    one, may be left out. Constraints are Annotated markers: Min, Max,
+    MinLen, MaxLen, Pattern, MinItems and MaxItems.
+
+    A field of type Secret reads a secret rather than holding a value; its
+    default names it: ``api_key: Secret[str] = Secret[str]("StripeKey")``.
+    The secret's scope is the config's: a Config reads its service's own
+    secret, a SharedConfig a shared one, a GlobalConfig a global one. The
+    secret is declared in code as usual, with that scope.
+
+Changes:
+    A config's value can change while the app runs: an edit to its files
+    under ``encore run``, a new value from Encore Cloud. Each read of
+    ``value`` gives the newest; keep the snapshot for as long as one
+    consistent value is wanted. on_change calls a function with each new
+    value, on a thread of its own; values that come faster than it is called
+    are coalesced to the latest.
+
+Files:
+    A config's value is written in a file named after it,
+    ``checkout.config.toml`` (or ``.json``), beside the declaring service's
+    ``encore.service.json``, or beside ``encore.app`` for a shared or global
+    config. Overlays change it for some environments only:
+    ``checkout.production.config.toml`` for an environment type,
+    ``checkout.@prod-eu.config.toml`` for one environment, and
+    ``checkout.user.config.toml``, the user override, for a developer's own
+    ``encore run`` (it is gitignored, and never read in tests).
+
+Tests:
+    Under ``encore test`` a config has its ``test`` overlay's value.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import threading
+from typing import Any, Callable, Generic, Optional, Tuple, TypeVar, get_args
+
+from ..internal.lazy import Lazy
+from ..internal.runtime import _native, runtime
+from ._build import ConfigMismatchError, build
+from ._markers import Max, MaxItems, MaxLen, Min, MinItems, MinLen, Pattern
+
+__all__ = [
+    "Config",
+    "ConfigMismatchError",
+    "GlobalConfig",
+    "Max",
+    "MaxItems",
+    "MaxLen",
+    "Min",
+    "MinItems",
+    "MinLen",
+    "Pattern",
+    "SharedConfig",
+]
+
+_T = TypeVar("_T")
+
+_log = logging.getLogger("encore.config")
+
+#: How long a change listener waits for a new value before looking again
+#: whether it has been stopped.
+_POLL = 0.5
+
+
+class _Config(Generic[_T]):
+    """Common public behavior, backed by a scope-specific lookup."""
+
+    def __init__(
+        self, name: str, load: Callable[[str], Optional[_native.Config]]
+    ) -> None:
+        self._name = name
+        self._handle = Lazy(lambda: load(name))
+        self._lock = threading.Lock()
+        # The value built for a revision: (revision, value).
+        self._built: Optional[Tuple[int, Any]] = None
+
+    @property
+    def name(self) -> str:
+        """The name the config was declared with."""
+        return self._name
+
+    def _type(self) -> Any:
+        args = get_args(getattr(self, "__orig_class__", None))
+        if not args:
+            raise TypeError(
+                f"Use {type(self).__name__}[T](name) with the config's type, such as "
+                f"{type(self).__name__}[Checkout]({self._name!r})"
+            )
+        return args[0]
+
+    @property
+    def value(self) -> _T:
+        """The config's value now, as its type.
+
+        A snapshot: built once for each new value, and shared by every read
+        until the value changes.
+
+        Raises:
+            TypeError: The config was declared without its type argument.
+            ConfigMismatchError: The value does not fit the type although it
+                satisfied the schema Encore derived from it: a bug in Encore.
+        """
+        tp = self._type()
+        handle = self._handle.get()
+        if handle is None:
+            # The runtime has no value for it: the type's defaults are it.
+            return self._value_of(tp, -1, "{}")
+        revision, text = handle.current()
+        return self._value_of(tp, revision, text)
+
+    def _value_of(self, tp: Any, revision: int, text: str) -> Any:
+        """The value of one revision, built once for it."""
+        built = self._built
+        if built is not None and built[0] == revision:
+            return built[1]
+        result = build(tp, json.loads(text), self._name)
+        with self._lock:
+            # Another thread may have built this revision meanwhile: one
+            # revision is one snapshot.
+            if self._built is not None and self._built[0] == revision:
+                return self._built[1]
+            # Only a newer revision replaces the snapshot: a listener may
+            # build one that the value has since moved on from.
+            if self._built is None or self._built[0] < revision:
+                self._built = (revision, result)
+        return result
+
+    def on_change(self, fn: Callable[[_T], None]) -> Callable[[], None]:
+        """Call ``fn`` with each new value the config is given from now on.
+
+        Values that come faster than ``fn`` is called are coalesced: ``fn``
+        gets the latest, once. ``fn`` runs on a thread of its own; keep it
+        quick. An exception it raises is logged, and later values still reach
+        it.
+
+        Returns:
+            A function that stops the calls.
+        """
+        stop = threading.Event()
+        handle = self._handle.get()
+        if handle is None:
+            # Nothing gives it a new value.
+            return stop.set
+        tp = self._type()
+        seen, _ = handle.current()
+
+        def listen() -> None:
+            nonlocal seen
+            while not stop.is_set():
+                got = handle.wait(seen, _POLL)
+                if got is None or stop.is_set():
+                    continue
+                # The revision waited for, not the value now: that may be a
+                # later one, which the next wait returns.
+                seen, text = got
+                try:
+                    fn(self._value_of(tp, seen, text))
+                except Exception:
+                    _log.exception("config %r: a change listener failed", self._name)
+
+        threading.Thread(
+            target=listen, name=f"encore-config-{self._name}", daemon=True
+        ).start()
+        return stop.set
+
+    def __repr__(self) -> str:
+        return f"{type(self).__name__}({self._name!r})"
+
+
+class Config(_Config[_T]):
+    """A config belonging to the service that declares it.
+
+    The service holds its own value for it. Must be declared inside a service.
+
+    Example:
+        checkout = Config[Checkout]("checkout")
+    """
+
+    def __init__(self, name: str) -> None:
+        """Declare a service's own config at module scope.
+
+        Args:
+            name: The config's name, an identifier. Instantiate with the type
+                argument, such as Config[Checkout]("checkout").
+        """
+        super().__init__(name, lambda key: runtime().config(key))
+
+
+class SharedConfig(_Config[_T]):
+    """A config with one value for the whole app.
+
+    A service that reads it is recorded as using it. May be declared outside a
+    service.
+
+    Example:
+        flags = SharedConfig[Flags]("flags")
+    """
+
+    def __init__(self, name: str) -> None:
+        """Declare a shared config at module scope.
+
+        Args:
+            name: The config's name, an identifier. Instantiate with the type
+                argument, such as SharedConfig[Flags]("flags").
+        """
+        super().__init__(name, lambda key: runtime().shared_config(key))
+
+
+class GlobalConfig(_Config[_T]):
+    """A config with one value for the whole app, available to every service.
+
+    Reading it is not recorded as using it. May be declared outside a service.
+
+    Example:
+        limits = GlobalConfig[Limits]("limits")
+    """
+
+    def __init__(self, name: str) -> None:
+        """Declare a global config at module scope.
+
+        Args:
+            name: The config's name, an identifier. Instantiate with the type
+                argument, such as GlobalConfig[Limits]("limits").
+        """
+        super().__init__(name, lambda key: runtime().shared_config(key))