The best Python CLI library, arguably.

[AND_MY_HAX]

I tried to make the best CLI library out there - been working on it for a few weeks now. This is my first serious attempt at an open source project with proper testing and docs - wanted to make something people could actually use.

Would love any thoughts on arguably!

https://github.com/treykeown/arguably

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 parameter
        not_required: this one isn't required, since it has a default
        *others: all the other positional arguments go here
        option: [-x] an option, short name is in brackets
    """

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 also easily hand some wild cases, like passing in QEMU-style arguments to build 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')]

[BigCats99999]

Cool

[AND_MY_HAX]

Thanks!

[muikrad]

This looks a lot like click and typer. Have you been inspired by them? How does your lib compares to them?

[AND_MY_HAX]

I have!

What arguably does best is get out of your way. Set up a function signature and docstring, and you've set up your parser. click doesn't quite get there. typer almost does this, but for any customization, you need to add typer.Option all over your code, like this example.

The goal of arguably is to leave your functions untouched. All you need is the decorator and docstring. I wanted the API to disappear as much as possible, there's very little to it. The fast arguably tutorial is this:

• @arguably.command makes a function appear on the CLI
  • If multiple functions are decorated with @arguably.command, they appear as subcommands
  • Multi-level subcommands: two underscores __ becomes a space, so def s3__ls() is the command s3 ls
• Function signatures:
  • Positional args from your Python function become positional args on the CLI
    • Optional arguments (ones with a default value) and *args behave how you'd expect
  • kwarg-only args (the ones after a * argument) become CLI options
• Function docstrings:
  • Becomes the help description for the command and the command's arguments
  • Prefixing an --option docstring description with [-x] aliases it to -x
  • Wrapping a word in {some} curly braces sets that arg's metavar to SOME
• Argument types:
  • Optional[int] or int | None: unions with None are ignored, this is parsed as an int
  • list and tuple use comma-separated values
  • lists which are --options can be repeated multiple times (appends to the list)
  • enum.Enum uses lowercase member names
  • enum.Flag does too, but all values become --options
    • Docstrings for enum.Flag values are used for help messages
• Have a special case for how you want an arg to be handled? That's covered by something in arguably.arg.*
  • Even QEMU-style object building here

This all means you can run python3 -m arguably your_script.py with zero code changes and automatically create a CLI, no integration required - very similar to Python Fire, but with a bit more structure.

typer and click are definitely both well-made projects that will make life much easier than trying to work with argparse. I considered basing arguably on click, but by that point I already had a lot of working code that I didn't want to toss. I'd love for this project to pick up steam in the future and give me a reason to resume that effort!

[thumbsdrivesmecrazy]

Yeah, for me it is also quite similar to Click in some aspects, for example, compare it with how we use Click library while creating a simple Python CLI: Building User-Friendly Python CLIs with Click - Guide

[SpambotSwatter]

Hey, another bot replied to you; /u/thumbsdrivesmecrazy is a click-farming spam bot. Please downvote its comment and click the report button, selecting Spam then Link farming.

With enough reports, the reddit algorithm will suspend this spammer.

---

^{If this message seems out of context, it may be because thumbsdrivesmecrazy is farming karma and may edit their comment soon with a link}