encore-dev 2.0.0a15__tar.gz → 2.0.0a17__tar.gz

{encore_dev-2.0.0a15 → encore_dev-2.0.0a17}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: encore-dev
-Version: 2.0.0a15
+Version: 2.0.0a17
 Summary: Encore SDK for Python — infrastructure resources
 Author: Encore
 License: MPL-2.0
@@ -15,16 +15,29 @@ Description-Content-Type: text/markdown
 
 The Python SDK for [Encore](https://encore.dev) — **infrastructure resources only**.
 
-The distribution is named `encore-dev`; Python code imports it as `encore`.
-
 Declare infrastructure (SQL databases, pub/sub topics & subscriptions, object
 storage buckets, Redis databases, cron jobs, metrics, secrets) as module-level variables.
-Encore's parser discovers them for provisioning and wiring, and the native runtime
-binding (`encore_sdk_core` over PyO3) connects them to the provisioned
-infrastructure at run time.
+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 — this SDK is infrastructure-only (the counterpart of the Go/TS/Rust SDKs).
+Python. Use the SDK with your preferred Python web framework.
+
+## Installation
+
+Requires Python 3.9 or later. Install from PyPI with pip:
+
+```sh
+python -m pip install encore-dev
+```
+
+Or add it to a uv project:
+
+```sh
+uv add encore-dev
+```
+
+## Declare resources
 
 ```python
 from encore import pubsub, secrets
@@ -65,7 +78,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 +91,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):
@@ -91,7 +105,7 @@ select `read()`, `write()`, or `admin()` before handing it to another function.
 Direct database operations infer writer permissions. Reference creation records
 reader, writer, or admin permissions at that call site.
 
-Like the Rust SDK, handles share the database's pool. A `read()` handle runs on
+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.
@@ -122,11 +136,6 @@ async def first_order():
                 return row
 ```
 
-Native Postgres integration tests can be enabled with
-`ENCORE_PYTHON_POSTGRES_TEST_HOST=host:port`. They expect an isolated Postgres
-instance with database/user `postgres` and password `encore-test`, and create and
-remove a temporary schema.
-
 ## Pub/Sub payloads
 
 Use `pubsub.Subscription[T]` to choose how payloads are decoded. Encore validates
@@ -303,94 +312,9 @@ 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.
 
-## Packaging
-
-`encore-dev` contains the Python SDK and is built with uv:
-
-```sh
-uv build sdk/py/infra
-```
-
-For release packaging, stage the SDK and stamp its version without changing the
-checked-in manifest:
-
-```sh
-cargo xtask pack-python --version v2.0.0-alpha.1
-```
-
-This writes `encore_dev-2.0.0a1-py3-none-any.whl`, the source distribution, and
-SHA-256 sidecars to `dist/python/` (override with `--output`). Alpha and beta
-versions become `aN` and `bN`; nightly and development versions become `.devN`.
-The command requires uv and the native build prerequisites (including Protoc).
-It builds the native runtime to generate fresh type stubs, but packages only the
-pure Python SDK and does not publish to PyPI.
-
-The Rust extension lives in the parent `sdk/py/` directory and is packaged separately by Maturin.
-Its `encore-runtime` wheel is an internal artifact for the CLI, not a dependency
-of the public SDK:
-
-```sh
-# With Maturin installed:
-cargo xtask build-py-runtime --release --wheel
-# Optionally select the wheel's target (requires a suitable toolchain):
-cargo xtask build-py-runtime --release --wheel --target aarch64-apple-darwin
-```
-
-SDK distributions are written to `sdk/py/infra/dist/`; native wheels go to
-`sdk/py/dist/`.
-
-## Building locally
-
-From the repository root:
-
-```sh
-cargo xtask build-py-runtime
-```
-
-This stages `_encore_runtime` inside `infra/encore/` for the SDK's local loader,
-and in `runtimes/python/` for the development CLI. It also regenerates
-`encore/internal/_native.pyi` from the compiled extension. Edit native signatures
-in Rust, then rerun this command to update the stub. An editable install of the SDK
-can then load the native extension without setting `PYTHONPATH`:
-
-```sh
-uv run --project sdk/py/infra pytest sdk/py/infra/tests
-```
-
-The CLI sets `ENCORE_PYTHON_RUNTIME_DIR` for runs, tests, and exec commands.
-The SDK selects the native library using the running interpreter's build ABI:
-standard CPython uses the root `abi3` library; free-threaded Python 3.14 uses
-`cp314t/_encore_runtime.so` (`.pyd` on Windows). This selection is unchanged if
-a free-threaded interpreter temporarily enables its GIL. Unsupported ABIs fail
-with a missing-runtime error instead of falling back to an incompatible library.
-
-Build the local free-threaded variant separately:
-
-```sh
-cargo xtask build-py-runtime --python-runtime cp314t
-```
-
-The default builds `abi3`. Both variants can coexist. Native-only wheel builds
-(`--wheel`) continue to use maturin's interpreter selection instead.
-
-`ENCORE_PYTHON_RUNTIME_LIB` overrides directory selection with an explicit library.
-An explicit library or directory is authoritative; failures do not fall back.
-Without either variable, the loader searches beside itself and in parent
-and `dist/` directories using the same ABI layout.
-
-Configure the development CLI's `ENCORE_RUNTIMES_PATH` to point at this checkout's
-`runtimes/` directory. Published SDK wheels exclude native libraries; standalone
-use requires a runtime directory or explicit library from the CLI installation.
-
-App builds install `encore-dev` and copy the runtime directory, preserving its ABI
-variants for selection by the deployment interpreter. An explicit library override
-is packaged separately and remains authoritative. Cross-platform runtime retrieval
-is not yet supported.
-
 ## Resource initialization
 
-Importing the SDK synchronously initializes the native Encore runtime, matching
-TypeScript. Run applications through Encore so runtime configuration is available
+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.
 
@@ -398,39 +322,12 @@ 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. SDK unit tests supply a minimal runtime configuration
-in `tests/conftest.py`; integration tests use `encore test`.
+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.
 
-## Linting and formatting
-
-From the repository root, lint the SDK and its tests:
-
-```sh
-uv run --locked --project sdk/py/infra ruff check sdk/py/infra
-```
-
-Add `--fix` to apply safe fixes. The enabled rules check syntax/style errors,
-undefined and unused names, common bug patterns, and Google-style docstrings
-(`E4`, `E7`, `E9`, `F`, `B`, `D`).
-
-From the repository root, format the SDK and its tests with Ruff:
-
-```sh
-uv run --project sdk/py/infra ruff format sdk/py/infra
-```
-
-To check formatting without changing files:
-
-```sh
-uv run --project sdk/py/infra ruff format --check sdk/py/infra
-```
-
-The generated `_native.pyi` is excluded from linting and formatting because it
-is owned by the PyO3 stub generator. It is still checked by ty.
-
 ## Metrics
 
 Metrics are OpenTelemetry instruments of the meter `encore`, declared at module
@@ -483,63 +380,6 @@ trace.set_tracer_provider(tracer_provider())
 metrics.set_meter_provider(meter_provider())
 ```
 
-## Documentation style
-
-Follow the [Google Python docstring guide](https://google.github.io/styleguide/pyguide.html#docstrings)
-for modules, classes, functions, methods, and Python examples in documentation.
-Start docstrings with a concise summary on the opening triple-double-quote line.
-End the summary with punctuation, keep it within 80 characters, and separate any
-further explanation with a blank line. Use imperative summaries for functions
-("Return the current phase.") and noun phrases for classes and properties.
-
-Use `Args:`, `Returns:`, `Yields:`, `Raises:`, and `Attributes:` as appropriate,
-with four-space indentation for entries and continuation lines. Document behavior
-callers need to know: units, defaults, side effects, resource ownership, and
-relevant exceptions. Parameter names must match the signature, including `*args`
-and `**kwargs`; type annotations usually make repeated type descriptions
-unnecessary. Document public data attributes in the class's `Attributes:` section
-and constructor arguments in `__init__`.
-
-Simple APIs can use a one-line docstring when the summary and signature explain
-their behavior completely. Omit `Returns:` for functions returning only `None`;
-use `Yields:` for generators, describing each yielded item. For a decorated
-context manager, describe the context manager returned to the caller. Put module
-examples under `Typical usage example:`. Keep README prose and examples consistent
-with these API contracts; Markdown guides retain their normal heading structure.
-
-Ruff enforces the Google docstring convention through the existing lint command
-and pre-commit hook. Test docstrings are optional; add them to explain unusual
-setup or behavior rather than repeating test names. Existing test docstrings
-still follow the same formatting rules. Review documentation for accuracy as
-well as formatting: Ruff cannot verify behavioral contracts.
-
-## Type checking
-
-From the repository root, check the SDK, native stubs, and tests with ty:
-
-```sh
-uv run --project sdk/py/infra ty check --project sdk/py/infra
-```
-
-The checker uses the minimum Python version from `requires-python` and resolves
-dependencies from the SDK's virtual environment.
-
-## Pre-commit hooks
-
-From the repository root, install the prek hooks once per checkout:
-
-```sh
-uv run --locked --project sdk/py/infra prek install
-```
-
-The hooks apply safe Ruff lint fixes, format the SDK, and check it with ty when
-relevant SDK files change. If a hook changes files, stage those changes and commit
-again. All hooks use the same locked tools as CI. To run them manually:
-
-```sh
-uv run --locked --project sdk/py/infra prek run --all-files
-```
-
 ## Object storage
 
 Declare a bucket at module scope, then use its async methods:
@@ -747,35 +587,3 @@ 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.
-
-## Testing Postgres
-
-Build the native runtime from the repository root:
-
-```sh
-cargo xtask build-py-runtime
-```
-
-Then run the Postgres tests from `sdk/py/infra`:
-
-```sh
-uv sync --locked
-uv run pytest tests/test_sqldb.py tests/test_postgres_runner.py -v
-```
-
-The integration runner starts one disposable `postgres:17` Docker container and
-removes it after the suite. To use an existing test server, set
-`ENCORE_PYTHON_POSTGRES_TEST_HOST=localhost:5432`. The server must provide a
-`postgres` database and user with password `encore-test` and schema creation
-privileges. Use a dedicated test server.
-
-`tests/test_postgres_runner.py` launches `tests/postgres_integration_suite.py`
-in a separate process to isolate the native runtime configuration. The suite is
-collected explicitly by the runner and excluded from normal pytest discovery
-by its filename.
-Each test and Hypothesis example gets a fresh schema. The suite includes
-parameter round trips, generated transaction and cursor operation sequences,
-and synchronized cancellation regressions. Hypothesis uses deterministic generation and reports minimized failing examples.
-Sequences are repeatable for unchanged tests and the same Hypothesis version.
-Resource cleanup and bounded polling live in `tests/postgres_test_support.py`.
-These integration tests are run locally and are not executed by CI.

{encore_dev-2.0.0a15 → encore_dev-2.0.0a17}/README.md

@@ -2,16 +2,29 @@
 
 The Python SDK for [Encore](https://encore.dev) — **infrastructure resources only**.
 
-The distribution is named `encore-dev`; Python code imports it as `encore`.
-
 Declare infrastructure (SQL databases, pub/sub topics & subscriptions, object
 storage buckets, Redis databases, cron jobs, metrics, secrets) as module-level variables.
-Encore's parser discovers them for provisioning and wiring, and the native runtime
-binding (`encore_sdk_core` over PyO3) connects them to the provisioned
-infrastructure at run time.
+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 — this SDK is infrastructure-only (the counterpart of the Go/TS/Rust SDKs).
+Python. Use the SDK with your preferred Python web framework.
+
+## Installation
+
+Requires Python 3.9 or later. Install from PyPI with pip:
+
+```sh
+python -m pip install encore-dev
+```
+
+Or add it to a uv project:
+
+```sh
+uv add encore-dev
+```
+
+## Declare resources
 
 ```python
 from encore import pubsub, secrets
@@ -52,7 +65,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.
@@ -64,7 +78,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):
@@ -78,7 +92,7 @@ select `read()`, `write()`, or `admin()` before handing it to another function.
 Direct database operations infer writer permissions. Reference creation records
 reader, writer, or admin permissions at that call site.
 
-Like the Rust SDK, handles share the database's pool. A `read()` handle runs on
+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.
@@ -109,11 +123,6 @@ async def first_order():
                 return row
 ```
 
-Native Postgres integration tests can be enabled with
-`ENCORE_PYTHON_POSTGRES_TEST_HOST=host:port`. They expect an isolated Postgres
-instance with database/user `postgres` and password `encore-test`, and create and
-remove a temporary schema.
-
 ## Pub/Sub payloads
 
 Use `pubsub.Subscription[T]` to choose how payloads are decoded. Encore validates
@@ -290,94 +299,9 @@ 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.
 
-## Packaging
-
-`encore-dev` contains the Python SDK and is built with uv:
-
-```sh
-uv build sdk/py/infra
-```
-
-For release packaging, stage the SDK and stamp its version without changing the
-checked-in manifest:
-
-```sh
-cargo xtask pack-python --version v2.0.0-alpha.1
-```
-
-This writes `encore_dev-2.0.0a1-py3-none-any.whl`, the source distribution, and
-SHA-256 sidecars to `dist/python/` (override with `--output`). Alpha and beta
-versions become `aN` and `bN`; nightly and development versions become `.devN`.
-The command requires uv and the native build prerequisites (including Protoc).
-It builds the native runtime to generate fresh type stubs, but packages only the
-pure Python SDK and does not publish to PyPI.
-
-The Rust extension lives in the parent `sdk/py/` directory and is packaged separately by Maturin.
-Its `encore-runtime` wheel is an internal artifact for the CLI, not a dependency
-of the public SDK:
-
-```sh
-# With Maturin installed:
-cargo xtask build-py-runtime --release --wheel
-# Optionally select the wheel's target (requires a suitable toolchain):
-cargo xtask build-py-runtime --release --wheel --target aarch64-apple-darwin
-```
-
-SDK distributions are written to `sdk/py/infra/dist/`; native wheels go to
-`sdk/py/dist/`.
-
-## Building locally
-
-From the repository root:
-
-```sh
-cargo xtask build-py-runtime
-```
-
-This stages `_encore_runtime` inside `infra/encore/` for the SDK's local loader,
-and in `runtimes/python/` for the development CLI. It also regenerates
-`encore/internal/_native.pyi` from the compiled extension. Edit native signatures
-in Rust, then rerun this command to update the stub. An editable install of the SDK
-can then load the native extension without setting `PYTHONPATH`:
-
-```sh
-uv run --project sdk/py/infra pytest sdk/py/infra/tests
-```
-
-The CLI sets `ENCORE_PYTHON_RUNTIME_DIR` for runs, tests, and exec commands.
-The SDK selects the native library using the running interpreter's build ABI:
-standard CPython uses the root `abi3` library; free-threaded Python 3.14 uses
-`cp314t/_encore_runtime.so` (`.pyd` on Windows). This selection is unchanged if
-a free-threaded interpreter temporarily enables its GIL. Unsupported ABIs fail
-with a missing-runtime error instead of falling back to an incompatible library.
-
-Build the local free-threaded variant separately:
-
-```sh
-cargo xtask build-py-runtime --python-runtime cp314t
-```
-
-The default builds `abi3`. Both variants can coexist. Native-only wheel builds
-(`--wheel`) continue to use maturin's interpreter selection instead.
-
-`ENCORE_PYTHON_RUNTIME_LIB` overrides directory selection with an explicit library.
-An explicit library or directory is authoritative; failures do not fall back.
-Without either variable, the loader searches beside itself and in parent
-and `dist/` directories using the same ABI layout.
-
-Configure the development CLI's `ENCORE_RUNTIMES_PATH` to point at this checkout's
-`runtimes/` directory. Published SDK wheels exclude native libraries; standalone
-use requires a runtime directory or explicit library from the CLI installation.
-
-App builds install `encore-dev` and copy the runtime directory, preserving its ABI
-variants for selection by the deployment interpreter. An explicit library override
-is packaged separately and remains authoritative. Cross-platform runtime retrieval
-is not yet supported.
-
 ## Resource initialization
 
-Importing the SDK synchronously initializes the native Encore runtime, matching
-TypeScript. Run applications through Encore so runtime configuration is available
+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.
 
@@ -385,39 +309,12 @@ 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. SDK unit tests supply a minimal runtime configuration
-in `tests/conftest.py`; integration tests use `encore test`.
+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.
 
-## Linting and formatting
-
-From the repository root, lint the SDK and its tests:
-
-```sh
-uv run --locked --project sdk/py/infra ruff check sdk/py/infra
-```
-
-Add `--fix` to apply safe fixes. The enabled rules check syntax/style errors,
-undefined and unused names, common bug patterns, and Google-style docstrings
-(`E4`, `E7`, `E9`, `F`, `B`, `D`).
-
-From the repository root, format the SDK and its tests with Ruff:
-
-```sh
-uv run --project sdk/py/infra ruff format sdk/py/infra
-```
-
-To check formatting without changing files:
-
-```sh
-uv run --project sdk/py/infra ruff format --check sdk/py/infra
-```
-
-The generated `_native.pyi` is excluded from linting and formatting because it
-is owned by the PyO3 stub generator. It is still checked by ty.
-
 ## Metrics
 
 Metrics are OpenTelemetry instruments of the meter `encore`, declared at module
@@ -470,63 +367,6 @@ trace.set_tracer_provider(tracer_provider())
 metrics.set_meter_provider(meter_provider())
 ```
 
-## Documentation style
-
-Follow the [Google Python docstring guide](https://google.github.io/styleguide/pyguide.html#docstrings)
-for modules, classes, functions, methods, and Python examples in documentation.
-Start docstrings with a concise summary on the opening triple-double-quote line.
-End the summary with punctuation, keep it within 80 characters, and separate any
-further explanation with a blank line. Use imperative summaries for functions
-("Return the current phase.") and noun phrases for classes and properties.
-
-Use `Args:`, `Returns:`, `Yields:`, `Raises:`, and `Attributes:` as appropriate,
-with four-space indentation for entries and continuation lines. Document behavior
-callers need to know: units, defaults, side effects, resource ownership, and
-relevant exceptions. Parameter names must match the signature, including `*args`
-and `**kwargs`; type annotations usually make repeated type descriptions
-unnecessary. Document public data attributes in the class's `Attributes:` section
-and constructor arguments in `__init__`.
-
-Simple APIs can use a one-line docstring when the summary and signature explain
-their behavior completely. Omit `Returns:` for functions returning only `None`;
-use `Yields:` for generators, describing each yielded item. For a decorated
-context manager, describe the context manager returned to the caller. Put module
-examples under `Typical usage example:`. Keep README prose and examples consistent
-with these API contracts; Markdown guides retain their normal heading structure.
-
-Ruff enforces the Google docstring convention through the existing lint command
-and pre-commit hook. Test docstrings are optional; add them to explain unusual
-setup or behavior rather than repeating test names. Existing test docstrings
-still follow the same formatting rules. Review documentation for accuracy as
-well as formatting: Ruff cannot verify behavioral contracts.
-
-## Type checking
-
-From the repository root, check the SDK, native stubs, and tests with ty:
-
-```sh
-uv run --project sdk/py/infra ty check --project sdk/py/infra
-```
-
-The checker uses the minimum Python version from `requires-python` and resolves
-dependencies from the SDK's virtual environment.
-
-## Pre-commit hooks
-
-From the repository root, install the prek hooks once per checkout:
-
-```sh
-uv run --locked --project sdk/py/infra prek install
-```
-
-The hooks apply safe Ruff lint fixes, format the SDK, and check it with ty when
-relevant SDK files change. If a hook changes files, stage those changes and commit
-again. All hooks use the same locked tools as CI. To run them manually:
-
-```sh
-uv run --locked --project sdk/py/infra prek run --all-files
-```
-
 ## Object storage
 
 Declare a bucket at module scope, then use its async methods:
@@ -734,35 +574,3 @@ 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.
-
-## Testing Postgres
-
-Build the native runtime from the repository root:
-
-```sh
-cargo xtask build-py-runtime
-```
-
-Then run the Postgres tests from `sdk/py/infra`:
-
-```sh
-uv sync --locked
-uv run pytest tests/test_sqldb.py tests/test_postgres_runner.py -v
-```
-
-The integration runner starts one disposable `postgres:17` Docker container and
-removes it after the suite. To use an existing test server, set
-`ENCORE_PYTHON_POSTGRES_TEST_HOST=localhost:5432`. The server must provide a
-`postgres` database and user with password `encore-test` and schema creation
-privileges. Use a dedicated test server.
-
-`tests/test_postgres_runner.py` launches `tests/postgres_integration_suite.py`
-in a separate process to isolate the native runtime configuration. The suite is
-collected explicitly by the runner and excluded from normal pytest discovery
-by its filename.
-Each test and Hypothesis example gets a fresh schema. The suite includes
-parameter round trips, generated transaction and cursor operation sequences,
-and synchronized cancellation regressions. Hypothesis uses deterministic generation and reports minimized failing examples.
-Sequences are repeatable for unchanged tests and the same Hypothesis version.
-Resource cleanup and bounded polling live in `tests/postgres_test_support.py`.
-These integration tests are run locally and are not executed by CI.

{encore_dev-2.0.0a15 → encore_dev-2.0.0a17}/encore/config/__init__.py

@@ -59,7 +59,7 @@ Changes:
 Files:
     A config's value is written in a file named after it,
     ``checkout.config.toml`` (or ``.json``), beside the declaring service's
-    ``encore.service.json``, or beside ``encore.app`` for a shared or global
+    ``encore.service.json``, or beside ``encore.app.json`` for a shared or global
     config. Overlays change it for some environments only:
     ``checkout.production.config.toml`` for an environment type,
     ``checkout.@prod-eu.config.toml`` for one environment, and

{encore_dev-2.0.0a15 → encore_dev-2.0.0a17}/encore/storage/postgres/__init__.py

@@ -53,7 +53,7 @@ class ExecResult:
 
 
 class Cursor:
-    """A SQL cursor consumed once by iteration, one(), or all().
+    """A SQL cursor consumed once by iteration, one(), first(), or all().
 
     Execution starts when iteration advances or a helper is awaited. Starting
     one consumption mode prevents any other consumption of this query, including
@@ -62,8 +62,8 @@ class Cursor:
 
     Exhaust a stream or call aclose() to release its connection. For early exits,
     use the query as an async context manager. Entering the context does not
-    execute or consume the query. Leaving it closes the stream. The one() and
-    all() helpers close their cursors automatically.
+    execute or consume the query. Leaving it closes the stream. The one(),
+    first(), and all() helpers close their cursors automatically.
     """
 
     def __init__(self, rows: AsyncGenerator[Row, None]) -> None:
@@ -89,23 +89,47 @@ class Cursor:
         """
         return self._consume()
 
-    async def one(self) -> Row | None:
-        """Return zero or one row and close the cursor.
+    async def one(self) -> Row:
+        """Return the query's only row and close the cursor.
+
+        Use first() when the query may match no rows.
 
         Returns:
-            A dictionary of column names to values, or None if no rows match.
+            A dictionary of column names to values.
 
         Raises:
-            EncoreError: The query fails or returns more than one row.
+            EncoreError: The query fails, returns no rows, or returns more than
+                one row.
         """
         rows = self._consume()
         try:
-            first = None
+            found = None
             async for row in rows:
-                if first is not None:
+                if found is not None:
                     raise EncoreError("query returned more than one row")
-                first = row
-            return first
+                found = row
+            if found is None:
+                raise EncoreError("query returned no rows")
+            return found
+        finally:
+            await rows.aclose()
+
+    async def first(self) -> Row | None:
+        """Return the query's first row, if any, and close the cursor.
+
+        Rows after the first are not read.
+
+        Returns:
+            A dictionary of column names to values, or None if no rows match.
+
+        Raises:
+            EncoreError: The query fails.
+        """
+        rows = self._consume()
+        try:
+            async for row in rows:
+                return row
+            return None
         finally:
             await rows.aclose()
 
@@ -231,9 +255,9 @@ class Queryable:
     def query(self, sql: str, *params: Any) -> Cursor:
         """Create a query for streaming or fetching rows.
 
-        Consume the query once with async iteration, one(), or all(). No SQL runs
-        until iteration advances or a helper is awaited. Exhaust the stream or
-        close it before reusing its connection or transaction. Use
+        Consume the query once with async iteration, one(), first(), or all().
+        No SQL runs until iteration advances or a helper is awaited. Exhaust the
+        stream or close it before reusing its connection or transaction. Use
         the query as an async context manager when leaving iteration early.
 
         Args:
@@ -445,9 +469,9 @@ class Database:
     def query(self, sql: str, *params: Any) -> Cursor:
         """Create a query for streaming or fetching rows.
 
-        Consume the query once with async iteration, one(), or all(). No SQL runs
-        until iteration advances or a helper is awaited. See Queryable.query
-        for stream cleanup requirements.
+        Consume the query once with async iteration, one(), first(), or all().
+        No SQL runs until iteration advances or a helper is awaited. See
+        Queryable.query for stream cleanup requirements.
 
         Args:
             sql: A SQL statement with positional placeholders such as $1 and $2.

{encore_dev-2.0.0a15 → encore_dev-2.0.0a17}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "encore-dev"
-version = "2.0.0a15"
+version = "2.0.0a17"
 description = "Encore SDK for Python — infrastructure resources"
 readme = "README.md"
 requires-python = ">=3.9"

{encore_dev-2.0.0a15 → encore_dev-2.0.0a17}/pyproject.toml.orig

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "encore-dev"
-version = "2.0.0a15"
+version = "2.0.0a17"
 description = "Encore SDK for Python — infrastructure resources"
 readme = "README.md"
 requires-python = ">=3.9"