This release is a pre-release and may not be stable for production use.
treno-dev-steward-sdk
The Steward SDK for Python. Today it holds the part for writing Steward plugins, imported from
steward_sdk.plugin. A plugin declares what it needs to connect to the tools it works with and what it
manages there, and implements the calls Steward makes. The SDK handles everything else: the gRPC
services, the handshake with the runner, the health check, and routing each call to your handler by
kind.
pip install treno-dev-steward-sdk
from steward_sdk.plugin import create_plugin
Requires Python 3.10 or newer. The package ships its type hints.
Start a plugin
steward plugin init my-plugin --language python
cd my-plugin
python -m venv .venv && source .venv/bin/activate
pip install -e .
steward plugin validate python src/plugin.py
steward plugin init takes its templates from the SDK release, so the project always matches the
SDK it depends on. To work on the SDK and its templates together, point it at a local checkout with
--sdk-path /path/to/steward-sdk. The template lives next to the SDKs, in ../templates/python.
A plugin
steward plugin init --language python generates a plugin with a resource that can be provisioned and
given access to. The whole file, with every call and its comments, is
templates/python/src/plugin.py.tmpl.
In short:
from steward_sdk.plugin import create_plugin
async def provision(request):
base_url = request.integration.inputs["base_url"]
return {"outputs": {"url": f"{base_url}/items/{request.name}"}}
async def deprovision(request):
return {}
plugin = create_plugin(
name="my-plugin",
version="0.1.0",
inputs=[{"name": "base_url", "label": "Base URL", "type": "string", "required": True}],
secrets=[{"name": "API_TOKEN", "description": "The token to call the API with.", "required": True}],
)
plugin.resource(
kind="item",
outputs=[{"name": "url", "label": "URL", "type": "string"}],
provision=provision,
deprovision=deprovision,
)
plugin.serve()
A plugin needs one create_plugin(...), any number of plugin.resource(...) and
plugin.application(...) declarations, and a final plugin.serve(). If it needs more than one tool,
for example both Cloudflare and AWS, take the credentials for each as secrets.
What you declare
The plugin, in create_plugin:
| Argument | |
|---|---|
name, version |
Required. |
title, description |
Shown in Steward. |
inputs |
The settings the plugin is configured with. |
secrets |
The credentials it is configured with, such as an API token. |
validate |
Optional. Checks the credentials, which Steward cannot. Returns {"errors": [{"field": ..., "message": ...}]}. Without it, every integration is accepted. |
roles, permissions, grant_access, revoke_access, get_access |
Access to the plugin as a whole, such as membership of an organization. |
A resource, with plugin.resource(kind=..., ...), and an application, with
plugin.application(kind=..., ...), both have a kind that is unique within the plugin, a title, a
description, inputs, secrets and outputs. Resources also take roles and permissions. Applications take
sources, the types they can be deployed from: "github", "registry", "s3" or "raw". The source
of an application arrives as type, config and ref, where config holds the settings of that type:
github {owner, name, branch?}, registry {image, tag?}, s3 {bucket, key} and raw {path}.
ref pins a commit, an image digest or an object version, and is empty for the newest.
Inputs and outputs are declared like variables:
{"name": "visibility", "label": "Visibility", "type": "select", "options": ["private", "public"], "default": "private"}
type is one of string, number, boolean, select, list (of strings) or map. Mark an output
"sensitive": True when it is a secret, such as a generated password, and it stays with the runner.
Secrets are credentials, and are kept, sent and shown apart from inputs. Each has a name, used as
it is, a description and whether it is required. Its value is never shown back once set.
{"name": "GITHUB_TOKEN", "description": "A token that can create repositories.", "required": True}
Access
Access exists at two levels, each with the same three handlers, grant_access, revoke_access and
get_access:
- The plugin, in
create_plugin: membership of the tool as a whole, such as an organization or a site. Steward grants this first, then access to the resources. - A resource kind, in
plugin.resource: a role on one resource, such as a repository. The generated plugin above shows this.
For the plugin it looks like this:
async def grant_access(request: PluginGrantAccessRequest) -> PluginGrantAccessResponse:
identity = request.identity
email = identity.external_id or plain(identity.attrs)["email"]
invitation = await invite(request.integration, email, request.role.name)
return {"id": invitation.id, "role": request.role, "pending": True} # an invitation is not access until accepted
plugin = create_plugin(
name="github",
version="0.1.0",
inputs=[...],
roles=[{"name": "member", "title": "Member"}, {"name": "owner", "title": "Owner"}],
grant_access=grant_access,
revoke_access=revoke_access,
get_access=get_access,
)
invite stands for a call to the tool's own API.
A resource kind takes the same three handlers and its own roles and permissions. Its requests also
carry the resource:
async def grant_access(request: ResourceGrantAccessRequest) -> ResourceGrantAccessResponse:
await add_collaborator(request.integration, request.resource.name, request.identity.external_id, request.role.name)
return {"role": plain(request.role), "permissions": [plain(item) for item in request.permissions]}
plugin.resource(
kind="repository",
permissions=[{"name": "pull"}, {"name": "push"}],
roles=[{"name": "viewer", "title": "Viewer"}, {"name": "editor", "title": "Editor"}],
grant_access=grant_access,
revoke_access=revoke_access,
get_access=get_access,
)
Declaring roles or permissions is what says that the plugin, or the kind, supports access. They are
two separate lists:
rolesare the ones the tool defines itself, each with aname,titleanddescription.permissionsare the pieces Steward builds its own roles from. A permission is anamewith an optionallevel:{"name": "pull_requests", "level": "read"}, or just{"name": "s3:GetObject"}.
Handlers receive the identity (external_id, name, attrs) and the role to apply, and a resource
call also gets the resource (kind, name). The role is always set. For a role Steward composed
from your permissions, permissions lists its pieces too, for you to apply as far as the tool allows.
They return:
grant_access: theroleandpermissionsas the tool applied them, which may differ from what was requested, anidfor the grant if the tool has one (Steward sends it back on revoke), andpending: Truewhile the person has to act first, such as accepting an invitation.revoke_access: nothing. It succeeds if the identity did not have the role.get_access: therolesandpermissionsthe identity holds now, and whether a grant is stillpending.
Steward works out overlap between roles before it asks you to revoke one, so you can remove the role you are given in full.
What Steward offers
Steward offers what you implement. A call for a handler you did not pass answers UNIMPLEMENTED, and
Steward treats that as not offered. Access also needs its roles or permissions, which tell Steward
what can be granted.
| You pass | The kind can |
|---|---|
provision, deprovision |
be created and removed |
list |
be discovered (optional: Steward keeps track of what it creates, so list is only for finding resources that already exist) |
roles or permissions, with grant_access, revoke_access, get_access |
have access granted (resources and the plugin) |
create, destroy, deploy |
be run as an application |
Handlers
A handler takes the request and returns the response. It may be async def or a plain function (a
plain one runs in a thread, so blocking calls do not stall the plugin).
- Requests are the generated protobuf messages, so fields are snake_case and your editor completes
them. A message the runner did not send reads as empty. A Struct such as
inputssupports[],inanddict();plain(message)turns any message into a plain dict. - Responses are a response message or a plain dict with the fields you have something to say
about (snake_case or camelCase). Messages inside it, such as the
roleyou were given, can be used as they are. Returning nothing is an empty response. - Inputs and secrets.
integration.inputsandinputshold the values of the inputs, keyed by input name; numbers arrive as floats. The values of secrets arrive apart from them, keyed by secret name, inintegration.secrets(and a resource's or application'ssecrets), a plaindict-like of strings. Never store them. - Idempotent, and no report of changes. Make calls that change something idempotent: creating what
exists, or removing what is gone, simply succeeds. Return the result of the change (the
outputs, the appliedrole), not a description of what changed: Steward keeps the state and works out the difference itself. - Resources and identities. A resource is identified by its
kindandname, which Steward stores and sends on every later call.provisionreceives them with theinputsand returns only theoutputs, such as a URL or an id the tool assigned. An identity hasexternal_id,name,ulidandattrs; those that are optional report whether they were set withHasField. - Variables. An application's variables each carry
sensitive,sealedandlocked. Adeploycarries the application's full set of variables, so changing them is a deploy. Fail it withFAILED_PRECONDITIONif it would change or remove a locked variable.
Errors
Raise a PluginError with a gRPC status code to report a specific failure:
from steward_sdk.plugin import PluginError, StatusCode
raise PluginError(StatusCode.FAILED_PRECONDITION, "APP_KEY is locked and cannot be removed")
Common codes: INVALID_ARGUMENT, NOT_FOUND, FAILED_PRECONDITION, UNIMPLEMENTED. Any other
exception is reported as INTERNAL, with its traceback on stderr. A call for an unknown kind is
answered with NOT_FOUND by the SDK.
Logging
Write logs to standard error (the logging module does by default), which the runner collects. What a
plugin prints to standard output after the handshake is not shown.
Developing the SDK
The messages and gRPC services are generated from ../proto with buf (buf.gen.yaml, using
buf's remote plugins, so it needs network access), and the generated code is not committed. The plugin
versions in buf.gen.yaml decide the minimum protobuf and grpcio the package requires.
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
buf generate # the messages into src/steward_sdk/_gen
python -m build # the wheel and sdist, with the generated code
Metadata
Release files for treno-dev-steward-sdk 0.1.0rc6
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| treno_dev_steward_sdk-0.1.0rc6.tar.gz | 16.2 kB | With provenance | Details for treno_dev_steward_sdk-0.1.0rc6.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| treno_dev_steward_sdk-0.1.0rc6-py3-none-any.whl | Python 3 | none | any | Details for treno_dev_steward_sdk-0.1.0rc6-py3-none-any.whl |
Total release size: 34.4 kB
Release files / treno_dev_steward_sdk-0.1.0rc6.tar.gz
| Download URL | treno_dev_steward_sdk-0.1.0rc6.tar.gz |
|---|---|
| Size | 16.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
0c4259f4a082aea4a6736062810c3617a2848610c599e91ffb266c423d32e7f8
|
|
BLAKE2b-256 checksum How to use checksums |
a59d24e96c4727cced7c35fc273d223e8b0b591941b84c7ac19881571c4699c9
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 8, 2026.
Transparency logRelease files / treno_dev_steward_sdk-0.1.0rc6-py3-none-any.whl
| Download URL | treno_dev_steward_sdk-0.1.0rc6-py3-none-any.whl |
|---|---|
| Size | 18.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
28dcc00b192c3e6b6d7ff9534e4d35876b3082646505aa3d32a1f33e1745d651
|
|
BLAKE2b-256 checksum How to use checksums |
de091afcb60dce51370c1172d528799fd93d2fa5d4d8d8098842a1178a2d81cc
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 8, 2026.
Transparency logSecurity for treno-dev-steward-sdk 0.1.0rc6
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for treno_dev_steward_sdk-0.1.0rc6.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 8, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.