Defining options

Introduction

Options are additional arguments that can modify the behavior of a command. Examples include git push's --force option, as well as various --verbose, --quiet, --log-level, etc. in many popular command-line utilities. Using argumentor, it is possible to define two types of options:

• Global options, that will be available with any command (for instance, it might be a good idea to define options such as --verbose as global).
• Non-global options, that are specific to a given command (for instance, options such as --force might not need to be available with all commands, depending on what the executable does).

Options

Global options

By default, options are always registered as global. Options can be defined using the Argumentor.register_option method:

program.py

from argumentor import Argumentor

argm = Argumentor()
# this will add a GLOBAL option
argm.register_option(
    "--verbose",
    description="be more verbose",
)

Non-global options

To define options as non-global, the value of the command parameter must be modified. By default, command is set to *, which is the character used to represent any command. The example below shows how to define a non-global option:

program.py

from argumentor import Argumentor

argm = Argumentor()
argm.register_command(
    "list",
    description="list things",
)
argm.register_option(
    "--all",
    command="list",
    description="also list hidden things",
)

Aliases

As with commands, it is possible to define aliases for options as well. This is particularly useful to allow short options to be used (i.e. -v for --verbose). Option aliases can be defined using the Argumentor.register_option method. The first parameter will always be the option itself, and the following ones will be its aliases:

program.py

from argumentor import Argumentor

argm = Argumentor()
argm.register_option(
    "--verbose",
    "--verb",  # alias
    "-v",  # alias
    description="be more verbose",
)

Aliases for existing global options

Aliases can also be defined for both global and non-global existing options, using the command parameter, just like in the Argumentor.register_option method.

To define aliases, the Argumentor.add_option_alias must be used. Below is an example for global options:

program.py

from argumentor import Argumentor

argm = Argumentor()
argm.register_option(
    "--verbose",
    description="be more verbose",
)
argm.add_option_alias(
    "-v",
    "--verbose",
)

Aliases for existing non-global options

Aliases for non-global options can be defined by specifying which command the option to alias is available with.

Note

In the example below, we need to define the command parameter in the Argumentor.add_option_alias method. If we don't set it to "list", argumentor will try to create an alias for a global option (which does not exist), and will raise a CommandNotFoundException error.

program.py

from argumentor import Argumentor

argm = Argumentor()
argm.register_command(
    "list",
    description="list things",
)
argm.register_option(
    "--all",
    command="list",
    description="also list hidden things",
)
argm.add_option_alias(
    "-a",
    "--all",
    command="list",
)

Expected values

Just like commands, options (as well as their aliases) can expect different types of values. The default one is bool, which means that its value will be set to True when the option is present in the user command-line input. However, the following types are supported as well:

• bool: the default type, will be set to True if the option is present
• str: the option expects a string
• int: the option expects a positive integer
• list: the option expects one or more strings

When the Argumentor.parse() method is called, values are automatically converted to their expected type. Any problem during the conversion will raise a fatal error (ParsingError).

Below is an example of an option that expects an integer as its value:

program.py (executable)

#!/usr/bin/env python3

import sys
from argumentor import Argumentor
from argumentor.exc import ParsingError

argm = Argumentor()
argm.register_command(
    "foo",
)
argm.register_option(
    "--level",
    command="foo",
    value_type=int,
)

try:
    cmd, opts = argm.parse()
except ParsingError as err:
    print(err)
    sys.exit(1)

print("command: ", cmd)
print("options: ", opts)

Running the program above will result in:

$ ./program.py foo --level=3
command:  {'foo': True}
options:  {'--level': 3}

And with an error:

$ ./program.py foo --level="a"
error: illegal value 'a' for argument: --level

Default values

Additionally, options can have a default value (that is, when they are not present in the command-line user input). It is possible, for example, to take the example above and to modify it so that the default value of --level is 1:

program.py (executable)

#!/usr/bin/env python3

import sys
from argumentor import Argumentor
from argumentor.exc import ParsingError

argm = Argumentor()
argm.register_command(
    "foo",
)
argm.register_option(
    "--level",
    command="foo",
    value_type=int,
    default_value=1,
)

try:
    cmd, opts = argm.parse()
except ParsingError as err:
    print(err)
    sys.exit(1)

print("command: ", cmd)
print("options: ", opts)

Now, executing the program without the --level option will result in:

$ ./program.py foo
command:  {'foo': True}
options:  {'--level': 1}

Flags

Option also support different flags, that modify how argumentor's command-line parser handles them. Supported flags are:

• REQUIRED: is used to make options mandatory (i.e., the program will raise a ParsingError if the option is not present in the command-line user input).
• SPECIAL: is used to ignore missing value for commands (this allows, for instance, to use a --help option for a command that requires a list of strings).

Mandatory option

The REQUIRED flag transforms an optional option into a mandatory one. Below is an example of a mandatory option:

program.py (executable)

#!/usr/bin/env python3

import sys
from argumentor import Argumentor, Flags
from argumentor.exc import ParsingError

argm = Argumentor()
argm.register_command(
    "foo",
)
argm.register_option(
    "--config",
    command="foo",
    value_type=str,
    flags=Flags.REQUIRED,
)

try:
    cmd, opts = argm.parse()
except ParsingError as err:
    print(err)
    sys.exit(1)

print("command: ", cmd)
print("options: ", opts)

When the --config option is omitted, a ParsingError will be raised:

$ ./program.py foo
error: mandatory option was omitted: --config

Special option

The SPECIAL flag prevents a command that is missing its value from raising a ParsingError. Instead, the value of the command will be set to None (instead of failing) when any special option is present. Below is an example of a special option:

program.py (executable)

#!/usr/bin/env python3

import sys
from argumentor import Argumentor, Flags
from argumentor.exc import ParsingError

argm = Argumentor()
argm.register_command(
    "foo",
    value_type=str,
)
argm.register_option(
    "--help",
    flags=Flags.SPECIAL,
)

try:
    cmd, opts = argm.parse()
except ParsingError as err:
    print(err)
    sys.exit(1)

print("command: ", cmd)
print("options: ", opts)

If executed without any value, this will result in:

$ ./program.py foo
error: expected argument after: foo

Now with the --help special option:

$ ./program.py foo --help
command:  {'foo': None}
options:  {'--help': True}

Note

If --help didn't have the SPECIAL flag, the result would have been the same as running foo without any other argument.