Example documentation¶
One of the great things about defopt is that the same docstrings it uses to parse arguments are consumed by other tools in the Python ecosystem.
This is the documentation generated by Sphinx for the examples. You can click the “Show Source” button to see the raw RST document that generated this page.
Annotations¶
Example showing annotations in defopt.
Type hints specified in function annotations may be used instead of writing types in docstrings.
Iterable[x], Sequence[x] and List[x] are all treated
in the same way as list[x] in the docstring itself.
(See the lists example for more information.)
Code usage:
>>> documented([1.2, 3.4], 2)
Command line usage:
$ python annotations.py documented 2 --numbers 1.2 3.4
$ python annotations.py documented --numbers 1.2 3.4 -- 2
- examples.annotations.documented(numbers, exponent)¶
Example function using annotations.
- examples.annotations.undocumented(numbers, exponent)¶
Boolean flags¶
Example showing boolean flags in defopt.
Optional boolean parameters are automatically converted to
--name and --no-name flags which take no arguments
and store True and False respectively.
Code usage:
>>> main('hello!', upper=False, repeat=True)
Command line usage:
$ python booleans.py 'hello!' --no-upper --repeat
Choices¶
Example showing choices in defopt.
If a parameter’s type is a subclass of enum.Enum or a typing.Literal (or
its backport typing_extensions.Literal), defopt automatically turns this
into a set of string choices on the command line.
Code usage:
>>> choose_enum(Choice.one, opt=Choice.two)
Command line usage:
$ python choices.py one --opt two
- class examples.choices.Choice(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)¶
Bases:
Enum- one = 1¶
- two = 2.0¶
- three = '03'¶
- examples.choices.choose_literal(arg, *, opt=None)¶
Example function with
typing.Literalarguments.
Exceptions¶
Example showing exception handling.
If the function raises an exception listed in the docstring using :raises:,
the traceback is suppressed (the error is still reported, of course!).
- examples.exceptions.main(arg)¶
- Parameters:
arg (int) – Don’t set this to zero!
- Raises:
ValueError – If arg is zero.
Lists¶
Example showing lists in defopt.
Lists are automatically converted to required flags which accept zero or more arguments.
Code usage:
>>> main([1.2, 3.4], 2)
Command line usage:
$ python lists.py 2 --numbers 1.2 3.4
$ python lists.py --numbers 1.2 3.4 -- 2
Parsers¶
Example showing parsers in defopt.
If a type is not simple enough for defopt to parse on its own,
you can explicitly specify parsers for types by passing a mapping
to defopt.run.
Code usage:
>>> main(datetime(2015, 9, 13))
Command line usage:
$ python parsers.py 2015-09-13
- examples.parsers.main(date)¶
Example function with a
datetime.datetimeargument.- Parameters:
date (datetime) – Date to display
- examples.parsers.parse_date(string)¶
Parse a
datetime.datetimeusing a simple string format.- Parameters:
string (str) – String to parse
- Return type:
datetime
Short flags¶
Example showing short flags in defopt.
You can add alternative short flags to arguments by passing a
dictionary to defopt.run which maps flag names to single letters.
Code usage:
>>> main(count=2)
Command line usage:
$ python short.py -C 2
$ python short.py --count 2
Variable positional arguments¶
Example showing *args handling in defopt.
Variable positional arguments can be specified any number of times and are received as a tuple.
Flags generated by list types (or equivalents) create a new list each time they are used.
Code usage:
>>> plain(1, 2, 3)
>>> iterable([1, 2], [3, 4, 5])
Command line usage:
$ python starargs.py plain 1 2 3
$ python starargs.py iterable --groups 1 2 --groups 3 4 5
Docstring styles¶
Example showing supported docstring styles in defopt.
You need to enable the sphinx.ext.napoleon extension
to generate documentation for this module.
Code usage:
>>> sphinx(2, farewell='goodbye!')
Command line usage:
$ python styles.py sphinx 2 --farewell goodbye!
- examples.styles.sphinx(integer, *, farewell=None)¶
Example function with a Sphinx-style docstring.
Squares a given integer.
$ python styles.py sphinx 2 --farewell goodbye! 4 goodbye!
- examples.styles.google(integer, *, farewell=None)¶
Example function with a Google-style docstring.
Squares a given integer.
$ python styles.py google 2 --farewell goodbye! 4 goodbye!
Nested subcommands¶
Example showing nested parsers in defopt.
Code usage:
>>> main(1.5)
>>> sub1(2.0)
>>> sub2(2.5)
Command line usage:
$ python nested.py main 1.5
$ python nested.py sub sub1 2.0
$ python nested.py sub sub2 2.5
