Command-line parsing library for Python 3.

Copyright 2021 by Larry Hastings

Quickstart

import appeal
import sys

app = appeal.Appeal()

@app.command()
def hello(name):
    print(f"Hello, {name}!")

app.main()

Here's a simple fgrep utility:

import appeal
import sys

app = appeal.Appeal()

@app.command()
def fgrep(pattern, *files, ignore_case=False):
    if not files:
        files = ['-']
    print_file = len(files) > 1
    if ignore_case:
        pattern = pattern.lower()
    for file in files:
        if file == "-":
            f = sys.stdin
        else:
            f = open(file, "rt")
        for line in f:
            if ignore_case:
                match = pattern in line.lower()
            else:
                match = pattern in line
            if match:
                if print_file:
                    print(file + ": ", end="")
                print(line.rstrip())
        if file != "-":
            f.close()


if __name__ == "__main__":
    app.main()

Overview

Appeal is a command-line argument processing library for Python, like argparse, optparse, getopt, click, and docopt. But Appeal takes a refreshing new approach.

Other libraries have complicated, cumbersome interfaces that force you to repeat yourself over and over. Appeal leverages Python's rich function call interface, which makes defining your command-line interface effortless. You write Python functions, and Appeal translates them into command-line options and arguments.

Appeal provides amazing power and flexibility--but it's also intuitive, because it mirrors Python itself. If you understand how to write Python functions, you're already halfway to understanding Appeal!

A New And Appealing Approach

Appeal isn't like other command-line parsing libraries. In fact, you really shouldn't think of Appeal as a "command-line parsing library" per se. And, although you work with Appeal by defining functions, nor should you think of these functions as "callbacks".

Appeal lets you design APIs callable from the command-line. It's just like any other Python library API--except that the caller calls you from the command-line instead of from Python. Appeal is the mechanism converting between these two domains: it translates your API into command-line semantics, then translates the user's command-line back into calls to your API.

This raises another good point: the API you build using Appeal also often makes for a very nice automation API, allowing your program to also be used as a library by other programs with minimal effort.

Basics

Taxonomy

Let's start by establishing the terminology we'll use for command-lines, based on command-line idioms established by POSIX and by popular programs. Here's a sample command-line, illustrating all the various types of things you might ever see:

% ./mygit.py --debug add --flag ro -v -xz myfile.txt
  ^          ^       ^   ^      ^  ^  ^   ^
  |          |       |   |      |  |  |   |
  |          |       |   |      |  |  |   argument
  |          |       |   |      |  |  |
  |          |       |   |      |  |  multiple short options
  |          |       |   |      |  |
  |          |       |   |      |  short option
  |          |       |   |      |
  |          |       |   |      oparg
  |          |       |   |
  |          |       |   long option
  |          |       |
  |          |       command
  |          |
  |          global long option
  |
  program name

Command-lines are a sequence of strings separated by whitespace. The meaning of each string can depend both on the position of the string and the characters in the string itself.

An argument is any whitespace-delimited string on the command-line that doesn't start with a - (minus sign). Unless it's an oparg--which we'll talk about in a minute--the meaning of an argument is defined by its position. For example, if you ran:

fgrep WM_CREATE window.c

WM_CREATE and window.c would be arguments; the first argument, WM_CREATE, would be the string you wanted to search for, and window.c would be the name of the file you wanted to search.

A command is a special kind of argument some programs use to specify what function you want the program to perform. A good example of a program that uses commands is "git"; when you run "git add" or "git commit", "add" and "commit" are both commands. The command is always the first argument to a program that uses them.

If a string on the command-line starts with a - (minus sign), that's an option. There are two styles of option: short options and long options.

Short options start with a single dash, -. This is followed by one or more individual characters, which are the short option strings. In the above example, we specify two sets of short options: the first is -v, the second is -xz. Here You can combine options togther, and it's the same as specifying them separately. We could have said -vxz, or -v -x -z. These all mean the same thing. When we talk about short options, we say it with the dash; -v would be pronounced "dash v".

Long options start with two dashes, --. Everything after the two dashes is the name of the option. In the above example, we can see one long option, --flag. Again, when we talk about long options, we say the dashes out loud, like --flag would be pronounced "dash dash flag".

Both types of options can optionally take one (or more) arguments of their own. An argument to an option is called an oparg. In the above example, the long option --flag takes the oparg ro.

Finally, there are global options and command options. Global options apply to the entire program, are always available, and are specified before the command. Command options are command-specific, and appear after the command. Global options can be long options or short options; command options can be long options or short options, too.

Remapping Python To The Command-Line

Now let's consider a Python function call:

def fgrep(pattern, filename, *, ignore_case=False):
    ...

We can draw some similarities between Python function calls and command-lines.

For example, they both support arguments where position is significant. A command-line argument is similar to a Python function positional parameter, in that they're both identified by position.

Python function calls and command-lines also both support arguments identified by name. A command-line option is similar to a Python keyword-only argument.

This leads us to the fundamental concept behind Appeal. With Appeal, you write a Python function, and tell Appeal that it represents a command. Appeal examines the function, translating its parameters into command-line features. Positional parameters become command-line arguments, and keyword-only parameters become options.

(Technically, Appeal translates both positional parameters and positional-or-keyword parameters into arguments. For the sake of clarity and consiseness, I'll always refer to these collectively as positional parameters.)

Our First Example

In all our examples, we're going to work with a script called mygit.py. The first version looks like this:

import appeal
app = appeal.Appeal()

@app.command()
def hello(name):
    print(f"Hello, {name}!")

app.main()

If you now ran python3 mygit.py help hello, you'd see usage information for your hello command. It'd start like this:

usage: mygit.py hello name

Already, a lot has happened! Let's go over it piece by piece:

We created an Appeal object called app. This object will handle processing the command-line and calling your function.
We decorated a function with @app.command(), a method call on our Appeal object. This tells Appeal that the function should be a command, using the name of the function as the command string, and translating the function's parameters into the command-line parameters. So our command is called hello. We call a function decorated with @app.command() a command function.
Our hello() command function takes one positional parameters, name. Therefore, our hello command on the command-line takes one positional argument, which we identify as name in the usage string.
Appeal also automatically created simple help for our program, displaying usage information. Usage shows you what command-line options and arguments the command will accept.

So! If you ran this command at the command-line:

% python3 mygit.py hello world

Appeal would call your hello() function like this:

hello('world')

The return value from your command function is the return code for your program. If you return None or 0, that's considered success; returning a non-zero integer indicates failure. (And if your function exits without a return statement, Python behaves as if your function ended with return None.)

Default Values And `*args`

Let's change up our example, and add an optional parameter:

import appeal
app = appeal.Appeal()

@app.command()
def fgrep(pattern, filename=None):
    print(f"fgrep {pattern} {filename}")

app.main()

Now filename is optional, with a default value of None.

You can call mygit.py fgrep with both parameters. Running this:

% python3 mygit.py fgrep WM_CREATE window.c

results in Appeal calling your fgrep() function like this:

fgrep('WM_CREATE', 'window.c')

But you can also omit the filename parameter. If you run this command at the command-line:

% python3 mygit.py fgrep WM_CREATE

Appeal would call fgrep() like this:

fgrep('WM_CREATE', None)

Actually that's not 100% accurate. When Appeal builds the arguments to call your fgrep() function, it only passes in the arguments you passed in on the command-line. So actually Appeal calls your fgrep() function like this:

fgrep('WM_CREATE')

And it's Python that sets the filename parameter to None.

What else can Appeal command functions do? Well, they can have a *args parameter. Naturally, a command function that takes *args (internally called a var_positional parameter) can accept as many positional arguments as the user wants to supply. Here's a demonstration:

import appeal
app = appeal.Appeal()

@app.command()
def fgrep(pattern, *filenames):
    print(f"fgrep {pattern} {filenames}")

app.main()

Now the user could pass in no filenames, one filename, fifty filenames--as many as they want! They'd all be collected in a tuple and passed in to fgrep() in the filenames parameter.

Options, Opargs, And Keyword-Only Parameters

Now let's examine what Appeal does with keyword-only parameters. Let's add three keyword-only parameters to our example:

import appeal
app = appeal.Appeal()

@app.command()
def fgrep(pattern, *filenames, color="", number=0, ignore_case=False):
    print(f"fgrep {pattern} {filenames} {color!r} {number} {ignore_case}")

app.main()

Now the fgrep command-line usage looks like this:

usage: mygit.py fgrep [-c|--color str] [-n|--number int] [-i|--ignore_case] pattern [str]...

Again, a lot just happened.

First, I'll remind you, keyword-only parameters are presented as options on the command-line. Appeal automatically took each keyword-only parameter, added '--' to the front of the parameter name, and turned that into an option. (Also, if the parameter name has any underscores, Appeal turns those into dashes.)

Second, options are always optional. (As a pedantic wag might put it--"the clue's right there in the name.") Therefore, in Appeal, keyword-only parameters to command functions must always have a default value. (Python programmers usually have default values for their keyword-only parameters anyway, so this requirement isn't a big deal.)

Third, Appeal automatically uses the first letter of a keyword-only argument as a short option. So the color keyword-only parameter becomes both the --color and -c options. When running your program, the user can use -c or --color interchangably. The same goes for -i and --ignore_case, and for -n and --number.

Fourth, notice that --color takes an argument, or oparg. Appeal noticed that the color parameter had a default value of ""--its default value is a str. So Appeal infers that you want the user to supply an oparg to --color. If the user specifies --color on the command-line, it must be followed by an oparg, and Appeal will take the string off the command-line and pass it straight into the color parameter.

Fifth, --number also takes an oparg, but it has a default of 0. Appeal noticed that too, so --number says it wants an int. Appeal automatically converts the string from the command-line into a Python object for you, using the type of the default value. (Appeal did that for --color too, except --color just wants a str so no conversion was necessary.) When the user provides an oparg to --number on the command-line, it must be followed by an oparg; Appeal will take that oparg, pass it in to int, then take the return value from int and pass it in to the number parameter.

Finally, ignore_case has a default value of False. Boolean values for options are a special case: they don't take an oparg. All they do is negate the default value. So if the user specifies -i once on the command-line, Appeal would pass True in to the ignore_case parameter.

(By the way, a default value of None is a second special case. If a positional or keyword-only parameter has a default value of None, Appeal behaves as if the type of the default is str. It consumes an argument or oparg from the command-line and passes it in unchanged to that parameter.)

Let's put it all together! If you ran this command at the command-line:

% python3 mygit.py fgrep -i --number 3 --color blue WM_CREATE window.c

Appeal would call fgrep() like this:

fgrep('WM_CREATE', 'window.c', color='blue', number=3, ignore_case=True)

And if you ran this command at the command-line:

% python3 mygit.py fgrep --color green boogaloo

Appeal would call fgrep() like this:

fgrep('boogaloo', color='green')

The Global Command, Subcommands, And The Default Command

Many programs that support "commands" also have "global options". Global options are options specified on the command-line before the command. For example, in the example command-line at the top of this document, mygit.py takes a --debug option specified before the command--which makes it a "global option".

Appeal supports global options too. It's simple: just write a command function like normal, but instead of decorating it with command(), decorate it with global_command(). Appeal will process all those options before command, and call your global command function.

On the flip side of this coin, Appeal also supports subcommands. This is often supported by command-line parsing libraries, though it's rarely-used in practice. The idea is, your command can itself be followed by another command.

To add a subcommand to your Appeal instance, just decorate your command function with two chained command calls, specifying the name of the existing command in the first call, like so:

@app.command()
def db(...):
    ...

@app.command("db").command()
def deploy(...):
    ...

This adds a deploy subcommand under the db command. You call it from the command-line like so:

mygit.py [global arguments and options] db [db arguments and options] deploy [deploy arguments and options]

Finally, what should Appeal do if your program takes commands, but the user doesn't supply one? That's what the default command is for. The default command is a command function Appeal will run for you if your Appeal instance has commands, and the user doesn't supply one. For example, if mygit.py has tend different commands, but the user just runs

mygit.py

without any arguments, Appeal would run the default command.

If you don't specify a default command, Appeal has a built-in default default command. The default default command raises a usage error which prints basic help information.

To specify your own default command, just decorate a command function with the Appeal.default_command() decorator. For example, if you wanted your program to run the status command when the user didn't specify a command, you could do this:

@app.default_command()
def default():
    return status()

Notice that the default command doesn't take any arguments or options. It simply can't accept any, by definition.

(If the user specified options without a command, they'd be considered "global options" and would be processed by the global command. And if the user specified an argument, that would automatically be the name of the command to run.)

And yes, subcommands can have a default command too:

@app.command('db').default_command()
def db_default():
    return db_status()

Annotations And Introspection

Python 3 supports annotations for function parameters, meant to conceptually represent types. Appeal supports annotations too; they explicitly tell Appeal what type of object a parameter wants. For example:

import appeal
app = appeal.Appeal()

@app.command()
def fgrep(pattern, *filenames, id:float=None):
    print(f"fgrep {pattern} {filenames} {id}")

app.main()

Here id has a default value of None, but it also has an explicit annotation of float. If the user uses --id on the command-line, it must be followed by an oparg, which Appeal will convert to a float. (So the annotation and the type of the default don't necessarily have to agree... although it's usually a good idea.)

Here's how Appeal decides on the converter for a parameter, from highest-priority to lowest-priority:

If the signature for that parameter has an annotation, Appeal uses the annotation as the converter.
If the signature for that parameter doesn't have an annotation, but does have a default value, Appeal will use type(default) as the converter in most cases. The exceptions:
- If type(default) is NoneType, Appeal will use str instead.
- If type(default) is bool, and the parameter is a keyword-only parameter, Appeal will use a special internal class that provides the special-case "negate the default" behavior for options with boolean default values.
If the signature for that parameter lacks both an annotation and a default value, Appeal uses str as the converter.

Although annotations are meant to represent types, Appeal actually accepts any callable--it can be a type, or a user-defined class, or just a regular function. Appeal calls these annotations converters. And converters sure are powerful!

For example, Appeal will introspect the converter for a keyword-only parameter and map all its positional arguments into opargs. That's how Appeal supports options that take multiple opargs: you simply annotate the keyword-only parameter with a converter that takes multiple arguments. Appeal will also pay attention to the annotations for the converter's own arguments, and use those to convert the strings from the command-line into Python objects.

Let's tie it all together with another example:

import appeal
app = appeal.Appeal()

def int_and_float(integer: int, real: float):
    return [integer*3, real*5]

@app.command()
def fgrep(pattern, *filenames, position:int_and_float=(0, 0.0)):
    print(f"fgrep {pattern} {filenames} {position}")

app.main()

Here, Appeal would introspect fgrep(), then also introspect int_and_float(). The resulting usage string would now look like this:

usage: mygit.py fgrep [-p|--position integer real] pattern [str]...

--position takes two opargs. Appeal would call int on the first one and float on the second one. It would then call int_and_float() with those values, and the return value of int_and_float() would be passed in to the position parameter on fgrep().

So now if you ran:

% python3 mygit.py fgrep -p 2 13 funkyfresh

Appeal would call:

fgrep('funkyfresh', position=[6, 65.0])

Finally, let's change the example to demonstrate something else: although converters can be any callable, user-defined classes work fine too. And Appeal can correctly infer the type based on the default value for any type. So consider this example:

" @app.command() def fgrep(pattern, *filenames, position=IntAndFloat(0, 0.0)): print(f"fgrep {pattern} {filenames} {position}") app.main()">

import appeal
app = appeal.Appeal()

class IntAndFloat:
    def __init__(self, integer: int, real: float):
        self.integer = integer * 3
        self.real = real * 5

    def __repr__(self):
        return f"
    
     "

@app.command()
def fgrep(pattern, *filenames, position=IntAndFloat(0, 0.0)):
    print(f"fgrep {pattern} {filenames} {position}")

app.main()

This example behaves essentially the same as the previous example in this section, except the formatting of position is slightly different. But the command-line usage is exactly the same! Appeal inferred the converter for position based on the type of its default value, then introspected that type to determine how many opargs it should consume from the command-line and how to convert them.

An important note about annotations

If you use static type analysis in your project, your static type analyzer may not appreciate you using normal Python functions as annotations. Depending on the behavior of your static type analyzer, you may need to decorate your Appeal command functions and converters with @typing.no_type_check(). If you only ever use types and classes this shouldn't be necessary.

Also, Appeal doesn't understand "type hint" annotations. It expects annotations to be callables, like functions or classes or types. It should be possible to add limited support in the future.

Converter Flexibility

You can use almost any function you like as an annotation, within reason. Appeal will introspect your annotation, determine its input parameters, and call it to convert the command-line argument into the argument it passes in to your command function.

For example, what if you wanted an option that accepted a string which gets broken up based on a delimiter substring? This is a common idiom for configure scripts on UNIX-like platforms; for example, Python's own configure script supports this option:

--with-dbmliborder=db1:db2:...

Happily that's easy to do in Appeal. Just write a converter function that accepts a string, breaks it into substrings however you like, and returns the list.

Appeal provides a converter that does just that, called appeal.split() . You pass in as many delimiter strings as you want, and appeal.split() will split the command-line across all of them. (If you don't specify any delimiters, appeal.split() will split at every whitespace character.)

Specifying An Option More Than Once

One thing you might have noticed by now: the interfaces you've seen only allow Appeal to handle command-lines where an option can be specified either zero times or one time. What if you want the user to be able to specify an option three times? Or ten? That's what the MultiOption class is for. MultiOption objects are converters that allow options to be specified multiple times.

MultiOption isn't useful by itself; it's only an abstract base class. To make use of it you'll need to use a subclass--or create your own.

This time, let's start with some examples. Appeal provides three useful subclasses of MultiOption: counter, accumulator, and mapping.

First, let's look at counter. counter simply counts the number of times an option is specified on the command-line. This is a somewhat common idiom for "verbose" options; a program that supports -v to mean verbose may allow you to specify -v more than once to make it more verbose. Here's how you'd do that with Appeal:

import appeal
app = appeal.Appeal()

@app.command()
def fgrep(*, verbose:appeal.counter()=0):
    print(f"fgrep {verbose=}")

app.main()

If the user ran

% python3 mygit.py fgrep

Appeal would call

fgrep()

allowing Python to pass in the default value of 0 to verbose. And if the user ran

% python3 mygit.py fgrep -v --verbose -v

Appeal would call

fgrep(verbose=3)

accumulator handles options that take a single oparg. It remembers them all and returns them in a single array. Like so:

import appeal
app = appeal.Appeal()

@app.command()
def fgrep(*, pattern:appeal.accumulator=[]):
    print(f"fgrep {pattern=}")

app.main()

If the user ran

% python3 mygit.py fgrep --pattern three -p four --pattern fiv5

Appeal would call

fgrep(pattern=['three', 'four', 'fiv5'])

What if you don't want strings, but another type? Using crazy science magic from the future, accumulator is actually parameterized. You can say:

import appeal
app = appeal.Appeal()

@app.command()
def fgrep(*, pattern:appeal.accumulator[int]=[]):
    print(f"fgrep {pattern=}")

app.main()

and now the opargs to --id will all be converted using int.

You can even specify multiple types as arguments to the parameterized version of accumulator, separated by commas. The option will then require multiple opargs and convert them to the types specified.

mapping is like accumulator except it returns a dict instead of a list. An option annotated with mapping() consumes two positional arguments from the command-line; the first one is the key, the second one is the value. (You can also parameterize mapping the same way you parameterize accumulator, though you can only specify exactly two types.)

Of course, you can also subclass MultiOption to make your own converter classes with custom behavior. MultiOption subclasses can override these three methods:

class Option:

    def init(self, default):
        ...

    def option(self, ...):
        ...

    def render(self):
        ...

Well, actually, subclasses are required to override option() and render(). But init() is optional.

If you then specify a subclass of MultiOption as an annotation on a keyword-only parameter of an Appeal command function, several things happen:

If that option is specified one or more times on the command-line, Appeal will instantiate exactly one of these objects and call its init() method.
Every time the user specifies that option on the command-line, Appeal will call the option() method on the object.
After finishing processing the command-line, Appeal will call the render() method on the object, and pass the value it returned as the argument to that keyword-only parameter.

The most powerful part of this interface: you can redefine option() to suit your needs--it supports the same sort of polymorphism as annotations do. Appeal will introspect your option() method to determine how many opargs to consume from the command-line, and how to convert them.

Let's demonstrate all this with another example. If you want your option to take two opargs, with one being an int and the other being a float, you would define option() in your subclass as:

class MyMultiOption(appeal.MultiOption):

    def option(self, a:int, b:float):
        ....

Every time the user specified your option, it would take two opargs, and they would be converted into an int and a float before calling your option() method. It's up to you to decide how to store them, and how to render them into a single value returned by your render() method.

MultiOption is a subclass of a general Option class. Option behaves identically to MultiOption, except it only permits specifying the option once on the command-line. (Which means it will only call your option() method once.)

Data Validation

What if you want to restrict the data the user provides on the command-line? That's simple, just use a converter! Appeal provides a couple sample converters for data validation, but it's easy to write your own.

The classic example is a parameter where you can only use one of a list of values. For that, you can use Appeal's validate() converter. For example, this command restricts the direction parameter to one of six canonical directions:

import appeal
app = appeal.Appeal()

@app.command()
def go(direction:appeal.validate('up', 'down', 'left', 'right', 'forward', 'back')):
    print(f"go {direction=}")

app.main()

You can pass in an explicit type using a type= named argument to validate(); if you omit it, it uses the type of the first argument.

Appeal also has a built-in range validator called validate_range(). It takes start and stop arguments the same way Python's range() function does. Then, if the user passes in a value outside that range,

Note that validate_range() differs from Python's range() in one subtle way: values that are equal to stop are allowed.

If you prefer, you can "clamp" the value the user passed in to the range, by supplying the argument clamp=True to validate_range(). In that case, if the value the user specifies is outside the range, validate_range() will return the closest value of either start or stop.

(That's why validate_range() allows the value to be equal to stop. clamp would be annoying to use if stop itself was an illegal value--particularly if the types were floats.)

Appeal validation functions are easy to write, so if these are insufficient to your needs, it's no problem to write your own. Take a look at the implementations of validate() and validate_range() to see one way to do it!

Multiple Options For The Same Parameter

Some programs have a set of options on their command-line that are mutually exclusive. Consider this simple-minded command-line:

go [--north|--south|--east|--west]

That is, you want the user to be able to "go" in one of those four directions, but only one. How would you do that in Appeal?

Easy. You simply define multiple options that write to the same parameter. All the behavior you've seen so far is using the default way of mapping keyword-only parameters to options. But actually Appeal allows you to make your own mappings. You can map a parameter as many ways as you want, even using different converters!

To manually define your own options, use the Appeal.option() method on your Appeal instance. It's a decorator you apply to your command function. The first parameter is the name of the parameter you want the option to write to. After that is one or more options you want to map to this parameter. By default, Appeal.option() uses the default value and annotation from the parameter, but you can override those by passing in a default or annotation argument.

Here's a simple example of how to implement the above go command with Appeal:

import appeal
app = appeal.Appeal()

@app.command()
@app.option("direction", "--north", annotation=lambda: "north")
@app.option("direction", "--south", annotation=lambda: "south")
@app.option("direction", "--east",  annotation=lambda: "east")
@app.option("direction", "--west",  annotation=lambda: "west")
def go(*, direction='north'):
    print(f"go {direction=}")

app.main()

All these annotations return a string. But actually you can return any type you want--and you can even map multiple annotations that return different types to the same parameter. You can even annotate with a MultiOption to allow specifying that option multiple times!

Note that, whenever you use the option() decorator to map your own options onto a parameter, Appeal won't add its default options for that parameter. It'll only have the options you explicitly set. Which means, for example, that in the sample code above, there aren't any short options for the options we created. -n won't work, only --north.

One final thing. Your command function can accept **kwargs too. The only things that will go into it are options you create with Appeal.option(), which map to parameters that don't otherwise exist.

Recursive Converters

You already know that you can pass in a converter that takes multiple arguments, and Appeal will consume multiple arguments from the command-line to fill it. And if the arguments to that converter have annotations, Appeal will call those functions to convert the command-line argument into the type your converter wants.

But what if you did... this?

import appeal
app = appeal.Appeal()

def int_float(i: int, f: float):
    return (i, f)

def my_converter(i_f: int_float, s: str):
    return [i_f, s]

@app.command()
def recurse(a:str, b:my_converter=[(0, 0), '']):
    print(f"recurse {a=} {b=}")

app.main()

Would it surprise you to know--yes, it actually works! The my_converter() parameter i_f is a positional parameter that, itself, takes positional parameters.

Converters have actually been fully recursive this whole time. Actually this fact was hiding in plain sight: examples using int_and_float() have always been recursive, because int_and_float() has parameters annotated with int and float.

How does this work on the command-line? Appeal "flattens" the tree of converter functions into a linear series of arguments and options. In this case the usage would look like this:

recurse a [i f s]

The recurse command takes either one or four command-line arguments. That optional group of three command-line arguments has a special name in Appeal: it's an "argument group". Technically, Appeal views this command-line as taking two "argument groups": the first group is required, and consumes one command-line argument; the second group is optional, and consumes three command-line arguments.

Now let's add an option and see what changes:

import appeal
app = appeal.Appeal()

def int_float(i: int, f: float):
    return (i, f)

def my_converter(i_f: int_float, s: str, *, verbose=False):
    return [i_f, s, verbose]

@app.command()
def recurse2(a:str, b:my_converter=[(0, 0), '', False]):
    print(f"recurse2 {a=} {b=}")

app.main()

Now the usage looks like this:

recurse2 a [i [-v|--verbose] f s]

Notice: the options aren't created until after the first argument in the optional argument group. This may be surprising, but it makes total sense.

From a high conceptual level, Appeal doesn't know that you've "entered" the optional argument group until it sees the user supply the first argument for that group. So it doesn't create the options defined in that group until after the first argument.

This high conceptual level maps directly down to how Appeal calls your function. Consider, if the user runs this command:

recurse2 xyz

Appeal calls your function like so:

recurse2('xyz')

Since Appeal never called my_converter(), it can't map --verbose. It can only map --verbose once it knows it's going to call my_converter(), and that only becomes true the moment you supply that second command-line argument.

Once you do supply that second command-line argument, you have to supply three more.

recurse2 pdq 1 2 xyz

Appeal calls your function like so:

recurse2('pdq', my_converter(int('1'), float('2'), xyz))

recurse2 pdq 1 2 xyz

And if you add that --verbose flag:

recurse2 pdq 1 2 xyz -v

Appeal calls you like this:

recurse2('pdq', my_converter(int('1'), float('2'), xyz, verbose=True))

You can supply the -v or --verbose anywhere after the second parameter.

Take a look back at all the examples in this document, and consider that anywhere you specify a function or type, you can pass in nearly any callable you like.

For example, the parameterized version of mapping isn't limited just to simple types. If you used mapping[str, int_float] as the annotation for a keyword-only parameter, that option would consume three arguments on the command line: a str, an int, and a float, and the dictionary would map strings to 2-tuples of ints and floats.

Now you're starting to see how powerful Appeal's converters really are!

Now Witness The Power Of This Fully Armed And Operational Battle Station

Buckle your seatbelt, Dorothy--because Kansas is going bye-bye.

--Cypher, "The Matrix" (1999)

But recursive converters are just the beginning. What if you did... this?

import appeal
app = appeal.Appeal()

def my_converter(a: int, *, verbose=False):
    return [a, verbose]

@app.command()
def inception(*, option:my_converter=[0, False]):
    print(f"inception {option=}")

app.main()

Woah, that works too! We've created an option that itself takes an option. If you run fgrep --option, you can now also specify -v or --verbose--but only after you've specified --option.

Options that map other options

In case you're wondering: Appeal.option() must decorate the function that takes the parameter you're mapping an option to. So if you wanted to define explicit options for the verbose parameter to my_converter in the above example, you'd add Appeal.option() decorators to my_converter, not to inception. (Which means, if you use my_converter with more than one converter, they all have the same options.)

But we're just getting started! How about this:

import appeal
app = appeal.Appeal()

def my_converter(a: int, *, verbose=False):
    return [a, verbose]

@app.command()
def repetition(*args:my_converter):
    print(f"repetition {args=}")

app.main()

That works too, and I bet you're already guessing what it does. This version of weird accepts as many int arguments as the user wants to specify on the command-line, and each one can optionally take a -v or --verbose flag.

I'll give you one more example:

" @app.command() def mixin(log:Logging): print(f"mixin {log=}") app.main()">

import appeal
app = appeal.Appeal()

class Logging:
    def __init__(self, *, verbose=False, log_level='info'):
        self.verbose = verbose
        self.log_level = log_level

    def __repr__(self):
        return f"
    
     "

@app.command()
def mixin(log:Logging):
    print(f"mixin {log=}")

app.main()

Can you guess what usage for mixin looks like? (Probably!) It looks like this:

mixin [-v|--verbose] [-l|--log-level str]

Even though log is a positional parameter, it doesn't consume any positional arguments on the command-line. The logging() converter only adds options! This is what object-oriented programmers might call a "mix-in". With the logging() converter, you can add logging options to every one of your commands, without having to re-implement it each time. (Though in most cases it's probably better to add such options to a global command function.)

What's really going on here is that, from Appeal's perspective, there's no difference between a "command function" and a "converter". A command function is just a converter that happens to be mapped to a command. So anything you can do with a command function, you can do with a converter too. A converter can define options, it can be decorated with app.option() (or app.argument() which we haven't discussed), it can have accept any kind of parameter defined by Python, and any parameter can use (almost) any converter. And those converters can recursively use other converters.

Anything can be used with anything:

Converters for positional parameters can take positional parameters, or keyword-only parameters, or *args, or **kwargs.
Converters for keyword-only parameters can take positional parameters, or keyword-only parameters, or *args, or **kwargs.
Converters for *args can take positional parameters, or keyword-only parameters, or *args, or **kwargs.
Command functions can use any converter.
The global command function can use any converter.

By now you can see the expressive power Appeal gives you. Of course, you'll rarely use only a fraction of that power. But it's reassuring to know that, whatever command-line API metaphor you want to express, it's not just possible in Appeal--it's easy.

Writing Help

Appeal automatically generates usage for your command functions. But it's up to you to write the documentation explaining what those commands and arguments and options actually do.

There's very complete notes on how to write documentation in Appeal, see appeal/notes/writing.documentation.txt in the Appeal source distribution. In a nutshell, you write docstring in a particular way, and Appeal can mechanically parse them and combine them together. So you document each converter separately, and Appeal smooshes all these bits of documentation together to produce the help for your command function.

(One note: the main help for your program should be the docstring for your Appeal instance's global command.)

API Reference

Appeal(help=True, version=None, positional_argument_usage_format="{name}", default_options=default_options)

Creates a new Appeal instance.

If help is true, Appeal automatically adds help support to your program:

Adds -h and --help options that print basic help.
If your Appeal instance has any commands, automatically adds a help command (if one has not already been defined).

If version is true, it should be a string denoting the version of your program. Appeal will automatically add version support to your program:

Adds -v and --version options that prints the version string.
If your Appeal instance has any commands, automatically adds a version command (if one has not already been defined) which also prints the version string.

positional_argument_usage_format is the format string used to format positional arguments for usage. The only valid interpolations inside this string are {name}, which evaluates to the name of the parameter, and {name.upper()}, which evaluates to the upper-cased name of the parameter. So if you want your usage string to show arguments or opargs as or NAME, you can achieve that by setting positional_argument_usage_format to <{name}> or {name.upper()} respectively.

default_options is a callable, called when a keyword-only parameter for a command function or a converter doesn't have any options explicitly mapped to it. The purpose of default_options is to call Appeal.option() one or more times to create some default options for that keyword-only parameter.

The API for a default_options callable should be:

default_options(appeal, fn, parameter_name, annotation, default)

appeal is the Appeal instance.
fn is the command function or converter the parameter is defined on.
parameter_name is the name of the keyword-only parameter that does not have any explicitly defined options.
annotation is the annotation function for this parameter. This may be explicitly set on the function, or it may be inferred from the default parameter. It will never be inspect.Parameter.empty.
default is the default value for this parameter. Since Appeal requires that keyword-only parameters must always have default values, this will never be inspect.Parameter.empty.

The return value of default_options is ignored.

The default value of default_options is Appeal.default_options(), documented below.

Appeal.command(name=None)

Used as a decorator. Returns a callable that accepts a single parameter fn, which must be a callable.

Adds the callable as a command for the current Appeal instance. If name is None, the name of the command will be fn.__name__.