Utils API¶
stackops.utils is the shared-library layer that most downstream code imports directly. It contains environment discovery, IO and path helpers, schedulers and caches, interactive selection utilities, notification helpers, installer runtime helpers, and the script-generation functions that feed the cluster and remote layers.
Topics in this section¶
| Topic | Use it when you need to... | Main modules |
|---|---|---|
| Environment and project wiring | Discover project virtualenvs and load default cloud settings | stackops.utils.cloud.defaults |
| Paths, files, and config | Read and write JSON / INI / pickle files, encrypt files with GPG, resolve paths and path references | stackops.utils.io, stackops.utils.path_core, stackops.utils.path_reference |
| Scheduling and cache | Run recurring routines and reuse expensive results through memory or disk caches | stackops.cluster.scheduler |
| Interactive helpers and notifications | Generate IDs, split work, present interactive choices, and send email | stackops.utils.accessories, stackops.utils.options_utils.options, stackops.cluster.remote.notifications |
| Code generation and command launching | Turn callables into scripts, build uv commands, run shell snippets, hand off shell work, and ensure CLIs exist |
stackops.utils.meta, stackops.utils.code, stackops.utils.installer_utils.installer_cli |
What tends to live outside this section¶
- Layout schemas and terminal-session backends are documented under Cluster, even though they depend on several utils modules.
stackops.utils.ssh_utilsis documented from Remote execution and networking because it is usually consumed as part of a remote workflow.- Installer data and package groups live under Jobs, while the runtime installer engine lives under
stackops.utils.installer_utils.
Typical import patterns¶
from stackops.utils.accessories import randstr, split_list
from stackops.utils.code import run_shell_script
from stackops.utils.io import read_json, save_json
from stackops.utils.options_utils.options import choose_from_options
from stackops.utils.path_core import collapseuser, tmpfile
from stackops.cluster.scheduler import Scheduler, CacheMemory
The utilities in this section are intentionally low-level. Higher-level session, cluster, and installer flows mostly build on these primitives rather than replacing them.