Skip to content

API Reference

stackops is easiest to approach as three connected layers:

  • stackops.utils for shared helpers and script-generation glue
  • stackops.cluster for layouts, terminal sessions, and remote job execution
  • stackops.utils.schemas.installer, stackops.jobs.installer, and stackops.utils.installer_utils for curated, grouped, and URL-driven installers

This reference follows those workflows instead of mirroring the raw package tree. It is the user-facing API surface: typed models, orchestration classes, installer entrypoints, path and IO helpers, schedulers, interactive helpers, and config schemas. Private helpers, generated assets, platform probes, and modules whose main job is CLI wiring are internal unless a page below names them as an import pattern.

Integration areas

Area What it covers Main modules Reference
Environment and project wiring .venv discovery, activation helpers, and cloud metadata defaults stackops.utils.python_env, stackops.utils.cloud_defaults Environment and project wiring
Paths, files, and config documents JSON / INI / pickle IO, GPG helpers, path mutation, path-reference lookup stackops.utils.io, stackops.utils.path_core, stackops.utils.path_helper, stackops.utils.path_reference Paths, files, and config
Scheduling and cache Repeating routines, memory cache, disk-backed cache stackops.utils.scheduler Scheduling and cache
Interactive helpers and notifications IDs, list splitting, fuzzy / TV-backed choices, HTML email stackops.utils.accessories, stackops.utils.options, stackops.utils.notifications Interactive helpers and notifications
Code generation and command launching Lambda-to-script conversion, uv command builders, shell execution, shell handoff, missing-tool install guards stackops.utils.meta, stackops.utils.code, stackops.utils.installer_utils.installer_cli Code generation and command launching
Remote execution and networking Remote job config and state, transfer, SSH, public-IP and LAN helpers stackops.cluster.remote.*, stackops.utils.ssh, stackops.scripts.python.helpers.helpers_network.* Remote execution and networking
Installer catalog and package groups Installer data, package groups, install request handling, install orchestration, direct URL installers stackops.utils.schemas.installer.*, stackops.jobs.installer.*, stackops.utils.installer_utils.* Jobs and installer APIs

Package map

stackops/
├── cluster/
│   ├── remote/                    # Remote job models, transfer, script generation
├── jobs/
│   └── installer/                 # package groups and install scripts
├── scripts/python/helpers/
│   └── helpers_network/           # IP and connectivity helpers
├── utils/
│   ├── accessories, cloud_defaults, code, io, meta, notifications, options, python_env, scheduler, ssh
│   ├── installer_utils/           # Runtime installer engine
│   ├── path_core, path_helper, path_reference
│   └── schemas/{installer,layouts} # installer_data.json and schema types
└── settings/                      # Configuration assets and templates

Choose a reference track

Utilities

Start here if you are importing helper APIs into your own scripts or applications:

Cluster and remote execution

Start here if you are generating layouts, managing terminal sessions, or submitting jobs to other machines:

Jobs and installers

Start here if you need the curated installer catalog, group definitions, or install orchestration helpers:

Common import patterns

from stackops.cluster.remote.models import RemoteStackOpsConfig
from stackops.cluster.remote.remote_machine import RemoteMachine
from stackops.cluster.sessions_managers.utils.maker import make_layout_from_functions
from stackops.utils.schemas.installer.package_groups import PACKAGE_GROUP2NAMES
from stackops.utils.code import run_shell_script
from stackops.utils.installer_utils.installer_cli import install_if_missing
from stackops.utils.scheduler import Scheduler, Cache

If you need end-user command entrypoints instead of library APIs, see the CLI Reference.