46

Python の関数は柔軟な型の引数を受け入れる場合があります。または、柔軟な型の値を返す場合があります。現在、そのような関数の良い例を思い出すことができないため、以下のおもちゃの例でそのような関数がどのように見えるかを示しています。

Sphinx のドキュメント表記法を使用して、そのような関数のドキュメント文字列を記述する方法を知りたいです。以下の例では、引数は または のいずれstrかintです。同様に、 または のいずれstrかを返しますint。

docstring の例を示しました (デフォルトの Sphinx 表記と、Sphinx のナポレオン拡張によって理解される Google 表記の両方)。これが柔軟な型を文書化する正しい方法であるかどうかはわかりません。

スフィンクスのデフォルト表記:

def add(a, b):
    """Add numbers or concatenate strings.

    :param int/str a: String or integer to be added
    :param int/str b: String or integer to be added
    :return: Result
    :rtype: int/str
    """
    pass

スフィンクス ナポレオン Google表記：

def add2(a, b):
    """Add numbers or concatenate strings.

    Args:
      a (int/str): String or integer to be added
      b (int/str): String or integer to be added

    Returns:
      int/str: Result
    """
    pass

Sphinx によって処理されることを意図した docstring でパラメータまたは戻り値の複数の型を表現する正しい方法は何ですか?

4

1 に答える 1

52

Python 3.5Union型ヒント

https://docs.python.org/3/library/typing.html#typing.Union

Python 2 の場合、Python 3 モジュールとまったく同じ構文を使用することをお勧めします。

  • 後で移植を容易にし、場合によっては自動化できるようにする
  • 物事を行うための明確に定義された独自の標準的な方法を指定する

例：

def f(int_or_float):
    """
    :param int_or_float: Description of the parameter
    :type int_or_float: Union[int, float]
    :rtype: float
    """
    return int_or_float + 1.0

次に、3.5 の場合は、次のように記述します。

from typing import Union

def f(int_or_float : Union[int, float]) -> float:
    """
    :param int_or_float: Description of the parameter
    """
    return int_or_float + 1.0

すでにドキュメント生成がサポートされていると思いますが、まだテストしていません: https://github.com/sphinx-doc/sphinx/issues/1968

于 2016-11-25T09:45:30.370 に答える