.. DO NOT EDIT. .. THIS FILE WAS AUTOMATICALLY GENERATED BY SPHINX-GALLERY. .. TO MAKE CHANGES, EDIT THE SOURCE PYTHON FILE: .. "auto_examples/plot_e02_typing.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_e02_typing.py: Function Signatures =================== This tutorial goes over how npdoc-cli parses function signatures affect the command line interface. .. GENERATED FROM PYTHON SOURCE LINES 8-13 .. code-block:: Python from pathlib import Path from npdoc_cli import cli .. GENERATED FROM PYTHON SOURCE LINES 14-18 Type Signatures --------------- Arguments given to the command line are cast into the provided type signature. .. GENERATED FROM PYTHON SOURCE LINES 18-40 .. code-block:: Python @cli.program def hello(name: str, number: int): """ Say hello! Parameters ---------- name : str Who is being greeted. number : int Number of times to greet. """ for i in range(number): print('hello', name) cli.build() args = cli.parse_args(['reader', '3']) cli.dispatch(args) .. rst-class:: sphx-glr-script-out .. code-block:: none hello reader hello reader hello reader .. GENERATED FROM PYTHON SOURCE LINES 41-48 Booleans -------- Booleans are a special case, as simply casting any string to bool will results in ``True``. To create an optional argument with a flag that stores ``True`` or ``False``, create a keyword argument in the function signature with the default value (when the option isn't specified in the CLI). .. GENERATED FROM PYTHON SOURCE LINES 48-67 .. code-block:: Python cli.reset() @cli.program def flags(flag_false: bool = True, flag_true: bool = False): """ Parameters ---------- flag_false : bool, optional Flag a false value. flag_true : bool, optional Flag a true value """ print(flag_false) print(flag_true) cli.build() print('-- dispatch --') args = cli.parse_args(['--flag-false','--flag-true']) cli.dispatch(args) .. rst-class:: sphx-glr-script-out .. code-block:: none -- dispatch -- False True .. GENERATED FROM PYTHON SOURCE LINES 68-73 Custom Types ------------ The type casting is called as ``(argument)``, so any arbitrary type can be used in a signature provided it can be called with the raw string as an input. .. GENERATED FROM PYTHON SOURCE LINES 73-92 .. code-block:: Python cli.reset() @cli.program def show_path(path: Path): """ Parameters ---------- path : Path Path to show. """ print(path, type(path)) cli.build() args = cli.parse_args(['my/path/file.ext']) cli.dispatch(args) .. rst-class:: sphx-glr-script-out .. code-block:: none my/path/file.ext .. GENERATED FROM PYTHON SOURCE LINES 93-94 You can define your own types or use functions to parse the string. .. GENERATED FROM PYTHON SOURCE LINES 94-126 .. code-block:: Python cli.reset() def hello(string): return 'hello ' + string class my_int(): def __init__(self, string): self.val = int(string) @cli.program def show_path(string: hello, count: my_int): """ Parameters ---------- string : hello hello to who? count : my_int hello how many times? """ for i in range(count.val): print(string) cli.build() args = cli.parse_args(['reader', '3']) cli.dispatch(args) .. rst-class:: sphx-glr-script-out .. code-block:: none hello reader hello reader hello reader .. GENERATED FROM PYTHON SOURCE LINES 127-132 Positional and Optional arguments --------------------------------- By default, positional arguments in the function signature are turned into positional arguments in the CLI. Keyword arguments are turned into optional arguments in the in the CLI .. GENERATED FROM PYTHON SOURCE LINES 132-150 .. code-block:: Python cli.reset() @cli.program def hello(name: str, number: int = 1): """ Parameters ---------- name : str Who is being greeted. number : int Number of times to greet. """ for i in range(number): print('hello', name) cli.build() cli.print_help() .. rst-class:: sphx-glr-script-out .. code-block:: none usage: hello [-h] [-n NUMBER] name positional arguments: name Who is being greeted. options: -h, --help show this help message and exit -n NUMBER, --number NUMBER Number of times to greet. .. GENERATED FROM PYTHON SOURCE LINES 151-158 Lists ----- Adding the ``list[type]`` to a function signature will tell the parser that function is to take multiple arguments. Each argument will be cast into the type enclosed in ``list[]``. By default, arguments with this signature will have the |argparse argument|_ set to ``action = 'extend'`` and ``nargs = '+'``. .. GENERATED FROM PYTHON SOURCE LINES 158-173 .. code-block:: Python cli.reset() @cli.program def hello(names: list[str]): """ Parameters ---------- names : list[str] Who is being greeted. """ for n in names: print(n) cli.build() cli.print_help() .. rst-class:: sphx-glr-script-out .. code-block:: none usage: hello [-h] names [names ...] positional arguments: names Who is being greeted. options: -h, --help show this help message and exit .. rst-class:: sphx-glr-timing **Total running time of the script:** (0 minutes 0.005 seconds) .. _sphx_glr_download_auto_examples_plot_e02_typing.py: .. only:: html .. container:: sphx-glr-footer sphx-glr-footer-example .. container:: sphx-glr-download sphx-glr-download-jupyter :download:`Download Jupyter notebook: plot_e02_typing.ipynb ` .. container:: sphx-glr-download sphx-glr-download-python :download:`Download Python source code: plot_e02_typing.py ` .. container:: sphx-glr-download sphx-glr-download-zip :download:`Download zipped: plot_e02_typing.zip ` .. only:: html .. rst-class:: sphx-glr-signature `Gallery generated by Sphinx-Gallery `_