encore-dev 2.0.0a16__tar.gz → 2.0.0b4__tar.gz

encore_dev-2.0.0a16/README.md → encore_dev-2.0.0b4/PKG-INFO

@@ -1,3 +1,23 @@
+Metadata-Version: 2.3
+Name: encore-dev
+Version: 2.0.0b4
+Summary: Encore SDK for Python — infrastructure resources
+Author: Encore
+License: MPL-2.0
+Classifier: Programming Language :: Python :: 3
+Requires-Dist: opentelemetry-api>=1.27
+Requires-Dist: typing-extensions>=4.12
+Requires-Dist: aiohttp>=3.14.4 ; python_full_version >= '3.10' and extra == 'aiohttp'
+Requires-Dist: httpx>=0.27 ; extra == 'httpx'
+Requires-Dist: niquests>=3.19 ; extra == 'niquests'
+Requires-Dist: requests>=2.34 ; python_full_version >= '3.10' and extra == 'requests'
+Requires-Python: >=3.9
+Provides-Extra: aiohttp
+Provides-Extra: httpx
+Provides-Extra: niquests
+Provides-Extra: requests
+Description-Content-Type: text/markdown
+
 # Encore SDK for Python
 
 The Python SDK for [Encore](https://encore.dev) — **infrastructure resources only**.
@@ -58,6 +78,184 @@ 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:
+
+```python
+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.
+
+A generated client takes an `httpx.Client` as its `http_client`, so give it
+`sync_client`. Their other arguments go to the client's constructor, as keywords. 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.
+
+## 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:
+
+```python
+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", record=True)
+```
+
+Read a field while handling a request, and set or clear one for the calls made
+in a block:
+
+```python
+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=True` also carries the field on the Pub/Sub messages published with
+  it set, into the handlers that receive them.
+- `record=True` records the value on the request's spans, as
+  `encore.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.
+
+```python
+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, with no OpenTelemetry setup in the app. 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.
+
+- `workers=N` runs N event loops on threads, sharing the app. It needs
+  free-threaded Python with the GIL disabled (`python3.14t`), where they run in
+  parallel. Each worker runs the app's lifespan with its own `state`, so
+  resources bound to an event loop stay on theirs.
+- `max_concurrency` caps 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=False` takes 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:
+
+```python
+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 records spans of its own once a tracer provider is set, as `run` sets
+Encore's: a second server span for each request, and spans of dependencies,
+endpoints and serialization. `run` turns them off for its requests; pass
+`server_spans=False` to leave the request's span, and those, to FastAPI.
+
+An app served by a server of its own adds Encore's middleware instead, for the
+same Request Context and tracing:
+
+```python
+from encore.server import asgi, wsgi
+
+app.add_middleware(asgi.Middleware)  # FastAPI, Starlette
+app = wsgi.Middleware(app)  # Flask, Django's WSGI application
+```
+
+Both make Encore's tracer provider OpenTelemetry's global one, unless the app
+set its own. 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.
@@ -65,7 +263,8 @@ Declare `postgres.Database("orders", migrations="./migrations")` at module scope
 reference a database declared elsewhere.
 
 `query(sql, *params)` returns a `Cursor`. Use `async for` to stream rows,
-`await query.one()` to fetch one row or `None` (rejecting multiple rows), or
+`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.
@@ -77,7 +276,7 @@ dictionaries keyed by column name. Values are bound with `$1`, `$2`, etc.
 
 ```python
 async def find_order(database: postgres.Queryable, order_id: int):
-    return await database.query("SELECT * FROM orders WHERE id = $1", order_id).one()
+    return await database.query("SELECT * FROM orders WHERE id = $1", order_id).first()
 
 
 async def handle_order(order_id: int):

encore_dev-2.0.0a16/PKG-INFO → encore_dev-2.0.0b4/README.md

@@ -1,16 +1,3 @@
-Metadata-Version: 2.3
-Name: encore-dev
-Version: 2.0.0a16
-Summary: Encore SDK for Python — infrastructure resources
-Author: Encore
-License: MPL-2.0
-Classifier: Programming Language :: Python :: 3
-Requires-Dist: opentelemetry-api>=1.27
-Requires-Dist: opentelemetry-semantic-conventions>=0.62b1
-Requires-Dist: typing-extensions>=4.12
-Requires-Python: >=3.9
-Description-Content-Type: text/markdown
-
 # Encore SDK for Python
 
 The Python SDK for [Encore](https://encore.dev) — **infrastructure resources only**.
@@ -71,6 +58,184 @@ 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:
+
+```python
+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.
+
+A generated client takes an `httpx.Client` as its `http_client`, so give it
+`sync_client`. Their other arguments go to the client's constructor, as keywords. 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.
+
+## 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:
+
+```python
+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", record=True)
+```
+
+Read a field while handling a request, and set or clear one for the calls made
+in a block:
+
+```python
+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=True` also carries the field on the Pub/Sub messages published with
+  it set, into the handlers that receive them.
+- `record=True` records the value on the request's spans, as
+  `encore.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.
+
+```python
+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, with no OpenTelemetry setup in the app. 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.
+
+- `workers=N` runs N event loops on threads, sharing the app. It needs
+  free-threaded Python with the GIL disabled (`python3.14t`), where they run in
+  parallel. Each worker runs the app's lifespan with its own `state`, so
+  resources bound to an event loop stay on theirs.
+- `max_concurrency` caps 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=False` takes 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:
+
+```python
+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 records spans of its own once a tracer provider is set, as `run` sets
+Encore's: a second server span for each request, and spans of dependencies,
+endpoints and serialization. `run` turns them off for its requests; pass
+`server_spans=False` to leave the request's span, and those, to FastAPI.
+
+An app served by a server of its own adds Encore's middleware instead, for the
+same Request Context and tracing:
+
+```python
+from encore.server import asgi, wsgi
+
+app.add_middleware(asgi.Middleware)  # FastAPI, Starlette
+app = wsgi.Middleware(app)  # Flask, Django's WSGI application
+```
+
+Both make Encore's tracer provider OpenTelemetry's global one, unless the app
+set its own. 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.
@@ -78,7 +243,8 @@ Declare `postgres.Database("orders", migrations="./migrations")` at module scope
 reference a database declared elsewhere.
 
 `query(sql, *params)` returns a `Cursor`. Use `async for` to stream rows,
-`await query.one()` to fetch one row or `None` (rejecting multiple rows), or
+`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.
@@ -90,7 +256,7 @@ dictionaries keyed by column name. Values are bound with `$1`, `$2`, etc.
 
 ```python
 async def find_order(database: postgres.Queryable, order_id: int):
-    return await database.query("SELECT * FROM orders WHERE id = $1", order_id).one()
+    return await database.query("SELECT * FROM orders WHERE id = $1", order_id).first()
 
 
 async def handle_order(order_id: int):

{encore_dev-2.0.0a16 → encore_dev-2.0.0b4}/encore/__init__.py

@@ -8,22 +8,44 @@ PyO3) connects them to the provisioned infrastructure at run time.
 Services are declared by the language-agnostic ``encore.service.json`` file, not in
 Python — this SDK is infrastructure-only.
 
-After importing resource declarations, call ``await encore.start()`` once from
-your async main or framework startup hook. This starts all registered subscription
-handlers on the application's loop and returns so the application can serve.
+Run the service with ``encore.run(app)``: it serves the ASGI app where Encore
+assigns the service, starts the Pub/Sub subscriptions, and shuts down gracefully
+with Encore. A service without an HTTP API calls ``encore.run()``.
 
+    import encore
     from encore import pubsub, secrets
     from encore.storage import postgres
+    from fastapi import FastAPI
 
     db = postgres.Database("orders", migrations="./migrations")
     events = pubsub.Topic("order-events")
     api_key = secrets.Secret("ApiKey")
+
+    app = FastAPI()
+
+    if __name__ == "__main__":
+        encore.run(app)
+
+An app served by a server of its own instead calls ``await encore.start()`` once
+from its startup hook, to start the subscriptions.
 """
 
 from __future__ import annotations
 
-from . import config, cron, env, metrics, pubsub, secrets, services, shutdown, storage
-from .internal.runtime import EncoreError, run_forever, version
+from . import (
+    config,
+    cron,
+    env,
+    metrics,
+    pubsub,
+    reqctx,
+    secrets,
+    services,
+    shutdown,
+    storage,
+)
+from ._run import run
+from .internal.runtime import EncoreError, version
 from .internal.startup import start
 from .env import app_meta
 
@@ -34,12 +56,13 @@ __all__ = [
     "cron",
     "env",
     "metrics",
+    "reqctx",
     "secrets",
     "services",
     "shutdown",
     "EncoreError",
     "app_meta",
-    "run_forever",
+    "run",
     "start",
     "version",
 ]