Metadata-Version: 2.1
Name: qwikfire
Version: 0.1.3
Summary: Decorate class methods with shell commands
Home-page: https://github.com/akarasulu/qwikfire
Author: Alex O. Karasulu
Author-email: akarasulu@gmail.com
Requires-Python: >=3.11,<4.0
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Dist: sh (>=2.1.0,<3.0.0)
Project-URL: Documentation, https://akarasulu.github.io/qwikfire/
Project-URL: Repository, https://github.com/akarasulu/qwikfire
Description-Content-Type: text/markdown

# qwikfire

[![Release](https://img.shields.io/github/v/release/akarasulu/qwikfire)](https://img.shields.io/github/v/release/akarasulu/qwikfire)
[![Build status](https://img.shields.io/github/actions/workflow/status/akarasulu/qwikfire/main.yml?branch=main)](https://github.com/akarasulu/qwikfire/actions/workflows/main.yml?query=branch%3Amain)
[![codecov](https://codecov.io/gh/akarasulu/qwikfire/branch/main/graph/badge.svg)](https://codecov.io/gh/akarasulu/qwikfire)
[![Commit activity](https://img.shields.io/github/commit-activity/m/akarasulu/qwikfire)](https://img.shields.io/github/commit-activity/m/akarasulu/qwikfire)
[![License](https://img.shields.io/github/license/akarasulu/qwikfire)](https://img.shields.io/github/license/akarasulu/qwikfire)

Decorate class methods with one or more shell commands

QwikFire allows users to annotate class methods with a list of shell commands. The decorator does not execute these commands but injects an extra (hidden) QwikFire argument into the annotated method's argument list right after `self`. The method implementation can use the `qf` handle to execute all commands in the annotation using a one-liner: `qf.run()`.

An brief example should clearly demonstrate the benefits of using the @qwikfire annotation to keep your python code clean and easy to read. The annotation executes two echo commands one after the other using Jinja style variable substitution. If an exception were to occur it will be caught, wrapped within a user defined, domain specific WrappingException which extends QwikFireException, and re-raised:

```python
  class WrappingException(QwikFireException):
    pass

  class MyAnnotatedClass:
    ...
    @qwikfire(WrappingException, "echo {{hello_var}}", "echo {{world_var}}")
    def many_twovars(self, qf: QwikFire) -> str:
      return qf.run(self, hello_var="hello", world_var="world").stripped

  ...
  # invoking the method without the (hidden) QwikFire argument
  instance.many_twovars()
```

Callers do not include the injected hidden QwikFire argument intended for the implementation to use. Notice that no warnings arise with callers missing the QwikFire argument: i.e. `instance.many_twovars()`.

The example above, demonstrates how almost all the boilerplate for try / except blocks,
conditional checks, logging, etc, is gone. Reading and understanding what commands the
method executes and what exceptions it raises makes the annotation self documenting.

QwikFire and its annotation is properly typed preventing Python typing tools (i.e pyright,
pyre, mypy) from needlessly littering your code with complaint's. This is a common problem
with decorators that inject additional parameters since the signature of the definition
differs from the signature of callers. Overall the code is much more readable while the
pattern results in pythonic OO code when chaining method outputs to other method inputs.

sh package kwargs (see https://sh.readthedocs.io/en/latest/sections/special_arguments.html#)
can be used in the run() method. They're prefixed with `_`, and are passed through to the
`sh.Command`. If the class whose methods are annotated, exposes a dictionary accessor method
called `sh_defaults(self, method: Caller[..., Any])`, the values of the dictionary it returns
are used for defaults both for variable substitutions and for pass-through arguments to the
`sh.Command`. NOTE: the method is provided to, if needed, tailor defaults to specific class
methods. Method specific kwarg key pairs provided to the run method override these defaults.

### Why?

Even with the glorious [sh package](https://sh.readthedocs.io/en/latest/), I still
find myself writing boilerplate code, logging, error handling and raising higher level
(wrapper) exceptions specific to the domain of the package or application using sh. Even
though sh does a great job minimizing the boilerplate, it still clutters my code, and
reduces its readability. Other code maintainers will still need to know about `sh` and
how I used it.

NOTE: Piped commands do **NOT** work. Use output chaining of one annotated method as
input into another, if needed as a one off. Multiple semi-colon separated commands in the
same string, i.e. "echo {{hello_var}}; echo {{world_var}}" will **NOT** work, just use
separate commands in the variadic string commands array.

If you find you need these or other shell features you're probably over doing it. Write an
actual shell script and execute that instead, or directly use the `sh package` in your code.
QwikFire is purposefully meant to be simple and there to prevent the occasional shell command
from cluttering up your code.

- **Github repository**: <https://github.com/akarasulu/qwikfire/>
- **Documentation** <https://akarasulu.github.io/qwikfire/>

---

