Skip to content

Module argumentor

Class Argumentor

Base class for building command-line interface.

Method __init__

Initialize a command-line interface builder object.

Usage

Argumentor(
    bin_name: str = "",
) -> None

Params

  • bin_name: the name of the executable (default: the executable file name)

Raises

Nothing.

Returns

None

Method add_command

Deprecation warning

Calling this method directly is deprecated since argumentor 2.1.0. You should use Argumentor.register_command instead.

Register a command to the executable's command-line interface.

Usage

Argumentor.add_command(
    command: str,
    description: str = "",
    value_type: Type[bool | str | int | list] = bool,
    value_name: str = "",
    hide: bool = False,
) -> None

Params

  • command: the command to register (typically something like foo)
  • description: a short description of the command (for help page)
  • value_type: the expected type for the value of this command (if set to bool, the value will automatically be set to True when the command is present in the user input) (default: bool)
  • value_name: then name of the expected value (to display on help page, note that this is not yet implemented and currently has no effect)
  • hide: hide this command from help page (default: False = display on help page)

Raises

  • CommandExistsException: when command is already defined
  • ValueError: when value_type is not bool, str, int or list

Returns

None

Method add_command_alias

Register an alias for an existing command.

Usage

Argumentor.add_command_alias(
    alias: str,
    command: str,
    hide: bool = False,
) -> None

Params

  • alias: the alias to register (typically something like bar)
  • command: the command to alias (e.g. foo)
  • hide: hide this alias from help page (default: False = display on help page)

Raises

  • CommandExistsException: when alias is either an existing command or an existing alias
  • CommandNotFoundException: when command is not an existing command

Returns

None

Method add_option

Deprecation warning

Calling this method directly is deprecated since argumentor 2.1.0. You should use Argumentor.register_option instead.

Register an option to the executable's command-line interface.

Usage

Argumentor.add_option(
    option: str,
    command: str = "*",
    description: str = "",
    value_type: Type[bool | str | int | list] = bool,
    default_value: bool | str | int | list | None = None,
    value_name: str = "",
    flags: Flags | None = None,
    hide: bool = False,
) -> None

Params

  • option: the option to register (typically something like --foo)
  • command: the command this option applies to (for general option, use *, which is the default)
  • description: a short description of option (for help page)
  • value_type: the expected type for the value of this option (if set to bool, the value will automatically be set to True when the option is present in the user input) (default: bool)
  • default_value: the default value of this option to use when the option is not present in the user input (default: None)
  • value_name: then name of the expected value (to display on help page, note that this is not yet implemented and currently has no effect)
  • flags: flags to apply to this option
  • hide: hide this option from help page (default: False = display on help page)

Raises

  • CommandNotFoundException: when command is neither *, nor a valid command
  • OptionExistsException: when option is already defined for command or as a general option
  • ValueError: when value_type is not bool, str, int or list, or when default_value is not a variable of the type specified in value_type

Returns

None

Method add_option_alias

Register an alias for an existing option.

Usage

Argumentor.add_option_alias(
    alias: str,
    option: str,
    command: str = "*",
    hide: bool = False,
) -> None

Params

  • alias: the alias to register (typically something like --bar)
  • option: the command to alias (e.g. --foo)
  • command: the command the option applies to (for general option, use *, which is the default)
  • hide: hide this alias from help page (default: False = display on help page)

Raises

  • OptionExistsException: when alias is either an existing option or an existing alias for command or as a general option
  • OptionNotFoundException: when option is not an existing option for command or as a general option

Returns

None

Method get_aliases

Get aliases of a given command or option.

Usage

Argumentor.get_aliases(
    arg: str,
    command: str | None = None,
    include_hidden: bool = True,
) -> Iterable[str]

Params

  • arg: the command or option to get aliases for
  • command: when arg is an option, the command the option applies to (or * if arg is a global option)
  • include_hidden: include hidden aliases (default: True)

Raises

Nothing.

Returns

Iterable[str]: an iterable containing the aliases

Method get_help

Generate help page for the command-line interface.

Usage

Argumentor.get_help(
    single_command: str = "",
    print_global_options: bool = True,
    print_all_options: bool = False,
    print_options_for_command: str = "",
    show_hidden: bool = False,
) -> str

Params

  • single_command: print only given command instead of all commands (leave empty to print all commands) (default: print all commands)
  • print_global_options: print global options (default: True)
  • print_all_options: print options for ALL commands (default: False)
  • print_options_for_command: print options available with given command (leave empty to disable) (disabled by default)
  • show_hidden: show hidden commands/options as well (default: False, i.e. hide hidden commands/options)

Raises

  • CommandNotFoundException: when single_command or print_options_for_command is not a valid command

Returns

str: a formatted help page, that can later be printed to the standard output

Method register_command

Register a command to the executable's command-line interface.

Usage

Argumentor.register_command(
    command: str,
    *aliases: str,
    description: str = "",
    value_type: Type[bool | str | int | list] = bool,
    value_name: str = "",
    hide: bool = False,
) -> None

Params

  • command: the command to register (typically something like foo)
  • *aliases: aliases to register (typically something like f or bar)
  • description: a short description of the command (for help page)
  • value_type: the expected type for the value of this command (if set to bool, the value will automatically be set to True when the command is present in the user input) (default: bool)
  • value_name: then name of the expected value (to display on help page, note that this is not yet implemented and currently has no effect)
  • hide: hide this command from help page (default: False = display on help page)

Raises

  • CommandExistsException: when command is already defined
  • ValueError: when value_type is not bool, str, int or list

Returns

None

Method register_option

Register an option to the executable's command-line interface.

Usage

Argumentor.add_option(
    option: str,
    *aliases: str,
    command: str = "*",
    description: str = "",
    value_type: Type[bool | str | int | list] = bool,
    default_value: bool | str | int | list | None = None,
    value_name: str = "",
    flags: Flags | None = None,
    hide: bool = False,
) -> None

Params

  • option: the option to register (typically something like --foo)
  • *aliases: aliases to register (typically something like -f or --bar)
  • command: the command this option applies to (for general option, use *, which is the default)
  • description: a short description of option (for help page)
  • value_type: the expected type for the value of this option (if set to bool, the value will automatically be set to True when the option is present in the user input) (default: bool)
  • default_value: the default value of this option to use when the option is not present in the user input (default: None)
  • value_name: then name of the expected value (to display on help page, note that this is not yet implemented and currently has no effect)
  • flags: flags to apply to this option
  • hide: hide this option from help page (default: False = display on help page)

Raises

  • CommandNotFoundException: when command is neither *, nor a valid command
  • OptionExistsException: when option is already defined for command or as a general option
  • ValueError: when value_type is not bool, str, int or list, or when default_value is not a variable of the type specified in value_type

Returns

None

Enum Flags

Flags that can be applied to options.

Property REQUIRED

Make given option mandatory.

Property SPECIAL

Prevent commands that expect a value from failing when given option is present. Note that if the command-line interface doesn't contain any command, SPECIAL will have no particular effect.