Metadata-Version: 2.4
Name: python-water
Version: 1.0.0
Summary: A library for automatically generating command line interfaces.
Author-email: David Bieber <david810+water@gmail.com>
License: Apache-2.0
Project-URL: Homepage, https://github.com/penut-slop/python-water
Project-URL: Repository, https://github.com/penut-slop/python-water
Keywords: command,line,interface,cli,python,water,interactive,bash,tool
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Operating System :: OS Independent
Classifier: Operating System :: POSIX
Classifier: Operating System :: MacOS
Classifier: Operating System :: Unix
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: termcolor
Provides-Extra: test
Requires-Dist: setuptools<=80.9.0; extra == "test"
Requires-Dist: pip; extra == "test"
Requires-Dist: pytest<=8.4.1; extra == "test"
Requires-Dist: termcolor<3.2.0; extra == "test"
Requires-Dist: hypothesis<6.137.0; extra == "test"
Requires-Dist: levenshtein<=0.27.1; extra == "test"
Provides-Extra: dev
Requires-Dist: ruff>=0.9.0; extra == "dev"
Requires-Dist: ty>=0.0.29; extra == "dev"
Dynamic: license-file

# Python Water [![PyPI](https://img.shields.io/pypi/pyversions/python-water.svg?style=plastic)](https://github.com/penut-slop/python-water)

> **Fork of [python-fire](https://github.com/google/python-fire)**
>
> I love Fire! But I need some Water.
>
> Python Water is a fork of Google's python-fire with the following additions:
>
> - **Auto-casting from type annotations.** CLI arguments are automatically
>     cast using Python type hints. Write `def foo(count: int)` and Water
>     handles the parsing. Supports `Optional[T]`, `Union`, and custom
>     constructors via `register_type_constructor()`.
>     [[details]](docs/guide.md#type-annotations)
> - **Type-safe codebase.** All source code passes the
>     [ty](https://docs.astral.sh/ty/) type checker and uses maximized
>     [Ruff](https://docs.astral.sh/ruff/) linting (`select = ["ALL"]`).
> - **Async support.** `async` and `await` functions are natively supported.
> - **Modernized tooling.** Migrated from pylint to Ruff and updated CI
>     workflows.

_Migrating from python-fire? See the [Migration Guide](docs/migration-from-fire.md)._

_Python Water is a library for automatically generating command line interfaces
(CLIs) from absolutely any Python object._

- Python Water is a simple way to create a CLI in Python.
    [[1]](docs/benefits.md#simple-cli)
- Python Water is a helpful tool for developing and debugging Python code.
    [[2]](docs/benefits.md#debugging)
- Python Water helps with exploring existing code or turning other people's
    code into a CLI. [[3]](docs/benefits.md#exploring)
- Python Water makes transitioning between Bash and Python easier.
    [[4]](docs/benefits.md#bash)
- Python Water makes using a Python REPL easier by setting up the REPL with the
    modules and variables you'll need already imported and created.
    [[5]](docs/benefits.md#repl)

## Installation

To install Python Water with pip, run: `pip install python-water`

To install Python Water from source, first clone the repository and then run:
`pip install .`

## Basic Usage

You can call `Water` on any Python object:<br>
functions, classes, modules, objects, dictionaries, lists, tuples, etc.
They all work!

Here's an example of calling Water on a function.

```python
import water

def hello(name="World"):
  return "Hello %s!" % name

if __name__ == '__main__':
  water.Water(hello)
```

Then, from the command line, you can run:

```bash
python hello.py  # Hello World!
python hello.py --name=David  # Hello David!
python hello.py --help  # Shows usage information.
```

Here's an example of calling Water on a class.

```python
import water

class Calculator(object):
  """A simple calculator class."""

  def double(self, number):
    return 2 * number

if __name__ == '__main__':
  water.Water(Calculator)
```

Then, from the command line, you can run:

```bash
python calculator.py double 10  # 20
python calculator.py double --number=15  # 30
```

To learn how Water behaves on functions, objects, dicts, lists, etc, and to learn
about Water's other features, see the [Using a Water CLI page](docs/using-cli.md).

For additional examples, see [The Python Water Guide](docs/guide.md).

## Why is it called Water?

When you call `Water`, it flows off (executes) your command.

## Where can I learn more?

Please see [The Python Water Guide](docs/guide.md).

## Reference

| Setup   | Command              | Notes                    |
| :------ | :------------------- | :----------------------- |
| install | `pip install python-water`  | Installs water from pypi |

| Creating a CLI | Command                  | Notes                                    |
| :------------- | :----------------------- | :--------------------------------------- |
| import         | `import water`           |                                          |
| Call           | `water.Water()`          | Turns the current module into a CLI.     |
| Call           | `water.Water(component)` | Turns `component` into a CLI.            |

| Type Casting   | Command                                      | Notes                                         |
| :------------- | :------------------------------------------- | :-------------------------------------------- |
| [Auto-cast](docs/guide.md#auto-casting-from-type-annotations) | `def foo(x: int)` | Water casts CLI args to annotated types.      |
| [Custom types](docs/guide.md#custom-type-constructors) | `water.register_type_constructor(T, fn)` | Define how CLI args become type `T`.          |
| [Example](examples/type_casting.py) | `python examples/type_casting.py` | Full working example.                         |

| Using a CLI                                | Command                                 | Notes                                              |
| :----------------------------------------- | :-------------------------------------- | :------------------------------------------------- |
| [Help](docs/using-cli.md#help-flag)        | `command --help` or `command -- --help` |                                                    |
| [REPL](docs/using-cli.md#interactive-flag) | `command -- --interactive`              | Enters interactive mode.                           |
| [Separator](docs/using-cli.md#separator-flag) | `command -- --separator=X`           | Sets the separator to `X`. Default is `-`.         |
| [Completion](docs/using-cli.md#completion-flag) | `command -- --completion [shell]`  | Generates a completion script for the CLI.         |
| [Trace](docs/using-cli.md#trace-flag)      | `command -- --trace`                    | Gets a Water trace for the command.                |
| [Verbose](docs/using-cli.md#verbose-flag)  | `command -- --verbose`                  |                                                    |

_Note that these flags are separated from the Water command by an isolated `--`._

## License

Licensed under the
[Apache 2.0](https://github.com/penut-slop/python-water/blob/master/LICENSE) License.

## Disclaimer

This is not an official Google product.
