Python Water

Fork of 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]
• Type-safe codebase. All source code passes the ty type checker and uses maximized 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.

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]
• Python Water is a helpful tool for developing and debugging Python code. [2]
• Python Water helps with exploring existing code or turning other people's code into a CLI. [3]
• Python Water makes transitioning between Bash and Python easier. [4]
• 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]

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:
functions, classes, modules, objects, dictionaries, lists, tuples, etc. They all work!

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

import water

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

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

Then, from the command line, you can run:

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.

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:

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.

For additional examples, see The Python Water Guide.

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.

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	def foo(x: int)	Water casts CLI args to annotated types.
Custom types	water.register_type_constructor(T, fn)	Define how CLI args become type T.
Example	python examples/type_casting.py	Full working example.

Using a CLI	Command	Notes
Help	command --help or command -- --help
REPL	command -- --interactive	Enters interactive mode.
Separator	command -- --separator=X	Sets the separator to X. Default is -.
Completion	command -- --completion [shell]	Generates a completion script for the CLI.
Trace	command -- --trace	Gets a Water trace for the command.
Verbose	command -- --verbose

Note that these flags are separated from the Water command by an isolated --.

License

Licensed under the Apache 2.0 License.

Disclaimer

This is not an official Google product.