Supported Types

In a file named 4-supported-types.py:

from enum import Enum

from arger import Arger
from tests.utils import _reprint


class Choice(Enum):
    one = "1. One"
    two = "2. Two"

    def __str__(self):
        """By implementing this function, one can control the enum display in the help string."""
        return self.name


arger = Arger(prog="pytest", description="App Description goes here")

container = []


@arger.add_cmd
def cmd1(
    an_int: int,
    an_str: str,
    a_tuple: tuple[str, str, str],  # nargs: 3 -> consumes 3
    a_var_tuple: tuple[str, ...],  # nargs: + -> consumes one or more
    an_enum=Choice.one,
    optional_str="",
    optional_int=0,
    optional_tpl=(),
):
    """Example function with types documented in the docstring."""
    _reprint(**locals())


@arger.add_cmd
def cmd2(
    a_list: list[int],  # nargs='*': -> captures many args
    m_opt=False,
    y_opt=False,
    my=False,
):
    """A script with three optional values.

    :param a_list: Catch all positional arguments
    :param m_opt: The m_opt helptext
    :param y_opt: The y_opt helptext
    :param my: The my helptext
    """
    _reprint(**locals())


if __name__ == "__main__":
    arger.run()

Usage

• Running without a sub-command shows help, since a sub-command is required

  $ python docs/examples/4-supported-types.py
  

• Show help message for main app

  $ python docs/examples/4-supported-types.py -h
  usage: pytest [-h] {cmd1,cmd2} ...
  
  App Description goes here
  
  options:
    -h, --help   show this help message and exit
  
  commands:
    {cmd1,cmd2}
      cmd1       Example function with types documented in the docstring.
      cmd2       A script with three optional values.
  

• Show the help message for 'cmd1' showing a variety of supported types

  $ python docs/examples/4-supported-types.py cmd1 -h
  usage: pytest cmd1 [-h] [-a {one,two}] [-o OPTIONAL_STR] [-p OPTIONAL_INT]
                     [-t [OPTIONAL_TPL ...]]
                     an_int an_str a_tuple a_tuple a_tuple
                     a_var_tuple [a_var_tuple ...]
  
  Example function with types documented in the docstring.
  
  positional arguments:
    an_int
    an_str
    a_tuple
    a_var_tuple
  
  options:
    -h, --help            show this help message and exit
    -a, --an-enum {one,two}
    -o, --optional-str OPTIONAL_STR
    -p, --optional-int OPTIONAL_INT
    -t, --optional-tpl [OPTIONAL_TPL ...]
  

• Run 'cmd1' with only required positional arguments (including tuples and variadic positional arguments)

  $ python docs/examples/4-supported-types.py cmd1 10 str1 tp1 tp2 tp3 vtp1
  a_tuple (<class 'tuple'>): ('tp1', 'tp2', 'tp3')
  a_var_tuple (<class 'tuple'>): ('vtp1',)
  an_enum (<enum 'Choice'>): one
  an_int (<class 'int'>): 10
  an_str (<class 'str'>): str1
  optional_int (<class 'int'>): 0
  optional_str (<class 'str'>):
  optional_tpl (<class 'tuple'>): ()
  

• Run 'cmd1' with both positional arguments and optional arguments (including list accumulation, enum values, and optional basic types)

  $ python docs/examples/4-supported-types.py cmd1 10 str1 tp1 tp2 tp3 vtp1 --optional-tpl otp1 otp2 --optional-tpl otp3 --optional-str ostr --optional-int 100 --an-enum two
  a_tuple (<class 'tuple'>): ('tp1', 'tp2', 'tp3')
  a_var_tuple (<class 'tuple'>): ('vtp1',)
  an_enum (<enum 'Choice'>): two
  an_int (<class 'int'>): 10
  an_str (<class 'str'>): str1
  optional_int (<class 'int'>): 100
  optional_str (<class 'str'>): ostr
  optional_tpl (<class 'tuple'>): ('otp1', 'otp2', 'otp3')
  

• Show the help message for 'cmd2' showing flags and lists

  $ python docs/examples/4-supported-types.py cmd2 -h
  usage: pytest cmd2 [-h] [-m] [-y] [--my] [a_list ...]
  
  A script with three optional values.
  
  positional arguments:
    a_list       Catch all positional arguments
  
  options:
    -h, --help   show this help message and exit
    -m, --m-opt  The m_opt helptext (default: False)
    -y, --y-opt  The y_opt helptext (default: False)
    --my         The my helptext (default: False)
  

• Run 'cmd2' passing multiple positional elements to a catch-all list

  $ python docs/examples/4-supported-types.py cmd2 10 100 1000
  a_list (<class 'list'>): [10, 100, 1000]
  m_opt (<class 'bool'>): False
  my (<class 'bool'>): False
  y_opt (<class 'bool'>): False