py-sparcli 0.3.0__tar.gz

py_sparcli-0.3.0/.editorconfig

@@ -0,0 +1,25 @@
+# EditorConfig: https://editorconfig.org
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+indent_style = space
+indent_size = 4
+max_line_length = 80
+
+[*.py]
+indent_size = 4
+
+[*.{md,markdown}]
+indent_size = 2
+# Keep trailing spaces off; hard line breaks use a backslash, not two spaces.
+trim_trailing_whitespace = true
+
+[*.{toml,yaml,yml,json}]
+indent_size = 2
+
+[Makefile]
+indent_style = tab

py_sparcli-0.3.0/.gitattributes

@@ -0,0 +1,29 @@
+# Normalize line endings: LF in the repository, auto on checkout.
+* text=auto eol=lf
+
+# Explicitly text.
+*.py    text
+*.pyi   text
+*.md    text
+*.toml  text
+*.cfg   text
+*.txt   text
+*.yml   text
+*.yaml  text
+
+# Binary assets (add screenshots/GIFs here as they are introduced).
+*.png   binary
+*.gif   binary
+*.jpg   binary
+*.svg   text
+
+# Keep source-distribution / `git archive` tarballs lean: development-only
+# files are excluded from exports.
+.editorconfig    export-ignore
+.gitattributes   export-ignore
+.gitignore       export-ignore
+.github/         export-ignore
+CLAUDE.md        export-ignore
+TODO.md          export-ignore
+tests/           export-ignore
+examples/        export-ignore

py_sparcli-0.3.0/.gitignore

@@ -0,0 +1,222 @@
+# ============================================================
+# Python
+# ============================================================
+
+# macOS
+.DS_Store
+**/.DS_Store
+._*
+.AppleDouble
+.LSOverride
+.Spotlight-V100
+.Trashes
+.fseventsd
+.DocumentRevisions-V100
+Icon
+
+# Windows
+Thumbs.db
+ehthumbs.db
+Desktop.ini
+$RECYCLE.BIN/
+
+# Linux / editor backups
+*~
+.netrwhist
+
+# Editors / IDEs
+.vscode
+.idea
+*.code-workspace
+*.sw?
+.history
+
+# Environment files
+.env
+# ...but keep committable example/template files:
+!.env.example
+!.env.template
+
+# Logs
+*.log
+
+# Claude Code
+.claude
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+src/*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+.benchmarks/
+nosetests.xml
+coverage.xml
+*.cover
+*.lcov
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django / Flask / Scrapy
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+instance/
+.webassets-cache
+.scrapy
+
+# Sphinx / mkdocs documentation
+docs/_build/
+docs/build/
+/site
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+.python-version
+
+# pdm
+.pdm.toml
+.pdm-python
+.pdm-build/
+
+# PEP 582
+__pypackages__/
+
+# Celery / message brokers
+celerybeat-schedule*
+celerybeat.pid
+*.rdb
+*.aof
+*.pid
+mnesia/
+rabbitmq/
+rabbitmq-data/
+activemq-data/
+
+# SageMath
+*.sage.py
+
+# pixi
+.pixi/*
+!.pixi/config.toml
+
+# Environments
+.envrc
+.venv
+.venv/
+# .venv may be a symlink -> .venv.nosync (iCloud-excluded real dir)
+.venv.nosync/
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder / Rope project settings
+.spyderproject
+.spyproject
+.ropeproject
+
+# mypy
+.mypy_cache*
+.dmypy.json
+dmypy.json
+
+# Pyre / pytype
+.pyre/
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# Ruff
+.ruff_cache/
+
+# isort
+*.isorted
+
+# PyPI configuration file
+.pypirc
+
+# Cursor
+.cursorignore
+.cursorindexingignore
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Streamlit
+.streamlit/secrets.toml
+
+# Abstra
+.abstra/
+
+# VS Code "Code Runner" extension
+tempCodeRunnerFile.py
+
+# Temp dirs
+temp/
+_temp/
+tmp/
+temp-*/
+tmp-*/
+
+# ------------------------------------------------------------
+# Project-specific
+# ------------------------------------------------------------
+.pixi

py_sparcli-0.3.0/.pre-commit-config.yaml

@@ -0,0 +1,32 @@
+# Pre-commit hooks: https://pre-commit.com
+# Install once with `pre-commit install`; run on demand with
+# `pre-commit run --all-files`. Optional but recommended for contributors,
+# since the project has no CI.
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: check-toml
+      - id: check-yaml
+      - id: check-merge-conflict
+      - id: end-of-file-fixer
+      - id: trailing-whitespace
+        args: [--markdown-linebreak-ext=md]
+      - id: mixed-line-ending
+        args: [--fix=lf]
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.15.21
+    hooks:
+      - id: ruff-check
+        args: [--fix]
+      - id: ruff-format
+
+  - repo: local
+    hooks:
+      - id: basedpyright
+        name: basedpyright (strict)
+        entry: basedpyright sparcli examples
+        language: system
+        types: [python]
+        pass_filenames: false

py_sparcli-0.3.0/CHANGELOG.md

@@ -0,0 +1,57 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.3.0] – 2026-07-11
+
+### Added
+
+- `Style.remove_modifier` clears one or more attributes from a layered style (the counterpart to `add_modifier`).
+- `TextInput` and `PasswordInput` gained keyword-only constructor options mirroring their fluent setters, so they configure like every other widget.
+- `OutcomeKind` is re-exported from the flat `sparcli` namespace.
+
+### Changed
+
+- Hide the terminal hardware cursor during in-place redraws (spinner, progress, multi-progress, live) and interactive prompts, and restore it reliably on finish, on prompt exit and at interpreter exit.
+
+### Fixed
+
+- `DatePicker` navigation past the representable date range (before year 1 or after year 9999) no longer raises; it clamps to `date.min` / `date.max`.
+- Inline markup no longer swallows a closed bracket that names no known style or attribute (such as `array[0]`); such text is emitted literally.
+- `char_width` no longer raises on an empty or multi-character string.
+- A negative `NumberInput.decimals` setting is clamped to zero instead of raising when the value is formatted.
+- The raw-mode paths in `TerminalGuard` and the external-editor suspension now also catch `termios.error`, so a non-terminal stdin falls back to the documented no-op instead of raising (`termios.error` is not an `OSError`).
+- `TextInput`'s Ctrl-G external editor now runs with raw mode suspended (cooked), matching `Textarea` and the Rust original; previously the editor launched while the terminal was still in raw mode.
+- `KeyValue` rows are no longer padded with trailing spaces when there is no right margin; shorter rows stay ragged, matching the Rust original.
+- Word wrapping splits on runs of whitespace (tabs, repeated spaces), matching Rust's `split_whitespace`, instead of on a single space only.
+- History files are split into entries on newlines only (like Rust's `str::lines`), so an entry containing an exotic line separator is no longer split in two.
+
+### Security
+
+- Control characters (C0, DEL and C1, except tab) are stripped from span content and OSC-8 link URLs before they reach the terminal, so untrusted text can no longer inject escape sequences or terminate a hyperlink early.
+- History files are written atomically (temp file plus rename), so a crash or a concurrent writer can no longer truncate the file.
+
+### Documentation
+
+- Align the minor version with the Rust `sparcli` port (both at 0.3.x); the two ports now track the same minor number.
+- Add `CONTRIBUTING.md`, `SECURITY.md`, `CODE_OF_CONDUCT.md`, `TODO.md`, README badges and editor/VCS tooling configs (`.editorconfig`, `.gitattributes`); migrate packaging metadata to an SPDX license expression and expand the project URLs for PyPI.
+
+### Notes
+
+- `DatePicker`'s initial "today" uses the local date here, while the Rust original uses UTC (it stays dependency-free). This one-point divergence is intentional; near midnight the default day can differ by one between the two ports.
+
+## [0.1.0] – 2026-07-10
+
+### Added
+
+- Initial release: idiomatic Python port of the Rust `sparcli` library.
+- Styled output widgets: `Panel`, `Table`, `List`, `Rule`, `Alert`, `Badge`, `Columns`, `Tree`, `KeyValue`, `Diff`, `Spinner`, `ProgressBar`, `MultiProgress`, `Live`, `Pager`.
+- Interactive input widgets: `TextInput`, `PasswordInput`, `NumberInput`, `Confirm`, `Select`, `FuzzySelect`, `DatePicker`, `Textarea`.
+- Unified `Theme`, inline `markup`, width utilities, terminal capability detection, validators, shortcuts and command history.
+- Dependency-free (standard library only).
+
+[Unreleased]: https://github.com/cgroening/py-sparcli/compare/v0.3.0...HEAD [0.3.0]: https://github.com/cgroening/py-sparcli/compare/v0.1.0...v0.3.0 [0.1.0]: https://github.com/cgroening/py-sparcli/releases/tag/v0.1.0

py_sparcli-0.3.0/CLAUDE.md

@@ -0,0 +1,107 @@
+# CLAUDE.md – sparcli (Python)
+
+Requirements for all future sessions in this project. On conflict, this file takes precedence over general conventions, but not over explicit user instructions. The global style guide (`~/.claude/CLAUDE.md` → §12 Python) applies additionally; this file refines and overrides it wherever it is more specific.
+
+## What is this?
+
+`sparcli` is a **lightweight, cross-platform** toolkit (macOS, Windows, Linux) for **styled CLI output** and **interactive single-input widgets** – an **idiomatic, dependency-free Python reimplementation** of the Rust library `sparcli`. Guiding idea: small, for little CLI tools. No async, no rich/textual/prompt_toolkit, minimal footprint.
+
+- **Foundation:** a custom ANSI renderer built directly on the standard library (no framework).
+- **API feel:** ratatui-familiar vocabulary (`Style`, `Color`, `Span`, `Line`, `Text`, `Modifier`); **both** a keyword constructor **and** fluent builder methods per widget.
+- **Scope:** output is complete; input covers single widgets only (no form/app/args). Fuzzy is only an inline select.
+- **Rust original is the SSOT for behavior:** `/Users/cgroening/Developer/Rust/ libs/sparcli`. For behavior questions, check there and preserve parity.
+
+## Rust parity (mandatory)
+
+- The Rust version lives at `/Users/cgroening/Developer/Rust/libs/sparcli`.
+- **On every change, check whether the same change also has to be made in the Rust version** (behavior, API, docs, examples) to keep both in parity.
+- When such a change might be needed, **ask the user** whether it should be carried over to the Rust version instead of deciding silently.
+- **Version sync:** the Python and Rust ports keep their **minor version in sync** (at minimum the minor number matches). On a release, bump this port to the Rust port's minor. This is why the Python port jumped 0.1.0 -> 0.3.0 to meet Rust `sparcli` v0.3.
+- **Known intentional divergence:** `DatePicker`'s initial "today" uses the **local** date here (`datetime.date.today`), while the Rust version uses **UTC** (it has no local-time API without a dependency, and both stay dependency-free). Near midnight the default day can differ by one between the two ports. Do not "fix" this into parity without user sign-off.
+
+## Distribution & import
+
+- PyPI distribution name: **`py-sparcli`** (the name `sparcli` is taken).
+- Import name: **`import sparcli`**.
+- Build backend: hatchling, static version in `pyproject.toml`, `[tool.hatch.build.targets.wheel] packages = ["sparcli"]`, ships `py.typed`.
+
+## Architecture (keep the layers strictly separated)
+
+- `core/` – foundation: style, color, text, render, geometry, border, theme, width, terminal, markup. No widget logic.
+- `output/` – printable widgets, subclass `Renderable` (`render(max_width) -> Rendered`). Shared helpers: `layout`, `compose`, `box`, `live`.
+- `input/` – interactive prompts over `EventSource` (DI) + the `prompt.run_prompt` loop + `line_edit.LineEditor` (SSOT for text editing) + `field` (rendering).
+- **Dependency direction:** `output`/`input` → `core`. Never cyclic, never `core` → widget layer.
+- **A single unified theme** in `core/theme.py` drives both input and output.
+- The public API is re-exported flat (`from sparcli import ...`, 80 symbols) plus the namespaces `sparcli.width/terminal/markup/event/validate/shortcut`. Every `__init__.py` carries an explicit `__all__` list.
+
+## Dependencies
+
+- **Zero runtime dependencies – standard library only.** Do not add a new runtime dependency without first checking with the user.
+- Deliberate stdlib decisions (do not soften them):
+  - Display width via `unicodedata` (no `wcwidth`).
+  - DatePicker via `datetime.date`/`calendar` (no hand-rolled date class).
+  - Fuzzy scorer written by hand (no `nucleo`/`rapidfuzz`).
+  - Terminal raw mode / key parsing via `termios`/`tty` + `msvcrt`.
+- `markup`, `fuzzy` and `pager` are always included (no feature flags/extras).
+
+## Style & tooling
+
+- Target Python: **3.12+** (`requires-python = ">=3.12"`).
+- **Strings: double quotes `"..."`** – a deliberate, user-mandated deviation from the style-guide default (§12.5). Enforced via `[tool.ruff.format] quote-style = "double"`. Exceptions that stay single-quoted: string literals nested inside a double-quoted f-string (`';'`, `' '`) and `repr` outputs in doctests.
+- **Formatting/linting:** `ruff` (format + lint). 80-character lines. Imports isort-sorted (stdlib → third-party → local). `from __future__ import annotations` as the first line of every module.
+- **Type checking:** `basedpyright` in **strict** mode must report 0 errors. Complete, modern type hints (`X | None`, builtin generics, PEP 695).
+- No em dash; straight quotes/apostrophes; named constants instead of magic numbers/strings.
+
+Commands (from the project root):
+
+```bash
+ruff check --fix . && ruff format .
+basedpyright sparcli examples
+python -m pytest -q
+```
+
+## API conventions (idiomatic)
+
+- Widgets: regular classes with `__slots__`, subclass `Renderable`, a keyword constructor (`*` keyword-only options) **and** fluent builder methods that mutate `self` and return it. `Rendered` is itself a `Renderable`.
+- Value types (`Style`, `Color`, `Edges`, `Title`, `BorderChars`, `Theme`) as `@dataclass(frozen=True, slots=True)` or `enum.Enum`; enums instead of magic strings.
+- Interfaces as `ABC` + `@abstractmethod` (`Renderable`, `EventSource`); DI via constructor/parameters.
+- Docstrings in NumPy style with an RST-title module docstring; public items get `Parameters`/`Returns`/`Examples`, third-person present ("Returns…").
+- Keep functions small (SRP), ≤ 3 parameters (otherwise bundle into an options/state object), guard clauses, at most 2 levels of nesting.
+
+## Error handling
+
+- Exception hierarchy in `sparcli/errors.py`: `SparcliError` (base) with `TerminalError`, `NoTerminalError`, `ConfigError`. Wrap foreign errors sensibly.
+- **No `assert` for validation** (stripped under `-O`). Do not return `None` for "no result"; use an empty collection, a special-case object, or an exception. (Parser optionals such as `Color.from_hex -> Color | None` are the documented exception.)
+- Prompts return `Outcome[T]` (`submitted`/`cancelled`/`shortcut`), not a cancel exception.
+- `TerminalGuard` (context manager, RAII) restores raw mode / bracketed paste on exit or error.
+- **Logging:** only `logging.getLogger(__name__)` and only `warning`/`debug` where a result would otherwise be silently swallowed (terminal restore, history load/save, temp cleanup). Do not ship a logger/backend; nothing in render/event loops; real errors come back via `SparcliError`.
+- `subprocess` only with an argument list (never `shell=True`/`os.system`); use `tempfile` safely; honor `NO_COLOR`/non-TTY.
+
+## Look
+
+- Muted look, a single accent tone, `dim` for secondary text. Default border `Rounded`; truncate overflow with `…`.
+- Glyphs in two tiers (Unicode + ASCII fallback), selected via the theme.
+- Selection lists navigate cyclically; honor `NO_COLOR` and non-TTY (then plain, no ANSI codes, no OSC-8).
+
+## Tests – mandatory
+
+- `pytest`; tests in `tests/`, grouped in `class TestXxx`; test names describe the expected behavior; prefer fakes over mocks.
+- **Output:** render to `Rendered` and assert on `plain()` or ANSI-stripped content and styles (no TTY).
+- **Input:** drive headlessly via `event.ScriptedSource` (scripted keys) + `run_with(source)` and assert on the `Outcome`.
+- Doctests in `# Examples` count as tests (`--doctest-modules`) and must pass. `repr` expected-outputs keep single quotes.
+- Test override: `SPARCLI_NO_TTY=1` forces non-TTY.
+- **Run all tests after every change** and keep ruff + basedpyright clean.
+
+## Environment variables
+
+`NO_COLOR` (disables color), `CLICOLOR_FORCE` (forces color), `COLORTERM` (truecolor/24bit → TrueColor), `SPARCLI_NO_TTY` (test override, non-TTY).
+
+## Docs / maintenance
+
+- On changes, update README.md, `docs/DEVELOPMENT.md`, CHANGELOG.md, docstrings and tests together. The CHANGELOG follows Keep a Changelog + SemVer.
+- Keep the `examples/` (five counterparts to the Rust version, including the two README generators `output_readme.py`/`prompt_readme.py` via `frame()`) current on API changes.
+- Remove dead/commented-out code; fix the cause, not the symptom.
+
+## Git
+
+- **No commits on your own.** At the end of a change, suggest a commit title (English, imperative, Conventional Commits).

py_sparcli-0.3.0/CONTRIBUTING.md

@@ -0,0 +1,52 @@
+# Contributing to sparcli
+
+Thanks for your interest in improving `sparcli`. This is a small, dependency-free library, so the workflow is deliberately lightweight.
+
+## Getting started
+
+The full build, test and lint workflow lives in [`docs/DEVELOPMENT.md`](docs/DEVELOPMENT.md). In short:
+
+```bash
+pip install -e .
+pip install ruff basedpyright pytest   # or: uv sync --group dev
+
+python -m pytest -q            # tests + doctests
+ruff check .                   # lint
+ruff format --check .          # formatting (drop --check to apply)
+basedpyright sparcli examples  # strict type checking
+```
+
+All three checks must be clean before a change is ready. Optionally, install the pre-commit hooks to run linting, formatting and type checks automatically:
+
+```bash
+pre-commit install          # once
+pre-commit run --all-files  # on demand
+```
+
+## Ground rules
+
+- **Target Python 3.12+.** The code uses PEP 695 generics and `type` statements.
+- **Zero runtime dependencies.** Do not add a runtime dependency; the standard library only. Open an issue first if you think one is unavoidable.
+- **Style gates** (enforced by `ruff` and `basedpyright`): 80-column lines, double-quoted strings, isort-ordered imports, complete modern type hints, and `basedpyright` strict with zero errors.
+- **Layering.** `output/` and `input/` depend on `core/`, never the reverse, and `core/` depends on nothing internal.
+- **Tests are mandatory.** Add headless tests under `tests/` following the patterns in `docs/DEVELOPMENT.md`; doctests in `# Examples` count as tests.
+- **Docs travel with code.** Update `README.md`, `CHANGELOG.md`, docstrings and, where relevant, the `examples/` gallery in the same change.
+
+The "Adding a widget" checklist in `docs/DEVELOPMENT.md` walks through a typical contribution end to end.
+
+## Rust parity
+
+`sparcli` is an idiomatic port of the Rust library at a matching version (the two ports keep their **minor version in sync**). The Rust original is the source of truth for behavior. When a change affects behavior, API or docs, note in your PR whether the same change should be mirrored to the Rust port.
+
+## Commits and pull requests
+
+- Use [Conventional Commits](https://www.conventionalcommits.org/) for commit titles (`feat:`, `fix:`, `docs:`, `refactor:`, `test:`, `chore:`), imperative mood, English.
+- Add a `CHANGELOG.md` entry under `## [Unreleased]` (Keep a Changelog format).
+- Keep pull requests focused; describe the behavior change and how you verified it.
+
+## Reporting bugs and security issues
+
+- Regular bugs and feature requests: open a [GitHub issue](https://github.com/cgroening/py-sparcli/issues).
+- Security vulnerabilities: **do not** open a public issue; follow [`SECURITY.md`](SECURITY.md).
+
+By contributing you agree that your contributions are licensed under the project's [MIT license](LICENSE).

py_sparcli-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Corvin Gröning
+
+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.