web-dev-qa-db-ja.com

dictsのフォーマットpython docstrings

辞書パラメータにdocstringを追加するための推奨される方法は何ですか？複数行のdocstringの例を見ることができます ここ 。

関数への入力引数をdocstringに文書化する必要があります。単純な変数の場合、次のようなものを使用できます。

 def func2(a=x, b = y):
 """ fun2 takes two integers 

 Keyword arguments:
 a -- refers to age (default 18)
 b -- refers to experience (default 0)
 """

関数への入力引数としてdictが渡された場合：

 def func3(**kwargs):
     """ takes dictionary as input

      <Here how to explain them - Is it like?> 
      kwargs['key1'] -- takes value1

      <or simply>
      key1 -- takes value1
      """
pythondictionarydocstring
14
webminal.org

私は通常 Google docstring style を使用するため、辞書パラメーターは次のようになります。

def func(a_dict):
    """Some function to do something to a dictionary.

    Args:
      a_dict (dict of str: int): Some mapping, I guess?

    """
    ...

**kwargsを受け取る関数（注：これはnotではなく（-===-）辞書パラメーターを持つのとまったく同じです）、次のようになります。

def func(**kwargs):
    """Some function to do stuff to arbitrary keyword arguments.

    Args:
        **kwargs: Arbitrary keyword arguments.

    Keyword Args:
        <kwarg_name> int: A description
        <kwarg_name_2> str: Another description
        <...>

    """
    ...

存在する必要のある特定のパラメーター（たとえば、key1）がある場合、それらは**kwargsにロールインされるのではなく、個別である必要があります。

Python 3.xでは、 関数アノテーション ：も使用できます。

def func(a_dict: dict):
    """Some function to do something to a dictionary."""
    ...

Python 3.5から、 typing ：を使用してさらに明示的にすることができます。

from typing import Mapping

def func(a_dict: Mapping[str, int]):
    """Some function to do something to a dictionary."""
    ...
19
jonrsharpe

PyCharmを使用している場合：デフォルトのdocstringフォーマットを以下で設定できます：

Preferences -> Tools -> Python Integrated Tools -> Docstrings

バージョン2019の時点で、許可されているオプションは次のとおりです。Plain、Epytext、reStructuredText、NumPy、Google。この機能は、二重引用符"を3つ入力し、enterを押すと、自動的にdocstringスケルトンを追加します。

0
Tomasz Bartkowiak