encore-dev 2.0.0a7__py3-none-any.whl

encore/internal/_native.pyi

@@ -0,0 +1,734 @@
+# Generated by cargo xtask build-py-runtime. Do not edit manually.
+import typing
+
+from collections.abc import Sequence
+from datetime import datetime
+from typing import Any, Final, final
+
+RUNTIME_LOGGER: Final[str]
+"""
+The logger of the runtime's own lines.
+"""
+
+@final
+class AttrsOptions:
+    def __new__(cls, /, *, version: str |None = None) -> "AttrsOptions": ...
+
+@final
+class Bucket:
+    def list(self, /, options: ListOptions |None = None, source: bytes |None = None) -> "typing.Awaitable[ListIterator]": ...
+    def object(self, /, name: str) -> "BucketObject": ...
+
+@final
+class BucketObject:
+    def attrs(self, /, options: AttrsOptions |None = None, source: bytes |None = None) -> "typing.Awaitable[ObjectAttrs]": ...
+    def delete(self, /, options: DeleteOptions |None = None, source: bytes |None = None) -> "typing.Awaitable[None]": ...
+    def download_all(self, /, options: DownloadOptions |None = None, source: bytes |None = None) -> "typing.Awaitable[bytes]": ...
+    def download_stream(self, /, options: DownloadOptions |None = None, source: bytes |None = None) -> "typing.Awaitable[DownloadStream]": ...
+    def exists(self, /, options: ExistsOptions |None = None, source: bytes |None = None) -> "typing.Awaitable[bool]": ...
+    def public_url(self, /) -> "str": ...
+    def signed_download_url(self, /, options: DownloadUrlOptions |None = None, source: bytes |None = None) -> "typing.Awaitable[str]": ...
+    def signed_upload_url(self, /, options: UploadUrlOptions |None = None, source: bytes |None = None) -> "typing.Awaitable[str]": ...
+    def upload(self, /, data: bytes, options: UploadOptions |None = None, source: bytes |None = None) -> "typing.Awaitable[ObjectAttrs]": ...
+    def upload_stream(self, /, options: UploadOptions |None = None, source: bytes |None = None) -> "UploadStream": ...
+
+@final
+class ByteRange:
+    def __new__(cls, /, *, offset: int, length: int |None = None) -> "ByteRange": ...
+
+@final
+class DeleteOptions:
+    def __new__(cls, /, *, version: str |None = None) -> "DeleteOptions": ...
+
+@final
+class DownloadOptions:
+    def __new__(cls, /, *, version: str |None = None, range: ByteRange |None = None) -> "DownloadOptions": ...
+
+@final
+class DownloadStream:
+    def close(self, /) -> "typing.Awaitable[None]": ...
+    def next(self, /) -> "typing.Awaitable[typing.Optional[bytes]]": ...
+
+@final
+class DownloadUrlOptions:
+    def __new__(cls, /, *, ttl: int |None = None) -> "DownloadUrlOptions": ...
+
+@final
+class ExistsOptions:
+    def __new__(cls, /, *, version: str |None = None) -> "ExistsOptions": ...
+
+@final
+class ListEntry:
+    @property
+    def etag(self, /) -> str: ...
+    @property
+    def name(self, /) -> str: ...
+    @property
+    def size(self, /) -> int: ...
+
+@final
+class ListIterator:
+    def mark_done(self, /) -> "typing.Awaitable[None]": ...
+    def next(self, /) -> "typing.Awaitable[typing.Optional[ListEntry]]": ...
+
+@final
+class ListOptions:
+    def __new__(cls, /, *, prefix: str |None = None, limit: int |None = None) -> "ListOptions": ...
+
+@final
+class MetricType:
+    Counter: Final[MetricType]
+    FloatCounter: Final[MetricType]
+    Gauge: Final[MetricType]
+    Histogram: Final[MetricType]
+    def __eq__(self, value: object, /) -> bool: ...
+    def __int__(self, /) -> int: ...
+    def __ne__(self, value: object, /) -> bool: ...
+    def __repr__(self, /) -> str: ...
+
+@final
+class MetricsRegistry:
+    def allocate_slot(self, /, name: str, labels: Sequence[tuple[str, str]], metric_type: MetricType) -> "int":
+        """
+        Allocate or reuse a metric slot. Label names are normalized to snake_case;
+        the runtime adds the reserved service label automatically.
+        """
+    def increment(self, /, slot: int, value: int = 1) -> "None":
+        """
+        Increment a counter by an unsigned integer. The total wraps on 64-bit overflow.
+        """
+    def increment_float(self, /, slot: int, value: float = 1.0) -> "None":
+        """
+        Add a finite, nonnegative value to a floating-point counter.
+        Reject an update that would overflow the total without changing it.
+        """
+    def observe(self, /, slot: int, value: float) -> "None":
+        """
+        Record an observation using the core's automatic exponential buckets.
+        NaN counts without a bucket and makes the sum NaN; infinities are bucketed.
+        """
+    def set(self, /, slot: int, value: float) -> "None":
+        """
+        Set a gauge to a finite floating-point value.
+        """
+    def slot_count(self, /) -> "int":
+        """
+        The number of registered metric and label combinations.
+        """
+
+@final
+class ObjectAttrs:
+    @property
+    def content_type(self, /) -> str |None: ...
+    @property
+    def etag(self, /) -> str: ...
+    @property
+    def name(self, /) -> str: ...
+    @property
+    def size(self, /) -> int: ...
+    @property
+    def version(self, /) -> str |None: ...
+
+@final
+class Pipeline:
+    """
+    Span lifecycle calls into the telemetry pipeline. Synchronous: no call
+    waits on I/O.
+    """
+    def dropped(self, /) -> "int":
+        """
+        The number of telemetry items dropped because the queue was full.
+        """
+    def end_span(self, /, packed: bytes) -> "None":
+        """
+        Ends a span. `packed`: the finished span in the packed layout.
+        """
+    def start_span(self, /, name: str, kind: int, parent: bytes |None, tracestate: str |None, start_unix_nanos: int |None, packed: bytes) -> "tuple[bytes, str, int, int]":
+        """
+        Starts a span. `parent`: 25-byte context, with `tracestate`.
+        `packed`: start scope, attributes, and links in the packed layout.
+        Returns the span's 25-byte context, tracestate, and start clocks
+        (unix, monotonic nanoseconds).
+        """
+
+@final
+class PostgresCursor:
+    """
+    A streaming query result that retains its connection or transaction.
+
+    Exhaust or close the cursor to release the borrowed handle. Destroying the
+    cursor also releases the handle once any in-flight operation finishes.
+    """
+    def close(self, /) -> "typing.Awaitable[None]":
+        """
+        Release the cursor's connection or transaction borrow.
+
+        Returns:
+            An awaitable that completes after any active read finishes and the cursor
+            closes. Repeated closes have no effect.
+        """
+    def next(self, /) -> "typing.Awaitable[typing.Optional[dict[str, typing.Any]]]":
+        """
+        Fetch the next row asynchronously.
+
+        Requires that no other read is active.
+
+        Returns:
+            An awaitable that produces a dictionary of column names to decoded Python
+            values, or None when the cursor is exhausted or closed. Exhaustion releases
+            the borrowed connection or transaction.
+
+        Raises:
+            EncoreError: Reading or decoding a row fails.
+        """
+
+@final
+class PostgresHandle:
+    """
+    A native database, connection, or transaction handle.
+
+    Python's public wrappers expose the operations appropriate to each handle.
+    Query cursors retain exclusive use of a connection or transaction until they
+    are exhausted or closed.
+    """
+    def acquire(self, /, source: bytes |None = None) -> "typing.Awaitable[PostgresHandle]":
+        """
+        Acquire a connection from a database's pool.
+
+        Requires a database handle.
+
+        Args:
+            source: Encoded parent tracing context, or None when no context is active.
+
+        Returns:
+            An awaitable that produces a connection handle. Close the handle to return
+            the connection to its pool.
+
+        Raises:
+            EncoreError: Acquiring a connection fails.
+        """
+    def begin(self, /, source: bytes |None = None) -> "typing.Awaitable[PostgresHandle]":
+        """
+        Begin a transaction on a database or acquired connection.
+
+        Requires a database handle or an open connection with no active operation,
+        transaction, or cursor.
+
+        Args:
+            source: Encoded parent tracing context, or None when no context is active.
+
+        Returns:
+            An awaitable that produces a transaction handle. A transaction on an
+            acquired connection retains exclusive use of it until completion.
+
+        Raises:
+            EncoreError: Acquiring a connection or beginning the transaction fails.
+        """
+    def close(self, /) -> "typing.Awaitable[None]":
+        """
+        Close an acquired connection and return it to the pool.
+
+        Requires a connection handle with no active operation, transaction, or cursor.
+
+        Returns:
+            An awaitable that completes when the connection is returned. Repeated
+            closes on a connection handle have no effect.
+        """
+    def commit(self, /) -> "typing.Awaitable[None]":
+        """
+        Commit a transaction and consume its handle.
+
+        Requires an open transaction with no active operation or cursor.
+        Once completion starts, cancelling the await does not interrupt completion.
+        Any borrowed connection stays unavailable until completion finishes.
+
+        Returns:
+            An awaitable that completes when Postgres finishes committing.
+
+        Raises:
+            EncoreError: Committing fails.
+        """
+    def conn_string(self, /) -> "str":
+        """
+        Return the database's proxy connection string.
+
+        Requires a database handle.
+
+        Returns:
+            The URL for connecting to the database through the local proxy.
+        """
+    def exec(self, /, sql: str, params: Sequence[Any], source: bytes |None = None) -> "typing.Awaitable[int]":
+        """
+        Execute a statement and return an awaitable affected-row count.
+
+        Connection and transaction handles must be open and have no active operation
+        or cursor.
+
+        Args:
+            sql: A SQL statement with positional placeholders such as $1 and $2.
+            params: Values bound to the placeholders in order.
+            source: Encoded parent tracing context, or None when no context is active.
+
+        Returns:
+            An awaitable that produces the affected-row count reported by Postgres.
+            Any rows returned by the statement are discarded.
+
+        Raises:
+            EncoreError: Acquiring a connection or executing the statement fails.
+        """
+    def is_closed(self, /) -> "bool":
+        """
+        Return whether this connection or transaction handle was consumed.
+
+        Returns:
+            True if the handle has been closed or transaction completion has started.
+            Returns False for database handles and handles that are currently borrowed.
+        """
+    def query(self, /, sql: str, params: Sequence[Any], source: bytes |None = None) -> "typing.Awaitable[PostgresCursor]":
+        """
+        Start a query and return an awaitable cursor.
+
+        Connection and transaction handles must be open and have no active operation
+        or cursor.
+
+        Args:
+            sql: A SQL statement with positional placeholders such as $1 and $2.
+            params: Values bound to the placeholders in order.
+            source: Encoded parent tracing context, or None when no context is active.
+
+        Returns:
+            An awaitable that produces a PostgresCursor. Exhaust or close the cursor
+            before reusing its connection or transaction.
+
+        Raises:
+            EncoreError: Acquiring a connection or executing the query fails.
+        """
+    def rollback(self, /) -> "typing.Awaitable[None]":
+        """
+        Roll back a transaction and consume its handle.
+
+        Requires an open transaction with no active operation or cursor.
+        Once completion starts, cancelling the await does not interrupt completion.
+        Any borrowed connection stays unavailable until completion finishes.
+
+        Returns:
+            An awaitable that completes when Postgres finishes rolling back.
+
+        Raises:
+            EncoreError: Rolling back fails.
+        """
+
+@final
+class PubSubMessage:
+    @property
+    def attributes(self, /) -> dict[str, str]:
+        """
+        The attributes supplied when publishing the message.
+        """
+    @property
+    def data(self, /) -> bytes:
+        """
+        The raw message payload, without JSON decoding.
+        """
+    @property
+    def delivery_attempt(self, /) -> int:
+        """
+        The delivery attempt, starting at one.
+        """
+    @property
+    def id(self, /) -> str:
+        """
+        The unique message id assigned by the cloud provider.
+        """
+    @property
+    def ordering_key(self, /) -> str |None:
+        """
+        The ordering key from the topic's configured attribute, if present.
+        """
+    @property
+    def publish_time(self, /) -> datetime:
+        """
+        The UTC publication time, or None if the provider did not supply it.
+        """
+
+@final
+class PubSubSubscription:
+    def subscribe(self, /) -> "typing.Awaitable[None]":
+        """
+        Consume messages on the calling asyncio loop until subscription shutdown.
+        Handler completion acknowledges a message; exceptions propagate to the core
+        so the provider can apply its retry policy.
+        """
+
+@final
+class PubSubSubscriptionConfig:
+    def __new__(cls, /, *, topic_name: str, subscription_name: str, handler: "typing.Callable[[PubSubMessage], typing.Awaitable[None]]") -> "PubSubSubscriptionConfig": ...
+
+@final
+class PubSubTopic:
+    def publish(self, /, payload: Sequence[int], attributes: dict[str, str] |None = None, source: bytes |None = None, *, ordering_key: str |None = None) -> "typing.Awaitable[str]":
+        """
+        Publish raw payload bytes with optional attributes and an explicit ordering key.
+        """
+
+@final
+class RedisDatabase:
+    def bitmap_bitcount(self, /, key: str, *, start: int |None = None, end: int |None = None, unit: str |None = None, source: bytes |None = None) -> "typing.Awaitable[int]": ...
+    def bitmap_bitop(self, /, operation: str, destination: str, keys: Sequence[str], *, source: bytes |None = None) -> "typing.Awaitable[int]": ...
+    def bitmap_bitpos(self, /, key: str, bit: bool, *, start: int |None = None, end: int |None = None, unit: str |None = None, source: bytes |None = None) -> "typing.Awaitable[int]": ...
+    def bitmap_getbit(self, /, key: str, offset: int, *, source: bytes |None = None) -> "typing.Awaitable[int]": ...
+    def bitmap_setbit(self, /, key: str, offset: int, value: bool, *, source: bytes |None = None) -> "typing.Awaitable[int]": ...
+    def connection_string(self, /) -> "str":
+        """
+        Direct server URL; external clients do not apply Encore key prefixes.
+        """
+    def generic_copy(self, /, key: str, destination: str, *, replace: bool = False, source: bytes |None = None) -> "typing.Awaitable[bool]": ...
+    def generic_delete(self, /, keys: Sequence[str], *, source: bytes |None = None) -> "typing.Awaitable[int]": ...
+    def generic_exists(self, /, keys: Sequence[str], *, source: bytes |None = None) -> "typing.Awaitable[int]": ...
+    def generic_expire(self, /, key: str, seconds: int, *, condition: str |None = None, source: bytes |None = None) -> "typing.Awaitable[bool]": ...
+    def generic_expireat(self, /, key: str, timestamp: int, *, condition: str |None = None, source: bytes |None = None) -> "typing.Awaitable[bool]": ...
+    def generic_expiretime(self, /, key: str, *, source: bytes |None = None) -> "typing.Awaitable[int]": ...
+    def generic_persist(self, /, key: str, *, source: bytes |None = None) -> "typing.Awaitable[bool]": ...
+    def generic_pexpire(self, /, key: str, milliseconds: int, *, condition: str |None = None, source: bytes |None = None) -> "typing.Awaitable[bool]": ...
+    def generic_pexpireat(self, /, key: str, timestamp: int, *, condition: str |None = None, source: bytes |None = None) -> "typing.Awaitable[bool]": ...
+    def generic_pexpiretime(self, /, key: str, *, source: bytes |None = None) -> "typing.Awaitable[int]": ...
+    def generic_pttl(self, /, key: str, *, source: bytes |None = None) -> "typing.Awaitable[int]": ...
+    def generic_rename(self, /, key: str, destination: str, *, source: bytes |None = None) -> "typing.Awaitable[None]": ...
+    def generic_renamenx(self, /, key: str, destination: str, *, source: bytes |None = None) -> "typing.Awaitable[bool]": ...
+    def generic_scan(self, /, cursor: int, *, pattern: str |None = None, count: int |None = None, key_type: str |None = None, source: bytes |None = None) -> "typing.Awaitable[tuple[int, list[bytes]]]": ...
+    def generic_touch(self, /, keys: Sequence[str], *, source: bytes |None = None) -> "typing.Awaitable[int]": ...
+    def generic_ttl(self, /, key: str, *, source: bytes |None = None) -> "typing.Awaitable[int]": ...
+    def generic_type(self, /, key: str, *, source: bytes |None = None) -> "typing.Awaitable[str]": ...
+    def generic_unlink(self, /, keys: Sequence[str], *, source: bytes |None = None) -> "typing.Awaitable[int]": ...
+    def geo_geoadd(self, /, key: str, items: Sequence[tuple[float, float, bytes]], *, nx: bool = False, xx: bool = False, ch: bool = False, source: bytes |None = None) -> "typing.Awaitable[int]": ...
+    def geo_geodist(self, /, key: str, member1: bytes, member2: bytes, *, unit: str = "m", source: bytes |None = None) -> "typing.Awaitable[typing.Optional[float]]": ...
+    def geo_geohash(self, /, key: str, members: Sequence[bytes], *, source: bytes |None = None) -> "typing.Awaitable[list[typing.Optional[bytes]]]": ...
+    def geo_geopos(self, /, key: str, members: Sequence[bytes], *, source: bytes |None = None) -> "typing.Awaitable[typing.Any]": ...
+    def geo_georadius(self, /, key: str, longitude: float, latitude: float, radius: float, *, unit: str = "m", count: int |None = None, any: bool = False, order: str |None = None, withcoord: bool = False, withdist: bool = False, withhash: bool = False, store: str |None = None, storedist: str |None = None, source: bytes |None = None) -> "typing.Awaitable[typing.Any]": ...
+    def geo_georadiusbymember(self, /, key: str, member: bytes, radius: float, *, unit: str = "m", count: int |None = None, any: bool = False, order: str |None = None, withcoord: bool = False, withdist: bool = False, withhash: bool = False, store: str |None = None, storedist: str |None = None, source: bytes |None = None) -> "typing.Awaitable[typing.Any]": ...
+    def geo_geosearch(self, /, key: str, *, member: bytes |None = None, longitude: float |None = None, latitude: float |None = None, radius: float |None = None, width: float |None = None, height: float |None = None, unit: str = "m", count: int |None = None, any: bool = False, order: str |None = None, withcoord: bool = False, withdist: bool = False, withhash: bool = False, source: bytes |None = None) -> "typing.Awaitable[typing.Any]": ...
+    def geo_geosearchstore(self, /, destination: str, key: str, *, member: bytes |None = None, longitude: float |None = None, latitude: float |None = None, radius: float |None = None, width: float |None = None, height: float |None = None, unit: str = "m", count: int |None = None, any: bool = False, order: str |None = None, storedist: bool = False, source: bytes |None = None) -> "typing.Awaitable[int]": ...
+    def hash_hdel(self, /, key: str, fields: Sequence[str], *, source: bytes |None = None) -> "typing.Awaitable[int]": ...
+    def hash_hexists(self, /, key: str, field: str, *, source: bytes |None = None) -> "typing.Awaitable[bool]": ...
+    def hash_hget(self, /, key: str, field: str, *, source: bytes |None = None) -> "typing.Awaitable[typing.Optional[bytes]]": ...
+    def hash_hgetall(self, /, key: str, *, source: bytes |None = None) -> "typing.Awaitable[dict[bytes, bytes]]": ...
+    def hash_hincrby(self, /, key: str, field: str, amount: int, *, source: bytes |None = None) -> "typing.Awaitable[int]": ...
+    def hash_hincrbyfloat(self, /, key: str, field: str, amount: float, *, source: bytes |None = None) -> "typing.Awaitable[float]": ...
+    def hash_hkeys(self, /, key: str, *, source: bytes |None = None) -> "typing.Awaitable[list[bytes]]": ...
+    def hash_hlen(self, /, key: str, *, source: bytes |None = None) -> "typing.Awaitable[int]": ...
+    def hash_hmget(self, /, key: str, fields: Sequence[str], *, source: bytes |None = None) -> "typing.Awaitable[list[typing.Optional[bytes]]]": ...
+    def hash_hrandfield(self, /, key: str, *, count: int |None = None, withvalues: bool = False, source: bytes |None = None) -> "typing.Awaitable[typing.Any]": ...
+    def hash_hscan(self, /, key: str, cursor: int, *, pattern: str |None = None, count: int |None = None, source: bytes |None = None) -> "typing.Awaitable[tuple[int, dict[bytes, bytes]]]": ...
+    def hash_hset(self, /, key: str, items: Sequence[tuple[str, bytes]], *, source: bytes |None = None) -> "typing.Awaitable[int]": ...
+    def hash_hsetnx(self, /, key: str, field: str, value: bytes, *, source: bytes |None = None) -> "typing.Awaitable[bool]": ...
+    def hash_hvals(self, /, key: str, *, source: bytes |None = None) -> "typing.Awaitable[list[bytes]]": ...
+    def json_arrappend(self, /, key: str, path: str, values: Sequence[str], *, source: bytes |None = None) -> "typing.Awaitable[typing.Any]": ...
+    def json_arrindex(self, /, key: str, path: str, value: str, *, start: int |None = None, stop: int |None = None, source: bytes |None = None) -> "typing.Awaitable[typing.Any]": ...
+    def json_arrinsert(self, /, key: str, path: str, index: int, values: Sequence[str], *, source: bytes |None = None) -> "typing.Awaitable[typing.Any]": ...
+    def json_arrlen(self, /, key: str, *, path: str = "$", source: bytes |None = None) -> "typing.Awaitable[typing.Any]": ...
+    def json_arrpop(self, /, key: str, *, path: str = "$", index: int = ..., source: bytes |None = None) -> "typing.Awaitable[typing.Any]": ...
+    def json_arrtrim(self, /, key: str, path: str, start: int, stop: int, *, source: bytes |None = None) -> "typing.Awaitable[typing.Any]": ...
+    def json_clear(self, /, key: str, *, path: str = "$", source: bytes |None = None) -> "typing.Awaitable[typing.Any]": ...
+    def json_delete(self, /, key: str, *, path: str = "$", source: bytes |None = None) -> "typing.Awaitable[typing.Any]": ...
+    def json_forget(self, /, key: str, *, path: str = "$", source: bytes |None = None) -> "typing.Awaitable[typing.Any]": ...
+    def json_get(self, /, key: str, *, paths: Sequence[str] |None = None, indent: str |None = None, newline: str |None = None, space: str |None = None, source: bytes |None = None) -> "typing.Awaitable[typing.Optional[bytes]]": ...
+    def json_merge(self, /, key: str, path: str, value: str, *, source: bytes |None = None) -> "typing.Awaitable[typing.Any]": ...
+    def json_mget(self, /, keys: Sequence[str], path: str, *, source: bytes |None = None) -> "typing.Awaitable[list[typing.Optional[bytes]]]": ...
+    def json_mset(self, /, items: Sequence[tuple[str, str, str]], *, source: bytes |None = None) -> "typing.Awaitable[None]": ...
+    def json_numincrby(self, /, key: str, path: str, number: float, *, source: bytes |None = None) -> "typing.Awaitable[typing.Any]": ...
+    def json_nummultby(self, /, key: str, path: str, number: float, *, source: bytes |None = None) -> "typing.Awaitable[typing.Any]": ...
+    def json_objkeys(self, /, key: str, *, path: str = "$", source: bytes |None = None) -> "typing.Awaitable[typing.Any]": ...
+    def json_objlen(self, /, key: str, *, path: str = "$", source: bytes |None = None) -> "typing.Awaitable[typing.Any]": ...
+    def json_set(self, /, key: str, path: str, value: str, *, condition: str |None = None, source: bytes |None = None) -> "typing.Awaitable[typing.Any]": ...
+    def json_strappend(self, /, key: str, path: str, value: str, *, source: bytes |None = None) -> "typing.Awaitable[typing.Any]": ...
+    def json_strlen(self, /, key: str, *, path: str = "$", source: bytes |None = None) -> "typing.Awaitable[typing.Any]": ...
+    def json_toggle(self, /, key: str, *, path: str = "$", source: bytes |None = None) -> "typing.Awaitable[typing.Any]": ...
+    def json_type(self, /, key: str, *, path: str = "$", source: bytes |None = None) -> "typing.Awaitable[typing.Any]": ...
+    def list_lindex(self, /, key: str, index: int, *, source: bytes |None = None) -> "typing.Awaitable[typing.Optional[bytes]]": ...
+    def list_linsert(self, /, key: str, position: str, pivot: bytes, value: bytes, *, source: bytes |None = None) -> "typing.Awaitable[int]": ...
+    def list_llen(self, /, key: str, *, source: bytes |None = None) -> "typing.Awaitable[int]": ...
+    def list_lmove(self, /, key: str, destination: str, from_side: str, to_side: str, *, source: bytes |None = None) -> "typing.Awaitable[typing.Optional[bytes]]": ...
+    def list_lpop(self, /, key: str, *, count: int |None = None, source: bytes |None = None) -> "typing.Awaitable[typing.Any]": ...
+    def list_lpos(self, /, key: str, element: bytes, *, rank: int |None = None, count: int |None = None, maxlen: int |None = None, source: bytes |None = None) -> "typing.Awaitable[typing.Any]": ...
+    def list_lpush(self, /, key: str, values: Sequence[bytes], *, source: bytes |None = None) -> "typing.Awaitable[int]": ...
+    def list_lpushx(self, /, key: str, values: Sequence[bytes], *, source: bytes |None = None) -> "typing.Awaitable[int]": ...
+    def list_lrange(self, /, key: str, start: int, stop: int, *, source: bytes |None = None) -> "typing.Awaitable[list[bytes]]": ...
+    def list_lrem(self, /, key: str, count: int, value: bytes, *, source: bytes |None = None) -> "typing.Awaitable[int]": ...
+    def list_lset(self, /, key: str, index: int, value: bytes, *, source: bytes |None = None) -> "typing.Awaitable[None]": ...
+    def list_ltrim(self, /, key: str, start: int, stop: int, *, source: bytes |None = None) -> "typing.Awaitable[None]": ...
+    def list_rpop(self, /, key: str, *, count: int |None = None, source: bytes |None = None) -> "typing.Awaitable[typing.Any]": ...
+    def list_rpush(self, /, key: str, values: Sequence[bytes], *, source: bytes |None = None) -> "typing.Awaitable[int]": ...
+    def list_rpushx(self, /, key: str, values: Sequence[bytes], *, source: bytes |None = None) -> "typing.Awaitable[int]": ...
+    def pubsub_psubscribe(self, /, patterns: Sequence[str], *, source: bytes |None = None) -> "typing.Awaitable[RedisSubscription]": ...
+    def pubsub_publish(self, /, channel: str, message: bytes, *, source: bytes |None = None) -> "typing.Awaitable[int]": ...
+    def pubsub_subscribe(self, /, channels: Sequence[str], *, source: bytes |None = None) -> "typing.Awaitable[RedisSubscription]": ...
+    def read(self, /, *, primary: bool = False) -> "RedisDatabase":
+        """
+        All currently configured core clients connect to the primary. The flag
+        is accepted for API parity; replica routing belongs in the shared core.
+        """
+    def set_sadd(self, /, key: str, members: Sequence[bytes], *, source: bytes |None = None) -> "typing.Awaitable[int]": ...
+    def set_scard(self, /, key: str, *, source: bytes |None = None) -> "typing.Awaitable[int]": ...
+    def set_sdiff(self, /, keys: Sequence[str], *, source: bytes |None = None) -> "typing.Awaitable[list[bytes]]": ...
+    def set_sdiffstore(self, /, destination: str, keys: Sequence[str], *, source: bytes |None = None) -> "typing.Awaitable[int]": ...
+    def set_sinter(self, /, keys: Sequence[str], *, source: bytes |None = None) -> "typing.Awaitable[list[bytes]]": ...
+    def set_sinterstore(self, /, destination: str, keys: Sequence[str], *, source: bytes |None = None) -> "typing.Awaitable[int]": ...
+    def set_sismember(self, /, key: str, member: bytes, *, source: bytes |None = None) -> "typing.Awaitable[bool]": ...
+    def set_smembers(self, /, key: str, *, source: bytes |None = None) -> "typing.Awaitable[list[bytes]]": ...
+    def set_smismember(self, /, key: str, members: Sequence[bytes], *, source: bytes |None = None) -> "typing.Awaitable[list[bool]]": ...
+    def set_smove(self, /, key: str, destination: str, member: bytes, *, source: bytes |None = None) -> "typing.Awaitable[bool]": ...
+    def set_spop(self, /, key: str, *, count: int |None = None, source: bytes |None = None) -> "typing.Awaitable[typing.Any]": ...
+    def set_srandmember(self, /, key: str, *, count: int |None = None, source: bytes |None = None) -> "typing.Awaitable[typing.Any]": ...
+    def set_srem(self, /, key: str, members: Sequence[bytes], *, source: bytes |None = None) -> "typing.Awaitable[int]": ...
+    def set_sscan(self, /, key: str, cursor: int, *, pattern: str |None = None, count: int |None = None, source: bytes |None = None) -> "typing.Awaitable[tuple[int, list[bytes]]]": ...
+    def set_sunion(self, /, keys: Sequence[str], *, source: bytes |None = None) -> "typing.Awaitable[list[bytes]]": ...
+    def set_sunionstore(self, /, destination: str, keys: Sequence[str], *, source: bytes |None = None) -> "typing.Awaitable[int]": ...
+    def sorted_set_zadd(self, /, key: str, items: Sequence[tuple[float, bytes]], *, nx: bool = False, xx: bool = False, gt: bool = False, lt: bool = False, ch: bool = False, source: bytes |None = None) -> "typing.Awaitable[int]": ...
+    def sorted_set_zcard(self, /, key: str, *, source: bytes |None = None) -> "typing.Awaitable[int]": ...
+    def sorted_set_zcount(self, /, key: str, minimum: str, maximum: str, *, source: bytes |None = None) -> "typing.Awaitable[int]": ...
+    def sorted_set_zincrby(self, /, key: str, amount: float, member: bytes, *, source: bytes |None = None) -> "typing.Awaitable[float]": ...
+    def sorted_set_zinterstore(self, /, destination: str, keys: Sequence[str], *, weights: Sequence[float] |None = None, aggregate: str |None = None, source: bytes |None = None) -> "typing.Awaitable[int]": ...
+    def sorted_set_zpopmax(self, /, key: str, *, count: int = 1, source: bytes |None = None) -> "typing.Awaitable[list[tuple[bytes, float]]]": ...
+    def sorted_set_zpopmin(self, /, key: str, *, count: int = 1, source: bytes |None = None) -> "typing.Awaitable[list[tuple[bytes, float]]]": ...
+    def sorted_set_zrandmember(self, /, key: str, *, count: int |None = None, withscores: bool = False, source: bytes |None = None) -> "typing.Awaitable[typing.Any]": ...
+    def sorted_set_zrange(self, /, key: str, start: int, stop: int, *, withscores: bool = False, source: bytes |None = None) -> "typing.Awaitable[typing.Any]": ...
+    def sorted_set_zrangebyscore(self, /, key: str, minimum: str, maximum: str, *, withscores: bool = False, offset: int |None = None, count: int |None = None, source: bytes |None = None) -> "typing.Awaitable[typing.Any]": ...
+    def sorted_set_zrank(self, /, key: str, member: bytes, *, source: bytes |None = None) -> "typing.Awaitable[typing.Optional[int]]": ...
+    def sorted_set_zrem(self, /, key: str, members: Sequence[bytes], *, source: bytes |None = None) -> "typing.Awaitable[int]": ...
+    def sorted_set_zremrangebyrank(self, /, key: str, start: int, stop: int, *, source: bytes |None = None) -> "typing.Awaitable[int]": ...
+    def sorted_set_zremrangebyscore(self, /, key: str, minimum: str, maximum: str, *, source: bytes |None = None) -> "typing.Awaitable[int]": ...
+    def sorted_set_zrevrange(self, /, key: str, start: int, stop: int, *, withscores: bool = False, source: bytes |None = None) -> "typing.Awaitable[typing.Any]": ...
+    def sorted_set_zrevrank(self, /, key: str, member: bytes, *, source: bytes |None = None) -> "typing.Awaitable[typing.Optional[int]]": ...
+    def sorted_set_zscan(self, /, key: str, cursor: int, *, pattern: str |None = None, count: int |None = None, source: bytes |None = None) -> "typing.Awaitable[tuple[int, list[tuple[bytes, float]]]]": ...
+    def sorted_set_zscore(self, /, key: str, member: bytes, *, source: bytes |None = None) -> "typing.Awaitable[typing.Optional[float]]": ...
+    def sorted_set_zunionstore(self, /, destination: str, keys: Sequence[str], *, weights: Sequence[float] |None = None, aggregate: str |None = None, source: bytes |None = None) -> "typing.Awaitable[int]": ...
+    def stream_xack(self, /, key: str, group: str, ids: Sequence[str], *, source: bytes |None = None) -> "typing.Awaitable[int]": ...
+    def stream_xadd(self, /, key: str, items: Sequence[tuple[str, bytes]], *, id: str = "*", nomkstream: bool = False, maxlen: int |None = None, minid: str |None = None, approximate: bool = False, limit: int |None = None, source: bytes |None = None) -> "typing.Awaitable[typing.Optional[bytes]]": ...
+    def stream_xautoclaim(self, /, key: str, group: str, consumer: str, min_idle_ms: int, start: str, *, count: int |None = None, justid: bool = False, source: bytes |None = None) -> "typing.Awaitable[typing.Any]": ...
+    def stream_xclaim(self, /, key: str, group: str, consumer: str, min_idle_ms: int, ids: Sequence[str], *, idle_ms: int |None = None, time_ms: int |None = None, retrycount: int |None = None, force: bool = False, justid: bool = False, source: bytes |None = None) -> "typing.Awaitable[typing.Any]": ...
+    def stream_xdel(self, /, key: str, ids: Sequence[str], *, source: bytes |None = None) -> "typing.Awaitable[int]": ...
+    def stream_xgroup_create(self, /, key: str, group: str, *, id: str = "$", mkstream: bool = False, entries_read: int |None = None, source: bytes |None = None) -> "typing.Awaitable[None]": ...
+    def stream_xgroup_destroy(self, /, key: str, group: str, *, source: bytes |None = None) -> "typing.Awaitable[bool]": ...
+    def stream_xinfo_stream(self, /, key: str, *, full: bool = False, count: int |None = None, source: bytes |None = None) -> "typing.Awaitable[typing.Any]": ...
+    def stream_xlen(self, /, key: str, *, source: bytes |None = None) -> "typing.Awaitable[int]": ...
+    def stream_xpending(self, /, key: str, group: str, *, start: str |None = None, end: str |None = None, count: int |None = None, consumer: str |None = None, idle_ms: int |None = None, source: bytes |None = None) -> "typing.Awaitable[typing.Any]": ...
+    def stream_xrange(self, /, key: str, start: str, end: str, *, count: int |None = None, source: bytes |None = None) -> "typing.Awaitable[typing.Any]": ...
+    def stream_xread(self, /, streams: Sequence[tuple[str, str]], *, count: int |None = None, block_ms: int |None = None, source: bytes |None = None) -> "typing.Awaitable[typing.Any]": ...
+    def stream_xreadgroup(self, /, group: str, consumer: str, streams: Sequence[tuple[str, str]], *, count: int |None = None, block_ms: int |None = None, noack: bool = False, source: bytes |None = None) -> "typing.Awaitable[typing.Any]": ...
+    def stream_xrevrange(self, /, key: str, end: str, start: str, *, count: int |None = None, source: bytes |None = None) -> "typing.Awaitable[typing.Any]": ...
+    def stream_xtrim(self, /, key: str, *, maxlen: int |None = None, minid: str |None = None, approximate: bool = False, limit: int |None = None, source: bytes |None = None) -> "typing.Awaitable[int]": ...
+    def string_append(self, /, key: str, value: bytes, *, source: bytes |None = None) -> "typing.Awaitable[int]": ...
+    def string_decr(self, /, key: str, *, source: bytes |None = None) -> "typing.Awaitable[int]": ...
+    def string_decrby(self, /, key: str, amount: int, *, source: bytes |None = None) -> "typing.Awaitable[int]": ...
+    def string_get(self, /, key: str, *, source: bytes |None = None) -> "typing.Awaitable[typing.Optional[bytes]]": ...
+    def string_getdel(self, /, key: str, *, source: bytes |None = None) -> "typing.Awaitable[typing.Optional[bytes]]": ...
+    def string_getex(self, /, key: str, *, ex: int |None = None, px: int |None = None, exat: int |None = None, pxat: int |None = None, persist: bool = False, source: bytes |None = None) -> "typing.Awaitable[typing.Optional[bytes]]": ...
+    def string_getrange(self, /, key: str, start: int, end: int, *, source: bytes |None = None) -> "typing.Awaitable[bytes]": ...
+    def string_incr(self, /, key: str, *, source: bytes |None = None) -> "typing.Awaitable[int]": ...
+    def string_incrby(self, /, key: str, amount: int, *, source: bytes |None = None) -> "typing.Awaitable[int]": ...
+    def string_incrbyfloat(self, /, key: str, amount: float, *, source: bytes |None = None) -> "typing.Awaitable[float]": ...
+    def string_mget(self, /, keys: Sequence[str], *, source: bytes |None = None) -> "typing.Awaitable[list[typing.Optional[bytes]]]": ...
+    def string_mset(self, /, items: Sequence[tuple[str, bytes]], *, source: bytes |None = None) -> "typing.Awaitable[None]": ...
+    def string_msetnx(self, /, items: Sequence[tuple[str, bytes]], *, source: bytes |None = None) -> "typing.Awaitable[bool]": ...
+    def string_psetex(self, /, key: str, milliseconds: int, value: bytes, *, source: bytes |None = None) -> "typing.Awaitable[None]": ...
+    def string_set(self, /, key: str, value: bytes, *, ex: int |None = None, px: int |None = None, exat: int |None = None, pxat: int |None = None, keepttl: bool = False, nx: bool = False, xx: bool = False, get: bool = False, source: bytes |None = None) -> "typing.Awaitable[typing.Optional[bytes]]": ...
+    def string_setex(self, /, key: str, seconds: int, value: bytes, *, source: bytes |None = None) -> "typing.Awaitable[None]": ...
+    def string_setnx(self, /, key: str, value: bytes, *, source: bytes |None = None) -> "typing.Awaitable[bool]": ...
+    def string_setrange(self, /, key: str, offset: int, value: bytes, *, source: bytes |None = None) -> "typing.Awaitable[int]": ...
+    def string_strlen(self, /, key: str, *, source: bytes |None = None) -> "typing.Awaitable[int]": ...
+    def write(self, /) -> "RedisDatabase": ...
+
+@final
+class RedisSubscription:
+    """
+    A dedicated Pub/Sub connection. close() interrupts a pending receive.
+    """
+    def close(self, /) -> "typing.Awaitable[None]": ...
+    def receive(self, /) -> "typing.Awaitable[typing.Optional[tuple[bytes, bytes]]]": ...
+
+@final
+class Runtime:
+    def __new__(cls, /) -> "Runtime": ...
+    def app_meta_json(self, /) -> "str":
+        """
+        Metadata about the running application, as a JSON document.
+
+        JSON rather than a tree of `#[pyclass]`es: the metadata is a small
+        document read once per process, and the typed, documented user-facing API
+        belongs in the pure-Python `encore.meta` package (which decodes this),
+        alongside the rest of the package's public surface.
+        """
+    def begin_shutdown(self, /, cooperative: bool = False) -> "None":
+        """
+        Start shutdown once and return immediately. The first call chooses the mode.
+        Cooperative shutdown waits for mark_application_drained before resource cleanup.
+        """
+    def bucket(self, /, name: str) -> "Bucket": ...
+    def cleanup(self, /) -> "typing.Awaitable[None]":
+        """
+        Wait until shutdown has reached or passed Cleanup. Call begin_shutdown first.
+        """
+    def completed(self, /) -> "typing.Awaitable[ShutdownResult]":
+        """
+        Wait for cleanup to finish, including after its deadline has elapsed.
+        Call begin_shutdown first. Cancelling this awaitable does not cancel cleanup.
+        """
+    def force_cleanup(self, /) -> "None":
+        """
+        Request resource cleanup without waiting for active work to drain.
+        Call begin_shutdown first, then await cleanup to observe the transition.
+        """
+    def get_metrics_registry(self, /) -> "MetricsRegistry":
+        """
+        Get the shared application metrics registry.
+        """
+    def mark_application_drained(self, /) -> "None":
+        """
+        Notify Encore that application work has drained. Repeated calls are harmless.
+        """
+    def phase(self, /) -> "ShutdownPhase":
+        """
+        Read the current shutdown phase, including before begin_shutdown.
+        """
+    def pubsub_subscription(self, /, config: PubSubSubscriptionConfig) -> "PubSubSubscription":
+        """
+        Resolve a declared subscription; consuming starts when subscribe is called.
+        """
+    def pubsub_topic(self, /, name: str) -> "PubSubTopic":
+        """
+        A handle to the named pub/sub topic, or an error if it isn't configured.
+        """
+    def redis_database(self, /, name: str) -> "RedisDatabase":
+        """
+        Look up a Redis database configured for this service.
+        """
+    def run_forever(self, /) -> "None":
+        """
+        Start draining infrastructure (pub/sub subscriptions, metrics export) on a
+        background thread, keeping the process serving until shutdown. Returns
+        immediately; the caller's own loop keeps the process alive.
+        """
+    def secret(self, /, name: str) -> "typing.Optional[Secret]":
+        """
+        A secret belonging to the service this process hosts, or `None` if it
+        isn't configured. A shared secret of the same name is deliberately not
+        consulted.
+        """
+    def shared_secret(self, /, name: str) -> "typing.Optional[Secret]":
+        """
+        An app-wide secret, readable from any service, or `None` if it isn't
+        configured. A service-scoped secret of the same name is deliberately not
+        consulted.
+        """
+    def sql_database(self, /, name: str) -> "PostgresHandle":
+        """
+        A handle to the named SQL database (looked up in the runtime config).
+        """
+    def started(self, /) -> "typing.Awaitable[None]":
+        """
+        Wait until shutdown has reached or passed Started. Call begin_shutdown first.
+        """
+    def telemetry(self, /) -> "Pipeline":
+        """
+        The telemetry pipeline's span lifecycle calls.
+        """
+    @staticmethod
+    def version() -> "str":
+        """
+        The version of the Encore runtime in use.
+        """
+
+@final
+class Secret:
+    def get(self, /) -> "str":
+        """
+        The secret's value as a UTF-8 string.
+        """
+    def get_bytes(self, /) -> "bytes":
+        """
+        The secret's raw value as bytes.
+        """
+
+@final
+class ShutdownPhase:
+    """
+    Current phase of Encore resource shutdown.
+    """
+    Cleanup: Final[ShutdownPhase]
+    Completed: Final[ShutdownPhase]
+    NotStarted: Final[ShutdownPhase]
+    Started: Final[ShutdownPhase]
+    def __eq__(self, value: object, /) -> bool: ...
+    def __int__(self, /) -> int: ...
+    def __ne__(self, value: object, /) -> bool: ...
+    def __repr__(self, /) -> str: ...
+
+@final
+class ShutdownResult:
+    """
+    Outcome of completed Encore resource cleanup.
+    """
+    Failed: Final[ShutdownResult]
+    Success: Final[ShutdownResult]
+    Timeout: Final[ShutdownResult]
+    def __eq__(self, value: object, /) -> bool: ...
+    def __int__(self, /) -> int: ...
+    def __ne__(self, value: object, /) -> bool: ...
+    def __repr__(self, /) -> str: ...
+
+@final
+class UploadOptions:
+    def __new__(cls, /, *, content_type: str |None = None, preconditions: UploadPreconditions |None = None) -> "UploadOptions": ...
+
+@final
+class UploadPreconditions:
+    def __new__(cls, /, *, not_exists: bool |None = None) -> "UploadPreconditions": ...
+
+@final
+class UploadStream:
+    def close(self, /) -> "typing.Awaitable[None]": ...
+    def finish(self, /) -> "typing.Awaitable[ObjectAttrs]": ...
+    def write(self, /, data: bytes) -> "typing.Awaitable[None]": ...
+
+@final
+class UploadUrlOptions:
+    def __new__(cls, /, *, ttl: int |None = None) -> "UploadUrlOptions": ...
+
+class EncoreError(RuntimeError): ...
+class ObjectsError(EncoreError): ...
+class ObjectNotFound(ObjectsError): ...
+class PreconditionFailed(ObjectsError): ...
+class InvalidArgument(ObjectsError): ...
+
+def encode_log(level: int, time_unix_nanos: int, message: str, *, logger: str |None = None, span_ctx: bytes |None = None, exception_type: str |None = None, exception_message: str |None = None, exception_stacktrace: str |None = None, code_function: str |None = None, code_file: str |None = None, code_line: int = 0, code_column: int = 0, runtime_target: str |None = None, attrs_json: str |None = None) -> "str":
+    """
+    One log record as a line in the Encore log format, without the newline,
+    for the `logging` handler to print: `level` the OpenTelemetry severity
+    number (1–24; 0 none), `time_unix_nanos` 0 for now, `span_ctx` the
+    span's 25-byte context, `exception_*` the exception (the stack trace in
+    Python's format), `code_*` the caller, `runtime_target` the runtime
+    module of a line of the runtime's own (logged under the runtime's logger,
+    in place of `logger`), `attrs_json` a JSON object of the user's
+    attributes. `None`, an empty string, and 0 are none. An attribute named
+    like a reserved key is that field when valid, `raw.<key>` otherwise; one
+    named like a key of the record's own fields is `raw.<key>`. Needs no
+    runtime.
+    """
+
+def flush_runtime_log(timeout: float) -> "int":
+    """
+    Waits, up to `timeout` seconds, for the handler to take the lines queued
+    so far. Returns how many lines it lost: dropped on a full queue, and
+    still queued at the timeout.
+    """
+
+def set_runtime_log_handler(handler: Any |None) -> "None":
+    """
+    Hands the runtime's own log lines to `handler(level, target, message,
+    fields_json, span_ctx)`, or drops them for `None`: `level` 1 ERROR to 5
+    TRACE, `fields_json` a JSON object of key-values (`exception.*`
+    included), `span_ctx` the current span's 25-byte context or `None`.
+    Lines logged before the first call are handed over first. The handler
+    runs on a dedicated thread; its exceptions are unraisable. Up to 1024
+    lines wait for it; more are dropped, counted by `flush_runtime_log`.
+    """