tomlrt-cli 1.0.1__tar.gz

tomlrt_cli-1.0.1/PKG-INFO

@@ -0,0 +1,173 @@
+Metadata-Version: 2.4
+Name: tomlrt-cli
+Version: 1.0.1
+Summary: Read and write values in TOML files while preserving comments and formatting.
+Keywords: cli,config,edit,rust,toml
+Author: Ryan Parman
+Author-email: Ryan Parman <ryan@ryanparman.com>
+License-Expression: MIT
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Utilities
+Classifier: Typing :: Typed
+Requires-Dist: tomlrt>=1.7.2,<2
+Requires-Python: >=3.12
+Project-URL: Homepage, https://github.com/northwood-labs/tomlrt-cli
+Project-URL: Issues, https://github.com/northwood-labs/tomlrt-cli/issues
+Project-URL: Repository, https://github.com/northwood-labs/tomlrt-cli
+Description-Content-Type: text/markdown
+
+# tomlrt-cli
+
+A command-line tool for reading and writing values in TOML files while preserving comments, formatting, and key ordering. Think `jq`, but for TOML.
+
+## Why use this?
+
+Most TOML libraries either can't write (Python's `tomllib`) or destroy comments and formatting when they do (`tomli-w`). `tomlrt-cli` uses a round-trip parser under the hood, so you can update a single value in a TOML file from a shell script or CI pipeline without mangling the rest of the document.
+
+Common use cases:
+
+* Bumping version numbers in `pyproject.toml` from CI
+* Pinning container digests in config files
+* Reading specific values for shell variable assignment
+* Scripted config modifications that respect hand-crafted formatting
+
+## Prerequisites
+
+* Python 3.12 or newer
+* [uv](https://docs.astral.sh/uv/) (for development and running from source)
+
+No prerequisites for end users — install and run directly with `uvx`:
+
+```bash
+uvx tomlrt-cli --help
+```
+
+## Usage
+
+### Read an entire file
+
+```bash
+tomlrt-cli config.toml
+```
+
+Outputs the full document to stdout (comments and formatting preserved).
+
+### Read a specific value
+
+```bash
+tomlrt-cli --path project.version pyproject.toml
+```
+
+Outputs just the value at that path.
+
+### Write a value (to stdout)
+
+```bash
+tomlrt-cli --path project.version --value "2.0.0" pyproject.toml
+```
+
+Outputs the full modified document to stdout. The original file is not changed.
+
+### Write a value (to file)
+
+```bash
+tomlrt-cli --path project.version --value "2.0.0" --output pyproject.toml pyproject.toml
+```
+
+Writes the modified document to the output file. Use the same path for input and output to edit in-place.
+
+### Path syntax
+
+Keys are separated by dots. Keys that contain dots or special characters can be quoted or bracketed:
+
+```bash
+# Simple dotted path
+tomlrt-cli --path version.v26.alpine config.toml
+
+# Quoted key (key "3.14" contains a dot)
+tomlrt-cli --path 'version."3.14".alpine' config.toml
+
+# Bracket notation (same result)
+tomlrt-cli --path 'version["3.14"].alpine' config.toml
+```
+
+All three notations are interchangeable and can be mixed in a single path.
+
+### Flags
+
+| Flag        | Short | Description                                 |
+|-------------|-------|---------------------------------------------|
+| `--path`    | `-p`  | TOML key path to read or write              |
+| `--value`   | `-v`  | Value to assign at the given path           |
+| `--output`  | `-o`  | Write result to this file (default: stdout) |
+| `--version` | `-V`  | Print version and exit                      |
+| `--help`    | `-h`  | Print help and exit                         |
+
+## Development
+
+### Setup
+
+```bash
+git clone <repo-url>
+cd tomlrt-cli
+uv sync
+```
+
+### Running tests
+
+This project uses [Tryke](https://tryke.dev), a Rust-based test runner with a Jest-style API:
+
+```bash
+task test
+```
+
+The test suite has two files:
+
+* `tests/test_cli.py` — Integration tests that exercise `main()` end-to-end with temporary TOML files. Verifies argument parsing, file I/O, and output routing.
+* `tests/test_parse_path.py` — Unit tests for the path parser covering dotted, quoted, and bracket notation. Includes a [Hypothesis](https://hypothesis.readthedocs.io/) property test that fuzzes bare-key round-tripping to catch edge cases.
+
+### Linting and formatting
+
+```bash
+task lint
+```
+
+### Build and publish
+
+```bash
+task build       # Produces sdist + wheel in dist/
+task publish     # Upload to PyPI
+```
+
+## Troubleshooting
+
+### `KeyError` when using `--path`
+
+The path does not exist in the document. Double-check key names — TOML keys are case-sensitive. Run without `--path` to see the full document structure.
+
+### Quoted keys not working
+
+Make sure your shell isn't stripping the quotes. Wrap the entire `--path` value in single quotes:
+
+```bash
+tomlrt-cli --path 'version."3.14".alpine' config.toml
+```
+
+### `--value` didn't change the file
+
+Without `--output`, changes go to stdout only. Add `--output <file>` to persist:
+
+```bash
+tomlrt-cli --path key --value new --output config.toml config.toml
+```
+
+### `ModuleNotFoundError: tomlrt`
+
+Run via `uv run tomlrt-cli` (which manages the virtualenv) or install with `uv sync` first.

tomlrt_cli-1.0.1/README.md

@@ -0,0 +1,148 @@
+# tomlrt-cli
+
+A command-line tool for reading and writing values in TOML files while preserving comments, formatting, and key ordering. Think `jq`, but for TOML.
+
+## Why use this?
+
+Most TOML libraries either can't write (Python's `tomllib`) or destroy comments and formatting when they do (`tomli-w`). `tomlrt-cli` uses a round-trip parser under the hood, so you can update a single value in a TOML file from a shell script or CI pipeline without mangling the rest of the document.
+
+Common use cases:
+
+* Bumping version numbers in `pyproject.toml` from CI
+* Pinning container digests in config files
+* Reading specific values for shell variable assignment
+* Scripted config modifications that respect hand-crafted formatting
+
+## Prerequisites
+
+* Python 3.12 or newer
+* [uv](https://docs.astral.sh/uv/) (for development and running from source)
+
+No prerequisites for end users — install and run directly with `uvx`:
+
+```bash
+uvx tomlrt-cli --help
+```
+
+## Usage
+
+### Read an entire file
+
+```bash
+tomlrt-cli config.toml
+```
+
+Outputs the full document to stdout (comments and formatting preserved).
+
+### Read a specific value
+
+```bash
+tomlrt-cli --path project.version pyproject.toml
+```
+
+Outputs just the value at that path.
+
+### Write a value (to stdout)
+
+```bash
+tomlrt-cli --path project.version --value "2.0.0" pyproject.toml
+```
+
+Outputs the full modified document to stdout. The original file is not changed.
+
+### Write a value (to file)
+
+```bash
+tomlrt-cli --path project.version --value "2.0.0" --output pyproject.toml pyproject.toml
+```
+
+Writes the modified document to the output file. Use the same path for input and output to edit in-place.
+
+### Path syntax
+
+Keys are separated by dots. Keys that contain dots or special characters can be quoted or bracketed:
+
+```bash
+# Simple dotted path
+tomlrt-cli --path version.v26.alpine config.toml
+
+# Quoted key (key "3.14" contains a dot)
+tomlrt-cli --path 'version."3.14".alpine' config.toml
+
+# Bracket notation (same result)
+tomlrt-cli --path 'version["3.14"].alpine' config.toml
+```
+
+All three notations are interchangeable and can be mixed in a single path.
+
+### Flags
+
+| Flag        | Short | Description                                 |
+|-------------|-------|---------------------------------------------|
+| `--path`    | `-p`  | TOML key path to read or write              |
+| `--value`   | `-v`  | Value to assign at the given path           |
+| `--output`  | `-o`  | Write result to this file (default: stdout) |
+| `--version` | `-V`  | Print version and exit                      |
+| `--help`    | `-h`  | Print help and exit                         |
+
+## Development
+
+### Setup
+
+```bash
+git clone <repo-url>
+cd tomlrt-cli
+uv sync
+```
+
+### Running tests
+
+This project uses [Tryke](https://tryke.dev), a Rust-based test runner with a Jest-style API:
+
+```bash
+task test
+```
+
+The test suite has two files:
+
+* `tests/test_cli.py` — Integration tests that exercise `main()` end-to-end with temporary TOML files. Verifies argument parsing, file I/O, and output routing.
+* `tests/test_parse_path.py` — Unit tests for the path parser covering dotted, quoted, and bracket notation. Includes a [Hypothesis](https://hypothesis.readthedocs.io/) property test that fuzzes bare-key round-tripping to catch edge cases.
+
+### Linting and formatting
+
+```bash
+task lint
+```
+
+### Build and publish
+
+```bash
+task build       # Produces sdist + wheel in dist/
+task publish     # Upload to PyPI
+```
+
+## Troubleshooting
+
+### `KeyError` when using `--path`
+
+The path does not exist in the document. Double-check key names — TOML keys are case-sensitive. Run without `--path` to see the full document structure.
+
+### Quoted keys not working
+
+Make sure your shell isn't stripping the quotes. Wrap the entire `--path` value in single quotes:
+
+```bash
+tomlrt-cli --path 'version."3.14".alpine' config.toml
+```
+
+### `--value` didn't change the file
+
+Without `--output`, changes go to stdout only. Add `--output <file>` to persist:
+
+```bash
+tomlrt-cli --path key --value new --output config.toml config.toml
+```
+
+### `ModuleNotFoundError: tomlrt`
+
+Run via `uv run tomlrt-cli` (which manages the virtualenv) or install with `uv sync` first.

tomlrt_cli-1.0.1/pyproject.toml

@@ -0,0 +1,47 @@
+[project]
+  name = "tomlrt-cli"
+  version = "1.0.1"
+  description = "Read and write values in TOML files while preserving comments and formatting."
+  readme = "README.md"
+  requires-python = ">=3.12"
+  license = "MIT"
+  authors = [ { email = "ryan@ryanparman.com", name = "Ryan Parman" } ]
+  keywords = [ "cli", "config", "edit", "rust", "toml" ]
+  classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Software Development :: Libraries",
+    "Topic :: Utilities",
+    "Typing :: Typed",
+  ]
+  dependencies = [ "tomlrt>=1.7.2,<2" ]
+
+  [project.urls]
+    Homepage = "https://github.com/northwood-labs/tomlrt-cli"
+    Issues = "https://github.com/northwood-labs/tomlrt-cli/issues"
+    Repository = "https://github.com/northwood-labs/tomlrt-cli"
+
+  [project.scripts]
+    tomlrt-cli = "tomlrt_cli.cli:main"
+
+[dependency-groups]
+  dev = [ "hypothesis>=6.155.1,<7", "ruff>=0.15,<1", "tryke>=0.0.29,<1", "zuban>=0.8,<1" ]
+
+[build-system]
+  requires = [ "uv_build>=0.11.17,<0.12.0" ]
+  build-backend = "uv_build"
+
+[tool.ruff]
+  target-version = "py312"
+  line-length = 120
+
+  [tool.ruff.lint]
+    select = [ "E", "F", "I", "N", "W", "UP" ]
+
+[tool.tryke]
+  src = [ ".", "src" ]

tomlrt_cli-1.0.1/src/tomlrt_cli/__init__.py

@@ -0,0 +1 @@
+"""tomlrt-cli."""

tomlrt_cli-1.0.1/src/tomlrt_cli/cli.py

@@ -0,0 +1,139 @@
+"""
+CLI entry point for tomlrt-cli.
+
+This module is the sole user-facing interface. It wires argument parsing to
+tomlrt operations so that shell scripts and CI pipelines can read or
+manipulate TOML files without writing Python.
+"""
+
+import argparse
+import re
+import sys
+from importlib.metadata import version
+
+import tomlrt
+
+# ------------------------------------------------------------------------------
+# PRIVATE FUNCTIONS
+
+
+def _parse_path(path: str) -> tuple[str, ...]:
+    """
+    Convert a user-supplied key path string into a tuple of literal key
+    segments that tomlrt can traverse.
+
+    tomlrt's `install()` accepts either a dot-separated string (which it
+    naively splits on `.`) or a tuple of literal segments. Naive splitting
+    breaks when a key itself contains a dot (e.g., version "3.14"). This
+    parser exists to let users express such keys with quoting or bracket
+    notation while still producing the tuple that tomlrt needs.
+    """
+    segments: list[str] = []
+    i = 0
+
+    while i < len(path):
+        # Dots are separators, not content — skip them.
+        if path[i] == ".":
+            i += 1
+
+        elif path[i] == "[":
+            # Bracket notation (version["3.14"]) lets users reference keys
+            # that would be ambiguous in dotted form because the key value
+            # itself contains dots or special characters.
+            i += 1
+
+            if i < len(path) and path[i] in ('"', "'"):
+                quote = path[i]
+                i += 1
+
+                end = path.index(quote, i)
+                segments.append(path[i:end])
+                i = end + 1
+
+                if i < len(path) and path[i] == "]":
+                    i += 1
+
+            else:
+                # Unquoted bracket content — treat everything up to `]`
+                # as the literal key name.
+                end = path.index("]", i)
+                segments.append(path[i:end])
+                i = end + 1
+
+        elif path[i] in ('"', "'"):
+            # Inline quoted key (version."3.14".alpine) — the quotes
+            # protect the enclosed value from being split on dots.
+            quote = path[i]
+            i += 1
+
+            end = path.index(quote, i)
+            segments.append(path[i:end])
+            i = end + 1
+
+        else:
+            # Bare key — consume everything until the next delimiter.
+            match = re.match(r'[^.\["\'\]]+', path[i:])
+
+            if match:
+                segments.append(match.group())
+                i += match.end()
+
+    return tuple(segments)
+
+
+# ------------------------------------------------------------------------------
+# PUBLIC FUNCTIONS
+
+
+def main() -> int:
+    """
+    Parse CLI arguments and perform the requested TOML read operation.
+
+    Designed to behave like jq for TOML: read a file, optionally drill into a
+    specific path, and emit the result to stdout or a file.
+    """
+    parser = argparse.ArgumentParser(prog="tomlrt-cli", description="tomlrt-cli")
+    parser.add_argument("-V", "--version", action="version", version=f"%(prog)s {version('tomlrt-cli')}")
+    parser.add_argument("-o", "--output", help="output file path (default: stdout)")
+    parser.add_argument("-p", "--path", help="TOML key path")
+    parser.add_argument("-v", "--value", help="value to assign to the TOML key path")
+    parser.add_argument("input", help="input file")
+    args = parser.parse_args()
+
+    with open(args.input, "rb") as f:
+        doc = tomlrt.load(f)
+
+    if args.path:
+        path = _parse_path(args.path)
+        node = doc
+
+        # Walk intermediate segments to reach the parent table. We stop one
+        # short so we can index the final key for its value rather than
+        # descending into it as a table.
+        for segment in path[:-1]:
+            node = node[segment]
+
+        if args.value:
+            # Write mode: set the value at the path, then emit the full modified
+            # document. The caller controls where it lands via --output (file)
+            # or stdout (default).
+            node[path[-1]] = args.value
+            result = tomlrt.dumps(doc)
+        else:
+            result = str(node[path[-1]])
+    else:
+        # No path specified — emit the entire document, preserving comments and
+        # formatting via tomlrt's round-trip serialiser.
+        result = tomlrt.dumps(doc)
+
+    if args.output:
+        with open(args.output, "w") as f:
+            f.write(result)
+    else:
+        sys.stdout.write(result)
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())