Metadata-Version: 2.4
Name: pyplines
Version: 2026.10.4rc1
Summary: Official PYPLINES Python SDK and typed Action runtime
Requires-Python: >=3.12
Description-Content-Type: text/markdown
Requires-Dist: jsonschema<5,>=4.25
Requires-Dist: pydantic==2.12.5
Requires-Dist: packaging==25.0
Requires-Dist: cryptography<47,>=46
Provides-Extra: client
Requires-Dist: truststore<1,>=0.10; extra == "client"
Requires-Dist: httpx<1,>=0.28; extra == "client"

# Pyplines Python SDK

Python 3.14 typed Action handlers:

```python
from pyplines.actions import Context, Inputs, Outputs

class EchoInputs(Inputs):
    message: str

class EchoOutputs(Outputs):
    message: str

def handler(inputs: EchoInputs, context: Context) -> EchoOutputs:
    context.log("Started")
    return EchoOutputs(message=inputs.message)
```

Declare `handler = "my_action:handler"` under `[project.entry-points."pyplines.action"]` in `pyproject.toml`. Use `pyplines-action init`, `validate`, `run` and `push` to build and publish the image with its captured schema. Actions execute synchronously; timeouts and container lifecycle belong to the runner.

Install `pyplines[client]` for `from pyplines.client import Client`. The operator CLI is a separate distribution, `pyplines-cli`.


## Execution context and logs

`Context` exposes `invocation_id`, `scratch_dir` (temporary `/tmp` space), and `log`:

```python
context.log("Action started")
context.log("Service restarted", level="info", service="payments", elapsed_ms=420)
context.log("Retrying connection", level="warning", attempt=2)
```

- Levels are `debug`, `info`, `warning`, and `error`; explicit logs default to `info`.
- Custom JSON-compatible attributes are nested under `fields`. Dictionary keys MUST
  be strings; numbers MUST be finite. Arbitrary Python objects are not serialized.
- Messages MUST be at most 4,096 characters. Encoded fields MUST fit within 8 KiB;
  the complete JSON record MUST fit within 16 KiB. Invalid or oversized calls raise
  `ValueError` without discarding fields or consuming a sequence number.
- Emission is serialized across threads. Each record is flushed immediately.
- `stream="stderr"` is independent of severity. Captured stdout defaults to `info`;
  captured stderr defaults to `error`. Large captured writes are split into records.
- Logs MUST NOT contain secrets. No automatic secret redaction is provided. The
  runner withholds server log collection for sensitive executions; authors must
  still avoid writing secrets to container stdout/stderr.
- Logs retain sequence, UTC timestamp, stream, message, level, and optional fields.
  The CLI renders concise lines; `--json` preserves the full records.

SDK base classes are `Inputs` and `Outputs`; singular imports are no longer supported.
Rebuild Action images after updating the SDK. Previously published images retain their
embedded SDK and can continue executing with their captured contracts.


## Compatibility and local diagnostics

Stable authoring APIs are `Inputs`, `Outputs`, `Context`, and `ActionError`.
Stable releases within a calendar year retain backwards-compatible authoring APIs;
prereleases do not carry that guarantee. CalVer tags identify releases, while the
execution contract `pyplines.action.v1` determines platform interoperability.
Actions carry their SDK/runtime and do not need to match the server release.

Declare a supported dependency requirement (exact pins are valid), commit `uv.lock`,
and upgrade deliberately with uv. Local tooling resolves the lock, not its own
release version, to choose Action bases.

`pyplines-action run` requests detailed local diagnostics through the supported
`python -m pyplines.actions.development` entry point. `--source PATH` uses source
without installing the Action; omitting it executes the installed Action.
`--build PATH` discovers the installed Action interface. `--diagnostics` accepts
`detailed` or `concise`; `--capabilities` reports versioned interface support.
Production entry points retain concise errors by default. Detailed diagnostics
never capture locals; exception messages and source lines are not automatically
redacted. Rebuild images with this SDK to obtain the new capabilities.

## Output serialization

Output instances are revalidated before serialization, including constructed or
mutated nested models. Field aliases and computed fields are supported. The wire
output uses serialization aliases, and the captured output schema uses Pydantic's
serialization mode, so computed fields and declared serializer return types match
what consumers receive. Serializers run after validation, not as a way to repair
invalid field values.

Rebuild matching SDK base images and Action images to adopt these changes;
previously published images retain their embedded SDK.
