fireaid 0.1.0__py3-none-any.whl

fireaid/__init__.py

@@ -0,0 +1,400 @@
+"""
+fireaid
+=======
+
+A transparent wrapper around Google Python Fire that rounds off its
+command-line help syntax.
+
+Instead of:
+
+    import fire
+
+use:
+
+    import fireaid as fire
+
+Existing code can continue to use:
+
+    fire.Fire(...)
+
+and attributes exposed by the original ``fire`` package remain available.
+
+Fire itself accepts:
+
+    tool foo -- --help
+    tool foo --help
+    tool foo -h
+
+fireaid additionally accepts Git-style help:
+
+    tool help
+    tool help foo
+    tool help foo bar
+
+and makes ``--help`` and ``-h`` print the help text to stdout, without
+Fire's INFO banner or pager, including for functions that take ``**kwargs``.
+
+An incomplete command, such as plain ``tool``, prints Fire's usage text
+and exits with an error, where Fire shows the full help as a success.
+"""
+
+from __future__ import annotations
+
+import inspect
+import shlex
+import sys
+from collections.abc import Sequence
+from importlib import metadata as _metadata
+from typing import Any
+
+import fire as _fire
+
+__all__ = ["Fire"]
+
+_HELP = ["--", "--help"]
+_FLAGS = ("-h", "--help")
+_NOT_CALLED = ("Initial component", "Instantiated class", "Accessed property")
+_NAMED = (inspect.Parameter.POSITIONAL_OR_KEYWORD, inspect.Parameter.KEYWORD_ONLY)
+
+
+def _member(component: Any, name: str) -> tuple[bool, Any]:
+    """
+    Look up a member the way Fire does: by name, then with ``-`` as ``_``.
+    """
+    for key in (name, name.replace("-", "_")):
+        if isinstance(component, dict):
+            if key in component:
+                return True, component[key]
+        else:
+            try:
+                return True, getattr(component, key)
+            except Exception:
+                pass
+    return False, None
+
+
+def _resolve(component: Any, path: Sequence[str]) -> tuple[Any, bool]:
+    """
+    Follow ``path`` from ``component`` as far as it names members.
+
+    Returns the component reached and whether it is known to be the
+    target of the command. It is when the whole path was followed, or
+    when a function was reached, since the rest are then its arguments.
+    Members that only exist on an instance cannot be followed; the class
+    is returned as not known to be the target.
+    """
+    for name in path:
+        if inspect.isroutine(component):
+            return component, True
+        found, member = _member(component, name)
+        if not found:
+            return component, False
+        component = member
+    return component, True
+
+
+def _accepts(target: Any, flag: str) -> bool:
+    """
+    Tell whether Fire would pass ``flag`` to ``target`` as an argument.
+
+    ``--help`` is an argument of a callable with a ``help`` parameter.
+    ``-h`` is Fire's shortcut for any parameter starting with ``h``.
+    """
+    if not (inspect.isclass(target) or inspect.isroutine(target)):
+        return False
+    try:
+        parameters = inspect.signature(target).parameters.values()
+    except (TypeError, ValueError):
+        return False
+    names = [p.name for p in parameters if p.kind in _NAMED]
+    if flag == "--help":
+        return "help" in names
+    return any(name.startswith("h") for name in names)
+
+
+def _normalize_help(argv: Sequence[str], component: Any, ours: bool) -> list[str]:
+    """
+    Translate conventional help syntax into Python Fire's native syntax.
+
+    Examples:
+
+        --help
+            -> -- --help
+
+        foo --help
+            -> foo -- --help
+
+        foo -h
+            -> foo -- --help
+
+        help
+            -> -- --help
+
+        help foo bar
+            -> foo bar -- --help
+
+    If an explicit ``--`` separator is already present, the command is
+    assumed to use native Fire syntax and is left untouched.
+
+    ``help`` is only interpreted as the first word, and only if it is
+    ``ours``: the component is not a function and has no ``help`` member
+    of its own. ``help --help`` is help for the help command itself.
+
+    ``-h`` and ``--help`` are only interpreted as the last word, and
+    only if the command they follow does not take them as an argument.
+    Where that command cannot be determined, ``-h`` is left to Fire.
+    """
+    argv = list(argv)
+
+    if not argv or "--" in argv:
+        return argv
+
+    flag = argv[-1]
+
+    if argv[0] == "help" and ours:
+        if flag not in _FLAGS:
+            return argv[1:] + _HELP
+        if len(argv) > 2 or not _member(component, "help")[0]:
+            return argv[1:-1] + _HELP
+
+    if flag not in _FLAGS:
+        return argv
+
+    target, known = _resolve(component, argv[:-1])
+    if _accepts(target, flag) or (flag == "-h" and not known):
+        return argv
+    return argv[:-1] + _HELP
+
+
+def _help_command(component: Any, name: Any) -> tuple[Any, Any]:
+    """
+    Make the help command of a component, as a function and as a method.
+
+    Command lines starting with ``help`` are translated before Fire sees
+    them, so this is mostly there for Fire to list with the component's
+    other commands. It is what runs if Fire is given the command in its
+    native syntax.
+    """
+
+    def help(*command):
+        """Show help for the program, or for a command.
+
+        Args:
+            command: The command to show help for, as it would be run.
+        """
+        words = [str(word) for word in command]
+        return _fire_with(_display_stdout, component, command=words + _HELP, name=name)
+
+    def method(self, *command):
+        return help(*command)
+
+    method.__name__ = help.__name__
+    method.__doc__ = help.__doc__
+    return help, method
+
+
+def _add_help(component: Any, name: Any = None) -> tuple[Any, Any]:
+    """
+    Give a component a help command.
+
+    Returns the component to pass to Fire, and a function to undo it.
+    A dict gets a copy with the command added. A module gets it as an
+    attribute, and anything else as a method of its class, for as long
+    as Fire runs. A component that cannot take one is returned as it is.
+    """
+    help, method = _help_command(component, name)
+    if isinstance(component, dict):
+        return dict(component, help=help), None
+    if inspect.ismodule(component):
+        owner, member = component, help
+    elif inspect.isclass(component):
+        owner, member = component, method
+    else:
+        owner, member = type(component), method
+    try:
+        setattr(owner, "help", member)
+    except (AttributeError, TypeError):
+        return component, None
+    return component, lambda: delattr(owner, "help")
+
+
+def _display_stdout(lines: Sequence[str], out: Any = None) -> None:
+    """
+    Stand in for fire.core.Display, printing to stdout instead of stderr,
+    and not through a pager.
+    """
+    sys.stdout.write("\n".join(lines) + "\n")
+
+
+def _display_unpaged(lines: Sequence[str], out: Any) -> None:
+    """
+    Stand in for fire.core.Display, paging only what Fire sends to stderr.
+
+    What Fire sends to stdout is the text for a command line that names
+    a group rather than a command. Its native help goes to stderr.
+    """
+    if out is sys.stdout:
+        _display_stdout(lines)
+    else:
+        _display(lines, out=out)
+
+
+def _called(trace: Any) -> bool:
+    """
+    Tell whether the last step of a Fire trace was a function call.
+
+    If the trace does not say, assume so, which leaves things to Fire.
+    """
+    try:
+        action = trace.elements[-1]._action
+    except (AttributeError, IndexError):
+        return True
+    return action not in _NOT_CALLED
+
+
+class _HelpText:
+    """
+    Stand in for the fire.helptext module, as fire.core sees it.
+
+    Fire prints the full help for a command line that names a group
+    rather than a command, and calls it a success. This makes it the
+    usage text, and keeps the trace, for the caller to call it an error.
+
+    Fire prints the same for an object returned by a function. That is
+    left alone: the command was complete.
+    """
+
+    def __init__(self) -> None:
+        self.incomplete = None
+
+    def __getattr__(self, name: str) -> Any:
+        return getattr(_helptext, name)
+
+    def HelpText(self, component: Any, trace: Any = None, verbose: bool = False) -> str:
+        if trace is None or trace.show_help or trace.HasError() or _called(trace):
+            return _helptext.HelpText(component, trace=trace, verbose=verbose)
+        self.incomplete = trace
+        return _helptext.UsageText(component, trace=trace, verbose=verbose)
+
+
+_display = getattr(_fire.core, "Display", None)
+_helptext = getattr(_fire.core, "helptext", None)
+
+# Obtain the signature from the installed Fire version instead of
+# duplicating it here. This makes fireaid less dependent on Fire's
+# particular API version.
+_FIRE_SIGNATURE = inspect.signature(_fire.Fire)
+
+
+def Fire(*args: Any, **kwargs: Any) -> Any:
+    """
+    Call fire.Fire(), adding conventional command-line help handling.
+
+    All arguments other than ``component`` and ``command`` are passed
+    through unchanged. The command, by default taken from sys.argv, is
+    normalized first, making this work:
+
+        fire.Fire(MyCLI, command=["foo", "--help"])
+        fire.Fire(MyCLI, command="help foo")
+    """
+    bound = _FIRE_SIGNATURE.bind_partial(*args, **kwargs)
+    arguments = bound.arguments
+
+    if arguments.get("component") is None:
+        # Fire would look at its caller, which is this function. Supply
+        # the context of our own caller instead.
+        frame = sys._getframe(1)
+        arguments["component"] = {**frame.f_globals, **frame.f_locals}
+
+    command = arguments.get("command")
+    if command is None:
+        command = sys.argv[1:]
+    elif isinstance(command, str):
+        command = shlex.split(command)
+
+    if not isinstance(command, (list, tuple)):
+        # Not a valid command. Let Fire report it.
+        return _fire.Fire(*bound.args, **bound.kwargs)
+
+    component = arguments["component"]
+    ours = not (inspect.isroutine(component) or _member(component, "help")[0])
+    undo = None
+    if ours:
+        arguments["component"], undo = _add_help(component, arguments.get("name"))
+
+    try:
+        arguments["command"] = _normalize_help(command, arguments["component"], ours)
+        if arguments["command"] == list(command):
+            display = _display_unpaged
+        else:
+            # Help was asked for in conventional syntax: it belongs on stdout.
+            display = _display_stdout
+        return _fire_with(display, *bound.args, **bound.kwargs)
+    finally:
+        if undo is not None:
+            undo()
+
+
+def _fire_with(display: Any, *args: Any, **kwargs: Any) -> Any:
+    """
+    Call fire.Fire() with a stand-in for its display of help.
+    """
+    if _display is None or _helptext is None:
+        return _fire.Fire(*args, **kwargs)
+
+    helptext = _HelpText()
+    _fire.core.helptext = helptext
+    _fire.core.Display = display
+    try:
+        result = _fire.Fire(*args, **kwargs)
+    finally:
+        _fire.core.Display = _display
+        _fire.core.helptext = _helptext
+
+    if helptext.incomplete is not None:
+        # Fire has printed the usage in place of a result.
+        raise _fire.core.FireExit(2, helptext.incomplete)
+    return result
+
+
+# Make introspection of fireaid.Fire look like fire.Fire rather than
+# showing the wrapper's (*args, **kwargs) implementation.
+Fire.__signature__ = _FIRE_SIGNATURE
+Fire.__wrapped__ = _fire.Fire
+Fire.__doc__ = _fire.Fire.__doc__
+
+
+def __getattr__(name: str) -> Any:
+    """
+    Proxy attributes not defined by fireaid to the real fire package.
+
+    Examples:
+
+        fireaid.core
+        fireaid.decorators
+        fireaid.inspectutils
+        fireaid.trace
+    """
+    return getattr(_fire, name)
+
+
+def __dir__() -> list[str]:
+    """
+    Return the combined namespace of fireaid and the wrapped fire module.
+    """
+    return sorted(set(globals()) | set(dir(_fire)))
+
+
+# Make the submodules Fire has loaded importable under our name too:
+#
+#     import fireaid.core
+#     from fireaid.core import FireExit
+#
+for _name, _module in list(sys.modules.items()):
+    if _name.startswith("fire.") and not _name.endswith("__main__"):
+        sys.modules.setdefault(__name__ + _name[len("fire"):], _module)
+
+try:
+    __version__ = _metadata.version("fireaid")
+except _metadata.PackageNotFoundError:
+    __version__ = "unknown"

fireaid/__main__.py

@@ -0,0 +1,28 @@
+"""
+Enables ``python -m fireaid [module] [arg] ...``, like ``python -m fire``.
+"""
+
+import sys
+
+import fireaid
+
+try:
+    from fire.__main__ import import_module
+except ImportError:
+    import_module = None
+
+
+def main(args):
+    if import_module is None:
+        sys.exit("python -m fireaid requires a Fire version with python -m fire")
+
+    if len(args) < 2:
+        print("usage: python -m fireaid [module] [arg] ...")
+        sys.exit(1)
+
+    module, module_name = import_module(args[1])
+    fireaid.Fire(module, name=module_name, command=args[2:])
+
+
+if __name__ == "__main__":
+    main(sys.argv)

fireaid-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,7 @@
+fireaid/__init__.py,sha256=GwBnKkdldgFtZb3RVn0tFbrngkbp7MAkG6EYsI_NkA4,12150
+fireaid/__main__.py,sha256=2UpNfCNbPU0vQqTMGsafsOcyPLqajcAd3bW1CvDwDdE,599
+fireaid-0.1.0.dist-info/licenses/LICENSE,sha256=J_uMfTQ0iAQ7TPxSa2X8EshsnriTEFCGZR9V5qUA-qA,1075
+fireaid-0.1.0.dist-info/METADATA,sha256=bp61sQVuPxZNgdK2Hn9lc3FGSRp7uJxmKzeqf3Yx6-Q,4956
+fireaid-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+fireaid-0.1.0.dist-info/top_level.txt,sha256=65JX_jgamkJKwojn8qXQDY0vqq-ch4gUVbOgnCjiOzk,8
+fireaid-0.1.0.dist-info/RECORD,,

fireaid-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

fireaid-0.1.0.dist-info/licenses/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.dist-info/top_level.txt

@@ -0,0 +1 @@
+fireaid