plexus-sdk (0.1.2)
Installation
pip install --index-url About this package
Python SDK for the Plexus school-administration platform — typed Convex client + API-token auth.
plexus-sdk
Typed Python SDK for the Plexus school-administration platform. It speaks to
the platform's self-hosted Convex backend over the standard HTTP RPC plane
(/api/query|mutation|action) and authenticates with an API token you mint in
the app.
It is intentionally dependency-light (httpx + pydantic only) so you can drop it
into scripts, data pipelines, or your own tools. The plexus-cli command-line tool
is a thin layer on top of this SDK.
Install
uv pip install plexus-sdk \
--extra-index-url https://gitea.i.ivo-zilkenat.de/api/packages/ivo.zilkenat/pypi/simple/
Get a token
In the Plexus app: Settings → API-Token → create. Copy the plx_… value (it is
shown only once). The token maps to your user, so it carries your permissions
across every tenant you can reach (a platform-admin token reaches all of them).
Use
from plexus_sdk import PlexusClient
client = PlexusClient(
convex_url="https://db.edos.schule", # /api/query|mutation|action
site_url="https://actions.db.edos.schule", # /cli/token (auth exchange)
token="plx_…",
)
# Who am I? (identity + permissions)
me = client.query("permissions:currentUserAccess", {})
# Search persons in a tenant
people = client.query("parties:listForMain", {"client": "<tenant-slug>", "q": "Müller"})
PlexusClient exchanges the opaque token for a short-lived JWT on first use,
caches it in memory, and refreshes automatically on expiry. Convex errors are
raised as PlexusError (never swallowed).
From environment variables
import os
from plexus_sdk import Config, PlexusClient
os.environ.update(
PLEXUS_CONVEX_URL="https://db.edos.schule",
PLEXUS_SITE_URL="https://actions.db.edos.schule",
PLEXUS_TOKEN="plx_…",
)
client = PlexusClient.from_config(Config.from_env())
Typed models
plexus_sdk.models contains generated Pydantic models for the platform's public
functions' arguments and return shapes. They are generated from the Convex
function-spec (scripts/regen-models.sh) and curated to the public surface — do
not hand-edit models.py.
Notes
- The backend uses
edos*identifiers internally (issuer, deployment) for historical reasons; you only ever need the two URLs above and your token. - Subscriptions/real-time are not supported by this SDK (HTTP RPC only).