diff options
Diffstat (limited to 'docs/features/argument_processing.rst')
| -rw-r--r-- | docs/features/argument_processing.rst | 129 |
1 files changed, 75 insertions, 54 deletions
diff --git a/docs/features/argument_processing.rst b/docs/features/argument_processing.rst index 20ab7879..5efc83ef 100644 --- a/docs/features/argument_processing.rst +++ b/docs/features/argument_processing.rst @@ -3,21 +3,29 @@ Argument Processing =================== -``cmd2`` makes it easy to add sophisticated argument processing to your commands using the ``argparse`` python module. -``cmd2`` handles the following for you: +``cmd2`` makes it easy to add sophisticated argument processing to your +commands using the ``argparse`` python module. ``cmd2`` handles the following +for you: 1. Parsing input and quoted strings like the Unix shell -2. Parse the resulting argument list using an instance of ``argparse.ArgumentParser`` that you provide -3. Passes the resulting ``argparse.Namespace`` object to your command function. The ``Namespace`` includes the - ``Statement`` object that was created when parsing the command line. It is stored in the ``__statement__`` - attribute of the ``Namespace``. + +2. Parse the resulting argument list using an instance of + ``argparse.ArgumentParser`` that you provide + +3. Passes the resulting ``argparse.Namespace`` object to your command function. + The ``Namespace`` includes the ``Statement`` object that was created when + parsing the command line. It is stored in the ``__statement__`` attribute of + the ``Namespace``. 4. Adds the usage message from the argument parser to your command. -5. Checks if the ``-h/--help`` option is present, and if so, display the help message for the command +5. Checks if the ``-h/--help`` option is present, and if so, display the help + message for the command -These features are all provided by the ``@with_argparser`` decorator which is importable from ``cmd2``. +These features are all provided by the ``@with_argparser`` decorator which is +importable from ``cmd2``. -See the either the argprint_ or decorator_ example to learn more about how to use the various ``cmd2`` argument -processing decorators in your ``cmd2`` applications. +See the either the argprint_ or decorator_ example to learn more about how to +use the various ``cmd2`` argument processing decorators in your ``cmd2`` +applications. .. _argprint: https://github.com/python-cmd2/cmd2/blob/master/examples/arg_print.py .. _decorator: https://github.com/python-cmd2/cmd2/blob/master/examples/decorator_example.py @@ -26,7 +34,8 @@ processing decorators in your ``cmd2`` applications. Decorators provided by cmd2 for argument processing --------------------------------------------------- -``cmd2`` provides the following decorators for assisting with parsing arguments passed to commands: +``cmd2`` provides the following decorators for assisting with parsing arguments +passed to commands: .. automethod:: cmd2.cmd2.with_argument_list :noindex: @@ -35,9 +44,10 @@ Decorators provided by cmd2 for argument processing .. automethod:: cmd2.cmd2.with_argparser_and_unknown_args :noindex: -All of these decorators accept an optional **preserve_quotes** argument which defaults to ``False``. -Setting this argument to ``True`` is useful for cases where you are passing the arguments to another -command which might have its own argument parsing. +All of these decorators accept an optional **preserve_quotes** argument which +defaults to ``False``. Setting this argument to ``True`` is useful for cases +where you are passing the arguments to another command which might have its own +argument parsing. Using the argument parser decorator @@ -45,10 +55,10 @@ Using the argument parser decorator For each command in the ``cmd2`` subclass which requires argument parsing, create a unique instance of ``argparse.ArgumentParser()`` which can parse the -input appropriately for the command. Then decorate the command method with -the ``@with_argparser`` decorator, passing the argument parser as the -first parameter to the decorator. This changes the second argument to the command method, which will contain the results -of ``ArgumentParser.parse_args()``. +input appropriately for the command. Then decorate the command method with the +``@with_argparser`` decorator, passing the argument parser as the first +parameter to the decorator. This changes the second argument to the command +method, which will contain the results of ``ArgumentParser.parse_args()``. Here's what it looks like:: @@ -75,20 +85,20 @@ Here's what it looks like:: .. warning:: - It is important that each command which uses the ``@with_argparser`` decorator be passed a unique instance of a - parser. This limitation is due to bugs in CPython prior to Python 3.7 which make it impossible to make a deep copy - of an instance of a ``argparse.ArgumentParser``. + It is important that each command which uses the ``@with_argparser`` + decorator be passed a unique instance of a parser. This limitation is due + to bugs in CPython prior to Python 3.7 which make it impossible to make a + deep copy of an instance of a ``argparse.ArgumentParser``. - See the table_display_ example for a work-around that demonstrates how to create a function which returns a unique - instance of the parser you want. + See the table_display_ example for a work-around that demonstrates how to + create a function which returns a unique instance of the parser you want. .. note:: - The ``@with_argparser`` decorator sets the ``prog`` variable in - the argument parser based on the name of the method it is decorating. - This will override anything you specify in ``prog`` variable when - creating the argument parser. + The ``@with_argparser`` decorator sets the ``prog`` variable in the argument + parser based on the name of the method it is decorating. This will override + anything you specify in ``prog`` variable when creating the argument parser. .. _table_display: https://github.com/python-cmd2/cmd2/blob/master/examples/table_display.py @@ -96,9 +106,10 @@ Here's what it looks like:: Help Messages ------------- -By default, cmd2 uses the docstring of the command method when a user asks -for help on the command. When you use the ``@with_argparser`` -decorator, the docstring for the ``do_*`` method is used to set the description for the ``argparse.ArgumentParser``. +By default, cmd2 uses the docstring of the command method when a user asks for +help on the command. When you use the ``@with_argparser`` decorator, the +docstring for the ``do_*`` method is used to set the description for the +``argparse.ArgumentParser``. With this code:: @@ -116,7 +127,7 @@ With this code:: the ``help tag`` command displays: -.. code-block:: none +.. code-block:: text usage: tag [-h] tag content [content ...] @@ -130,8 +141,8 @@ the ``help tag`` command displays: -h, --help show this help message and exit -If you would prefer you can set the ``description`` while instantiating the ``argparse.ArgumentParser`` and leave the -docstring on your method empty:: +If you would prefer you can set the ``description`` while instantiating the +``argparse.ArgumentParser`` and leave the docstring on your method empty:: import argparse from cmd2 import with_argparser @@ -146,7 +157,7 @@ docstring on your method empty:: Now when the user enters ``help tag`` they see: -.. code-block:: none +.. code-block:: text usage: tag [-h] tag content [content ...] @@ -176,7 +187,7 @@ To add additional text to the end of the generated help message, use the ``epilo Which yields: -.. code-block:: none +.. code-block:: text usage: tag [-h] tag content [content ...] @@ -193,9 +204,11 @@ Which yields: .. warning:: - If a command **foo** is decorated with one of cmd2's argparse decorators, then **help_foo** will not - be invoked when ``help foo`` is called. The argparse_ module provides a rich API which can be used to - tweak every aspect of the displayed help and we encourage ``cmd2`` developers to utilize that. + If a command **foo** is decorated with one of cmd2's argparse decorators, + then **help_foo** will not be invoked when ``help foo`` is called. The + argparse_ module provides a rich API which can be used to tweak every + aspect of the displayed help and we encourage ``cmd2`` developers to + utilize that. .. _argparse: https://docs.python.org/3/library/argparse.html @@ -250,11 +263,12 @@ argument list instead of a string:: pass -Using the argument parser decorator and also receiving a list of unknown positional arguments ---------------------------------------------------------------------------------------------- +Unknown positional arguments +---------------------------- -If you want all unknown arguments to be passed to your command as a list of strings, then -decorate the command method with the ``@with_argparser_and_unknown_args`` decorator. +If you want all unknown arguments to be passed to your command as a list of +strings, then decorate the command method with the +``@with_argparser_and_unknown_args`` decorator. Here's what it looks like:: @@ -279,14 +293,17 @@ Here's what it looks like:: ... -Using custom argparse.Namespace with argument parser decorators ---------------------------------------------------------------- +Using custom argparse.Namespace +------------------------------- -In some cases, it may be necessary to write custom ``argparse`` code that is dependent on state data of your -application. To support this ability while still allowing use of the decorators, both ``@with_argparser`` and -``@with_argparser_and_unknown_args`` have an optional argument called ``ns_provider``. +In some cases, it may be necessary to write custom ``argparse`` code that is +dependent on state data of your application. To support this ability while +still allowing use of the decorators, both ``@with_argparser`` and +``@with_argparser_and_unknown_args`` have an optional argument called +``ns_provider``. -``ns_provider`` is a Callable that accepts a ``cmd2.Cmd`` object as an argument and returns an ``argparse.Namespace``:: +``ns_provider`` is a Callable that accepts a ``cmd2.Cmd`` object as an argument +and returns an ``argparse.Namespace``:: Callable[[cmd2.Cmd], argparse.Namespace] @@ -302,19 +319,23 @@ To use this function with the argparse decorators, do the following:: @with_argparser(my_parser, ns_provider=settings_ns_provider) -The Namespace is passed by the decorators to the ``argparse`` parsing functions which gives your custom code access -to the state data it needs for its parsing logic. +The Namespace is passed by the decorators to the ``argparse`` parsing functions +which gives your custom code access to the state data it needs for its parsing +logic. Sub-commands ------------ Sub-commands are supported for commands using either the ``@with_argparser`` or -``@with_argparser_and_unknown_args`` decorator. The syntax for supporting them is based on argparse sub-parsers. +``@with_argparser_and_unknown_args`` decorator. The syntax for supporting them +is based on argparse sub-parsers. -You may add multiple layers of sub-commands for your command. Cmd2 will automatically traverse and tab-complete -sub-commands for all commands using argparse. +You may add multiple layers of sub-commands for your command. Cmd2 will +automatically traverse and tab-complete sub-commands for all commands using +argparse. -See the subcommands_ and tab_autocompletion_ example to learn more about how to use sub-commands in your ``cmd2`` application. +See the subcommands_ and tab_autocompletion_ example to learn more about how to +use sub-commands in your ``cmd2`` application. .. _subcommands: https://github.com/python-cmd2/cmd2/blob/master/examples/subcommands.py .. _tab_autocompletion: https://github.com/python-cmd2/cmd2/blob/master/examples/tab_autocompletion.py |