15

Python で関数が期待するデータと返すデータの種類に関するコメントを記述するための標準をいくつか見てきました。どちらがベストプラクティスであるかについてコンセンサスはありますか?

http://www.python.org/dev/peps/pep-3107/の新しい機能は、このために使い始める必要がありますか?

4

3 に答える 3

21

関数アノテーションは特定の用途ではなく、あらゆる用途に使用できます。

注釈から情報を抽出し、型のチェックやドキュメントの生成など、必要なことを行うツールを作成できます。しかし、python 自体は情報に対して何もしません。完全に異なる目的に使用できます。つまり、パラメーターで呼び出される関数を提供したり、可能な戻り値の文字列を宣言したりできます。

注釈は任意のオブジェクトにすることができます:

def somefunc(param1: "string annotation", 
             param2: 151631,  
             param3: any_object): -> "some information here":

以下を使用してオブジェクトを取得できます。

print (somefunc.func_annotations)
{'param1': "string annotation", 
 'param2': 151631,  
 'param3': <object any_object>,
 'return': "some information here"}

PEP によって提供されるユースケースの提案:

  • タイピング情報の提供
    • 型チェック
    • 関数が期待する型と返す型を IDE に表示させる
    • 関数のオーバーロード / 汎用関数
    • 外国語ブリッジ
    • 適応
    • 述語論理関数
    • データベース クエリ マッピング
    • RPC パラメータのマーシャリング
  • その他の情報
    • パラメータと戻り値のドキュメント

関数注釈構文は新しすぎるため、実稼働ツールでは実際には使用されていません。

それを文書化するために他の方法を使用することをお勧めします。私は epydoc を使用してドキュメントを生成し、docstring からパラメーターの型情報を読み取ることができます。

def x_intercept(m, b):
    """
    Return the x intercept of the line M{y=m*x+b}.  The X{x intercept}
    of a line is the point at which it crosses the x axis (M{y=0}).

    This function can be used in conjuction with L{z_transform} to
    find an arbitrary function's zeros.

    @type  m: number
    @param m: The slope of the line.
    @type  b: number
    @param b: The y intercept of the line.  The X{y intercept} of a
              line is the point at which it crosses the y axis (M{x=0}).
    @rtype:   number
    @return:  the x intercept of the line M{y=m*x+b}.
    """
    return -b/m

この例は、epydoc の Web サイトからのものです。さまざまな形式でドキュメントを生成でき、クラスと呼び出しプロファイルから優れたグラフを生成できます。

于 2009-01-28T10:44:32.487 に答える
11

epydocを使用して API ドキュメントを作成する場合、3 つの選択肢があります。

  • エピテキスト。

  • ReStructuredText、RST。

  • エピテキストに少し似た JavaDoc 表記。

RST をお勧めします。これは、API リファレンスを含む全体的なドキュメント スイートを生成するためにsphinxとうまく連携するためです。RST マークアップはここで定義されています。指定できるさまざまな epydoc フィールドは、ここで定義されています。

例。

def someFunction( arg1, arg2 ):
    """Returns the average of *two* (and only two) arguments.

    :param arg1: a numeric value
    :type arg1: **any** numeric type

    :param arg2: another numeric value
    :type arg2: **any** numeric type

    :return: mid-point (or arithmetic mean) between two values 
    :rtype: numeric type compatible with the args.
    """
    return (arg1+arg2)/2
于 2009-01-28T11:30:54.360 に答える