複雑なAPI関数に対する小さな変更を文書化する方法は？

いくつかのライブラリからインポートされた複雑なAPI関数があるとします。

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

小さな変更を加えるために、その関数の周りに簡単なラッパーを書きたいと思います。たとえば、最初の引数を文字列として渡すことができるはずです。これを文書化する方法は？私は次のオプションを検討しました：

オプション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)

欠点：およびcomplex_api_functionに関する情報を取得するには、ユーザーはのドキュメントを参照する必要が*argsあり**kwargsます。コピーからセクションを貼り付けてcomplex_api_function変更する場合は調整が必要です。

オプション2：

コピーアンドペーストcomplex_api_function（代わりに使用したのの署名*argsと**kwargs）とそのドキュメンテーション文字列を。docstringに小さな変更を加え、最初の引数も文字列にすることができることを述べます。例を追加します。

短所：詳細、変更時にcomplex_api_function変更する必要があります。

オプション3：

飾るmy_complex_api_functionとfunctools.wraps(complex_api_function)。

欠点：number文字列になる可能性のある情報はありません。

の変更点の詳細に依存しない答えを探していますmy_complex_api_function。この手順は、オリジナルを少し調整するだけで機能しcomplex_api_functionます。

私は次のようなものをお勧めします：

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
    """

これは明確で簡潔です。ただし、sphinxなどのドキュメンテーションシステムを使用している場合は、関数を:ref:`bob`同様。

あなたは、元のドキュメンテーション文字列の「専門」を自動化することができ補遺。たとえば、pydocは特別な属性__doc__を使用しています。__doc__補遺で元の関数を自動的にオーバーライドするデコレータを書くことができます。

例えば：

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)

または...

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)

pydoc（pydoc3 -w my_module.py）を実行すると、以下が生成されます：pydocによって生成されたhtmlのプレビュー

追加の注記：Python 3を使用している場合は、アノテーションを使用して関数パラメーターのタイプを文書化できます。ドキュメントだけでなく、多くの利点があります。例えば：

from typing import Union

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

これがあなたが探しているものかどうかはわかりませんが、質問を完全に回避するのに役立ちます。

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)