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)[source]¶ Copy docstrings from one or more template functions to a target function. Assumes Google-style docstrings.
- Parameters
target_function (
Callable
) – Function to modifytemplate_functions (
List
[Any
]) – Functions containing docstrings to apply totarget_function
- Return type
Callable
-
pyinaturalist.forge_utils.
copy_signature
(template_function, include=None, exclude=None)[source]¶ 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)[source]¶ Copy function signatures from one or more template functions to a target function.
- Parameters
target_function (
Callable
) – Function to modifytemplate_functions (
List
[Any
]) – Functions containing params to apply totarget_function
- Return type
Callable
-
pyinaturalist.forge_utils.
document_request_params
(template_functions)[source]¶ 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.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