fireaid 0.1.0__tar.gz

fireaid-0.1.0/LICENSE

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

fireaid-0.1.0/MANIFEST.in

@@ -0,0 +1,3 @@
+include Makefile
+recursive-include tests *.py
+recursive-include examples *.py *.sh

fireaid-0.1.0/Makefile

@@ -0,0 +1,19 @@
+PYTHON ?= python3
+VENV := .venv
+
+.PHONY: test clean
+
+# Tests run against the latest stable Fire, whatever was installed before.
+test: $(VENV)
+	$(VENV)/bin/pip install --quiet --upgrade fire
+	$(VENV)/bin/pytest
+
+$(VENV): pyproject.toml
+	$(PYTHON) -m venv $(VENV)
+	$(VENV)/bin/pip install --quiet --upgrade pip
+	$(VENV)/bin/pip install --quiet --editable ".[test]"
+	touch $(VENV)
+
+clean:
+	rm -rf $(VENV) .pytest_cache build dist src/fireaid.egg-info
+	find . -name __pycache__ -not -path "./.git/*" -prune -exec rm -rf {} +

fireaid-0.1.0/PKG-INFO

@@ -0,0 +1,164 @@
+Metadata-Version: 2.4
+Name: fireaid
+Version: 0.1.0
+Summary: Familiar help for command-line tools made with Python Fire
+Author-email: Christiane Ruetten <cr@23bit.net>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/cr/fireaid
+Project-URL: Repository, https://github.com/cr/fireaid
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fire>=0.2.0
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Dynamic: license-file
+
+# fireaid
+
+*A little help for Python Fire.*
+
+[Python Fire](https://github.com/google/python-fire) turns any Python
+function, class or module into a command-line tool with a single line
+of code. `fireaid` is a thin wrapper around it that adds the help
+conventions people know from tools like `git`: a `help` command,
+`--help` printed plainly to the terminal, and a short usage message
+when a command is incomplete. Everything else is Fire, unchanged.
+
+All you need is:
+
+    pip install git+https://github.com/cr/fireaid
+
+    import fireaid as fire
+
+    fire.Fire(MyTool)
+
+## Installation
+
+Directly from the repository:
+
+    pip install git+https://github.com/cr/fireaid
+
+As a dependency in another project's `pyproject.toml`:
+
+    dependencies = ["fireaid @ git+https://github.com/cr/fireaid"]
+
+From the project directory:
+
+    pip install .
+
+For development:
+
+    pip install -e .
+
+fireaid requires Fire 0.2.0 or later, the first version to accept
+`--help` without a separator. On Python 3.13 and later, Fire itself
+requires version 0.7.0.
+
+## Usage
+
+Change:
+
+    import fire
+
+to:
+
+    import fireaid as fire
+
+Existing code such as:
+
+    fire.Fire(MyCLI)
+
+continues to work, as do `import fireaid.core` and `python -m fireaid`.
+
+## Help
+
+Python Fire accepts:
+
+    tool foo -- --help
+    tool foo --help
+    tool foo -h
+
+fireaid additionally supports Git-style help:
+
+    tool help
+    tool help foo
+    tool help foo bar
+
+`help` is a command like any other: Fire lists it with the program's
+commands in the usage text and in the help, and `tool help help` shows
+help for it.
+To that end, fireaid adds the command to the program for as long as
+Fire runs: to its class, or to a copy if the program is a dict.
+
+With `--help` and `-h`, fireaid also
+
+- prints the help text to stdout, so that `tool --help | less` works,
+- prints it as it is, where Fire starts a pager on a terminal,
+- omits Fire's `INFO: Showing help with the command ...` banner,
+- shows help for functions taking `**kwargs`, where Fire passes
+  `help=True` to the function.
+
+Native Fire syntax continues to work unchanged, printing to stderr,
+or to a pager on a terminal.
+
+## Usage text
+
+A command line that names a group rather than a command, such as
+plain `tool`, is a success to Fire, which shows the full help for the
+group, in a pager. To fireaid it is an incomplete command, as it is to
+Git: it prints Fire's short usage text to stdout, and exits with 2,
+Fire's exit code for errors:
+
+    Usage: tool <group|command>
+      available groups:      shelf
+      available commands:    add | help | list | remove | search
+
+    For detailed information on this command, run:
+      tool --help
+
+A function that returns an object is a complete command. There, Fire
+shows the help for the object, which fireaid only keeps from the pager.
+
+`examples/pantry.py` is a small program to try all of this on, and
+`examples/tour.sh` runs through it.
+
+## Limits
+
+fireaid does not take anything away from the wrapped program:
+
+- `help` is only help as the first word, and not if the program has
+  a `help` command of its own, or is a single function.
+- `--help` and `-h` are only help as the last word. `--help` is left
+  to a command with a `help` parameter, `-h` to a command with a
+  parameter starting with `h`, for which it is Fire's shortcut.
+- A command that fireaid cannot find without running the program, such
+  as a member created in `__init__`, may have such a parameter. There,
+  `-h` is left to Fire, which shows help with its banner on stderr.
+
+Help for a command that does not exist is an error, as it is in
+Fire's native syntax.
+
+As with Fire, help is shown for what the command line evaluates to.
+`tool foo x --help` calls `foo` and shows help for its result. Ask
+for `tool foo --help` to get help for `foo`.
+
+## Tests
+
+    make test
+
+creates a virtual environment in `.venv`, upgrades it to the latest
+stable Fire, and runs the test suite. The tests hold fireaid to what
+this README says, mostly by comparing it to Fire on the same command
+lines. `make test PYTHON=python3.14` selects the Python for a new
+environment, `make clean` removes it.
+
+## Releasing
+
+Set the new `version` in `pyproject.toml`, commit, then tag and push:
+
+    git tag v0.1.0 && git push origin main v0.1.0
+
+The tag starts `.github/workflows/publish.yml`, which runs the tests,
+checks that the tag is the package version, builds, and publishes to
+PyPI as a trusted publisher. PyPI never takes the same version twice.

fireaid-0.1.0/README.md

@@ -0,0 +1,148 @@
+# fireaid
+
+*A little help for Python Fire.*
+
+[Python Fire](https://github.com/google/python-fire) turns any Python
+function, class or module into a command-line tool with a single line
+of code. `fireaid` is a thin wrapper around it that adds the help
+conventions people know from tools like `git`: a `help` command,
+`--help` printed plainly to the terminal, and a short usage message
+when a command is incomplete. Everything else is Fire, unchanged.
+
+All you need is:
+
+    pip install git+https://github.com/cr/fireaid
+
+    import fireaid as fire
+
+    fire.Fire(MyTool)
+
+## Installation
+
+Directly from the repository:
+
+    pip install git+https://github.com/cr/fireaid
+
+As a dependency in another project's `pyproject.toml`:
+
+    dependencies = ["fireaid @ git+https://github.com/cr/fireaid"]
+
+From the project directory:
+
+    pip install .
+
+For development:
+
+    pip install -e .
+
+fireaid requires Fire 0.2.0 or later, the first version to accept
+`--help` without a separator. On Python 3.13 and later, Fire itself
+requires version 0.7.0.
+
+## Usage
+
+Change:
+
+    import fire
+
+to:
+
+    import fireaid as fire
+
+Existing code such as:
+
+    fire.Fire(MyCLI)
+
+continues to work, as do `import fireaid.core` and `python -m fireaid`.
+
+## Help
+
+Python Fire accepts:
+
+    tool foo -- --help
+    tool foo --help
+    tool foo -h
+
+fireaid additionally supports Git-style help:
+
+    tool help
+    tool help foo
+    tool help foo bar
+
+`help` is a command like any other: Fire lists it with the program's
+commands in the usage text and in the help, and `tool help help` shows
+help for it.
+To that end, fireaid adds the command to the program for as long as
+Fire runs: to its class, or to a copy if the program is a dict.
+
+With `--help` and `-h`, fireaid also
+
+- prints the help text to stdout, so that `tool --help | less` works,
+- prints it as it is, where Fire starts a pager on a terminal,
+- omits Fire's `INFO: Showing help with the command ...` banner,
+- shows help for functions taking `**kwargs`, where Fire passes
+  `help=True` to the function.
+
+Native Fire syntax continues to work unchanged, printing to stderr,
+or to a pager on a terminal.
+
+## Usage text
+
+A command line that names a group rather than a command, such as
+plain `tool`, is a success to Fire, which shows the full help for the
+group, in a pager. To fireaid it is an incomplete command, as it is to
+Git: it prints Fire's short usage text to stdout, and exits with 2,
+Fire's exit code for errors:
+
+    Usage: tool <group|command>
+      available groups:      shelf
+      available commands:    add | help | list | remove | search
+
+    For detailed information on this command, run:
+      tool --help
+
+A function that returns an object is a complete command. There, Fire
+shows the help for the object, which fireaid only keeps from the pager.
+
+`examples/pantry.py` is a small program to try all of this on, and
+`examples/tour.sh` runs through it.
+
+## Limits
+
+fireaid does not take anything away from the wrapped program:
+
+- `help` is only help as the first word, and not if the program has
+  a `help` command of its own, or is a single function.
+- `--help` and `-h` are only help as the last word. `--help` is left
+  to a command with a `help` parameter, `-h` to a command with a
+  parameter starting with `h`, for which it is Fire's shortcut.
+- A command that fireaid cannot find without running the program, such
+  as a member created in `__init__`, may have such a parameter. There,
+  `-h` is left to Fire, which shows help with its banner on stderr.
+
+Help for a command that does not exist is an error, as it is in
+Fire's native syntax.
+
+As with Fire, help is shown for what the command line evaluates to.
+`tool foo x --help` calls `foo` and shows help for its result. Ask
+for `tool foo --help` to get help for `foo`.
+
+## Tests
+
+    make test
+
+creates a virtual environment in `.venv`, upgrades it to the latest
+stable Fire, and runs the test suite. The tests hold fireaid to what
+this README says, mostly by comparing it to Fire on the same command
+lines. `make test PYTHON=python3.14` selects the Python for a new
+environment, `make clean` removes it.
+
+## Releasing
+
+Set the new `version` in `pyproject.toml`, commit, then tag and push:
+
+    git tag v0.1.0 && git push origin main v0.1.0
+
+The tag starts `.github/workflows/publish.yml`, which runs the tests,
+checks that the tag is the package version, builds, and publishes to
+PyPI as a trusted publisher. PyPI never takes the same version twice.

fireaid-0.1.0/examples/pantry.py

@@ -0,0 +1,93 @@
+#!/usr/bin/env python3
+"""
+A pantry manager, to show off fireaid's help.
+
+Run examples/tour.sh to see all of the below, or try:
+
+    pantry.py --help
+    pantry.py help
+    pantry.py help add
+    pantry.py add --help
+    pantry.py shelf -h
+    pantry.py help shelf label
+    pantry.py list --help
+    pantry.py search --help
+    pantry.py search milk -h
+    pantry.py add -- --help
+"""
+
+import fireaid as fire
+
+
+class Shelf:
+    """A shelf of the pantry."""
+
+    def label(self, text):
+        """Label the shelf.
+
+        Args:
+            text: The text to write on the label.
+        """
+        return f"Shelf labelled {text!r}."
+
+    def clear(self):
+        """Take everything off the shelf."""
+        return "Shelf cleared."
+
+
+class Pantry:
+    """Keep track of what is in the pantry.
+
+    Ask for help with --help, -h or help, at any level:
+
+        pantry.py help
+        pantry.py add --help
+        pantry.py help shelf label
+    """
+
+    def __init__(self):
+        self.shelf = Shelf()
+
+    def add(self, item, quantity=1, expires=None):
+        """Put an item into the pantry.
+
+        Args:
+            item: What to put in.
+            quantity: How many of it.
+            expires: A date, or nothing for things that keep.
+        """
+        when = f", best before {expires}" if expires else ""
+        return f"Added {quantity} x {item}{when}."
+
+    def remove(self, item, quantity=1):
+        """Take an item out of the pantry."""
+        return f"Removed {quantity} x {item}."
+
+    def list(self, **filters):
+        """List the pantry, optionally filtered.
+
+        Filters are free-form, such as --shelf=top or --expired=true.
+        Fire would take --help for a filter here; fireaid shows help.
+        """
+        if filters:
+            return f"Listing items where {filters}."
+        return "Listing all items."
+
+    def search(self, pattern, hidden=False):
+        """Search the pantry.
+
+        -h is Fire's shortcut for --hidden, so 'search milk -h' searches
+        hidden items, while 'search --help' shows this help.
+
+        Args:
+            pattern: A substring of the item name.
+            hidden: Also search items hidden at the back.
+        """
+        where = "everywhere" if hidden else "in plain sight"
+        return f"Searching for {pattern!r} {where}."
+
+
+if __name__ == "__main__":
+    # An instance rather than the class: Fire then lists the commands in
+    # the top-level help, and fireaid sees members created in __init__.
+    fire.Fire(Pantry())

fireaid-0.1.0/examples/tour.sh

@@ -0,0 +1,63 @@
+#!/bin/sh
+# A tour of fireaid's help syntax, run on examples/pantry.py.
+#
+# Every command is printed before it runs. The pager is switched off so
+# that the output is plain text.
+
+cd "$(dirname "$0")" || exit 1
+export PAGER=cat
+
+demo() {
+    printf '\n$ pantry.py %s\n' "$*"
+    python3 pantry.py "$@"
+}
+
+echo '### An incomplete command gets the usage, and exit code 2'
+demo
+echo "(exit code $?)"
+demo shelf
+
+echo
+echo '### Help at the top level, three ways'
+demo --help
+demo -h
+demo help
+
+echo
+echo '### Help for a command, and Git-style help'
+demo add --help
+demo help add
+
+echo
+echo '### help is a command like any other, with help of its own'
+demo help help
+
+echo
+echo '### Help for a group and a command within it'
+demo shelf -h
+demo help shelf label
+
+echo
+echo '### Fire itself would pass --help to a **kwargs function as a filter'
+demo list --help
+
+echo
+echo '### -h stays the shortcut for a parameter starting with h'
+demo search --help
+demo search milk -h
+
+echo
+echo "### Fire's native syntax is untouched, and prints to stderr"
+printf '\n$ pantry.py add -- --help 2>/dev/null | head -3\n'
+python3 pantry.py add -- --help 2>/dev/null | head -3
+echo '(nothing, it all went to stderr)'
+
+echo
+echo '### fireaid prints help to stdout, so it can be piped'
+printf '\n$ pantry.py add --help 2>/dev/null | head -3\n'
+python3 pantry.py add --help 2>/dev/null | head -3
+
+echo
+echo '### Help after arguments is help for the result, as in Fire'
+printf '\n$ pantry.py add milk 2 --help | head -8\n'
+python3 pantry.py add milk 2 --help | head -8

fireaid-0.1.0/pyproject.toml

@@ -0,0 +1,38 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "fireaid"
+version = "0.1.0"
+description = "Familiar help for command-line tools made with Python Fire"
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+    {name = "Christiane Ruetten", email = "cr@23bit.net"}
+]
+dependencies = [
+    "fire>=0.2.0"
+]
+
+[project.optional-dependencies]
+test = [
+    "pytest"
+]
+
+[project.urls]
+Homepage = "https://github.com/cr/fireaid"
+Repository = "https://github.com/cr/fireaid"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+# Fire 0.7.1 calls a function deprecated in Python 3.14 and removed in 3.16.
+# Remove this filter once Fire has replaced it.
+filterwarnings = [
+    "ignore:'asyncio.iscoroutinefunction' is deprecated:DeprecationWarning:fire",
+]

fireaid-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+