Clize

5.0.2 · active · verified Sat Apr 11

Clize is a Python library that simplifies the creation of command-line interfaces (CLIs) by directly transforming Python functions into CLIs. It automatically infers CLI parameters from function signatures and generates comprehensive `--help` messages from docstrings. The library is actively maintained, with the current stable version being 5.0.2.

Warnings

breaking The `bytes` annotation (converter) now re-encodes the corresponding parameter back to bytes, changing its behavior from previous versions.
Fix: Review usage of `bytes` annotations in function parameters and adjust expectations or encoding/decoding logic if necessary.
deprecated The `convert_default` argument to `clize.parser.value_converter` is deprecated. Its functionality should now be handled via `clize.Parameter.cli_default`.
Fix: Replace `convert_default` with `clize.Parameter.cli_default` for specifying default values that are converted by CLI value converters.
gotcha Using mutable objects (e.g., lists, dictionaries) as default arguments in Python functions passed to `clize.run` can lead to unexpected shared state. Python evaluates default arguments once when the function is defined, not on each call.
Fix: Set mutable default arguments to `None` and initialize the mutable object inside the function if `None` is detected (e.g., `if my_list is None: my_list = []`).
gotcha Prior to v5.0.1, using a dictionary in the `alt=` parameter of `clize.run` did not work correctly.
Fix: Upgrade to `clize` version 5.0.1 or newer if you are using `alt=` with a dictionary to define alternate commands.

Install

pip install clize Install stable version

Imports

run
```
from clize import run
```
The primary entry point for turning a function into a command-line interface.
Parameter
```
from clize import Parameter
```
Used for advanced parameter annotations like `Parameter.cli_default`.

Quickstart

This example demonstrates how to create a simple CLI using `clize.run`. It defines a function `hello` with a positional argument `name` and a keyword-only argument `capitalize`. Running this script from the command line will automatically generate a CLI, including a `--help` message from the docstring.

from clize import run

def hello(name: str = 'world', *, capitalize: bool = False):
    """Greets the world or a specific person.

    :param name: The name to greet.
    :param capitalize: Whether to capitalize the name.
    """
    if capitalize:
        name = name.title()
    print(f"Hello, {name}!")


if __name__ == '__main__':
    run(hello)

view raw JSON →