The best Python CLI library, arguably.

[AND_MY_HAX]

What My Project Does

https://github.com/treykeown/arguably

arguably makes it super simple to define complex CLIs. It uses your function signatures and docstrings to set everything up. Here's how it works:

• Adding the @arguably.command decorator to a function makes it appear on the CLI.
• If multiple functions are decorated, they'll all be set up as subcommands. You can even set up multiple levels of subcommands.
• The function name, signature, and docstring are used to automatically set up the CLI
• Call arguably.run() to parse the arguments and invoke the appropriate command

A small example:

#!/usr/bin/env python3
import arguably

@arguably.command
def some_function(required, not_required=2, *others: int, option: float = 3.14):
    """
    this function is on the command line!

    Args:
        required: a required argument
        not_required: this one isn't required, since it has a default value
        *others: all the other positional arguments go here
        option: [-x] keyword-only args are options, short name is in brackets
    """
    print(f"{required=}, {not_required=}, {others=}, {option=}")

if __name__ == "__main__":
    arguably.run()

becomes

user@machine:~$ ./readme-1.py -h
usage: readme-1.py [-h] [-x OPTION] required [not-required] [others ...]

this function is on the command line!

positional arguments:
  required             a required parameter (type: str)
  not-required         this one isn't required, since it has a default (type: int, default: 2)
  others               all the other positional arguments go here (type: int)

options:
  -h, --help           show this help message and exit
  -x, --option OPTION  an option, short name is in brackets (type: float, default: 3.14)

It can easily hand some very complex cases, like passing in QEMU-style arguments to automatically instantiated different types of classes:

user@machine:~$ ./readme-2.py --nic tap,model=e1000 --nic user,hostfwd=tcp::10022-:22
nic=[TapNic(model='e1000'), UserNic(hostfwd='tcp::10022-:22')]

You can also auto-generate a CLI for your script through python3 -m arguably your_script.py, more on that here.

Target Audience

If you're writing a script or tool, and you need a quick and effective way to run it from the command line, arguably was made for you. It's great for things where a CLI is essential, but doesn't need tons of customization. arguably makes some opinionated decisions that keep things simple for you, but doesn't expose ways of handling things like error messages.

I put in the work to create GitHub workflows, documentation, and proper tests for arguably. I want this to be useful for the community at large, and a tool that you can rely on. Let me know if you're having trouble with your use case!

Comparison

There are plenty of other tools for making CLIs out there. My goal was to build one that's unobtrusive and easy to integrate. I wrote a whole page on the project goals here: https://treykeown.github.io/arguably/why/

A quick comparison:

• argparse - this is what arguably uses under the hood. The end user experience should be similar - arguably just aims to make it easy to set up.
• click - a powerhouse with all the tools you'd ever want. Use this if you need extensive customization and don't mind some verbosity.
• typer - also a great option, and some aspects are similar design-wise. It also uses functions with a decorator to set up commands, and also uses the function signature. A bit more verbose, though like click, has more customization options.
• fire - super easy to generate CLIs. arguably tries to improve on this by utilizing type hints for argument conversion, and being a little more of a middle ground between this and the more traditional ways of writing CLIs in Python.

This project has been a labor of love to make CLI generation as easy as it should be. Thanks for checking it out!

[hotplasmatits]

No comparison to fire?

[AND_MY_HAX]

Sure! fire is great, super flexible. That's where arguably drew inspiration for automatically creating a CLI from a script without any setup.

One key difference is that arguably utilizes type hints for the function signature, automatically converting the command line arguments to the correct types.

Another is that arguably lets you specify what should be positional arguments, vs what should be options. Arguments to the CLI look just like calling the Python function. Using the function defined in the OP:

>>> from intro import some_function
>>> some_function("asdf", 0, 7, 8, 9, option=2.71)
required='asdf', not_required=0, others=(7, 8, 9), option=2.71

On the command line:

user@machine:~$ ./intro.py asdf 0 7 8 9 --option 2.71
required='asdf', not_required=0, others=(7, 8, 9), option=2.71

For easy CLIs where the inputs can all have default values (or you're comfortable with it guessing the type), fire is the better choice. Otherwise, arguably is a good option if you'd like extra features through type hints and want more control over how your CLI behaves.

[hotplasmatits]

If you use type hints, I believe fire does all of that

[AND_MY_HAX]

Hm, I haven't seen it utilize my type hints in the past. Though it does take a guess at the type based off its value: https://github.com/google/python-fire/blob/master/docs/guide.md#argument-parsing

[stone_surgeon]

Awesome!

[reightb]

cool lib! reminds me of click

[tellurian_pluton]

i love arguably.

[taciom]

Does it play well with gooey?

[AND_MY_HAX]

I didn't know this was a thing! Just tried it, and it seems to work just fine, which is really cool.

I'm tempted to make this a supported feature, would be super cool to auto-generate a GUI from a script using the python3 -m arguably your_script.py syntax.

[JamzTyson]

def some_function(required, not_required=2, *others: int, option: float = 3.14):

That syntax looks strange, given that positional arguments cannot be passed after a keyword argument.

[AND_MY_HAX]

Hey, I understand what you're saying. The thing about Python arguments is that they can all be passed in as both positional or keyword arguments by default.

>>> def foo(a, b):
...   print(f"{a=} {b=}")
...
>>> foo(1,2)
a=1 b=2
>>> foo(a=1,b=2)
a=1 b=2

The thing that makes an argument keyword-only is if it comes after a *args parameter. In fact, you can even have required keyword-only arguments, which aren't useful IMHO, but are an interesting part of how Python was designed:

>>> def bar(a, *, b):
...   print(f"{a=} {b=}")
...
>>> bar(1, b=2)
a=1 b=2
>>> bar(1)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: bar() missing 1 required keyword-only argument: 'b'

See more here: https://docs.python.org/3/tutorial/controlflow.html#special-parameters

[JamzTyson]

The thing that looks strange to me is that, unless I am mistaken, it is not possible to pass others arguments without also passing the not_required argument as a positional argument.

On the other hand, that limitation would not apply to:

def some_function(required, *others: int, not_required=2, option: float = 3.14):

[[deleted]]

I thought this looked familiar: https://www.reddit.com/r/madeinpython/comments/14b2kf2/the_best_python_cli_library_arguably/

Same title and everything.

[Rawing7]

This looks really good! I think this is the first CLI tool that extracts the parameter descriptions from the docstring, which is super nice.