pyinaturalist.forge_utils module

Utilities built on top of python-forge that simplify defining API docs by combining function signature modification with docstring modification. This module makes python-forge optional; if not installed, these functions will quietly fail without modifying the target functions.

pyinaturalist.forge_utils.copy_docstrings(target_function, template_functions)

Copy docstrings from one or more template functions to a target function. Assumes Google-style docstrings.

Parameters

• target_function (Callable) – Function to modify

• template_functions (List[Any]) – Functions containing docstrings to apply to target_function

Return type

Callable

pyinaturalist.forge_utils.copy_signature(template_function, include=None, exclude=None)

A wrapper around forge.copy() that silently fails if forge is not installed

Return type

Callable

Parameters

template_function (Callable) –

pyinaturalist.forge_utils.copy_signatures(target_function, template_functions)

Copy function signatures from one or more template functions to a target function.

Parameters

• target_function (Callable) – Function to modify

• template_functions (List[Any]) – Functions containing params to apply to target_function

Return type

Callable

pyinaturalist.forge_utils.document_request_params(template_functions)

Document a function with both docstrings and function signatures from one or more template functions.

Signature modification requires python-forge. If not installed, only docstrings will be modified.

If used with other decorators, this should go first (e.g., last in the call order).

Example

>>> # 1. Template function with individual request params + docs
>>> def get_foo_template(arg_1: str = None, arg_2: bool = False):
>>>     '''
>>>     arg_1: Example request parameter 1
>>>     arg_2: Example request parameter 2
>>>     '''

>>> # 2. Decorated API Endpoint function with generic (variadic) keyword args
>>> @document_request_params(get_foo_template)
>>> def get_foo(**kwargs) -> List:
    ''' Get Foo resource '''

>>> # 3. Modified function signature + docstring
>>> help(get_foo)
'''
Help on function get_foo:
get_foo(arg_1: str = None, arg_2: bool = False) -> List
Get Foo resource
Args:
    arg_1: Example request parameter 1
    arg_2: Example request parameter 2
'''

Parameters

template_functions (List[Any]) – Template functions containing docstrings and params to apply to the wrapped function

Return type

Callable