Metadata-Version: 2.5
Name: stackless-sdk
Version: 0.4.0
Summary: CLI-backed Python SDK for stackless lifecycle verbs
Project-URL: Homepage, https://github.com/snowmead/stackless
Project-URL: Repository, https://github.com/snowmead/stackless
Project-URL: Issues, https://github.com/snowmead/stackless/issues
Project-URL: Documentation, https://github.com/snowmead/stackless/tree/main/sdks/python
Author: stackless contributors
License-Expression: MIT OR Apache-2.0
Keywords: cli,ephemeral,infrastructure,stackless,testing
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Testing
Requires-Python: >=3.10
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == 'dev'
Description-Content-Type: text/markdown

# stackless-sdk (Python)

Python SDK for [`stackless`](https://github.com/snowmead/stackless). Published as
[`stackless-sdk`](https://pypi.org/project/stackless-sdk/) on PyPI
(`import stackless`). Speaks the JSON protocol
([`../PROTOCOL.md`](../PROTOCOL.md)) via the `stackless` CLI.

The PyPI distribution is **`stackless-sdk`**; the import package remains
`stackless`.

## Install

```bash
pip install stackless-sdk
```

Editable (from this repo):

```bash
pip install -e "sdks/python[dev]"
```

## Usage

```python
from stackless import Client, Create, Resume

client = Client.system()
out = client.up(Create(on="local", file="stackless.toml", name="demo"))
print(out.origins["web"])
print(out.integrations.get("clerk", {}))
client.down("demo")
```

Binary resolution: `STACKLESS_BIN`, then `stackless` on `PATH`.

## Secrets

`up` returns secret references scoped to the immutable instance ID. Inject
credentials into service or verify environments with `${integrations.<name>.<output>}`.
The controller redacts known secrets from returned logs and errors.

## Tests

```bash
cd sdks/python && python -m pytest
```

Named endpoint bindings are in `out.endpoints`. Each entry has `workload`,
`url`, and `source` (`provider` or `declared`). `out.endpoint_urls` supplies the
map accepted by generated `bind_endpoints`. Declared URLs are unverified.
TCP workloads return `tcp://host:port`; endpoint URLs do not imply HTTP support.

Resolved hosting providers are in `outcome.placements.workloads` and the corresponding
`resources` map. The top-level substrate is the default; individual workloads
and resources can select other providers with `on`.
