Awesome

action_hero is a python package that helps you
write powerful command line applications using the built-in argparse library

Introduction · Quick Usage · Help & FAQ · Catalog · Development

Introduction

argparse is a python standard library module used to make command line applications. argparse provides ArgumentParser that parses user arguments and runs argparse.Actions on them.

action_hero augments argparse making it more capable by providing a large number of custom actions. For example, the FileIsWritableAction automatically verifies that file path(s) accepted as arguments are writable, even informing the user if they aren't. This saves you the trouble of doing all that work yourself. These actions can be pipelined as well. Nice, no? Browse the catalog for many such actions.

Quick Usage

1. Installation:

pip install action_hero

2. Quick Usage: Import an action and specify it when adding an argument to your parser.

from action_hero import FileIsReadableAction
...
parser.add_argument("--file", action=FileIsReadableAction)
...

3. Full Example: CLI program that counts number of lines of a file.

# examples/line_counter.py
import argparse

from action_hero import FileIsReadableAction


if __name__ == "__main__":

    # Create parser
    parser = argparse.ArgumentParser()

    # Add user argument "--file" and confirm that it will be readable
    parser.add_argument("--file", action=FileIsReadableAction)

    # Parse user arguments
    args = parser.parse_args()

    if args.file:
        # Print number of lines in file
        with open(args.file) as f:
            print("{} has {} lines".format(args.file, len(f.readlines())))
    else:
        # Print usage if no arguments were given
        parser.print_usage()

Run line_counter.py on the command line

$ ls
line_counter.py mary.md

$ python line_counter.py --file mary.md
mary.md has 39 lines

$ python line_counter.py
usage: line_counter.py [-h] [--file FILE]

$ python line_counter.py --file nofile.md
usage: line_counter.py [-h] [--file FILE]
line_counter.py: error: argument --file: File is not readable

Note: Supported Python Versions >= 3.5

Help and FAQ

Accepting action_values

There are times your action requires an additional value. For instance, when your argument accepts only filenames with md or markdown extensions. You can use the FileHasExtensionAction action for this and pass in the extensions to check for via action_values, like so —

parser.add_argument(
    "--file", 
    action=FileHasExtensionAction,
    action_values=["md", "markdown"]
)

Unless otherwise mentioned, action_values should be provided as a non-empty list of strings. e.g. action_values = ["md", "markdown"].

Pipelining multiple actions

The PipelineAction allows you to run multiple actions as a pipeline. Pass in your pipeline of actions as a list to action_values. If one of the actions you're passing in has it's own action_values, put that one as a tuple, like such: (FileHasExtensionAction, ["md", "markdown"]). Here's an example of pipelining actions for --file

1. File has extensions md or markdown
2. File exists

parser.add_argument(
    "--file", 
    action=PipelineAction, 
    action_values=[
        (FileHasExtensionAction, ["md", "markdown"]),
        FileExistsAction
    ]
)

Another helpful feature, this action provides is the order of error reporting. In the above example, if the supplied argument file did not have the markdown extensions, the error message would reflect that and exit. After the user redoes the entry with a valid filename the next action in the pipeline applies FileExistsAction which checks for existence. If the file does not exist, an error message about file not existing will be shown and exits allowing the user to try again.

Pipelining can save you a lot of manual condition checks. For example, here's how to check for an existing markdown file that is writable and empty, -

parser.add_argument(
    "--file", 
    action=PipelineAction, 
    action_values=[
        FileExistsAction, 
        (FileHasExtensionAction, ["md", "markdown"]),
        FileIsWritableAction,
        FileIsEmptyAction
    ]

Exceptions in this module

You'll come across two different exceptions in action_hero.

1. ValueError: These are intended for you, the CLI developer. You'd want to fix any underlying issue that causes them before releasing your CLI. e.g. when action_values is an empty list.

2. argparse.ArgumentError: These are intended for your CLI's users, so they might use the messages as hints to provide corrent command line options.

Not capturing user argument exceptions

argparse.ArgumentParser has a slightly unconventional approach to handling argparse.ArgumentErrors. Upon encountering one, it prints argument usage information, error and exits. I mention this, so you don't setup a try/except around parser.parse_args() to capture that exception.

In order to maintain consistency with the rest of your argparse code, exceptions in action_hero are also of type argparse.ArgumentError and causes system exit as well. More information can be found in PEP 389. Since this is expected behavior, I recommend you allow this exception and let it display usage information and exit.

Arguments accepting multiple values

Just like any other argparse.Action each action_hero.Action handles multiple values and provides relevant error messages.

FAQ

What do I need to know to use action_hero in my command line application?

Vanilla argparse knowledge should do it.

Where can I find information about argparse?

argparse is part of the Python standard library.

Is action_hero tied to the argparse module?

Yes (but technically no — any project that can use an argpoarse.Action should work as long as it handles the argparse.ArgumentError exception)

What type are the user argument exceptions?

argparse.ArgumentError{"helpful error message"}, just like any other argparse.Action.

Why re-implement actions already provided by argparse like the choices action?

In order to include them in PipelineAction.

There was no mention of humans! Does this work for humans?

Yes, it works for humans :)

Catalog

1. Special actions:

2. Path, Directory and File related actions:

3. Net & Email related actions:

4. Type related actions:

5. Range related actions:

6. Miscellaneous actions:

Footnotes

† Actions that can make changes to self.dest
‡ Actions that can make changes to disk

Development

• Feedback: Please use the github issue tracker to submit feedback and recommend ideas for new actions.
• Note: Class inheritance here is dealt with slightly unusually in order to accomodate argparse manageably.
• Formatting: PEP8 only. Please format with black using blacklinelength=79
• License: The MIT License.
• Image Attributions: Karate by Alex Auda Samora from the Noun Project

Thank you for using action_hero — @kadimisetty ⭐️✨