This release is a pre-release and may not be stable for production use.
Encore SDK for Python
The Python SDK for Encore — infrastructure resources only.
Declare infrastructure (SQL databases, pub/sub topics & subscriptions, object storage buckets, Redis databases, cron jobs, metrics, secrets) as module-level variables. Encore discovers these declarations, provisions the resources, and connects your application to them at runtime.
Services are declared by the language-agnostic encore.service.json file, not in
Python. Use the SDK with your preferred Python web framework.
Installation
Requires Python 3.9 or later. Install from PyPI with pip:
python -m pip install encore-dev
Or add it to a uv project:
uv add encore-dev
Declare resources
from encore import pubsub, secrets
from encore.storage import postgres
db = postgres.Database("orders", migrations="./migrations")
events = pubsub.Topic("order-events", exactly_once=True)
api_key = secrets.Secret[str]("ApiKey")
async def place_order(order):
await db.exec("INSERT INTO orders (id) VALUES ($1)", order.id)
await events.publish({"id": order.id})
Secrets
secrets.Secret[str]("Name") belongs to the service that declares it.
secrets.Secret[str]("Name", scope="shared") is one secret for the whole app,
given to the services that read it, and scope="global" one that every service
is given. value reads the secret as a string, and raises KeyError when it
has no value. A secret's value is resolved once per process: a new value
reaches a service when it restarts.
A shared secret is declared once in the app. Another Python service can't import the declaring service's modules, so it references the secret by name instead:
from encore.secrets import Secret
support_email = Secret[str].named("SupportEmail")
Reading value makes the service one the secret is given to. The declaration
can be in any language. Encore reports a reference to a name that isn't
declared as a shared secret.
Service URLs
Use base_url to look up a service's configured base URL:
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.
Calling services
To call a service, use the adapter for your HTTP client. Each adapter re-exports
encore.services and adds client(service), a client whose relative URLs are
the service's: the async one where the library has both kinds, with
sync_client(service) for the other:
from encore.services import httpx as services
billing = services.client("billing")
async def invoices():
response = await billing.get("/invoices")
return response.json()
| Adapter | Install | client returns |
sync_client returns |
|---|---|---|---|
encore.services.httpx |
encore-dev[httpx] |
httpx.AsyncClient |
httpx.Client |
encore.services.requests |
encore-dev[requests] |
requests.Session |
|
encore.services.aiohttp |
encore-dev[aiohttp] |
aiohttp.ClientSession |
|
encore.services.niquests |
encore-dev[niquests] |
niquests.AsyncSession |
niquests.Session |
The requests and aiohttp extras need Python 3.10: on 3.9 they install
nothing, as their releases for 3.9 have known vulnerabilities, and the adapters
use the client the app installed.
client and sync_client pass their other arguments to the client's
constructor, as keywords. A requests.Session takes none, so the requests
adapter's client sets them on the session instead, as
client("billing", headers={"x-tenant": "a"}, verify=False), and takes a
timeout for each request that sets none. The same rules as base_url apply
to the service's name. aiohttp joins relative URLs as
links are, so write them without the leading slash there: get("invoices");
and it creates a session only in a running event loop, so call its client in
a coroutine, such as a lifespan handler.
The clients send the Request Context of the calls made with them to the app's
services, and never to anything else, redirects included. A client you build
yourself can do the same with the adapter's hook: Transport and
AsyncTransport for httpx, the requests Adapter, the aiohttp middleware, or the
niquests pre_request hook.
Generated clients
A service that lists another in its encore.service.json clients gets
clients for it in encore_gen/clients/: a package per service, with a module
per entry of the service's api, named after the entry's name (openapi,
graphql or grpc for one that sets none). Each operation is an async
function of its module, with nothing to set up first:
from encore_gen.clients import catalog
product = await catalog.openapi.get_product("xyz")
products = await catalog.storefront.products(skus=["xyz"])
stuff = await catalog.grpc.stuff_service.do_stuff(catalog.grpc.DoStuffMessage())
A call looks the service's URL up when it is first made, and carries the
current trace and Request Context. It has no time limit unless it is given
one: every call takes a timeout, in seconds, for the whole call, and
headers to send:
product = await catalog.openapi.get_product("xyz", timeout=2.0)
stuff = await catalog.grpc.stuff_service.do_stuff(
catalog.grpc.DoStuffMessage(), headers={"x-tenant": "a"}
)
To give many calls the same settings, make the module's
AsyncClient(base_url=None, *, timeout=None, headers=None, http_client=None),
for instance at the top of a module of your service. A call's timeout takes
the place of its client's, and None is no limit, as a long stream may need;
its headers are sent over the client's. The clients share their
connections, so one made for a single call costs nothing:
catalog_api = catalog.openapi.AsyncClient(timeout=10.0)
product = await catalog_api.get_product("xyz")
report = await catalog_api.export_products(timeout=120.0)
async with catalog.storefront.AsyncClient(headers={"x-tenant": "a"}) as client:
products = await client.products(skus=["xyz"])
A spec's own parameter that is named timeout or headers is renamed
timeout2 or headers2.
Closing a client, as async with does, closes neither the shared connections
nor an http_client it was given, which stays yours to close. An
httpx.AsyncClient you give one carries the Request Context when made with
transport=services.AsyncTransport(). An OpenAPI or GraphQL client given a
transport instead, as a retrying or instrumented one, sends through it under
the SDK's, so its calls carry their Request Context, and closes the
connections it opens.
A call that fails raises encore.services.CallError, whatever the kind of API:
its code is the ErrCode the service answered with, or the one its HTTP
status means; UNAVAILABLE when no answer came, and DEADLINE_EXCEEDED when
the call took longer than its timeout. message says what went wrong, and
status is the HTTP status of the service's answer, 0 when there was none. A GraphQL answer with errors raises its subclass
GraphQLRequestError, whose errors are the answer's, and a gRPC status's
details are its details, each its protobuf-py message, or the
protobuf.wkt.Any it came as, for a type the client's protos lack.
from encore.errs import ErrCode
from encore.services import CallError
try:
product = await catalog.openapi.get_product("xyz")
except CallError as error:
if error.code is not ErrCode.NOT_FOUND:
raise
product = None
A gRPC module speaks the gRPC protocol over HTTP/2, with connectrpc, so it
calls any gRPC server: h2c to an http:// URL, TLS to an https:// one,
trusting the system's certificates and those SSL_CERT_FILE and
SSL_CERT_DIR name. A server or bidi stream is an async iterator, and a client
or bidi stream takes an async iterable of requests. Its messages are
protobuf-py's, which protoc-gen-py generates into encore_gen/protos/, a
module per .proto file that every client of the service shares; the gRPC
module has the top-level messages and enums of the service's protos as its
own, and the well-known types its RPCs take and return.
async for update in catalog.grpc.stuff_service.watch_stuff(
catalog.grpc.WatchRequest(), timeout=30.0
):
print(update)
A gRPC call behaves as connectrpc makes it, which CallError only carries
the code of. Its timeout is its deadline, which the service is told, and which
applies to each read from the network: a stream raises DEADLINE_EXCEEDED at
the read after it, so messages that arrived together in one read can still
come past it. Cancelling the task that makes a call fails the call with
CANCELED, which an except CallError catches too unless it raises that code
again, and an exception the requests of a stream raise fails it with
UNAVAILABLE, that exception its __cause__.
OpenAPI and GraphQL modules need httpx (encore-dev[httpx]), and gRPC modules
connectrpc and protobuf-py (encore-dev[grpc], on Python 3.11 and later). A
module is imported when first used, so a service needs only what the modules it
uses need.
Request Context
Request Context fields are typed values that travel with a request to every service it reaches, such as the user it is made for. Declare a field once, at module scope, with its name and the type of its value:
from dataclasses import dataclass
from encore import reqctx
@dataclass
class User:
id: str
admin: bool = False
current_user = reqctx.Field[User]("user")
tenant = reqctx.Field[str]("tenant", trace=True)
Read a field while handling a request, and set or clear one for the calls made in a block:
user = current_user.get() # None when not set
with current_user.set(User(id="system")):
await billing.get("/invoices")
with tenant.unset():
...
Reference a field declared elsewhere, in any language, by name and with its
value's type: current_user = reqctx.Field[User].named("user"). Encore checks
that the types agree.
pubsub=Truealso carries the field on the Pub/Sub messages published with it set, into the handlers that receive them.trace=Trueputs the value on the request's spans, asencore.ctx.<name>. Use it for identifiers worth finding traces by, never for secrets.
A request keeps every field it carries, including ones the service never
declares, and passes them on to the services it calls through the
encore.services clients. Fields are never sent to anything else. A field's
value may encode to at most 4 KiB (1 KiB with pubsub), and a request's fields
to at most 8 KiB in all: setting a value beyond that raises ValueError.
Running the service
encore.run(app) runs the service: it serves an ASGI app (FastAPI, Starlette,
...) with Encore's server, built on hyper, Rust's HTTP library, and handles its
lifecycle.
import encore
from fastapi import FastAPI
app = FastAPI()
if __name__ == "__main__":
encore.run(app)
- Startup: it binds the address Encore assigns the service, runs the app's lifespan startup, starts listening, and starts Encore's Pub/Sub subscriptions. A failed startup exits with 1.
- Requests: HTTP/1.1 and HTTP/2 (h2c). Each request has its Request Context
and a span continuing its trace. The
server records the span itself, from the request's arrival to its response,
named after the route the app matched; the app's code reaches it as
trace.get_current_span(). - Shutdown: on SIGTERM or SIGINT it stops accepting connections and taking Pub/Sub messages, lets the requests in flight finish, runs the app's lifespan shutdown, and lets Encore clean up the resources the app used, all within Encore's shutdown deadline. A request waiting for its client to go away, as a stream of events does, is told it did. A second Ctrl-C stops waiting.
A service without an HTTP API, as one that only handles Pub/Sub messages, calls
encore.run(): the same, without the server.
threads=Nruns N event loops, each on a thread of its own, sharing the app. It needs free-threaded Python with the GIL disabled (python3.14t), where they run in parallel. Each loop runs the app's lifespan with its ownstate, so resources bound to an event loop stay on theirs.max_concurrencycaps the requests the app handles at once.read_timeout(30 seconds) bounds how long a client may take to send a request's headers, a body of up to 64 KiB (answered with 408 when it takes longer), or each part of a longer one (after which its request reads as its client gone).tracing=Falsetakes only the Request Context.- WebSockets are not supported yet.
A WSGI app (Flask, Django's WSGI application) runs through a WSGI-to-ASGI
adapter, such as a2wsgi's, which calls it on a thread pool in the request's
context, so its code reads the Request Context and its calls carry it on:
import encore
from a2wsgi import WSGIMiddleware
from flask import Flask
app = Flask(__name__)
if __name__ == "__main__":
encore.run(WSGIMiddleware(app))
Its spans are not named after its routes: WSGI frameworks don't say which one they matched.
FastAPI can record its own server, dependency, endpoint and serialization
spans when configured with a tracer provider. run turns them off for its
requests, preserving one server span. To leave those spans to FastAPI, pass
server_spans=False and configure its provider explicitly:
from encore.tracing import tracer_provider
app = FastAPI(telemetry={"tracer_provider": tracer_provider()})
encore.run(app, server_spans=False)
encore.run and server middleware leave global OpenTelemetry trace, meter and
logger providers unchanged.
An app served by a server of its own adds Encore's middleware instead, for the same Request Context and tracing:
from encore.server import asgi, wsgi
app.add_middleware(asgi.Middleware) # FastAPI, Starlette
app = wsgi.Middleware(app) # Flask, Django's WSGI application
The middleware works beside OpenTelemetry's own: inside it, as
FastAPIInstrumentor arranges, the request's span is that one's; outside it,
OpenTelemetry's records an internal span under Encore's. The ASGI middleware
names the span after the route FastAPI or Starlette matched; WSGI frameworks
don't say which route they matched.
Postgres queries and handles
Declare postgres.Database("orders", migrations="./migrations") at module scope.
migrations is optional and keyword-only. Use Database.named("orders") to
reference a database declared elsewhere.
query(sql, *params) returns a Cursor. Use async for to stream rows,
await query.one() to fetch exactly one row (raising EncoreError on no rows or
more than one), await query.first() to fetch the first row or None, or
await query.all() to collect all rows in a list. Each query can be consumed
once. Reusing it or mixing helpers with iteration raises EncoreError, including
after partial iteration or an error. Helpers close their cursors automatically.
For an early exit from streaming, use async with db.query(...) as query:.
Entering the context does not execute SQL. Exiting it closes the query.
exec(sql, *params) returns an ExecResult with rows_affected. Rows are
dictionaries keyed by column name. Values are bound with $1, $2, etc.
Column values have the Python types asyncpg and psycopg use. numeric is a
decimal.Decimal with the column's scale, so a numeric(10,2) holding 7 is
Decimal('7.00'); NaN and ±Infinity are Decimal('NaN') and
Decimal('Infinity'). timestamptz is an aware datetime.datetime in UTC,
timestamp a naive one, and date and time are datetime.date and
datetime.time. bytea is bytes, arrays are lists of their elements' types,
JSON is decoded, and uuid, inet and cidr are strings. Parameters accept
the same types; a naive datetime bound to a timestamptz is taken as UTC,
and an aware one may use any tzinfo, zoneinfo.ZoneInfo included.
async def find_order(database: postgres.Queryable, order_id: int):
return await database.query("SELECT * FROM orders WHERE id = $1", order_id).first()
async def handle_order(order_id: int):
return await find_order(db.read(), order_id)
DatabaseRef, Connection, and Transaction implement the nominal Queryable
interface. Database exposes the same query methods but deliberately does not
implement Queryable. Encore rejects passing or aliasing the declaration;
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.
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.
async def rename_order(order_id: int, name: str):
async with db.acquire() as conn:
async with conn.begin() as tx:
result = await tx.exec(
"UPDATE orders SET name = $1 WHERE id = $2", name, order_id
)
return result.rows_affected
Both begin() and acquire() can be awaited or used as async context managers.
Transaction contexts commit on a clean exit and roll back on exceptions;
connection contexts return the connection to its pool. A connection cannot be
used or closed while its transaction is active. Closed handles reject queries.
Streaming queries borrow their connection or transaction until exhausted or closed. If you stop early, close the stream explicitly before reusing its owner:
async def first_order():
async with db.acquire() as conn:
async with conn.query("SELECT * FROM orders ORDER BY id") as rows:
async for row in rows:
return row
Pub/Sub payloads
Use pubsub.Subscription[T] to choose how payloads are decoded. Encore validates
the type argument when subscriptions start. Omitting it selects ordinary JSON
decoding. Handler annotations guide type checking but do not select the decoder.
from pydantic import BaseModel
class Order(BaseModel):
id: str
async def process_order(message: pubsub.Message[Order]) -> None:
print(message.data.id)
processed = pubsub.Subscription[Order](events, "process-order", handler=process_order)
Supported payloads are JSON values, bytes, and top-level Pydantic v2 models
(when Pydantic is installed). pubsub.JSON and pubsub.Payload describe these
public types. Use Subscription[pubsub.JSON] for plain JSON: decoding returns ordinary
Python values without validating or constructing nested types. Use a Pydantic
model when fields need validation or nested models need construction.
Subscription[bytes] returns the payload unchanged. Unparameterized Subscription
decodes ordinary JSON. Dataclasses, model unions, models nested in plain JSON
containers, and string forward references are not supported; wrap nested models
in a top-level Pydantic model and pass that class directly. Original bytes remain
available as message.raw_data. Payloads are decoded once before the handler is
called; decoding errors propagate for normal retry handling.
Gateway Middleware
A service with a gateway section in its encore.service.json hosts the app's
gateway, and its program serves it with Middleware: code that authenticates,
limits, logs or meters the public requests the gateway serves. Encore runs it on
the gateway variant of the native runtime.
import asyncio
from dataclasses import dataclass
import encore
from encore import gateway, reqctx
from encore.errs import ErrCode
from encore.gateway import match
@dataclass
class User:
id: str
current_user = reqctx.Field[User]("user")
class Authenticate(gateway.Middleware):
match = match.path_prefix("/api")
async def on_request(self, req: gateway.Request) -> None:
user = await verify(req.header("authorization"))
if user is None:
raise gateway.reject(ErrCode.UNAUTHENTICATED, "missing token")
req.set(current_user, user)
async def main() -> None:
await encore.start()
await gateway.serve(Authenticate())
asyncio.run(main())
A Middleware is called at the hooks it defines (on_request, on_request_body,
on_response, on_response_body, on_complete), only for the requests its
match matches: Encore checks that before a request reaches Python. A hook may
read any header, query parameter or cookie; each reaches Python only as the hook
reads it. Encore checks a subclass when it is defined, so a misspelt hook raises
at once.
on_request sets the request's Request Context fields with
req.set(field, value): the services the request reaches read them with
field.get(), and no client can set them. Every hook runs in the request's
trace and context, so it reads them with field.get() too, or req.get(field),
and the calls it makes to services carry both.
gateway.serve handles SIGTERM while it serves, so hooks keep running while the
gateway drains, and returns once the shutdown has completed.
Application-owned shutdown
Without a hook, Encore shuts down non-cooperatively as the interpreter exits: after the server has drained, it drains Pub/Sub and flushes telemetry. On import it makes SIGTERM exit the interpreter, unless a handler is already set or the process runs tests: with 0 once the shutdown completed in time, else 1.
Use cooperative shutdown when application tasks may still use Encore resources. The following hook accepts a framework-specific callback that stops new application work and waits for existing work to finish:
from typing import Awaitable, Callable
from encore import shutdown
async def on_shutdown(
stop_and_drain_application: Callable[[], Awaitable[None]],
) -> int:
shutdown.begin(cooperative=True)
await stop_and_drain_application()
shutdown.mark_application_drained()
result = await shutdown.completed()
return result.code()
Connect this hook to the host's shutdown lifecycle. Keep its event loop and the Encore runtime alive until cleanup completes. The host should enforce its own overall shutdown deadline and decide when to terminate the process.
Call begin() before awaiting phase helpers. With cooperative shutdown, signal
application draining before awaiting cleanup() or completed(); otherwise
Encore waits for that signal until its deadline expires.
If application work has already drained, use non-cooperative shutdown:
from encore import shutdown
async def stop_encore() -> int:
shutdown.begin() # cooperative=False
result = await shutdown.completed()
return result.code()
begin() returns immediately. All callers share the same shutdown process, and
the first call chooses the cooperative mode. Repeated calls do not restart
cleanup, change the mode, or reset the deadline. Cancelling an individual waiter
does not cancel background cleanup.
Phases and observation
| Phase | Meaning |
|---|---|
NOT_STARTED |
Shutdown has not started. |
STARTED |
Pub/Sub intake has been signalled to stop. Encore is waiting for message handlers and, in cooperative mode, application draining. |
CLEANUP |
Encore has stopped waiting for draining and is performing resource cleanup. |
COMPLETED |
The cleanup task has finished, including if it failed. Check the result or exception. |
phase() reads the current phase synchronously. await started() and
await cleanup() wait until shutdown has reached or passed their respective
phases. They return immediately if the phase has already passed.
await completed() waits for actual cleanup completion, including after the
deadline. These waits are independent: callers do not need to await every phase
in sequence. Reading phase() is valid before begin(); waiting for a phase
before begin() raises ShutdownError.
CLEANUP closes SQL, Redis, and object-storage resources concurrently, then
exports final metrics and flushes tracing. Retaining a database, cache client,
bucket, or object handle does not keep its connections usable after cleanup.
New operations fail; interrupted object downloads report an error rather than
returning a partial body as success, and Redis subscriptions end.
Drain application work before signalling mark_application_drained(). Forced
cleanup cancels Encore-owned resource I/O even if application tasks are still
running. External clients created from connection URLs are owned by your
application. Cloud SDKs release their HTTP pools when their clients are dropped;
best-effort S3 multipart abort requests may outlive completed() and require a
running executor to finish.
Deadline and forced cleanup
The core deadline defaults to five seconds, configured by
deployment.graceful_shutdown.total in the runtime configuration. It starts
when shutdown is first begun and covers both draining and cleanup.
When the deadline expires:
- Encore records
Timeoutin the shared state. - If draining is still in progress, Encore stops waiting for it and enters
CLEANUP, even without an application-drained signal. - Cleanup continues.
completed()returns only after the cleanup task finishes.
The timeout is sticky: finishing later does not change it to success. It is not
a hard upper bound on how long completed() can wait. The controller does not
exit the process when its deadline expires.
To skip draining before the deadline, request forced cleanup:
from encore import shutdown
async def force_remaining_cleanup() -> int:
# Shutdown must already have been started with begin().
shutdown.force_cleanup()
await shutdown.cleanup() # Observe the transition; cleanup is not done yet.
result = await shutdown.completed()
return result.code()
force_cleanup() returns immediately and is idempotent. It raises
ShutdownError before begin(). Once resource cleanup has started, forcing it
again has no effect. Forcing alone does not record Timeout: successful cleanup
before the deadline still returns SUCCESS.
Both the deadline and explicit forcing abandon the drain wait; they do not kill active handlers. Those handlers may continue using resources while cleanup runs. The host must account for this when choosing when to force cleanup.
Results and errors
| Python outcome | Meaning |
|---|---|
ShutdownResult.SUCCESS |
Cleanup finished before the deadline. Explicit forcing may have skipped draining. code() returns 0. |
ShutdownResult.TIMEOUT |
The deadline expired before cleanup finished. The returned result still means the cleanup task has now finished. code() returns 1. |
ShutdownError |
The core reported cleanup failure or progress could not be observed, including waiting before begin(). |
The SDK maps native Failed to ShutdownError; it does not return the public
FAILED enum member from completed(). Native progress errors are translated
to ShutdownError with the original EncoreError retained as their cause.
An unrecognized native enum value raises ValueError.
If cleanup panics after the deadline has already recorded Timeout, the core
logs the failure and preserves Timeout as the reported result. A timeout is
not evidence that all cleanup operations eventually succeeded.
Resource initialization
Importing the SDK synchronously initializes the Encore runtime. Run applications through Encore so runtime configuration is available before imports. Initialization failures surface during import, before normal application startup completes.
Buckets, SQL databases, pub/sub topics, and secrets store their declarations and
resolve native handles on first use, caching the results with thread-safe
initialization. These lookups are synchronous against the already initialized
runtime. Importing application modules requires the configured runtime and native
extension. Use encore test to run application tests with Encore-managed
resources.
Initialize independently in each worker process. Forking an already initialized native runtime is not supported by this startup model.
Logs
Write structured application logs with a message and fields:
from encore import logs
logs.info("Order placed", order_id=42, items=3)
logs.debug, info, warning, error, and critical take a positional
message and structured keyword fields. logs.exception logs the active
exception at error level. Helper fields cannot replace metadata or trace
correlation: message, level, time, logger, trace_id, span_id,
sampled, service.name, exception.type, exception.message,
exception.stacktrace, code.function.name, code.file.path,
code.line.number, code.column.number, and encore.runtime.target are
reserved, as are LogRecord attributes, methods, and factory-added attributes. Collisions gain raw. prefixes until the key
conflicts with neither record attributes nor other supplied fields. For
example, logs.info("charged", level="fatal") keeps level info and writes
raw.level="fatal"; if raw.level is also supplied, the level field
becomes raw.raw.level. Keyword arguments are fields, not Python logging
options. Direct StructuredLogHandler usage retains its reserved-key behavior:
valid reserved-key attributes can override the corresponding output fields.
The helpers use the standard encore.logs logger. With no application
handler, they write Encore-formatted lines to stderr without changing the
root logger. The fallback uses INFO when root remains WARNING with no handlers;
setting root WARNING alone is indistinguishable from the default. To suppress
INFO, set encore.logs to WARNING or install an application handler with the
desired level. Other explicit levels, filters and disabling are respected.
Application handlers replace the fallback, without duplicate output.
To enable debug output:
import logging
logging.getLogger("encore.logs").setLevel(logging.DEBUG)
Python logging
Use StructuredLogHandler for structured JSON output from standard Python loggers:
import logging
from encore.logs import StructuredLogHandler
logging.basicConfig(level=logging.INFO, handlers=[StructuredLogHandler()])
OpenTelemetry
Encore collects process output and exports it through an out-of-process
collector as OpenTelemetry logs over OTLP. Encore-formatted logs preserve
structured fields, severity and current trace/span IDs, including those from
OpenTelemetry instrumentation. Other output is collected as unstructured text.
Use the helpers or Python logging with StructuredLogHandler for structured logs;
global OpenTelemetry logger providers are unchanged.
Traces
Create spans around application work:
from encore import tracing
with tracing.span("place_order", attributes={"order.id": order_id}) as span:
span.set_attribute("order.items", 3)
with tracing.span("validate_order"):
...
A span becomes current inside its block. Nested spans inherit its trace; spans
end on block exit, and uncaught exceptions are recorded as failures and
propagate. Use regular with blocks in async code too.
OpenTelemetry
Encore spans share OpenTelemetry context. Obtain a tracer directly from Encore's provider for standard trace API calls:
from encore.tracing import tracer_provider
tracer = tracer_provider().get_tracer(__name__)
with tracer.start_as_current_span("place_order") as span:
span.set_attribute("order.id", order_id)
Optional opentelemetry-instrumentation-* packages instrument frameworks and
libraries. Pass the provider directly, for example
FastAPIInstrumentor().instrument_app(app, tracer_provider=tracer_provider()),
or opt in once if your app owns global OpenTelemetry setup:
from opentelemetry import trace
trace.set_tracer_provider(tracer_provider())
Encore always uses its cached, owned provider for SDK-created spans,
independent of the global provider. tracing.span, encore.run and server
middleware leave global trace, meter and logger providers unchanged.
Metrics
Declare metrics at module scope: Counter for increasing totals,
UpDownCounter for totals that can decrease, Gauge for current values, and
Histogram for distributions. Each has a …Group form whose labels are a
TypedDict or a dataclass:
from dataclasses import dataclass
from encore import metrics
@dataclass(frozen=True)
class Labels:
route: str
latency = metrics.HistogramGroup[Labels]("request_duration", unit="s")
latency.with_labels(Labels("/orders")).record(0.025)
A service's own metric, the default scope, is exported as <service>.<name>:
request_duration of the service shop is shop.request_duration. Shared
(scope="shared") and global (scope="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().
Metric names and scopes must be string literals. Names start with a letter,
followed by letters, digits, _, ., - or /. 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.
OpenTelemetry
Encore metric declarations use the encore meter. Obtain a meter from Encore's
provider for standard metrics API calls:
from encore.metrics import meter_provider
meter = meter_provider().get_meter("orders")
orders = meter.create_counter("orders_placed", unit="{order}")
orders.add(1, attributes={"outcome": "success"})
These instruments are exported alongside Encore metrics, with their names
unchanged. The meter's instrumentation scope (orders here) is distinct from
an Encore declaration's service/shared/global scope. The process resource
identifies the service recording them. Use the standard API for observable
instruments or attributes beyond Encore's label types.
Encore declarations always use the cached, owned meter provider, independent
of the global provider. Pass meter_provider() directly to instrumentation,
or opt in once if your app owns global OpenTelemetry setup:
from opentelemetry import metrics
metrics.set_meter_provider(meter_provider())
Encore leaves global trace, meter and logger providers unchanged, including in
encore.run and server middleware.
Object storage
Declare a bucket at module scope, then use its async methods:
from encore.storage import objects
uploads = objects.Bucket("uploads")
async def example() -> None:
await uploads.upload(
"hello.txt",
b"Hello!",
content_type="text/plain",
if_not_exists=True,
)
attrs = await uploads.attrs("hello.txt")
present = await uploads.exists("hello.txt")
part = await uploads.download("hello.txt", offset=0, length=5)
async for entry in uploads.list(prefix="hello", limit=10):
print(entry.name, entry.size)
download_url = await uploads.signed_download_url("hello.txt", ttl=3600)
await uploads.remove("hello.txt")
attrs, exists, download, and remove accept a keyword-only version.
signed_upload_url and signed_download_url return URL strings (str);
TTL is in seconds, defaults to one hour, and must be between 1 and 604800.
public_url is synchronous and requires a public bucket. Bucket.named(name)
looks up an existing bucket configured for the service.
Storage failures raise ObjectsError (an EncoreError subclass), with
ObjectNotFound, PreconditionFailed, and InvalidArgument for specific cases.
exists returns False for missing objects and raises on other storage failures.
If leaving a listing early, use contextlib.aclosing(bucket.list(...)) to close
the native stream promptly.
For large objects, upload_stream(name, chunks) consumes an asynchronous iterable
of bytes with backpressure. It supports the same content_type and
if_not_exists options as upload. The native pipe is limited to 64 KiB, and
each write across the native boundary is at most 64 KiB. S3 multipart uploads retain at most four 8 MiB part payloads
and apply backpressure while waiting for the provider; completed parts retain
only their metadata. Other providers may use their own upload buffers.
The input iterable owns its chunks, so avoid producing the entire object at once.
Producer exceptions and cancellation abort the upload. The caller owns closing
an input generator that needs cleanup; cancellation cannot undo an upload the
provider has already committed.
download_stream yields provider-sized byte chunks and supports version,
offset, and length. It reads on demand. Use aclosing when a loop might stop
early, including when piping a download into another upload:
from contextlib import aclosing
async def copy_large_object() -> None:
async with aclosing(uploads.download_stream("source.bin")) as chunks:
await uploads.upload_stream(
"copy.bin", chunks, content_type="application/octet-stream"
)
Redis databases
Declare a database at module scope and call commands through its families:
from encore.storage.redis import Database, ReadOnlyDatabaseRef
sessions = Database("sessions")
async def save_user():
await sessions.string.set("user:1", b"hello", ex=60)
return await sessions.string.get("user:1") # bytes | None
async def load(reader: ReadOnlyDatabaseRef):
return await reader.string.get("user:1")
async def handle_request():
return await load(sessions.read())
A database is a cache unless declared Database(name, persistent=True): a
cache may lose what it holds, and evicts the least recently used keys when it
runs out of memory. Database.named(name) references a database declared
elsewhere. Creating a database,
selecting a family, and creating a handle defer native lookup until first use.
Direct resource calls must keep the family and command together, as in
sessions.string.get(...), so Encore can determine their permissions. To pass
access to another function or keep a family interface in a variable, obtain a
read() or write() handle first.
Families are the properties generic, string, bitmap, geo, hash, json,
list, set, sorted_set, stream, hyperloglog, and pubsub. Read handles expose
only read operations, and the native runtime also rejects writes through them.
read(primary=True) requests primary access; the current runtime uses the primary
for all reads, including when this flag is false.
A pipeline sends commands in one round trip, and a transaction (MULTI/EXEC)
runs them together. Commands are queued through the same families, each
returning a Queued whose value is the decoded result once the batch has
run; execute() raises BatchError if any failed, each Queued its own
error:
pipe = sessions.pipeline()
name = pipe.string.get[str]("name:1")
hits = pipe.string.incr("hits")
await pipe.execute()
print(name.value, hits.value)
watch(keys, body) runs body(conn, tx) as an optimistic transaction,
retrying while a watched key changes; acquire() takes a connection out of the
pool (async with sessions.acquire() as conn:). A Script runs by its hash,
falling back to its source; only its KEYS get the database's prefix, so it
must take every key it touches through key():
RELEASE = Script(
'if redis.call("get", KEYS[1]) == ARGV[1] then '
'return redis.call("del", KEYS[1]) end return 0'
)
released = await sessions.script(RELEASE).key("lock:job").arg(token).invoke()
The blocking pops (list.blpop, brpop, blmove, blmpop,
sorted_set.bzpopmin, bzpopmax, bzmpop) take a keyword-only timeout in
seconds, 0 waiting for ever, and return None once it passes. They wait on a
connection of their own, so they hold up no other command; cancelling the task
ends the wait. They can't be queued, nor run on an acquired connection.
bitmap.bitfield(key) builds a BITFIELD (.get(), .set(), .incrby(),
.overflow(), then await .invoke()), and generic.scan_iter(),
hash.hscan_iter, set.sscan_iter and sorted_set.zscan_iter follow a scan's
cursor to the end.
command(name) sends a command the families lack, by its name, which must be
a string literal: await sessions.command("OBJECT").arg("FREQ").key("hot").invoke().
Before it is sent the runtime checks it against Redis's command table, and
raises CommandRefused if a key it takes isn't passed with key(), or if it
would reach past the database, change a connection other calls share, or has a
call of its own here (MULTI, SUBSCRIBE, EVAL, SCAN, FLUSHALL, ...). A command
the server rejects raises ServerError, whose code is the first word of the
server's message (WRONGTYPE).
Keys and hash/stream field names are str inputs. Stored values, members, and
message payloads accept Value: bytes, str, int, float, or an implementation of
RedisValue. Strings are encoded as UTF-8, integers as decimal text, floats as
ASCII text using repr(), and bytes are sent unchanged. Booleans are not
supported as stored values. Floats include nan and infinities, which can be
stored and retrieved but may be rejected by Redis numeric commands.
Reads return bytes by default. Select a type with command[str](...),
command[int](...), command[float](...), or a custom value class to decode
stored values. The return type follows the requested type:
await sessions.string.set("visits", 42)
visits = await sessions.string.get[int]("visits") # int | None
await sessions.string.set("balance", 1.25)
balance = await sessions.string.get[float]("balance") # float | None
await sessions.list.rpush("names", "Ada", "Grace")
names = await sessions.list.lrange[str]("names", 0, -1) # list[str]
RedisValue is a structural protocol: no base class or registration is required.
Implement encode(self) -> bytes and a class method decode(cls, data: bytes)
that returns an instance of the class:
import json
from dataclasses import dataclass
@dataclass
class User:
name: str
def encode(self) -> bytes:
return json.dumps({"name": self.name}).encode("utf-8")
@classmethod
def decode(cls, data: bytes) -> "User":
return cls(**json.loads(data))
await sessions.string.set("user:1", User("Ada"))
user = await sessions.string.get[User]("user:1") # User | None
await sessions.hash.hset("profiles", ("first", User("Ada")))
users = await sessions.hash.hgetall[User]("profiles") # dict[bytes, User]
The same conversion applies to list elements, hash values, set/sorted-set/geo
members, stream field values, and pubsub payloads. For pubsub, use subscribe[User](...)
or psubscribe[User](...); Message.payload then has that type.
Database keys, hash/stream field names, stream IDs, channel names, cursors,
scores, and other metadata retain their existing types. Where hash field names
are what a command returns (hkeys, and hrandfield without values), they
are its values: hkeys[str] reads them as str. A custom value class
is not recorded in Redis: callers must choose the matching decoder.
Missing values remain None, and empty collections remain empty. Malformed
UTF-8, invalid integers, and custom codec errors raise instead of becoming
None. Reads that also mutate data (for example getdel, lpop, or set with
get=True) execute before decoding: a decoding error does not undo the command.
set[User](..., get=True) decodes the previous value; without get=True,
set only accepts the default bytes response mode.
Multi-value operations accept variadic arguments, with tuples for grouped values,
for example
db.hash.hset("user", ("name", b"Ada")) and
db.string.mget("first", "second"). Unpack existing collections with *items.
Most commands require at least one item; geo.geohash, geo.geopos, and
json.get allow none. json.mget requires a keyword-only path, and
sorted_set.zinterstore/zunionstore keep weights as a keyword sequence.
Commands with structured, option-dependent
replies (including streams and geo searches) retain the native RESP structure:
lists/dictionaries containing bytes, numbers, and None. With withscores=True,
sorted-set ranges return (member: bytes, score: float) pairs.
string.set() returns None normally; with get=True it returns the previous
value. With nx=True or xx=True and no get, it returns b"OK" if the write
happened and None otherwise.
RedisJSON methods accept Python JSON values and decode document replies:
await sessions.json.set("profile", "$", {"name": "Ada", "active": True})
profiles = await sessions.json.get("profile", "$")
JSONPath replies preserve arrays of matches. JSON requires a server with RedisJSON support; the local emulator does not currently implement it.
Redis channel subscriptions are separate from Encore's pubsub.Topic API. Use
an async context manager to release the dedicated connection on exit:
async def listen():
async with await sessions.pubsub.subscribe("events") as messages:
async for message in messages:
print(message.channel, message.payload) # both bytes
psubscribe() accepts glob patterns. Subscription.receive() returns a Message
or None after closure; close() interrupts pending receives and is safe to
repeat. Leaving the context also closes the subscription when the body raises or
is cancelled.
db.connection_string (also available on write handles) returns the direct server
URL and grants broad read-write access. External clients using that URL do not
apply Encore's key prefixes or tracing. Read-only handles do not expose this URL.
Metadata
Release files for encore-dev 2.0.0b10
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| encore_dev-2.0.0b10.tar.gz | 246.8 kB | Without provenance | Details for encore_dev-2.0.0b10.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| encore_dev-2.0.0b10-py3-none-any.whl | Python 3 | none | any | Details for encore_dev-2.0.0b10-py3-none-any.whl |
Total release size: 530.8 kB
Release files / encore_dev-2.0.0b10.tar.gz
| Download URL | encore_dev-2.0.0b10.tar.gz |
|---|---|
| Size | 246.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
54ce009ed7bd41f75a5155ceed4ffacce25b4a601fd0b988995ef250cade47b7
|
|
BLAKE2b-256 checksum How to use checksums |
c421f01b0939485a6e33822ecde759482cbeedff9376930f58dd6fd98e0c0d65
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.12.10 {"installer":{"name":"uv","version":"0.12.10","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / encore_dev-2.0.0b10-py3-none-any.whl
| Download URL | encore_dev-2.0.0b10-py3-none-any.whl |
|---|---|
| Size | 284.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
62533311b1fc2547b379efd1f78ae231addc54fff01707d97cc88a08e0bab1a3
|
|
BLAKE2b-256 checksum How to use checksums |
68cf9e719787460fe8f2e256bb9d70b15c8ba2546015c2b1c18d9858517a7968
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.12.10 {"installer":{"name":"uv","version":"0.12.10","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Security for encore-dev 2.0.0b10
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.