.. DO NOT EDIT. .. THIS FILE WAS AUTOMATICALLY GENERATED BY SPHINX-GALLERY. .. TO MAKE CHANGES, EDIT THE SOURCE PYTHON FILE: .. "auto_examples/plot_e04_commands_subcommands.py" .. LINE NUMBERS ARE GIVEN BELOW. .. only:: html .. note:: :class: sphx-glr-download-link-note :ref:`Go to the end ` to download the full example code. .. rst-class:: sphx-glr-example-title .. _sphx_glr_auto_examples_plot_e04_commands_subcommands.py: Commands and Subcommands ======================== This module explains how to organize a CLI into different commands and subcommands. .. GENERATED FROM PYTHON SOURCE LINES 8-12 .. code-block:: Python from npdoc_cli import cli .. GENERATED FROM PYTHON SOURCE LINES 13-18 Commands -------- Commands can be added to the program by using the wrapper ``cli.command`` on additional functions, and adding type hinting and documentation the same way you would a program. You can do this with multiple commands. .. GENERATED FROM PYTHON SOURCE LINES 18-62 .. code-block:: Python @cli.program def program(): """ Description of program. """ pass @cli.command def hello(name: str): """ Say hello. Parameters ---------- name : str Say hello to?. """ print('hello', name) @cli.command def goodbye(name: str): """ Say goodbye. Parameters ---------- name : str Say goodbye to?. """ print('goodbye', name) cli.build() cli.print_help() print('--dispatch--') args = cli.parse_args(['hello','reader']) cli.dispatch(args) args = cli.parse_args(['goodbye','reader']) cli.dispatch(args) .. rst-class:: sphx-glr-script-out .. code-block:: none usage: program [-h] {hello,goodbye} ... Description of program. positional arguments: {hello,goodbye} command help options: -h, --help show this help message and exit --dispatch-- hello reader goodbye reader .. GENERATED FROM PYTHON SOURCE LINES 63-71 Subcommands ----------- If you want, you can got one step further and organize subcommands under any command by instead wrapping ``cli.command`` around a class, and wrapping ``cli.subcommand`` around methods you would like to expose to the interface. Use a the static method wrapper if you don't need a class instance to invoke the call. .. GENERATED FROM PYTHON SOURCE LINES 71-121 .. code-block:: Python cli.reset() @cli.program def program(): """ Description of program. """ pass @cli.command class say(): """ This is a command for saying things. """ @cli.subcommand @staticmethod def hello(name: str): """ Say hello. Parameters ---------- name : str Say hello to?. """ print('hello', name) @cli.subcommand @staticmethod def goodbye(name: str): """ Say goodbye. Parameters ---------- name : str Say goodbye to?. """ print('goodbye', name) cli.build(say()) args = cli.parse_args(['say', 'hello','reader']) cli.dispatch(args) args = cli.parse_args(['say', 'goodbye','reader']) cli.dispatch(args) .. rst-class:: sphx-glr-script-out .. code-block:: none hello reader goodbye reader .. GENERATED FROM PYTHON SOURCE LINES 122-128 Class Instances ^^^^^^^^^^^^^^^ By default, the build method will assign the class itself to call the routine when building the CLI. If your function requires an instance of the class to call the function (i.e. an instance method) then you need to pass that instance to the build call ``cli.build(inst1,inst2,...)``. .. GENERATED FROM PYTHON SOURCE LINES 128-160 .. code-block:: Python cli.reset() @cli.program def program(): """ Description of program. """ pass @cli.command class say(): """ This is a command for saying things. """ def __init__(self,name:str): self.name = name @cli.subcommand def hello(self): """ Say hello. """ print('hello', self.name) s = say('reader') cli.build(s) args = cli.parse_args(['say','hello']) cli.dispatch(args) .. rst-class:: sphx-glr-script-out .. code-block:: none hello reader .. GENERATED FROM PYTHON SOURCE LINES 161-170 Resolution Order ---------------- The :py:obj:`NumpyDocCLI` class (of which ``cli`` is an instance) delays building the CLI until ``cli.build()`` is called. You don't need to declare your programs/commands/subcommands in any particular order. By default, commands and subcommands will be added in the order they are defined. If they are spread out across modules, that will depend on the order the modules are imported. Optionally, you can change the sort setting when calling ``cli.build``. .. GENERATED FROM PYTHON SOURCE LINES 170-215 .. code-block:: Python cli.reset() @cli.command def hello(name: str): """ Say hello. Parameters ---------- name : str Say hello to?. """ print('hello', name) @cli.command def goodbye(name: str): """ Say goodbye. Parameters ---------- name : str Say goodbye to?. """ print('goodbye', name) @cli.program def program(): """ Description of program. """ pass print('-- unsorted --') cli.build() cli.print_help() print('\n-- alphabetical --') cli.build(sort = 'alphabetical') cli.print_help() .. rst-class:: sphx-glr-script-out .. code-block:: none -- unsorted -- usage: program [-h] {hello,goodbye} ... Description of program. positional arguments: {hello,goodbye} command help options: -h, --help show this help message and exit -- alphabetical -- usage: program [-h] {goodbye,hello} ... Description of program. positional arguments: {goodbye,hello} command help options: -h, --help show this help message and exit .. rst-class:: sphx-glr-timing **Total running time of the script:** (0 minutes 0.008 seconds) .. _sphx_glr_download_auto_examples_plot_e04_commands_subcommands.py: .. only:: html .. container:: sphx-glr-footer sphx-glr-footer-example .. container:: sphx-glr-download sphx-glr-download-jupyter :download:`Download Jupyter notebook: plot_e04_commands_subcommands.ipynb ` .. container:: sphx-glr-download sphx-glr-download-python :download:`Download Python source code: plot_e04_commands_subcommands.py ` .. container:: sphx-glr-download sphx-glr-download-zip :download:`Download zipped: plot_e04_commands_subcommands.zip ` .. only:: html .. rst-class:: sphx-glr-signature `Gallery generated by Sphinx-Gallery `_