glacier

glacier is a python CLI building library for minimalists.

glacier

Installation

pip install glacier

Quick start

You only have to call glacier against the entrypoint function.

from glacier import glacier
def main(name: str, verbose: bool = False) -> None:
    pass
if __name__ == '__main__':
    glacier(main)

Then, you can see help 🍰.

quick start help

Basic Usage

CLI without subcommand

If you just call glacier to a function, it will invoke it as stand-alone CLI
(like the example in Quick start).

CLI with subcommands

You can easily construct CLI with subcommands in the following two ways.

Pass a list of functions

from glacier import glacier
def run(name: str, verbose: bool = False) -> None:
    """ Run """
    pass
def build(name: str, verbose: bool = False) -> None:
    """ Build """
    pass
def test(name: str, verbose: bool = False) -> None:
    """ Test """
    return
if __name__ == '__main__':
    glacier([run, build, test])

If you passes a lift of function, glacier constructs the CLI with subcommands whose names are the same as the declared function names.
In this example, the subcommans will be run, build, and test.

sub commands help

Pass a dictionary of functions

You can easily give the different name as the subcommand name from any declared name of the function.
Just give a dictionary (key will be a subcommand name).

from glacier import glacier
def f1(name: str, verbose: bool = False) -> None:
    pass
def f2(name: str, verbose: bool = False) -> None:
    pass
def f3(name: str, verbose: bool = False) -> None:
    pass
if __name__ == '__main__':
    glacier({
        'run': f1,
        'build': f2,
        'test': f3,
    })

This works exactly the same as the previous example.

This interface makes it very easy to build a simple CLI tool from an existing project.

Async entrypoint support

You sometimes want your async function to be a CLI entrypoint.
Only you have to do is just passing the async function as if it were sync function.

The example below combine two async functions and a sync function into CLI
with nested subcommand structure.

from glacier import glacier
async def main() -> None:
    return
def sub_1() -> None:
    return
async def sub_2() -> None:
    return
if __name__ == '__main__':
    glacier({
        'main': main,
        'sub': [
            sub_1,
            sub_2,
        ],
    })

Positional argument

If the name of function argument is underscore-prefiexed, it is understood as positional argument.

from glacier import glacier
def all_positional(_a: str, _b: str, _c: str) -> None:
    print(_a)
    print(_b)
    print(_c)
if __name__ == '__main__':
    glacier(all_positional)

The above example is invoked as follows

<command_name> <value of a> <value of b> <value of c>

Options

All other (non-underscore-prefixed) arguments are understood as options.

from glacier import glacier
def all_options(a: str, b: str, c: str) -> None:
    print(a)
    print(b)
    print(c)
if __name__ == '__main__':
    glacier(all_options)

The above example is invoked as follows

<command_name> --a <value of a> --b <value of b> --c <value of c>

Default value for optional argument

If you set the default value for function argument, it also defines the default value for CLI option.

from glacier import glacier
def default(verbose: bool = False) -> None:
    print(verbose)
if __name__ == '__main__':
    glacier(default)

The above example is invoked as follows

<command_name> # Just call without flag (`False` will be printed)

<command_name> --verbose # Call with flag (`True` will be printed)

Help with docstring

Help message for options or command itself can be provided with python docstring.

Following style of doctrings are supported

The functions with docstring below will produce the exact the same help message with fed into glacier.
(You don’t need to specify which docstring style is used 😄)

Google Style

def main_google(
    _path: str,
    name: str,
    verbose: bool = False,
) -> None:
    """
    This is my simple entry point of CLI.
    Args:
        _path: Positional argument representing the target file path.
        name: Name of this operation.
        verbose: Verbose output will be shown if set.
    """
    print(_path)
    print(name)
    print(verbose)
    return

Numpy Style

def main_numpy(
    _path: str,
    name: str,
    verbose: bool = False,
) -> None:
    """
    This is my simple entry point of CLI.
    Parameters
    ----------
    _path: str
        Positional argument representing the target file path.
    name: str
        Name of this operation.
    verbose: bool
        Verbose output will be shown if set.
    """
    print(_path)
    print(name)
    print(verbose)
    return

reStructuredText Style

def main_restructured_text(
    _path: str,
    name: str,
    verbose: bool = False,
) -> None:
    """
    This is my simple entry point of CLI.
    :param _path: Positional argument representing the target file path.
    :param name: Name of this operation.
    :param verbose: Verbose output will be shown if set.
    """
    print(_path)
    print(name)
    print(verbose)
    return

Supported types

int
str
bool
Enum
List[int]
List[str]

Note

Philosophy

This library is made for building CLI quickly especially for personal use, so the features provided by it is not rich.
If you want to build really user-friend CLI or that in production, I suggest that you use click (actually glacier uses it internally), or other full-stack CLI builing libraries.

Warnings

Please note that any destructive change (backward incompatible) can be done without any announcement.
This plugin is in a very early stage of development. Feel free to report problems or submit feature requests in Issues.

LICENSE

MIT

glacier

Installation

Quick start

Basic Usage

CLI without subcommand

CLI with subcommands

Pass a list of functions

Pass a dictionary of functions

Async entrypoint support

Positional argument

Options

Default value for optional argument

Help with docstring

Google Style

Numpy Style

reStructuredText Style

Supported types

Note

Philosophy

Warnings

Related works

LICENSE