lib-cli-exit-tools 1.0.3__tar.gz → 1.1.1__tar.gz

lib_cli_exit_tools-1.1.1/AGENTS.md

@@ -0,0 +1,230 @@
+# Repository Guidelines
+
+## On session start
+
+- Connect to the `systemprompts` MCP filesystem.
+- Read following files and keep their guidance in working memory:
+  - core_programming_solid.md
+  - bash_clean_architecture.md
+  - bash_clean_code.md
+  - bash_small_functions.md
+  - python_solid_architecture_enforcer.md
+  - python_clean_architecture.md/media/srv-main-softdev/projects/libs/bitranox_template_py_cli
+  - python_clean_code.md
+  - python_small_functions_style.md
+  - python_libraries_to_use.md
+  - python_structure_template.md
+  - self_documenting.md
+
+
+always apply those Rules :
+
+- core_programming_solid.md
+
+when writing or refracturing Bash scripts, apply those Rules :
+
+- core_programming_solid.md
+- bash_clean_architecture.md
+- bash_clean_code.md
+- bash_small_functions.md
+
+when writing or refracturing Python scripts, apply those Rules :
+- core_programming_solid.md
+- python_solid_architecture_enforcer.md
+- python_clean_architecture.md
+- python_clean_code.md
+- python_small_functions_style.md
+- python_libraries_to_use.md
+- python_lib_structure_template.md
+
+
+## Project Structure & Module Organization
+
+- `src/lib_cli_exit_tools/`: Python package.
+- `scripts/`: shared automation (build/test/release) reused from scaffold.
+- `packaging/`: Conda, Homebrew, and Nix specs kept in sync via scripts.
+- `tests/`: placeholder suite skipping until logging features exist.
+
+
+## Build, Test, and Development Commands
+
+- `make help` — list all targets with one‑line docs.
+- `make test` — run ruff (lint + format check), pyright, pytest with coverage (enabled by default), and upload to Codecov (if configured via `.env`).
+  - Auto‑bootstrap: `make test` installs dev tools (`pip install -e .[dev]`) if linters/test deps are missing. Use `SKIP_BOOTSTRAP=1 make test` to disable.
+  - Coverage control: `COVERAGE=on|auto|off` (default `on` locally). Uses a unique `COVERAGE_FILE` each run to avoid DB locks.
+  - Before uploading to Codecov the harness creates an allow-empty commit (`test: auto commit before Codecov upload`) so the report attaches to a revision. Reset or amend if you do not want to keep it.
+- `make build` — build Python wheel/sdist and attempt Conda/Homebrew/Nix builds (auto‑installs missing tools when needed).
+- `make push` — runs the full `scripts/test.py` flow, prompts for/accepts a commit message (or `COMMIT_MESSAGE`), creates an allow-empty commit if needed, then pushes to the selected remote.
+- `make clean` — remove caches, coverage, and build artifacts (includes `dist/` and `build/`).
+
+### Versioning & Releases
+
+- Single source of truth for the package version is `pyproject.toml` (`[project].version`).
+- Runtime code reads metadata via `importlib.metadata`; do not duplicate the version in code files.
+- On a version bump, update only `pyproject.toml` and the `CHANGELOG.md` entry; do not edit `src/lib_cli_exit_tools/__init__conf__.py` for versioning.
+- Tag releases `vX.Y.Z` and push tags; CI will build artifacts and publish when configured.
+
+### Common Make Targets (Alphabetical)
+
+
+| Target            | One-line description                                                           |
+|-------------------|--------------------------------------------------------------------------------|
+| `build`           | Build wheel/sdist and attempt Conda/Brew/Nix builds (auto-installs tools).     |
+| `bump`            | Bump version (VERSION=X.Y.Z or PART=major\|minor\|patch) and update changelog. |
+| `bump-major`      | Increment major version ((X+1).0.0).                                           |
+| `bump-minor`      | Increment minor version (X.Y.Z → X.(Y+1).0).                                   |
+| `bump-patch`      | Increment patch version (X.Y.Z → X.Y.(Z+1)).                                   |
+| `clean`           | Remove caches, coverage, and build artifacts (includes `dist/` and `build/`).  |
+| `dev`             | Install package with dev extras.                                               |
+| `help`            | Show this table.                                                               |
+| `install`         | Editable install.                                                              |
+| `menu`            | Interactive TUI menu (make menu).                                              |
+| `push`            | Commit changes once and push to GitHub (no CI monitoring).                     |
+| `release`         | Tag vX.Y.Z, push, sync packaging, run gh release if available.                 |
+| `run`             | Run module entry (`python -m ... --help`).                                     |
+| `test`            | Lint, format, type-check, run tests with coverage, upload to Codecov.          |
+| `version-current` | Print current version from `pyproject.toml`.                                   |
+
+
+## Coding Style & Naming Conventions
+
+## Testing Guidelines
+
+- Unit and integration-style tests live under `tests/`; keep them up to date when adding features.
+- Extend coverage for new CLI or library behaviour (the suite exercises CLI commands, package metadata, and automation scripts).
+- When adding functionality, replace or remove placeholders and ensure `make test` remains green.
+- write good doctests which clearly show how the function works and what are the intensions. Use it as an enhancement of the inline documentation
+
+## Commit & Pull Request Guidelines
+
+## Architecture Overview
+  - apply python_clean_architecture.md
+
+## Security & Configuration Tips
+- `.env` is only for local tooling (CodeCov tokens, etc.); do not commit secrets.
+- Rich logging should sanitize payloads before rendering once implemented.
+
+## Translations (Docs)
+
+## Translations (App UI Strings)
+
+## Changes in WEB Documentation
+
+- when asked to update documentation - only do that in the english docs under /website/docs because other languages will be translated automatically,
+  unless stated otherwise by the user. In doubt - ask the user
+
+## Changes in APP Strings
+
+- when i18 strings are changed, only to that in sources/\_locales/en because other languages will be translated automatically,
+  unless stated otherwise by the user. In doubt - ask the user
+
+## commit/push/GitHub policy
+
+- run "make test" before any push to avoid lint/test breakage.
+- after push, monitor errors in the github actions and try to correct the errors
+
+## Jupyter Notebooks
+use at least nbformat >=4.5 
+ - "nbformat": 4,
+ - "nbformat_minor": 5
+
+---
+
+# 📘 Documentation Review & Enhancement Prompt
+
+You are a **senior software developer specializing in code documentation and system design clarity**. Your task is to review, correct, and enhance all documentation (external and inline) across the codebase with the following principles and workflow.
+
+---
+
+## **Principles**
+
+* Documentation should emphasize **WHY** and **WHAT**, not just **HOW**.
+* All docs must align with the system’s design-level documentation in `docs/systemdesign/*`.
+* Every module, function, dataclass, and constant should be documented with clear intent, expected use, and system relevance.
+* Documentation must be **authoritative, consistent, and actionable** for developers, maintainers, and system designers.
+
+---
+
+## **Workflow Checklist**
+
+### **Step 1 – System Alignment**
+
+* [ ] For every feature, function, configuration, dataclass, and constant:
+
+  * [ ] Verify alignment with `docs/systemdesign/*`.
+  * [ ] Document it in `docs/systemdesign/module_reference.md` using the template in `systemprompts/self_documenting.md`.
+  * [ ] Ensure consistent terminology and style with system docs.
+
+---
+
+### **Step 2 – Module-Level Documentation**
+
+* [ ] At the top of each module, create or update a **header block** that:
+
+  * [ ] States the **purpose and intention** of the module.
+  * [ ] Outlines its **contents** (functions, classes, constants).
+  * [ ] Explains how it connects to the **overall system design**.
+
+---
+
+### **Step 3 – Function Documentation**
+
+For every function:
+
+* [ ] Document **Why** it exists (its role in the system).
+* [ ] Document **What** it does (conceptual description).
+* [ ] Document **Inputs** (parameters, types, ranges, meaning).
+* [ ] Document **Outputs** (return values, meaning, edge cases).
+* [ ] Document **Side Effects** (state changes, I/O, mutations).
+* [ ] Add or refine **doctests** that:
+
+  * [ ] Demonstrate common use cases.
+  * [ ] Cover edge cases.
+  * [ ] Illustrate not just mechanics but **intent**.
+
+---
+
+### **Step 4 – Dataclasses & Structures**
+
+* [ ] For each dataclass:
+
+  * [ ] Document each field’s **expected value and type**.
+  * [ ] Explain **why the field exists**.
+  * [ ] Describe how it interacts with other parts of the system.
+
+---
+
+### **Step 5 – Constants & Magic Numbers**
+
+* [ ] For each constant or magic number:
+
+  * [ ] Explain **what it represents**.
+  * [ ] Explain **why this value was chosen**.
+  * [ ] Reference relevant standards, business rules, or domain logic.
+  * [ ] Replace unexplained “magic numbers” with named constants if possible.
+
+---
+
+### **Step 6 – Corrections & Enhancements**
+
+* [ ] Remove or rewrite **obsolete documentation**.
+* [ ] Correct **inaccurate or unclear explanations**.
+* [ ] Fill in **missing documentation**.
+* [ ] Reframe overly technical notes to emphasize **intent and reasoning**.
+
+---
+
+## ✅ Definition of Done (DoD)
+
+Documentation is considered **complete and high quality** when:
+
+1. **System Consistency**: Every documented element aligns with `docs/systemdesign/*` and is included in `docs/systemdesign/module_reference.md`.
+2. **Module Headers**: Each module has a clear header block with purpose, contents, and system role.
+3. **Function Docs**: Every function has complete, accurate, and intent-driven documentation, including doctests for clarity and correctness.
+4. **Dataclass Docs**: Every dataclass field is fully described with expected type, purpose, and relevance.
+5. **Constants**: Every constant or magic number has a clear explanation or has been replaced with a meaningful named constant.
+6. **Corrections**: All obsolete, unclear, or incorrect docs have been fixed.
+7. **Completeness**: No feature, function, configuration, dataclass, or constant is left undocumented.
+8. **Clarity**: Documentation emphasizes **WHY** and **WHAT**, making the codebase understandable without digging into implementation details.
+
+---

{lib_cli_exit_tools-1.0.3 → lib_cli_exit_tools-1.1.1}/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## [1.1.1] - 2025-09-18
+
+- Documentation and doctest updates
+
+## [1.1.0] - 2025-09-16
+
+- introduced lib_cli_exit_tools.run_cli helper to reduce boilerplate code. see cli.py as example
+
 ## [1.0.3] - 2025-09-16
 
 - added make menu

lib_cli_exit_tools-1.0.3/README.md → lib_cli_exit_tools-1.1.1/DEVELOPMENT.md

@@ -1,102 +1,8 @@
-# lib_cli_exit_tools
+# Development Guide
 
-<!-- Badges -->
-[![CI](https://github.com/bitranox/lib_cli_exit_tools/actions/workflows/ci.yml/badge.svg)](https://github.com/bitranox/lib_cli_exit_tools/actions/workflows/ci.yml)
-[![CodeQL](https://github.com/bitranox/lib_cli_exit_tools/actions/workflows/codeql.yml/badge.svg)](https://github.com/bitranox/lib_cli_exit_tools/actions/workflows/codeql.yml)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
-[![Jupyter](https://img.shields.io/badge/Jupyter-Launch-orange?logo=jupyter)](https://mybinder.org/v2/gh/bitranox/lib_cli_exit_tools/HEAD?labpath=notebooks%2FQuickstart.ipynb)
-[![PyPI](https://img.shields.io/pypi/v/lib_cli_exit_tools.svg)](https://pypi.org/project/lib_cli_exit_tools/)
-[![PyPI - Downloads](https://img.shields.io/pypi/dm/lib_cli_exit_tools.svg)](https://pypi.org/project/lib_cli_exit_tools/)
-[![Code Style: Ruff](https://img.shields.io/badge/Code%20Style-Ruff-46A3FF?logo=ruff&labelColor=000)](https://docs.astral.sh/ruff/)
-[![codecov](https://codecov.io/gh/bitranox/lib_cli_exit_tools/graph/badge.svg?token=z1D8JSjWEH)](https://codecov.io/gh/bitranox/lib_cli_exit_tools)
-[![Maintainability](https://qlty.sh/gh/bitranox/projects/lib_cli_exit_tools/maintainability.svg)](https://qlty.sh/gh/bitranox/projects/lib_cli_exit_tools)
-[![Known Vulnerabilities](https://snyk.io/test/github/bitranox/lib_cli_exit_tools/badge.svg)](https://snyk.io/test/github/bitranox/lib_cli_exit_tools)
+This guide aggregates everything maintainers need for building, testing, and releasing `lib_cli_exit_tools`.
 
-Small helpers for robust CLI exit handling:
-- Portable signal handling (SIGINT, SIGTERM/SIGBREAK)
-- Consistent exception → exit code mapping
-- Concise error printing with optional traceback and subprocess stdout/stderr capture
-
-## Install
-
-Pick one of the options below. All methods register the `lib_cli_exit_tools` and `cli-exit-tools` commands on your PATH.
-
-### 1) Standard virtualenv (pip)
-
-```bash
-python -m venv .venv
-source .venv/bin/activate  # Windows: .venv\\Scripts\\activate
-pip install -e .[dev]       # dev install
-# or for runtime only:
-pip install .
-```
-
-### 2) Per-user (no venv)
-
-```bash
-pip install --user .
-```
-
-Note: respects PEP 668; avoid on system Python if “externally managed”. Ensure `~/.local/bin` (POSIX) is on PATH.
-
-### 3) pipx (isolated, recommended for end users)
-
-```bash
-pipx install .
-pipx upgrade lib_cli_exit_tools
-# From Git tag/commit:
-pipx install "git+https://github.com/bitranox/lib_cli_exit_tools@v0.1.0"
-```
-
-### 4) uv (fast installer/runner)
-
-```bash
-uv pip install -e .[dev]
-uv tool install .
-uvx lib_cli_exit_tools --help
-```
-
-### 5) From artifacts
-
-```bash
-python -m build
-pip install dist/lib_cli_exit_tools-*.whl
-pip install dist/lib_cli_exit_tools-*.tar.gz   # sdist
-```
-
-### 6) Poetry / PDM (project-managed envs)
-
-```bash
-# Poetry
-poetry add lib_cli_exit_tools     # as dependency
-poetry install                    # for local dev
-
-# PDM
-pdm add lib_cli_exit_tools
-pdm install
-```
-
-### 7) From Git via pip (CI-friendly)
-
-```bash
-pip install "git+https://github.com/bitranox/lib_cli_exit_tools@v0.1.0#egg=lib_cli_exit_tools"
-```
-
-### 8) Conda/mamba (optional)
-
-```bash
-mamba create -n cli-exit python=3.12 pip
-mamba activate cli-exit
-pip install .
-```
-
-### 9) System package managers (optional distribution)
-
-- Homebrew formula (macOS): `brew install lib_cli_exit_tools` (if published)
-- Nix: flake/package for reproducible installs
-- Deb/RPM via `fpm` for OS-native packages
-
-### Make Targets
+## Make Targets
 
 | Target            | Description                                                                                |
 |-------------------|--------------------------------------------------------------------------------------------|
@@ -115,54 +21,43 @@ pip install .
 | `build`           | Build wheel/sdist and attempt conda, brew, and nix builds (auto-installs tools if missing) |
 | `menu`            | Interactive TUI to run targets and edit parameters (requires dev dep: textual)             |
 
-#### Target Parameters (env vars)
+### Target Parameters (env vars)
 
 - Global
   - `PY` (default: `python3`) — Python interpreter used to run scripts
   - `PIP` (default: `pip`) — pip executable used by bootstrap/install
-
 - `install`
   - No specific parameters (respects `PY`, `PIP`).
-
 - `dev`
   - No specific parameters (respects `PY`, `PIP`).
-
 - `test`
   - `COVERAGE=on|auto|off` (default: `on`) — controls pytest coverage run and Codecov upload
   - `SKIP_BOOTSTRAP=1` — skip auto-install of dev tools if missing
   - `TEST_VERBOSE=1` — echo each command executed by the test harness
   - Also respects `CODECOV_TOKEN` when needed for uploads
-
 - `run`
   - No parameters via `make` (always shows `--help`). For custom args: `python scripts/run_cli.py -- <args>`.
-
 - `version-current`
   - No parameters
-
 - `bump`
   - `VERSION=X.Y.Z` — explicit target version
   - `PART=major|minor|patch` — semantic part to bump (default if `VERSION` not set: `patch`)
   - Examples:
     - `make bump VERSION=1.0.2`
     - `make bump PART=minor`
-
 - `bump-patch` / `bump-minor` / `bump-major`
   - No parameters; shorthand for `make bump PART=...`
-
 - `clean`
   - No parameters
-
 - `push`
   - `REMOTE=<name>` (default: `origin`) — git remote to push to
-
 - `build`
   - No parameters via `make`. Advanced: use the script directly, e.g. `python scripts/build.py --no-conda --no-nix`.
-
 - `release`
   - `REMOTE=<name>` (default: `origin`) — git remote to push to
   - Advanced (via script): `python scripts/release.py --retries 5 --retry-wait 3.0`
 
-### Interactive Menu (Textual)
+## Interactive Menu (Textual)
 
 `make menu` launches a colorful terminal UI (powered by `textual`) to browse targets, edit parameters, and run them with live output.
 
@@ -178,7 +73,7 @@ Run the menu:
 make menu
 ```
 
-#### Target Details
+### Target Details
 
 - `test`: single entry point for local CI — runs ruff lint + format check, pyright, pytest (including doctests) with coverage (enabled by default), and uploads coverage to Codecov if configured (reads `.env`).
 - Auto‑bootstrap: `make test` will try to install dev tools (`pip install -e .[dev]`) if `ruff`/`pyright`/`pytest` are missing. Set `SKIP_BOOTSTRAP=1` to skip this behavior.
@@ -189,57 +84,7 @@ make menu
 - `pipx-*` and `uv-*`: isolated CLI installations for end users and fast developer tooling.
 - `which-cmd`/`verify-install`: quick diagnostics to ensure the command is on PATH.
 
-## Usage
-
-Console script:
-
-```bash
-# After install (pip/pipx/uv tool)
-lib_cli_exit_tools --help
-cli-exit-tools --help  # alias
-lib_cli_exit_tools info
-```
-
-Library:
-
-```python
-import lib_cli_exit_tools
-
-lib_cli_exit_tools.config.traceback = False  # show short messages
-try:
-    raise FileNotFoundError("missing.txt")
-except Exception as e:
-    code = lib_cli_exit_tools.get_system_exit_code(e)   # 2 on POSIX
-    lib_cli_exit_tools.print_exception_message()        # prints: FileNotFoundError: missing.txt
-    raise SystemExit(code)
-```
-
-Command names registered on install
-- lib_cli_exit_tools (default)
-- cli-exit-tools (alias)
-- python -m lib_cli_exit_tools (module entry)
-
-If you installed with --user or in a venv, make sure the corresponding bin directory is on PATH:
-- Linux/macOS venv: .venv/bin
-- Linux/macOS user: ~/.local/bin
-- Windows venv: .venv\Scripts
-- Windows user: %APPDATA%\Python\PythonXY\Scripts
-
-## Exit Codes
-
-- SIGINT → 130, SIGTERM → 143 (POSIX), SIGBREAK → 149 (Windows)
-- SystemExit(n) → n
-- Common exceptions map to POSIX/Windows codes (FileNotFoundError, PermissionError, ValueError, etc.)
-
-### Broken pipe behavior
-- Default: exit 141 quietly (128+SIGPIPE), no noisy error output.
-- Configure: `config.broken_pipe_exit_code = 0` to treat as benign truncation, or `32` (EPIPE).
-
-### Sysexits mode (optional)
-- Set `config.exit_code_style = "sysexits"` to map ValueError/TypeError → EX_USAGE(64),
-  FileNotFoundError → EX_NOINPUT(66), PermissionError → EX_NOPERM(77), generic OSError → EX_IOERR(74).
-
-## Development
+## Testing & Coverage
 
 ```bash
 make test                 # ruff + pyright + pytest + coverage (default ON)
@@ -248,15 +93,19 @@ COVERAGE=off make test       # disable coverage locally
 COVERAGE=on make test        # force coverage and generate coverage.xml/codecov.xml
 ```
 
-### Packaging sync (Conda/Brew/Nix)
+### Local Codecov uploads
+
+- `make test` (with coverage enabled) generates `coverage.xml` and `codecov.xml`, then attempts to upload via the Codecov CLI or the bash uploader.
+- For private repos, set `CODECOV_TOKEN` (see `.env.example`) or export it in your shell.
+- For public repos, a token is typically not required.
+
+## Packaging Sync (Conda/Brew/Nix)
 
 - `make test` and `make push` automatically align the packaging skeletons in `packaging/` with the current `pyproject.toml`:
   - Conda: updates `{% set version = "X.Y.Z" %}` and both `python >=X.Y` constraints to match `requires-python`.
   - Homebrew: updates the source URL tag to `vX.Y.Z` and sets `depends_on "python@X.Y"` to match `requires-python`.
   - Nix: updates the package `version`, example `rev = "vX.Y.Z"`, and switches `pkgs.pythonXYZPackages` / `pkgs.pythonXYZ` to match the minimum Python version from `requires-python`.
-
 - To run just the sync without bumping versions: `python scripts/bump_version.py --sync-packaging`.
-
 - On release tags (`v*.*.*`), CI validates that packaging files are consistent with `pyproject.toml` and will fail if they drift.
 
 ## Versioning & Metadata
@@ -285,18 +134,8 @@ GitHub Actions workflows are included:
 
 To publish a release:
 1. Bump `pyproject.toml` version and update `CHANGELOG.md`.
-2. Tag the commit (`git tag v0.1.1 && git push --tags`).
+2. Tag the commit (`git tag v1.1.0 && git push --tags`).
 3. Ensure `PYPI_API_TOKEN` secret is configured in the repo.
 4. Release workflow uploads wheel/sdist to PyPI.
 
 Conda/Homebrew/Nix: use files in `packaging/` to submit to their ecosystems. CI also attempts builds to validate recipes, but does not publish automatically.
-
-### Local Codecov uploads
-
-- `make test` (with coverage enabled) generates `coverage.xml` and `codecov.xml`, then attempts to upload via the Codecov CLI or the bash uploader.
-- For private repos, set `CODECOV_TOKEN` (see `.env.example`) or export it in your shell.
-- For public repos, a token is typically not required.
-
-## License
-
-MIT