Ctrl+K

format_doc#

astropy.utils.decorators.format_doc(docstring, *args, **kwargs)[源代码]#

替换装饰对象的docstring，然后格式化它。

格式的工作原理如下 str.format() 如果装饰对象已经有一个docstring，那么如果使用 {{__doc__}} 占位符。它的主要用途是重用 long docstring在多个函数中相同或只是略有不同。

参数:
docstring : str 或 object 或 NonePYTHON：字符串或对象或PYTHON：无

将替换装饰对象的docstring的docstring。如果它是一个类似于函数或类的对象，它将获取该对象的docstring。如果它是一个字符串，它将使用字符串本身。一个特殊情况是如果字符串 None 然后它将使用修饰函数docstring并格式化它。

args

传递给 str.format() .

kwargs

传递给 str.format() . 如果函数有一个（不是空的）docstring，则原始docstring将使用关键字添加到kwargs中 '__doc__' .

加薪:
ValueError

如果 docstring （或者解释docstring，如果是的话 None 或不是字符串）为空。

IndexError, KeyError

如果中的占位符（已解释） docstring 未填充。看见 str.format() 更多信息。

笔记

例如，使用这个修饰符可以解析正确的docstring。

实例

替换当前的docstring非常简单：

>>> from astropy.utils.decorators import format_doc
>>> @format_doc('''Perform num1 + num2''')
... def add(num1, num2):
...     return num1+num2
...
>>> help(add) 
Help on function add in module __main__:

add(num1, num2)
    Perform num1 + num2

有时候，你不想替换，只想添加：

>>> doc = '''
...       {__doc__}
...       Parameters
...       ----------
...       num1, num2 : Numbers
...       Returns
...       -------
...       result: Number
...       '''
>>> @format_doc(doc)
... def add(num1, num2):
...     '''Perform addition.'''
...     return num1+num2
...
>>> help(add) 
Help on function add in module __main__:

add(num1, num2)
    Perform addition.
    Parameters
    ----------
    num1, num2 : Numbers
    Returns
    -------
    result : Number

以防有人想进一步格式化它：

>>> doc = '''
...       Perform {0}.
...       Parameters
...       ----------
...       num1, num2 : Numbers
...       Returns
...       -------
...       result: Number
...           result of num1 {op} num2
...       {__doc__}
...       '''
>>> @format_doc(doc, 'addition', op='+')
... def add(num1, num2):
...     return num1+num2
...
>>> @format_doc(doc, 'subtraction', op='-')
... def subtract(num1, num2):
...     '''Notes: This one has additional notes.'''
...     return num1-num2
...
>>> help(add) 
Help on function add in module __main__:

add(num1, num2)
    Perform addition.
    Parameters
    ----------
    num1, num2 : Numbers
    Returns
    -------
    result : Number
        result of num1 + num2
>>> help(subtract) 
Help on function subtract in module __main__:

subtract(num1, num2)
    Perform subtraction.
    Parameters
    ----------
    num1, num2 : Numbers
    Returns
    -------
    result : Number
        result of num1 - num2
    Notes : This one has additional notes.

这些方法可以组合在一起；甚至可以从另一个对象获取文档字符串作为文档字符串属性。您只需指定对象：：

>>> @format_doc(add)
... def another_add(num1, num2):
...     return num1 + num2
...
>>> help(another_add) 
Help on function another_add in module __main__:

another_add(num1, num2)
    Perform addition.
    Parameters
    ----------
    num1, num2 : Numbers
    Returns
    -------
    result : Number
        result of num1 + num2

但要知道这个装修师 only 格式化给定的docstring而不是作为 args 或 kwargs （甚至连原始的docstring都没有）：：

>>> @format_doc(doc, 'addition', op='+')
... def yet_another_add(num1, num2):
...    '''This one is good for {0}.'''
...    return num1 + num2
...
>>> help(yet_another_add) 
Help on function yet_another_add in module __main__:

yet_another_add(num1, num2)
    Perform addition.
    Parameters
    ----------
    num1, num2 : Numbers
    Returns
    -------
    result : Number
        result of num1 + num2
    This one is good for {0}.

为了解决这个问题，可以将docstring指定为 None ：：

>>> @format_doc(None, 'addition')
... def last_add_i_swear(num1, num2):
...    '''This one is good for {0}.'''
...    return num1 + num2
...
>>> help(last_add_i_swear) 
Help on function last_add_i_swear in module __main__:

last_add_i_swear(num1, num2)
    This one is good for addition.

与一起使用 None 因为docstring允许在一个对象上使用decorator两次，首先解析新的docstring，然后解析原始docstring或 args 和 kwargs .

Edit on GitHub