otto-sh 0.1.0__tar.gz

otto_sh-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Chris Collins
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

otto_sh-0.1.0/PKG-INFO

@@ -0,0 +1,229 @@
+Metadata-Version: 2.4
+Name: otto-sh
+Version: 0.1.0
+Summary: Our Trusty Testing Orchestrator - framework and CLI for deploying, testing, and monitoring software across remote hosts.
+Keywords: testing,automation,orchestration,ssh,telnet,asyncio,cli,remote-execution
+Author: Chris Collins
+Author-email: Chris Collins <chriscoll93@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Topic :: Software Development :: Testing
+Classifier: Topic :: System :: Systems Administration
+Requires-Dist: aioftp>=0.27.2
+Requires-Dist: aiosqlite>=0.21.0
+Requires-Dist: asyncssh>=2.22.0
+Requires-Dist: fastapi>=0.135.1
+Requires-Dist: jinja2>=3.1.0
+Requires-Dist: pytest>=9.0.1
+Requires-Dist: pytest-asyncio>=1.3.0
+Requires-Dist: rich>=14.3.3
+Requires-Dist: sse-starlette>=3.3.3
+Requires-Dist: telnetlib3>=4.0.1
+Requires-Dist: tomli>=2.4.0
+Requires-Dist: typer>=0.24.0
+Requires-Dist: uvicorn>=0.42.0
+Requires-Python: >=3.10
+Project-URL: Homepage, https://github.com/ludachrish3/otto-sh
+Project-URL: Source, https://github.com/ludachrish3/otto-sh
+Project-URL: Issues, https://github.com/ludachrish3/otto-sh/issues
+Project-URL: Documentation, https://otto-sh.readthedocs.io
+Project-URL: Changelog, https://github.com/ludachrish3/otto-sh/blob/main/CHANGELOG.md
+Description-Content-Type: text/markdown
+
+# otto
+
+**otto** — Our Trusty Testing Orchestrator — is a framework for deploying
+products to remote hosts for testing and validation. It provides a CLI and a
+Python API for running commands on remote systems, transferring files,
+executing test suites, and monitoring host metrics in real time.
+
+## Who is otto for?
+
+Otto is a general-purpose tool for developers and testers who need to interact
+with one or more remote machines as part of their workflow — deploying builds,
+validating firmware, running integration tests, or collecting performance
+data.
+
+## Two ways to use otto
+
+- **CLI users** — interact with otto through the `otto run`, `otto test`, and
+  `otto monitor` commands.
+- **API builders** — import otto's Python packages to build higher-level
+  automation on top of hosts, suites, and the monitor.
+
+## Key concepts
+
+### Hosts
+
+A **Host** represents a machine otto can talk to. `RemoteHost` connects over
+SSH or Telnet; `LocalHost` runs commands on the local machine without any
+network connection.
+
+Both expose the same core interface — `run`, `oneshot`, `send` / `expect`, and
+file-transfer methods (`put`, `get`).
+
+`run` executes a command on a host's persistent shell session (state like the
+working directory and environment variables are preserved between calls).
+`oneshot` runs each call independently of the persistent shell and of other
+concurrent `oneshot` calls, making it safe to fan out via `asyncio.gather()`.
+
+### Labs
+
+Hosts can be reached through intermediate **hops** — SSH jump hosts that otto
+tunnels through automatically. Hops can be chained for multi-hop paths
+(`otto -> hop1 -> hop2 -> target`). All file transfer protocols (SCP, SFTP,
+FTP, netcat) work through hops. Set the `hop` field in a host's JSON
+definition or use `--hop` on the CLI.
+
+A **Lab** is a JSON file that describes a set of hosts and their topology.
+Otto loads labs at startup (via `--lab` or the `OTTO_LAB` environment
+variable) and makes every host available to instructions, test suites, and
+the monitor. Multiple labs can be merged by passing several names.
+
+### Repos and settings
+
+Otto discovers your project through a `.otto/settings.toml` file at the
+repository root. This file tells otto where to find your Python libraries,
+test suites, run instructions, and lab data:
+
+```toml
+name = "my_project"
+version = "1.0.0"
+
+labs  = ["${sutDir}/../lab_data"]
+libs  = ["${sutDir}/pylib"]
+tests = ["${sutDir}/tests"]
+init  = ["my_instructions"]
+```
+
+`${sutDir}` is replaced with the repository root at load time. The `init` list
+names Python modules that otto imports at startup — this is where you
+register your instructions and shared options.
+
+### Instructions (`otto run`)
+
+An **instruction** is an async function decorated with `@instruction()` that
+becomes a subcommand of `otto run`. Instructions have full access to the
+lab's hosts and can accept their own CLI options via Typer annotations:
+
+```python
+from otto.cli.run import instruction
+from otto.configmodule.configmodule import all_hosts
+from otto.logger import getOttoLogger
+
+logger = getOttoLogger()
+
+@instruction()
+async def deploy(
+    debug: Annotated[bool, typer.Option("--field/--debug")] = False,
+):
+    for host in all_hosts():
+        await host.run(["echo deploying", "make install"])
+    logger.info("Done")
+```
+
+```bash
+otto -l my_lab run deploy --debug
+```
+
+### Test suites (`otto test`)
+
+A **suite** is a class that extends `OttoSuite` and is registered with the
+`@register_suite()` decorator. Each suite becomes a subcommand of `otto test`.
+Suites can define their own `Options` dataclass whose fields appear as CLI
+flags:
+
+```python
+from dataclasses import dataclass
+from typing import Annotated
+
+import typer
+from otto.suite import OttoSuite, register_suite
+
+@dataclass
+class _Options:
+    firmware: Annotated[str, typer.Option(help="Firmware version.")] = "latest"
+
+@register_suite()
+class TestDevice(OttoSuite[_Options]):
+    Options = _Options
+
+    async def test_device_reachable(self, suite_options: _Options) -> None:
+        self.logger.info(f"firmware={suite_options.firmware}")
+        assert True
+```
+
+```bash
+otto -l my_lab test TestDevice --firmware 2.1
+otto test --iterations 10 --threshold 95 TestDevice
+```
+
+Suites support pytest markers (`timeout`, `retry`, `parametrize`,
+`integration`), non-fatal assertions via `self.expect()`, per-test artifact
+directories, and built-in monitoring.
+
+Both suites and instructions accept an options dataclass. For flags that are
+repo-wide (device type, lab environment, etc.), define a single `RepoOptions`
+dataclass in your pylib and inherit it from both sides.
+
+### Monitor (`otto monitor`)
+
+The monitor collects live performance metrics (CPU, memory, disk, network)
+from one or more hosts and serves an interactive web dashboard:
+
+```bash
+otto -l my_lab monitor                     # all hosts, default 5 s interval
+otto monitor host1,host2 --interval 2.0    # specific hosts, faster polling
+otto monitor --db metrics.db               # persist data for later viewing
+otto monitor --file metrics.db             # replay saved data
+```
+
+Monitoring can also be started from within a test suite using
+`await self.startMonitor(hosts=...)` and `await self.stopMonitor()`.
+
+## Quick-start example
+
+1. **Set the environment** — point otto at your repo and lab:
+
+   ```bash
+   export OTTO_SUT_DIRS=/path/to/my_project
+   otto --lab my_lab --list-hosts          # verify hosts are visible
+   ```
+
+2. **Run an instruction:**
+
+   ```bash
+   otto -l my_lab run deploy --debug
+   ```
+
+3. **Run a test suite:**
+
+   ```bash
+   otto -l my_lab test TestDevice --firmware 2.1
+   ```
+
+4. **Monitor hosts:**
+
+   ```bash
+   otto -l my_lab monitor
+   ```
+
+## Documentation
+
+Hosted documentation: [otto-sh.readthedocs.io](https://otto-sh.readthedocs.io).
+
+The same content lives under `docs/` and can be built locally with `make docs`
+— the generated HTML is written to `docs/_build/html/`. Key entry points:
+
+- `docs/getting-started.md` — installation and first steps
+- `docs/guide/` — detailed guides for each CLI command
+- `docs/cookbook/` — recipes for common asyncio patterns
+- `docs/api/` — full API reference for all otto packages

otto_sh-0.1.0/README.md

@@ -0,0 +1,189 @@
+# otto
+
+**otto** — Our Trusty Testing Orchestrator — is a framework for deploying
+products to remote hosts for testing and validation. It provides a CLI and a
+Python API for running commands on remote systems, transferring files,
+executing test suites, and monitoring host metrics in real time.
+
+## Who is otto for?
+
+Otto is a general-purpose tool for developers and testers who need to interact
+with one or more remote machines as part of their workflow — deploying builds,
+validating firmware, running integration tests, or collecting performance
+data.
+
+## Two ways to use otto
+
+- **CLI users** — interact with otto through the `otto run`, `otto test`, and
+  `otto monitor` commands.
+- **API builders** — import otto's Python packages to build higher-level
+  automation on top of hosts, suites, and the monitor.
+
+## Key concepts
+
+### Hosts
+
+A **Host** represents a machine otto can talk to. `RemoteHost` connects over
+SSH or Telnet; `LocalHost` runs commands on the local machine without any
+network connection.
+
+Both expose the same core interface — `run`, `oneshot`, `send` / `expect`, and
+file-transfer methods (`put`, `get`).
+
+`run` executes a command on a host's persistent shell session (state like the
+working directory and environment variables are preserved between calls).
+`oneshot` runs each call independently of the persistent shell and of other
+concurrent `oneshot` calls, making it safe to fan out via `asyncio.gather()`.
+
+### Labs
+
+Hosts can be reached through intermediate **hops** — SSH jump hosts that otto
+tunnels through automatically. Hops can be chained for multi-hop paths
+(`otto -> hop1 -> hop2 -> target`). All file transfer protocols (SCP, SFTP,
+FTP, netcat) work through hops. Set the `hop` field in a host's JSON
+definition or use `--hop` on the CLI.
+
+A **Lab** is a JSON file that describes a set of hosts and their topology.
+Otto loads labs at startup (via `--lab` or the `OTTO_LAB` environment
+variable) and makes every host available to instructions, test suites, and
+the monitor. Multiple labs can be merged by passing several names.
+
+### Repos and settings
+
+Otto discovers your project through a `.otto/settings.toml` file at the
+repository root. This file tells otto where to find your Python libraries,
+test suites, run instructions, and lab data:
+
+```toml
+name = "my_project"
+version = "1.0.0"
+
+labs  = ["${sutDir}/../lab_data"]
+libs  = ["${sutDir}/pylib"]
+tests = ["${sutDir}/tests"]
+init  = ["my_instructions"]
+```
+
+`${sutDir}` is replaced with the repository root at load time. The `init` list
+names Python modules that otto imports at startup — this is where you
+register your instructions and shared options.
+
+### Instructions (`otto run`)
+
+An **instruction** is an async function decorated with `@instruction()` that
+becomes a subcommand of `otto run`. Instructions have full access to the
+lab's hosts and can accept their own CLI options via Typer annotations:
+
+```python
+from otto.cli.run import instruction
+from otto.configmodule.configmodule import all_hosts
+from otto.logger import getOttoLogger
+
+logger = getOttoLogger()
+
+@instruction()
+async def deploy(
+    debug: Annotated[bool, typer.Option("--field/--debug")] = False,
+):
+    for host in all_hosts():
+        await host.run(["echo deploying", "make install"])
+    logger.info("Done")
+```
+
+```bash
+otto -l my_lab run deploy --debug
+```
+
+### Test suites (`otto test`)
+
+A **suite** is a class that extends `OttoSuite` and is registered with the
+`@register_suite()` decorator. Each suite becomes a subcommand of `otto test`.
+Suites can define their own `Options` dataclass whose fields appear as CLI
+flags:
+
+```python
+from dataclasses import dataclass
+from typing import Annotated
+
+import typer
+from otto.suite import OttoSuite, register_suite
+
+@dataclass
+class _Options:
+    firmware: Annotated[str, typer.Option(help="Firmware version.")] = "latest"
+
+@register_suite()
+class TestDevice(OttoSuite[_Options]):
+    Options = _Options
+
+    async def test_device_reachable(self, suite_options: _Options) -> None:
+        self.logger.info(f"firmware={suite_options.firmware}")
+        assert True
+```
+
+```bash
+otto -l my_lab test TestDevice --firmware 2.1
+otto test --iterations 10 --threshold 95 TestDevice
+```
+
+Suites support pytest markers (`timeout`, `retry`, `parametrize`,
+`integration`), non-fatal assertions via `self.expect()`, per-test artifact
+directories, and built-in monitoring.
+
+Both suites and instructions accept an options dataclass. For flags that are
+repo-wide (device type, lab environment, etc.), define a single `RepoOptions`
+dataclass in your pylib and inherit it from both sides.
+
+### Monitor (`otto monitor`)
+
+The monitor collects live performance metrics (CPU, memory, disk, network)
+from one or more hosts and serves an interactive web dashboard:
+
+```bash
+otto -l my_lab monitor                     # all hosts, default 5 s interval
+otto monitor host1,host2 --interval 2.0    # specific hosts, faster polling
+otto monitor --db metrics.db               # persist data for later viewing
+otto monitor --file metrics.db             # replay saved data
+```
+
+Monitoring can also be started from within a test suite using
+`await self.startMonitor(hosts=...)` and `await self.stopMonitor()`.
+
+## Quick-start example
+
+1. **Set the environment** — point otto at your repo and lab:
+
+   ```bash
+   export OTTO_SUT_DIRS=/path/to/my_project
+   otto --lab my_lab --list-hosts          # verify hosts are visible
+   ```
+
+2. **Run an instruction:**
+
+   ```bash
+   otto -l my_lab run deploy --debug
+   ```
+
+3. **Run a test suite:**
+
+   ```bash
+   otto -l my_lab test TestDevice --firmware 2.1
+   ```
+
+4. **Monitor hosts:**
+
+   ```bash
+   otto -l my_lab monitor
+   ```
+
+## Documentation
+
+Hosted documentation: [otto-sh.readthedocs.io](https://otto-sh.readthedocs.io).
+
+The same content lives under `docs/` and can be built locally with `make docs`
+— the generated HTML is written to `docs/_build/html/`. Key entry points:
+
+- `docs/getting-started.md` — installation and first steps
+- `docs/guide/` — detailed guides for each CLI command
+- `docs/cookbook/` — recipes for common asyncio patterns
+- `docs/api/` — full API reference for all otto packages

otto_sh-0.1.0/pyproject.toml

@@ -0,0 +1,164 @@
+[project]
+name = "otto-sh"
+version = "0.1.0"
+description = "Our Trusty Testing Orchestrator - framework and CLI for deploying, testing, and monitoring software across remote hosts."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+    { name = "Chris Collins", email = "chriscoll93@gmail.com" },
+]
+keywords = [
+    "testing",
+    "automation",
+    "orchestration",
+    "ssh",
+    "telnet",
+    "asyncio",
+    "cli",
+    "remote-execution",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Framework :: AsyncIO",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: POSIX :: Linux",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Topic :: Software Development :: Testing",
+    "Topic :: System :: Systems Administration",
+]
+dependencies = [
+    "aioftp>=0.27.2",
+    "aiosqlite>=0.21.0",
+    "asyncssh>=2.22.0",
+    "fastapi>=0.135.1",
+    "jinja2>=3.1.0",
+    # pytest + pytest-asyncio are runtime deps because otto imports user
+    # test files at runtime (orchestration introspection), and those files
+    # commonly `import pytest` / use `pytest_asyncio` markers.
+    "pytest>=9.0.1",
+    "pytest-asyncio>=1.3.0",
+    "rich>=14.3.3",
+    "sse-starlette>=3.3.3",
+    "telnetlib3>=4.0.1",
+    "tomli>=2.4.0",
+    "typer>=0.24.0",
+    "uvicorn>=0.42.0",
+]
+
+[project.scripts]
+otto = "otto:app"
+
+[project.urls]
+Homepage = "https://github.com/ludachrish3/otto-sh"
+Source = "https://github.com/ludachrish3/otto-sh"
+Issues = "https://github.com/ludachrish3/otto-sh/issues"
+Documentation = "https://otto-sh.readthedocs.io"
+Changelog = "https://github.com/ludachrish3/otto-sh/blob/main/CHANGELOG.md"
+
+[build-system]
+requires = [
+    "uv_build>=0.10.0",
+    "uv_build<0.11.0",
+]
+build-backend = "uv_build"
+
+# Dist name is `otto-sh` (for PyPI); the import package stays `otto`, so the
+# build backend needs to be pointed at src/otto/ explicitly.
+[tool.uv.build-backend]
+module-name = "otto"
+
+[dependency-groups]
+dev = [
+    "bump-my-version>=1.3.0",
+    "sphinx-immaterial",
+    "myst-parser>=4.0.1",
+    "py-spy>=0.4.1",
+    "pyinstrument>=5.1.2",
+    "pytest-cov>=7.0.0",
+    "pytest-xdist>=3.8.0",
+    "ruff>=0.14.7",
+    "sphinx>=8.0",
+    "sphinx-autodoc-typehints>=2.0",
+    "ty==0.0.31",
+]
+
+[tool.pyright]
+typeCheckingMode = "strict"
+ignore = [
+    #"tests", # pytest does not play nice with type checking
+]
+
+# ty is being trialled alongside pyright; see todo/ty_vs_pylance_eval.md.
+# Pinned hard because ty uses 0.0.x versioning with breaking changes between
+# any two releases.
+[tool.ty.environment]
+python-version = "3.10"
+root = ["./src"]
+
+[tool.ty.src]
+include = ["src"]
+exclude = ["tests", "typings", "docs", "build", "dist"]
+
+# All rules at error — there is no pyright-style --strict preset, so we
+# escalate everything uniformly. Rules that turn out to be too noisy should
+# be demoted individually here (not silenced globally) so the decision is
+# visible in diff review.
+[tool.ty.rules]
+all = "error"
+
+[tool.pytest.ini_options]
+testpaths = [
+    "tests/unit",
+    "tests/integration",
+]
+pythonpath = ["src", "."]
+log_cli = true
+log_level = "INFO"
+log_format = "%(asctime)s [%(levelname)s] %(message)s"
+log_cli_date_format = "%Y-%m-%d %H:%M:%S.%f"
+addopts = "--doctest-modules --cov=otto --cov-context=test --cov-report term-missing --cov-report html -n auto --dist loadgroup"
+doctest_optionflags = ["NORMALIZE_WHITESPACE", "ELLIPSIS"]
+asyncio_default_fixture_loop_scope = "function"
+asyncio_mode = "strict"
+markers = [
+    "integration: requires running Vagrant VMs (deselect with -m 'not integration')",
+    "hops: multi-hop integration tests requiring 3 Vagrant VMs (deselect with -m 'not hops')",
+    "timeout(seconds): fail the test if it exceeds the given number of seconds",
+    "retry(n): retry the test up to n times on failure before reporting it as failed",
+]
+
+[tool.bumpversion]
+current_version = "0.1.0"
+commit = true
+tag = true
+tag_name = "v{new_version}"
+tag_message = "Release v{new_version}"
+message = "chore(release): bump version {current_version} -> {new_version}"
+
+[[tool.bumpversion.files]]
+filename = "pyproject.toml"
+search = 'version = "{current_version}"'
+replace = 'version = "{new_version}"'
+
+[[tool.bumpversion.files]]
+filename = "CHANGELOG.md"
+search = "## [Unreleased]"
+replace = "## [Unreleased]\n\n## [{new_version}] - {now:%Y-%m-%d}"
+
+[[tool.bumpversion.files]]
+filename = "CHANGELOG.md"
+search = "[Unreleased]: https://github.com/ludachrish3/otto-sh/compare/v{current_version}...HEAD"
+replace = "[Unreleased]: https://github.com/ludachrish3/otto-sh/compare/v{new_version}...HEAD\n[{new_version}]: https://github.com/ludachrish3/otto-sh/compare/v{current_version}...v{new_version}"
+
+# Keep the lock entry for otto-sh in sync. Without this, every `uv run`
+# after a bump detects pyproject ↔ lock drift and re-syncs the lock,
+# dirtying the tree and blocking the next `make release`.
+[[tool.bumpversion.files]]
+filename = "uv.lock"
+search = "name = \"otto-sh\"\nversion = \"{current_version}\""
+replace = "name = \"otto-sh\"\nversion = \"{new_version}\""

otto_sh-0.1.0/src/otto/__init__.py

@@ -0,0 +1,6 @@
+# Ensure that the OttoLogger is initialized correctly before anything else happens
+from otto.logger import getOttoLogger as getOttoLogger
+
+getOttoLogger()
+
+from otto.cli import app

otto_sh-0.1.0/src/otto/__main__.py

@@ -0,0 +1,3 @@
+from otto import app
+
+app()

otto_sh-0.1.0/src/otto/cli/__init__.py

@@ -0,0 +1,4 @@
+"""otto is a test suite and instruction framework."""
+from .main import (
+    app as app,
+)

otto_sh-0.1.0/src/otto/cli/banner.py

@@ -0,0 +1,10 @@
+from rich.text import (
+    Text,
+)
+
+banner = Text(style="bold green", no_wrap=True)
+banner.append(r'          __  __       ' '\n')
+banner.append(r'   ____  / /_/ /_____  ' '\n')
+banner.append(r'  / __ \/ __/ __/ __ \ ' '\n')
+banner.append(r' / /_/ / /_/ /_/ /_/ / ' '\n')
+banner.append(r' \____/\__/\__/\____/  ' '\n')

otto_sh-0.1.0/src/otto/cli/callbacks.py

@@ -0,0 +1,14 @@
+"""Shared Typer option callbacks used across multiple CLI subapps."""
+
+from ..configmodule import getConfigModule
+
+
+def list_hosts_callback(value: bool) -> None:
+    """Print all host IDs from the current lab and exit."""
+    if not value:
+        return
+    lab = getConfigModule().lab
+    print()
+    for host in lab.hosts:
+        print(f'\u2022 {host}')
+    print()