¿Cómo documentar pequeños cambios en funciones API complejas?

Digamos que tenemos una función API compleja, importada de alguna biblioteca.

def complex_api_function(
        number, <lots of positional arguments>,
        <lots of keyword arguments>):
    '''really long docstring'''
    # lots of code

Quiero escribir un contenedor simple alrededor de esa función para hacer un pequeño cambio. Por ejemplo , debería ser posible pasar el primer argumento como una cadena. ¿Cómo documentar esto? Consideré las siguientes opciones:

Opción 1:

def my_complex_api_function(number_or_str, *args, **kwargs):
    '''
    Do something complex.

    Like `complex_api_function`, but first argument can be a string.

    Parameters
    ----------
    number_or_str : int or float or str
        Can be a number or a string that can be interpreted as a float.
        <copy paste description from complex_api_function docstring>
    *args
        Positional arguments passed to `complex_api_function`.
    **kwargs
        Keyword arguments passed to `complex_api_function`.

    Returns
    -------
    <copy paste from complex_api_function docstring>

    Examples
    --------
    <example where first argument is a string, e.g. '-5.0'>

    '''
    return complex_api_function(float(number_or_str), *args, **kwargs)

Desventaja: el usuario debe consultar los documentos de complex_api_functionpara obtener información sobre *argsy **kwargs. Necesita ajuste cuando la copia pegó secciones del complex_api_functioncambio.

Opcion 2:

Copie y pegue complex_api_functionla firma (en lugar de usar *argsy **kwargs) y su cadena de documentos. Realice un pequeño cambio en la cadena de documentación que menciona que el primer argumento también puede ser una cadena. Agrega un ejemplo.

Desventaja: detallado, debe cambiarse cuando complex_api_functioncambia.

Opcion 3:

Decorar my_complex_api_functioncon functools.wraps(complex_api_function).

Desventaja: no hay información que numbertambién pueda ser una cadena.

Estoy buscando una respuesta que no dependa de los detalles de los cambios my_complex_api_function. El procedimiento debería funcionar para cualquier pequeño ajuste al original complex_api_function.

Recomiendo algo como lo siguiente:

def my_complex_api_function(number_or_str, *args, **kwargs):
    """This function is a light wrapper to `complex_api_function`.
    It allows you to pass a string or a number, whereas `complex_api_function` requires a 
    number. See :ref:`complex_api_function` for more details.

    :param number_or_str: number or str to convert to a number and pass to `complex_api_function`.
    :param args: Arguments to pass to `complex_api_function`
    :param kwargs: Keyword arguments to pass to `complex_api_function`
    :return: Output of `complex_api_function`, called with passed parameters
    """

Esto es claro y conciso. Pero recuerde también que, si utiliza un sistema de documentación como sphinx, para vincular las funciones con :ref:`bob`o similar.

Puede automatizar la "especialización" de la cadena de documentación original con un apéndice . Por ejemplo, pydoc está utilizando el atributo especial__doc__ . Podría escribir un decorador que anule automáticamente la función original __doc__con su anexo.

Por ejemplo:

def extend_docstring(original, addendum):
    def callable(func):
        func.__doc__ = original + addendum
        return func

    return callable


def complex_api_function(a, b, c):
    '''
    This is a very complex function.

    Parameters
    ----------
    a: int or float
        This is the argument A.
    b: ....
    '''
    print('do something')

@extend_docstring(
    complex_api_function.__doc__,
    '''
    Addendum
    --------
    Parameter a can also be a string
    '''
)
def my_complex_api_function(a, b, c):
    return complex_api_function(float(a), b, c)

o...

def extend_docstring(original):
    def callable(func):
        func.__doc__ = original + func.__doc__
        return func

    return callable


def complex_api_function(a, b, c):
    '''
    This is a very complex function.

    Parameters
    ----------
    a: int or float
        This is the argument A.
    b: ....
    '''
    print('do something')

@extend_docstring(complex_api_function.__doc__)
def my_complex_api_function(a, b, c):
    '''
    Addendum
    --------
    Parameter a can also be a string
    '''
    return complex_api_function(float(a), b, c)

Si ejecuta pydoc ( pydoc3 -w my_module.py) produce: vista previa de html generado por pydoc

Nota adicional: Si está utilizando Python 3, podría usar anotaciones para documentar el tipo (s) de los parámetros de su función. Ofrece muchos beneficios, no solo documentación. Por ejemplo:

from typing import Union

def my_complex_api_function(number_or_str: Union[int, float, str], *args, **kwargs):

No estoy seguro de si esto es lo que está buscando, pero ayuda a evitar la pregunta por completo.

def first_as_num_or_str(func):
    '''Decorator allowing the first parameter of the given function to be a number or a string

    :param func: A function whose first argument is a number
    :return: `func`, but now the first argument is cast to a float
    ''' 
    def new_func(*args, **kwargs):
        func(float(args[0]), args[1:], kwargs)
    return new_func

wrapped_api_func = first_as_num_or_str(complex_api_function)