5

バージョン 1.3.4の sphinx-doc napoleon Google スタイル docstring の例は、関数/メソッドのオプションの引数を次のように文書化する必要があることを示しています。

param2 (str, optional): The second parameter. Defaults to None.
  Second line of description should be indented.

しかし、ここのバージョン 1.4a0 の同じページには、同じことを行う次の方法が示されています。

param2 (Optional[str]): The second parameter. Defaults to None.
    Second line of description should be indented.

しかし、ドキュメントにはこの新しい構文の説明がありません。sphinx-doc のナポレオン拡張を使用して、Google スタイルの docstring でサポートされている新しい構文に関する詳細情報はどこにありますか?

4

2 に答える 2

6

要約すると、次のようになります。

リンクした関数module_level_functionの冒頭にあるドキュメントを見ると、次のことがわかります。

def module_level_function(param1, param2=None, *args, **kwargs):
    """This is an example of a module level function.

    Function parameters should be documented in the ``Args`` section. The name
    of each parameter is required. The type and description of each parameter
    is optional, but should be included if not obvious.

    Parameter types -- if given -- should be specified according to
    `PEP 484`_, though `PEP 484`_ conformance isn't required or enforced.

    # ^^^^^ this! ^^^^

最後の行にはヒントが含まれています。どうやら、モジュールPEP 484によって支援されて導入された表記法typingは、あなたが見ているものです。

記譜法の簡単な紹介:

PEP 484で説明されている関数注釈に基づいていますPEP 3107。基本的に、各関数パラメーターは、その名前の後にオプションの型指定子を持つことができます。したがって、次のような関数の場合:

def foo(a, b): 
    pass

次の方法で型に注釈を付けることができます。

def foo(a: int, b: str) -> None:
    pass

型ヒンティングの導入により、型が示される方法を形式化する必要が生じました。ここでtypingモジュールの出番です。

このtypingモジュールには、 などの標準の組み込み以外の追加の型を指定するための、優れた抽象型のセット (および、一般に、型理論のマンボジャンボ) が含まれていintますstr。たとえば、このOptional[str]表記は、パラメーターがstr型または「型」のいずれかを取ることができることを示しNoneます。つまり、オプションで文字列です。

一言で言えば、パラメータの型を文書化するための型ヒントの導入で定義された表記法を使用しています。これは、整数のリストである引数を取る関数がある場合、次のことを意味します。

 def func(param1)

ドキュメントは次のようになります。

param1 (List[int]): The first parameter containing a list of ints

は、 typingList[int]モジュールの表記から来ています。

いくつかの例:

この特定の表記法が定義され、さらに説明されているいくつかの例は、 (に影響を与えた静的チェッカー) のドキュメントでmypyPEP 484見つけることができます。コードで文書化する必要がある一般的なケースは、組み込み型の表に含まれています。

Type                Description
----                -----------

int                 integer of arbitrary size
float               floating point number
bool                boolean value
str                 unicode string
bytes               8-bit string
object              an arbitrary object (object is the common base class)
List[str]           list of str objects
Dict[str, int]      dictionary from str keys to int values
Iterable[int]       iterable object containing ints
Sequence[bool]      sequence of booleans
Any                 dynamically typed value with an arbitrary type

その他Any, Unionはここで定義されていますが、一般的な表記法はここで説明されています。

于 2016-01-20T12:32:22.800 に答える
1

Optional[X]私が理解している限り、構文は sphinx-doc に固有のものではありません。typing型ヒントのモジュールからのものです: https://docs.python.org/3/library/typing.html

于 2016-01-20T11:05:41.017 に答える