Python API — overview
The reference is generated automatically from the sources of the dagstack-plugin-system package via pydoc-markdown and refreshed on every release.
:::info Generation deferred at launch
The first version of the documentation site does not include the rendered reference yet. The pipeline configuration lives in pydoc-markdown.yaml at the repository root; the entry point is make api-python. Content lands in subsequent commits.
:::
What the reference covers (planned)
| Module | Contents |
|---|---|
dagstack.plugin_system | Public top level — discover, PluginRegistry, PluginManifest, errors. |
dagstack.plugin_system.contract | Contract tests — run_contract_suite, assert_* checks, report types. |
dagstack.plugin_system.dispatch | Dispatchers — BroadcastCollectDispatcher, ChainDispatcher, CapabilityDispatcher. |
dagstack.plugin_system.resources | Standard resources plus their real and test injection forms. |
dagstack.plugin_system.adapters | MCP adapters for out-of-process plugins. |
dagstack.plugin_system.sinks | ProgressSink, CheckpointStore reference implementations. |
Generating locally
Requires Python 3.11+ and pydoc-markdown installed:
pip install pydoc-markdown
cd <repo-root>
make api-python
The generated .mdx files land in site/docs/api/python/. Run this either by hand before a commit, or from a CI job that automatically opens a PR with the refreshed reference after a Python-package release.
While the reference is not generated
Use:
- Docstrings straight from the package:
python -c "import dagstack.plugin_system as m; help(m)". - The guide pages: Writing a plugin, Configuration, Lifecycle.
- The spec and ADRs in
dagstack/plugin-system-spec— the normative source of contracts.