Skip to content

fresh2dev/yapx

Repository files navigation

Yapx

The next generation of Python's Argparse.

Yapx is "Yeah, Another Argparse eXtension", a Python library for creating tools with type-safe command-line interfaces (CLIs) -- and even textual user interfaces (TUIs) -- by analyzing type-hints of functions and dataclasses.

Yeah, Another?

I intended to publish this package as simply apx, but PyPi didn't allow it, so I tacked on the y to make *yapx*. The nomenclature "Yet Another" seems demeaning considering what this package is capable of.

So, Yeah, Another Argparse eXtension 👊

Think about the repetitive steps involved in creating a command-line application.

  1. Define function(s).
  2. Define the command-line interface; i.e., build the ArgumentParser.
  3. Parse arguments.
  4. Call the appropriate function(s).

For example:

from argparse import ArgumentParser

# 1. Define function(s).
def say_hello(name: str = 'World'):
    print(f"Hello {name}")

# 2. Define the command-line interface.
parser = ArgumentParser()
parser.add_argument("--name", default="World")

# 3. Parse arguments.
parsed_args = parser.parse_args()

# 4. Call the appropriate function(s).
say_hello(name=parsed_args.name)

Yapx combines these steps into one:

import yapx

def say_hello(name: str = 'World'):
    print(f"Hello {name}")

yapx.run(say_hello)

Yapx is a superset of Python's native Argparse ArgumentParser, so you can make use of the high-level abstractions or do the low-level work you're familiar with. Either way, Yapx provides benefits including:

  • 🔒 Type-casting and validation, with or without Pydantic.
  • ❓ Automatic addition of "helpful" arguments, including --help, --help-all, --version, and most impressively --tui.
  • ❤️ Prettier help and error messages.
  • ⚡ Command-line autocompletion scripts.

Yapx is among several modern Python CLI frameworks, including Typer and Fire. Distinguishing characteristics of Yapx include:

  • 📦 No 3rd-party dependencies required (but can be opted into)
  • 🔒 Type-safe argument validation
  • 🕸️ Infinitely-nested commands
  • 📺 Display your CLI as a TUI
  • ❓ Handling of unknown arguments using *args and **kwargs
  • 💡 Most intuitive
  • 😓 Least documented

I'd appreciate a more analytical comparison between Yapx and the array of Python CLI frameworks, but that's too ambitious of a goal right now 😬

Install

pip install 'yapx[extras]'

Or, to install without 3rd-party dependencies:

pip install yapx

Use


License GitHub tag (with filter) GitHub last commit (branch) GitHub Repo stars