API Reference¶
Classes
|
Subclass of an argument parser that get’s parts of the information |
-
class
FuncArgParser
(*args, **kwargs)[source]¶ Bases:
argparse.ArgumentParser
Subclass of an argument parser that get’s parts of the information from a given function
- Parameters
*args,**kwargs – Theses arguments are determined by the
argparse.ArgumentParser
base class. Note that by default, we use aargparse.RawTextHelpFormatter
class for the formatter_class keyword, whereas theargparse.ArgumentParser
uses aargparse.HelpFormatter
- Other Parameters
epilog_sections (list of str) – The default sections to use for the epilog (see the
epilog_sections
attribute). They can also be specified each time thesetup_args()
method is calledepilog_formatter ({‘header’, ‘bold’, ‘rubric’} or function) – Specify how the epilog sections should be formatted and defaults to the
epilog_formatter
attribute. This can either be a string out of ‘header’, ‘bold’, or ‘rubric’ or a callable (i.e. function) that takes two arguments, the section title and the section text, and returns a string.- ‘heading’
Use section headers such as:
Notes -----
- ‘bold’
Just make a bold header for the section, e.g.
**Notes**
- ‘rubric’
Use a rubric rst directive, e.g.
.. rubric:: Notes
Methods
add_subparsers
(*args, **kwargs)Add subparsers to this parser
create_arguments
([subparsers])Create and add the arguments
extract_as_epilog
(text[, sections, …])Extract epilog sections from the a docstring
format_bold
(section, text)Make a bold formatting for the section header
format_epilog_section
(section, text)Format a section for the epilog by inserting a format
format_heading
(section, text)format_rubric
(section, text)Make a bold formatting for the section header
get_param_doc
(doc, param)Get the documentation and datatype for a parameter
get_subparser
(name)Convenience method to get a certain subparser
grouparg
(arg[, my_arg, parent_cmds])Grouper function for chaining subcommands
parse2func
([args, func])Parse the command line arguments to the setup function
parse_chained
([args])Parse the argument directly to the function used for setup
parse_known2func
([args, func])Parse the command line arguments to the setup function
parse_known_args
([args, namespace])parse_known_chained
([args])Parse the argument directly to the function used for setup
setup_subparser
([func, setup_as, insert_at, …])Create a subparser with the name of the given function
Modification methods
append2help
(arg, s)Append the given string to the help of argument arg
pop_arg
(*args, **kwargs)Delete a previously defined argument from the parser
pop_key
(arg, key, *args, **kwargs)Delete a previously defined key for the add_argument
update_arg
(arg[, if_existent])Update the add_argument data for the given parameter
update_long
(**kwargs)Update the long optional arguments (those with two leading ‘-‘)
update_short
(**kwargs)Update the short optional arguments (those with one leading ‘-‘)
Decorator methods
append2helpf
(arg, s)Append the given string to the help of argument arg
pop_argf
(*args, **kwargs)Delete a previously defined argument from the parser via decorators
pop_keyf
(*args, **kwargs)Delete a previously defined key for the add_argument
setup_args
([func, setup_as, insert_at, …])Add the parameters from the given func to the parameter settings
update_argf
(arg, **kwargs)Update the arguments as a decorator
update_longf
(**kwargs)Update the long optional arguments belonging to a function
update_shortf
(**kwargs)Update the short optional arguments belonging to a function
Attributes
The formatter specification for the epilog.
The sections to extract from a function docstring that should be used in the epilog of this parser.
The unfinished arguments after the setup
-
add_subparsers
(*args, **kwargs)[source]¶ Add subparsers to this parser
- Parameters
**kwargs (*args,) – As specified by the original
argparse.ArgumentParser.add_subparsers()
methodchain (bool) – Default: False. If True, It is enabled to chain subparsers
-
create_arguments
(subparsers=False)[source]¶ Create and add the arguments
- Parameters
subparsers (bool) – If True, the arguments of the subparsers are also created
-
epilog_formatter
= 'heading'¶ The formatter specification for the epilog. This can either be a string out of ‘header’, ‘bold’, or ‘rubric’ or a callable (i.e. function) that takes two arguments, the section title and the section text, and returns a string.
- ‘heading’
Use section headers such as:
Notes -----
- ‘bold’
Just make a bold header for the section, e.g.
**Notes**
- ‘rubric’
Use a rubric rst directive, e.g.
.. rubric:: Notes
Warning
When building a sphinx documentation using the sphinx-argparse module, this value should be set to
'bold'
or'rubric'
! Just add this two lines to your conf.py:import funcargparse funcargparse.FuncArgParser.epilog_formatter = 'rubric'
-
epilog_sections
= ['Notes', 'References']¶ The sections to extract from a function docstring that should be used in the epilog of this parser. See also the
setup_args()
method
-
extract_as_epilog
(text, sections=None, overwrite=False, append=True)[source]¶ Extract epilog sections from the a docstring
- Parameters
text – The docstring to use
sections (list of str) – The headers of the sections to extract. If None, the
epilog_sections
attribute is usedoverwrite (bool) – If True, overwrite the existing epilog
append (bool) – If True, append to the existing epilog
-
static
get_param_doc
(doc, param)[source]¶ Get the documentation and datatype for a parameter
This function returns the documentation and the argument for a napoleon like structured docstring doc
-
get_subparser
(name)[source]¶ Convenience method to get a certain subparser
- Parameters
name (str) – The name of the subparser
- Returns
The subparsers corresponding to name
- Return type
-
grouparg
(arg, my_arg=None, parent_cmds=[])[source]¶ Grouper function for chaining subcommands
- Parameters
- Returns
The grouping key for the given arg or None if the key does not correspond to this parser or this parser is the main parser and does not have seen a subparser yet
- Return type
Notes
Quite complicated, there is no real need to deal with this function
-
parse2func
(args=None, func=None)[source]¶ Parse the command line arguments to the setup function
This method parses the given command line arguments to the function used in the
setup_args()
method to setup up this parser- Parameters
args (list) – The list of command line arguments
func (function) – An alternative function to use. If None, the last function or the one specified through the setup_as parameter in the
setup_args()
is used.
- Returns
What ever is returned by the called function
- Return type
Note
This method does not cover subparsers!
-
parse_chained
(args=None)[source]¶ Parse the argument directly to the function used for setup
This function parses the command line arguments to the function that has been used for the
setup_args()
.- Parameters
args (list) – The arguments parsed to the
parse_args()
function- Returns
The namespace with mapping from command name to the function return
- Return type
See also
-
parse_known2func
(args=None, func=None)[source]¶ Parse the command line arguments to the setup function
This method parses the given command line arguments to the function used in the
setup_args()
method to setup up this parser- Parameters
args (list) – The list of command line arguments
func (function or str) – An alternative function to use. If None, the last function or the one specified through the setup_as parameter in the
setup_args()
is used.
- Returns
object – What ever is returned by the called function
list – The remaining command line arguments that could not be interpreted
Note
This method does not cover subparsers!
-
parse_known_chained
(args=None)[source]¶ Parse the argument directly to the function used for setup
This function parses the command line arguments to the function that has been used for the
setup_args()
method.- Parameters
args (list) – The arguments parsed to the
parse_args()
function- Returns
argparse.Namespace – The namespace with mapping from command name to the function return
list – The remaining arguments that could not be interpreted
See also
parse_known()
-
pop_argf
(*args, **kwargs)[source]¶ Delete a previously defined argument from the parser via decorators
Same as
pop_arg()
but it can be used as a decorator
-
pop_keyf
(*args, **kwargs)[source]¶ Delete a previously defined key for the add_argument
Same as
pop_key()
but it can be used as a decorator
-
setup_args
(func=None, setup_as=None, insert_at=None, interprete=True, epilog_sections=None, overwrite=False, append_epilog=True)[source]¶ Add the parameters from the given func to the parameter settings
- Parameters
func (function) – The function to use. If None, a function will be returned that can be used as a decorator
setup_as (str) – The attribute that shall be assigned to the function in the resulting namespace. If specified, this function will be used when calling the
parse2func()
methodinsert_at (int) – The position where the given func should be inserted. If None, it will be appended at the end and used when calling the
parse2func()
methodinterprete (bool) – If True (default), the docstrings are interpreted and switches and lists are automatically inserted (see the [interpretation-docs]
epilog_sections (list of str) – The headers of the sections to extract. If None, the
epilog_sections
attribute is usedoverwrite (bool) – If True, overwrite the existing epilog and the existing description of the parser
append_epilog (bool) – If True, append to the existing epilog
- Returns
Either the function that can be used as a decorator (if func is
None
), or the given func itself.- Return type
function
Examples
Use this method as a decorator:
>>> @parser.setup_args ... def do_something(a=1): ''' Just an example Parameters ---------- a: int A number to increment by one ''' return a + 1 >>> args = parser.parse_args('-a 2'.split())
Or by specifying the setup_as function:
>>> @parser.setup_args(setup_as='func') ... def do_something(a=1): ''' Just an example Parameters ---------- a: int A number to increment by one ''' return a + 1 >>> args = parser.parse_args('-a 2'.split()) >>> args.func is do_something >>> parser.parse2func('-a 2'.split()) 3
References
- interpretation-docs(1,2)
http://funcargparse.readthedocs.io/en/latest/docstring_interpretation.html)
-
setup_subparser
(func=None, setup_as=None, insert_at=None, interprete=True, epilog_sections=None, overwrite=False, append_epilog=True, return_parser=False, name=None, **kwargs)[source]¶ Create a subparser with the name of the given function
Parameters are the same as for the
setup_args()
function, other parameters are parsed to theadd_subparsers()
method if (and only if) this method has not already been called.- Parameters
func (function) – The function to use. If None, a function will be returned that can be used as a decorator
setup_as (str) – The attribute that shall be assigned to the function in the resulting namespace. If specified, this function will be used when calling the
parse2func()
methodinsert_at (int) – The position where the given func should be inserted. If None, it will be appended at the end and used when calling the
parse2func()
methodinterprete (bool) – If True (default), the docstrings are interpreted and switches and lists are automatically inserted (see the [interpretation-docs]
epilog_sections (list of str) – The headers of the sections to extract. If None, the
epilog_sections
attribute is usedoverwrite (bool) – If True, overwrite the existing epilog and the existing description of the parser
append_epilog (bool) – If True, append to the existing epilog
return_parser (bool) – If True, the create parser is returned instead of the function
name (str) – The name of the created parser. If None, the function name is used and underscores (
'_'
) are replaced by minus ('-'
)**kwargs – Any other parameter that is passed to the add_parser method that creates the parser
- Returns
Either the function that can be used as a decorator (if func is
None
), or the given func itself. If return_parser is True, the created subparser is returned- Return type
FuncArgParser or function
Examples
Use this method as a decorator:
>>> from funcargparser import FuncArgParser >>> parser = FuncArgParser() >>> @parser.setup_subparser ... def my_func(my_argument=None): ... pass >>> args = parser.parse_args('my-func -my-argument 1'.split())
-
unfinished_arguments
= {}¶ The unfinished arguments after the setup
-
update_arg
(arg, if_existent=None, **kwargs)[source]¶ Update the add_argument data for the given parameter
- Parameters
arg (str) – The name of the function argument
if_existent (bool or None) – If True, the argument is updated. If None (default), the argument is only updated, if it exists. Otherwise, if False, the given
**kwargs
are only used if the argument is not yet existing**kwargs – The keyword arguments any parameter for the
argparse.ArgumentParser.add_argument()
method
-
update_argf
(arg, **kwargs)[source]¶ Update the arguments as a decorator
- Parameters
arg (str) – The name of the function argument
if_existent (bool or None) – If True, the argument is updated. If None (default), the argument is only updated, if it exists. Otherwise, if False, the given
**kwargs
are only used if the argument is not yet existing**kwargs – The keyword arguments any parameter for the
argparse.ArgumentParser.add_argument()
method
Examples
Use this method as a decorator:
>>> from funcargparser import FuncArgParser >>> parser = FuncArgParser() >>> @parser.update_argf('my_argument', type=int) ... def my_func(my_argument=None): ... pass >>> args = parser.parse_args('my-func -my-argument 1'.split()) >>> isinstance(args.my_argument, int) True
See also
-
update_long
(**kwargs)[source]¶ Update the long optional arguments (those with two leading ‘-‘)
This method updates the short argument name for the specified function arguments as stored in
unfinished_arguments
- Parameters
**kwargs – Keywords must be keys in the
unfinished_arguments
dictionary (i.e. keywords of the root functions), values the long argument names
Examples
Setting:
>>> parser.update_long(something='s', something_else='se')
is basically the same as:
>>> parser.update_arg('something', long='s') >>> parser.update_arg('something_else', long='se')
which in turn is basically comparable to:
>>> parser.add_argument('--s', dest='something', ...) >>> parser.add_argument('--se', dest='something_else', ...)
See also
-
update_longf
(**kwargs)[source]¶ Update the long optional arguments belonging to a function
This method acts exactly like
update_long()
but works as a decorator (seeupdate_arg()
andupdate_argf()
)- Parameters
**kwargs – Keywords must be keys in the
unfinished_arguments
dictionary (i.e. keywords of the root functions), values the long argument names- Returns
The function that can be used as a decorator
- Return type
function
Examples
Use this method as a decorator:
>>> @parser.update_shortf(something='s', something_else='se') ... def do_something(something=None, something_else=None): ... ...
See also the examples in
update_long()
.See also
-
update_short
(**kwargs)[source]¶ Update the short optional arguments (those with one leading ‘-‘)
This method updates the short argument name for the specified function arguments as stored in
unfinished_arguments
- Parameters
**kwargs – Keywords must be keys in the
unfinished_arguments
dictionary (i.e. keywords of the root functions), values the short argument names
Examples
Setting:
>>> parser.update_short(something='s', something_else='se')
is basically the same as:
>>> parser.update_arg('something', short='s') >>> parser.update_arg('something_else', short='se')
which in turn is basically comparable to:
>>> parser.add_argument('-s', '--something', ...) >>> parser.add_argument('-se', '--something_else', ...)
See also
-
update_shortf
(**kwargs)[source]¶ Update the short optional arguments belonging to a function
This method acts exactly like
update_short()
but works as a decorator (seeupdate_arg()
andupdate_argf()
)- Parameters
**kwargs – Keywords must be keys in the
unfinished_arguments
dictionary (i.e. keywords of the root functions), values the short argument names- Returns
The function that can be used as a decorator
- Return type
function
Examples
Use this method as a decorator:
>>> @parser.update_shortf(something='s', something_else='se') ... def do_something(something=None, something_else=None): ... ...
See also the examples in
update_short()
.See also