Sokel Plugin SDK — Python

简体中文

Write Sokel plugins in Python. The contract lives in a language-neutral sokel.yaml; sokel-gen turns it into pydantic models and typed registration functions, and the SDK handles registration, transport, credentials, files, heartbeats and reconnects.

async def issues_list(ctx: Ctx, in_: IssuesListIn) -> IssuesListOut:
    issues = await client.list_issues(in_.project, in_.state)
    return IssuesListOut(issues=issues, count=len(issues))

on_issues_list(p, issues_list)

A typo in in_.project is a red squiggle in your editor, not a failed call in production — there is no dict["key"] anywhere in your code.

Install

pip install sokel-plugin-sdk
go install github.com/sokel-dev/sokel-plugin-sdk/cmd/sokel-gen@latest   # the generator

sokel-gen is a single binary (written in Go) used only at generation time; running a plugin does not need it.

Four steps

sokel-gen init -lang python ./my-plugin
cd my-plugin
pip install -r requirements.txt
sokel-gen generate .     # sokel.yaml → sokel_gen.py
python main.py

Declare — sokel.yaml: operations, events, credentials, authentication. Format: docs/manifest.md, or run sokel-gen docs.
Generate — sokel-gen generate . writes sokel_gen.py: an XxxIn / XxxOut model pair and an on_xxx(p, fn) per operation; a payload model and a trigger_xxx(ctx, event_id, payload) per event.
Implement — handler signatures are fully concrete. async def or a plain function, both work.
Connect — asyncio.run(p.run()). A plugin dials out: no inbound port, no public IP, no firewall hole.

What you can do

Task	How
Read credentials	`credential(ctx)` → the generated `Credential` model
Read an input file's bytes	`await ctx.fetch(in_.file)`
Produce a file	`await ctx.upload(name, mime, data)`, or `await ctx.upload_file(path)` for large files
Stream output	`out.text(...)` frame by frame for humans, `out.vars(Out(...))` for downstream nodes
Push an event	`await trigger_message(ctx, event_id, MessageEvent(...))`
Long-running event source	`p.register_source(id, label, fn)`; loop while `not ctx.stopping.is_set()`
Handle a platform-relayed webhook	`p.register_webhook(fn)`, return `ok()` / `text(401, "...")`
Collaborative authentication	`p.register_auth(start=…, poll=…, submit=…)`
Refresh a session credential	`await ctx.update_credential({"session": "…"})`
Report runtime state	`ctx.report_status("auth_required", "…")`

upload_file(path) streams from disk: memory stays at one chunk (1 MiB) regardless of file size. Anything above a few hundred megabytes should use it — upload(bytes) reads the whole file into memory first, and the symptom of that is a container mysteriously killed by the OOM reaper.

Configuration

The SDK reads SOKEL_-prefixed environment variables:

Variable	Required	Meaning
`SOKEL_ENDPOINT`	yes	`nats://broker:4222`, or an `https://` platform URL to discover the broker from
`SOKEL_TOKEN`	yes	Access-group token (`skp_…`) identifying plugin + workspace
`SOKEL_NATS_TOKEN`	no	Broker-level auth
`SOKEL_NATS_CA`	no	Custom CA bundle for `tls://` brokers
`SOKEL_INSTANCE_ID`	no	Pin a replica identity (otherwise derived from the token and cached on disk)
`SOKEL_REGION`	no	Region label for the replica

Credentials are never stored by the plugin: the platform injects the resolved fields with each call.

Example

examples/kitchen-sink covers every shape — each field type, files, streaming, events, webhooks, collaborative auth — and the Python and Node implementations share one declaration.

cd examples/kitchen-sink/python
pip install -r requirements.txt
SOKEL_ENDPOINT=nats://localhost:4222 SOKEL_TOKEN=skp_xxx python main.py

Developing this SDK

uv venv && uv pip install -e '.[dev]'
python -m pytest -q

License

Apache-2.0.

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

sokel_plugin_sdk-0.4.0.tar.gz (32.6 kB view details)

Uploaded Aug 26, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

sokel_plugin_sdk-0.4.0-py3-none-any.whl (29.5 kB view details)

Uploaded Aug 26, 2026 Python 3

File details

Details for the file sokel_plugin_sdk-0.4.0.tar.gz.

File metadata

Download URL: sokel_plugin_sdk-0.4.0.tar.gz
Upload date: Aug 26, 2026
Size: 32.6 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for sokel_plugin_sdk-0.4.0.tar.gz
Algorithm	Hash digest
SHA256	`7d5159aec24c289ca2f1a408d531a50fe2ef5e4ce1eb94692f8700713ec3e9cc`
MD5	`da172c216c8e4d77d3bc74f0e16a1fe6`
BLAKE2b-256	`fd53133e70a9d6f98012f31c4febb8aed0602348d284d114d93ea944db75b67d`

See more details on using hashes here.

Provenance

The following attestation bundles were made for sokel_plugin_sdk-0.4.0.tar.gz:

Publisher: release.yml on sokel-dev/sokel-plugin-sdk

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: sokel_plugin_sdk-0.4.0.tar.gz
- Subject digest: 7d5159aec24c289ca2f1a408d531a50fe2ef5e4ce1eb94692f8700713ec3e9cc
- Sigstore transparency entry: 2604457649
- Sigstore integration time: Aug 26, 2026
Source repository:
- Permalink: sokel-dev/sokel-plugin-sdk@da3ff1a61affcda5c51e4d92522eb03d40d7cbf4
- Branch / Tag: refs/tags/v0.4.0
- Owner: https://github.com/sokel-dev
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: release.yml@da3ff1a61affcda5c51e4d92522eb03d40d7cbf4
- Trigger Event: push

File details

Details for the file sokel_plugin_sdk-0.4.0-py3-none-any.whl.

File metadata

Download URL: sokel_plugin_sdk-0.4.0-py3-none-any.whl
Upload date: Aug 26, 2026
Size: 29.5 kB
Tags: Python 3
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for sokel_plugin_sdk-0.4.0-py3-none-any.whl
Algorithm	Hash digest
SHA256	`04073288020fb67908660148665ed9d2d3f0a2f2fac16088da4d919e686d22cb`
MD5	`57eebc8d57bfbdb797c4a73bd86267e2`
BLAKE2b-256	`b8cdaea50201a80659f69b06dfbbe165753ad8c0399455d8049ebeb2551e2db8`

See more details on using hashes here.

Provenance

The following attestation bundles were made for sokel_plugin_sdk-0.4.0-py3-none-any.whl:

Publisher: release.yml on sokel-dev/sokel-plugin-sdk

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: sokel_plugin_sdk-0.4.0-py3-none-any.whl
- Subject digest: 04073288020fb67908660148665ed9d2d3f0a2f2fac16088da4d919e686d22cb
- Sigstore transparency entry: 2604457677
- Sigstore integration time: Aug 26, 2026
Source repository:
- Permalink: sokel-dev/sokel-plugin-sdk@da3ff1a61affcda5c51e4d92522eb03d40d7cbf4
- Branch / Tag: refs/tags/v0.4.0
- Owner: https://github.com/sokel-dev
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: release.yml@da3ff1a61affcda5c51e4d92522eb03d40d7cbf4
- Trigger Event: push

Release history Release notifications | RSS feed

This release

0.4.0 This release

Aug 26, 2026 2 files

0.3.0

Aug 26, 2026 2 files

0.2.1

Aug 26, 2026 2 files

0.2.0

Aug 26, 2026 2 files

sokel-plugin-sdk 0.4.0

Sokel Plugin SDK — Python

Install

Four steps

What you can do

Configuration

Example

Developing this SDK

License

Project links

Key dates

1 maintainer

GitHub Statistics

License

Requires

Provides Extra

Tags

Classifiers

Download files

Source Distribution

Built Distribution

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

Release history Release notifications | RSS feed