format_doc¶

astropy.utils.decorators.format_doc(docstring, *args, **kwargs)[ソース]¶

修飾対象の文書文字列を置き換え，それをフォーマットする.

フォーマットの動作原理は以下のとおりである. str.format() 修飾対象がすでに文書文字列を持っている場合は、その文書文字列を新しい文書に含めることができる(使用すれば {{__doc__}} 占位符。その主な用途は重用である long 複数の関数間で同一またはわずかに異なる場合、複数の関数中の文書文字列。

パラメータ

docstring文字列またはオブジェクトまたはなし: 修飾対象の文書文字列の文書文字列を置き換える.関数やクラスのようなオブジェクトであれば、そのオブジェクトの文書文字列を取得する。それが文字列であれば、それは文字列自体を使用するだろう。1つの特殊な場合文字列が None そして，修飾関数docstringを用いて定式化する.
パラメータ：: 伝えられています str.format() それがそうです。
コバルガス：: 伝えられています str.format() それがそうです。関数が(空でない)文書文字列を持つ場合、元の文書文字列はキーワードを用いてkwargsに追加される '__doc__' それがそうです。

賃上げをする

ValueError: もし docstring (または解釈された文書文字列(そうであれば) None 文字列ではない)が空である.
IndexError、KeyError: もし(解釈された)中の占位子が docstring 記入していません。参照してください str.format() より多くの情報を得ることができます

注意事項

たとえば，この修飾子を用いてSphinxが正しい文書文字列を解析することを可能にする.

実例.

現在の文書文字列を置き換えることは非常に容易です：

>>> 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 与えられた文書文字列をフォーマットするのではなく args あるいは…。 kwargs (元文書文字列でもない)：

>>> @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}.

この問題を解決するためには，文書文字列を指定することができる 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 AS docstringは，1つのオブジェクトに2回の修飾子を使用することを許可し，まず新たなdocstringを分析し，次にオリジナルdocstringや解析を行う. args そして kwargs それがそうです。

ナビゲーション

format_doc¶