API Reference¶

Generate an ArgumentParser from the docstring.

Disclaimer

Licensed under the Apache License, Version 2.0 (the “License”); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

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 –
Theses arguments are determined by the argparse.ArgumentParser base class. Note that by default, we use a argparse.RawTextHelpFormatter class for the formatter_class keyword, whereas the argparse.ArgumentParser uses a argparse.HelpFormatter
**kwargs`` –
Theses arguments are determined by the argparse.ArgumentParser base class. Note that by default, we use a argparse.RawTextHelpFormatter class for the formatter_class keyword, whereas the argparse.ArgumentParser uses a argparse.HelpFormatter
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 the setup_args() method is called
epilog_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

add_subparsers(*args, **kwargs)[source]¶

Add subparsers to this parser

Parameters

``*args –
As specified by the original argparse.ArgumentParser.add_subparsers() method
**kwargs`` – As specified by the original argparse.ArgumentParser.add_subparsers() method
chain (bool) – Default: False. If True, It is enabled to chain subparsers

append2help(arg, s)[source]¶

Append the given string to the help of argument arg

Parameters

arg (str) – The function argument
s (str) – The string to append to the help

append2helpf(arg, s)[source]¶

Append the given string to the help of argument arg

Parameters

arg (str) – The function argument
s (str) – The string to append to the help

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 used
overwrite (bool) – If True, overwrite the existing epilog
append (bool) – If True, append to the existing epilog

static format_bold(section, text)[source]¶: Make a bold formatting for the section header

format_epilog_section(section, text)[source]¶: Format a section for the epilog by inserting a format

static format_heading(section, text)[source]¶

static format_rubric(section, text)[source]¶: Make a bold formatting for the section header

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

Parameters

doc (str) – The base docstring to use
param (str) – The argument to use

Returns

str – The documentation of the given param
str – The datatype of the given param

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: FuncArgParser

grouparg(arg, my_arg=None, parent_cmds=[])[source]¶

Grouper function for chaining subcommands

Parameters

arg (str) – The current command line argument that is parsed
my_arg (str) – The name of this subparser. If None, this parser is the main parser and has no parent parser
parent_cmds (list of str) – The available commands of the parent parsers

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

str or None

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

object

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: argparse.Namespace

See also

parse_known_chained

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_args(args=None, namespace=None)[source]¶

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_arg(*args, **kwargs)[source]¶: Delete a previously defined argument from the parser

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_key(arg, key, *args, **kwargs)[source]¶: Delete a previously defined key for the add_argument

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() method
insert_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() method
interprete (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 used
overwrite (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 the add_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() method
insert_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() method
interprete (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 used
overwrite (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_arg

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_short, update_longf

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 (see update_arg() and update_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, update_longf

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, update_long

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 (see update_arg() and update_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

update_short, update_longf