livery-toolroom 0.6.2__tar.gz

livery_toolroom-0.6.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Willem Kokke
+
+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.

livery_toolroom-0.6.2/PKG-INFO

@@ -0,0 +1,130 @@
+Metadata-Version: 2.4
+Name: livery-toolroom
+Version: 0.6.2
+Summary: Typed surfaces for command-line tools, generated from the tools themselves.
+Author: Willem Kokke
+Author-email: Willem Kokke <mail@willem.net>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Typing :: Typed
+Requires-Dist: livery-footman>=0.52.2 ; extra == 'test'
+Requires-Dist: footman>=0.52.2 ; extra == 'test'
+Requires-Dist: mkdocs>=1.6 ; extra == 'test'
+Requires-Dist: toolroom>=0.6.2 ; extra == 'test'
+Requires-Python: >=3.11
+Project-URL: Repository, https://github.com/willemkokke/livery
+Provides-Extra: test
+Description-Content-Type: text/markdown
+
+# toolroom
+
+Typed surfaces for command-line tools, generated from the tools
+themselves.
+
+```python
+from toolroom import git, cmake, ruff
+
+git.switch("-c", "release/v1.4")
+cmake.build("build", parallel=8)
+ruff.check("src", fix=True, select=["E", "F"])
+```
+
+A tool room is where precision tools are made, kept with their
+measurements, repaired when they drift, and issued for use. That is the
+whole design, one verb at a time: a stub generator reads each tool's own
+`--help` and writes a typed surface for it; the surfaces are kept with
+the version they were read from; a weekly refresh re-takes them when the
+tool moves; and the bridge issues any tool as a Python handle —
+including tools no stub has ever described.
+`toolroom.terraform("plan")` runs whether or not toolroom has heard of
+terraform.
+
+> **Beta.** toolroom is pre-1.0: minor versions may include breaking
+> changes — always called out in the
+> [changelog](https://github.com/willemkokke/toolroom/blob/main/CHANGELOG.md),
+> never in a patch release. Pin the minor (`toolroom~=0.6.0`) if you
+> build on it.
+
+## No transcription
+
+toolroom does **not** transcribe a tool's flags into Python parameters.
+Transcription drifts: the wrapper pins the flag-set its author copied,
+the tool moves on, and one day a call emits a flag the installed binary
+rejects. Instead, keyword arguments translate *mechanically*, so the
+installed tool's own CLI stays the single source of truth, at whatever
+version it is:
+
+- `fix=True` → `--fix` (`False`/`None` → omitted entirely)
+- `strict=off` → `--no-strict` (`off` is the `toolroom.off` sentinel)
+- `output_format="github"` → `--output-format github`
+- `select=["E", "F"]` → `--select E --select F`
+- `x=1` (single letter) → `-x 1`
+- a trailing underscore escapes Python keywords: `import_="x"` → `--import x`
+
+Attribute access chains subcommands
+(`toolroom.docker.compose.up(detach=True)`), and positional strings pass
+through verbatim. The typed stubs *suggest* — your editor knows the
+flags and what each one does — but they never forbid: the hints decide
+whether your editor can help, never whether a call works.
+[Using the tools](https://willemkokke.github.io/toolroom/usage/) has the
+full grammar.
+
+## Standalone, or hosted
+
+With nothing else installed, a call spawns the tool with plain
+`subprocess` and answers in a `Result` — the exit code as an `int`
+subclass, carrying the captured streams. A failure raises `ToolError`
+unless the call opted into `nofail`.
+
+When [footman](https://willemkokke.github.io/footman/) is present in the
+process, the same call routes through footman's `run()` instead and
+inherits everything a task run means: capture, replay-on-failure,
+dry-run, `recording()`, `--json` receipts, parallel lanes. Neither
+package imports or depends on the other — they were designed together
+and are better together, but each is useful with the other absent.
+[With footman](https://willemkokke.github.io/toolroom/footman/) tells
+that story.
+
+## Built, not run
+
+`.argv` turns a handle's call into a command line instead of an
+execution — an ordinary `list[str]`, with `.posix()` and `.windows()`
+for the moment it crosses into a shell:
+
+```python
+cmd = git.push.argv(force=True)  # ["git", "push", "--force"]
+cmd.posix()  # "git push --force", quoted for a POSIX shell
+```
+
+## Testing
+
+Code that calls tools is tested with `toolroom.testing.answers()`: the
+handles stay real — chaining, flag translation, redaction are all
+exercised — and only execution is replaced, answered from a table of
+canned output and exit codes:
+
+```python
+from toolroom.testing import answers
+
+with answers({("git", "push"): 1}) as calls:
+    release()  # exercises the failure path
+
+assert calls[0].argv == ["git", "push"]
+```
+
+[Testing](https://willemkokke.github.io/toolroom/testing/) has the whole
+story.
+
+## Install
+
+```sh
+uv add toolroom        # or: pip install toolroom
+```
+
+toolroom has **zero runtime dependencies** and needs Python 3.11+. The
+docs live at
+[willemkokke.github.io/toolroom](https://willemkokke.github.io/toolroom/).
+MIT licensed.

livery_toolroom-0.6.2/README.md

@@ -0,0 +1,109 @@
+# toolroom
+
+Typed surfaces for command-line tools, generated from the tools
+themselves.
+
+```python
+from toolroom import git, cmake, ruff
+
+git.switch("-c", "release/v1.4")
+cmake.build("build", parallel=8)
+ruff.check("src", fix=True, select=["E", "F"])
+```
+
+A tool room is where precision tools are made, kept with their
+measurements, repaired when they drift, and issued for use. That is the
+whole design, one verb at a time: a stub generator reads each tool's own
+`--help` and writes a typed surface for it; the surfaces are kept with
+the version they were read from; a weekly refresh re-takes them when the
+tool moves; and the bridge issues any tool as a Python handle —
+including tools no stub has ever described.
+`toolroom.terraform("plan")` runs whether or not toolroom has heard of
+terraform.
+
+> **Beta.** toolroom is pre-1.0: minor versions may include breaking
+> changes — always called out in the
+> [changelog](https://github.com/willemkokke/toolroom/blob/main/CHANGELOG.md),
+> never in a patch release. Pin the minor (`toolroom~=0.6.0`) if you
+> build on it.
+
+## No transcription
+
+toolroom does **not** transcribe a tool's flags into Python parameters.
+Transcription drifts: the wrapper pins the flag-set its author copied,
+the tool moves on, and one day a call emits a flag the installed binary
+rejects. Instead, keyword arguments translate *mechanically*, so the
+installed tool's own CLI stays the single source of truth, at whatever
+version it is:
+
+- `fix=True` → `--fix` (`False`/`None` → omitted entirely)
+- `strict=off` → `--no-strict` (`off` is the `toolroom.off` sentinel)
+- `output_format="github"` → `--output-format github`
+- `select=["E", "F"]` → `--select E --select F`
+- `x=1` (single letter) → `-x 1`
+- a trailing underscore escapes Python keywords: `import_="x"` → `--import x`
+
+Attribute access chains subcommands
+(`toolroom.docker.compose.up(detach=True)`), and positional strings pass
+through verbatim. The typed stubs *suggest* — your editor knows the
+flags and what each one does — but they never forbid: the hints decide
+whether your editor can help, never whether a call works.
+[Using the tools](https://willemkokke.github.io/toolroom/usage/) has the
+full grammar.
+
+## Standalone, or hosted
+
+With nothing else installed, a call spawns the tool with plain
+`subprocess` and answers in a `Result` — the exit code as an `int`
+subclass, carrying the captured streams. A failure raises `ToolError`
+unless the call opted into `nofail`.
+
+When [footman](https://willemkokke.github.io/footman/) is present in the
+process, the same call routes through footman's `run()` instead and
+inherits everything a task run means: capture, replay-on-failure,
+dry-run, `recording()`, `--json` receipts, parallel lanes. Neither
+package imports or depends on the other — they were designed together
+and are better together, but each is useful with the other absent.
+[With footman](https://willemkokke.github.io/toolroom/footman/) tells
+that story.
+
+## Built, not run
+
+`.argv` turns a handle's call into a command line instead of an
+execution — an ordinary `list[str]`, with `.posix()` and `.windows()`
+for the moment it crosses into a shell:
+
+```python
+cmd = git.push.argv(force=True)  # ["git", "push", "--force"]
+cmd.posix()  # "git push --force", quoted for a POSIX shell
+```
+
+## Testing
+
+Code that calls tools is tested with `toolroom.testing.answers()`: the
+handles stay real — chaining, flag translation, redaction are all
+exercised — and only execution is replaced, answered from a table of
+canned output and exit codes:
+
+```python
+from toolroom.testing import answers
+
+with answers({("git", "push"): 1}) as calls:
+    release()  # exercises the failure path
+
+assert calls[0].argv == ["git", "push"]
+```
+
+[Testing](https://willemkokke.github.io/toolroom/testing/) has the whole
+story.
+
+## Install
+
+```sh
+uv add toolroom        # or: pip install toolroom
+```
+
+toolroom has **zero runtime dependencies** and needs Python 3.11+. The
+docs live at
+[willemkokke.github.io/toolroom](https://willemkokke.github.io/toolroom/).
+MIT licensed.

livery_toolroom-0.6.2/pyproject.toml

@@ -0,0 +1,64 @@
+[build-system]
+requires = ["uv_build>=0.11,<0.13"]
+build-backend = "uv_build"
+
+[project]
+name = "livery-toolroom"
+version = "0.6.2"
+description = "Typed surfaces for command-line tools, generated from the tools themselves."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.11"
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Typing :: Typed",
+]
+dependencies = []
+
+[[project.authors]]
+name = "Willem Kokke"
+email = "mail@willem.net"
+
+[project.optional-dependencies]
+test = [
+    "livery-footman>=0.52.2",
+    "footman>=0.52.2",
+    "mkdocs>=1.6",
+    "toolroom>=0.6.2",
+]
+
+[project.entry-points."footman.tasks"]
+"livery.toolroom" = "livery.toolroom._docsgen"
+
+[project.urls]
+Repository = "https://github.com/willemkokke/livery"
+
+[tool.uv.build-backend]
+module-name = "livery.toolroom"
+
+[tool.ruff]
+extend = "../../pyproject.toml"
+
+[tool.ruff.lint.per-file-ignores]
+"src/**" = [
+    "D105",
+    "D102",
+    "D107",
+    "D205",
+    "D301",
+    "D415",
+]
+"tests/**" = [
+    "D1",
+    "D205",
+    "D301",
+    "D415",
+    "E501",
+]
+"src/livery/toolroom/_stubs/*.pyi" = [
+    "E501",
+    "D",
+]

livery_toolroom-0.6.2/pyproject.toml.orig

@@ -0,0 +1,74 @@
+# Seeded from the template channel (package-python kind) at
+# birth; this file is the workspace's own. Edit it directly:
+# the template never rewrites it.
+[build-system]
+requires = ["uv_build>=0.11,<0.13"]
+build-backend = "uv_build"
+
+[project]
+name = "livery-toolroom"
+version = "0.6.2"
+description = "Typed surfaces for command-line tools, generated from the tools themselves."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.11"
+authors = [{ name = "Willem Kokke", email = "mail@willem.net" }]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Typing :: Typed",
+]
+
+# Dependency-free at runtime, pinned by test: the one declared
+# runtime dependency stays reserved for strongroom. The private
+# _machinery and _docsgen modules import footman, and load only
+# through footman's own plugin() - the livery.forge._dev precedent.
+dependencies = []
+
+# The suite's needs beyond the (empty) runtime dependencies: the
+# hosted seam, the machinery, and the playground probe all drive
+# footman for real. The isolated release legs install this extra;
+# a consumer never sees it unasked.
+[project.optional-dependencies]
+test = [
+    "livery-footman>=0.52.2",
+    # The playground harness speaks the compat spelling on purpose
+    # (it is the spelling a browser consumer installs), so its probe
+    # needs the shim beside the real distribution.
+    "footman>=0.52.2",
+    # The driver suite interrogates mkdocs structurally (the click
+    # ladder) and reads its version; without a venv copy the finder
+    # meets whatever the machine carries, which the suite's python
+    # cannot introspect.
+    "mkdocs>=1.6",
+    # The playground writes a consumer tasks.py that imports the
+    # package by its index spelling; the suite drives that spelling
+    # on purpose, so it needs this package's own shim.
+    "toolroom>=0.6.2",
+]
+
+[project.entry-points."footman.tasks"]
+"livery.toolroom" = "livery.toolroom._docsgen"
+
+[project.urls]
+Repository = "https://github.com/willemkokke/livery"
+
+[tool.uv.build-backend]
+# PEP 420 namespace: the importable package is livery.toolroom and
+# there is no livery/__init__.py anywhere in this repository.
+module-name = "livery.toolroom"
+
+[tool.ruff]
+extend = "../../pyproject.toml"
+
+[tool.ruff.lint.per-file-ignores]
+# The imported sources predate the workspace's pydocstyle rule;
+# their docstring conformance is a tracked content pass, not a
+# cut-time rewrite. Retired by that pass.
+"src/**" = ["D105", "D102", "D107", "D205", "D301", "D415"]
+"tests/**" = ["D1", "D205", "D301", "D415", "E501"]
+# The generated stubs' ruling rides here too when ruff resolves this
+# nested config for the package's own tree.
+"src/livery/toolroom/_stubs/*.pyi" = ["E501", "D"]