Pythonコードのドキュメント文字列の位置を変更します

Question

まあ、私はPythonが大好きですが、主に次の2つの厄介なものを見つけます：selfとdocstringsは宣言の下にあります。

私が知りたいのは、コード内の宣言の前にドキュメントストリングを作成するにはどうしたらよいですか？次のようなもの：

"""Class docstring""" 
class MyClass(object): 
    "Method documentation" 
    def my_method(self): 
     pass 

おそらく何らかの形式のデコレータを使用していますか？

Answer 1

__doc__プロパティを設定するデコレータを書くことが可能です：

def doc(docstr): 
    def deco(f): 
     f.__doc__ = docstr 
     return f 
    return deco 

これは__doc__属性以来、機能や古いスタイルのクラスのためではなく、新しい形式のクラスのために動作します新しいスタイルのクラスは、読み取り専用です（メタクラスを使用しない限り、ほとんど利益を得ずにさらに複雑になります）。

とにかくこのようなデコレータを使用しないことをおすすめします。通常の規則に従うだけです。こうすることで、他の開発者がすぐにドキュメンテーション文字列のためのソースコードを解析するツールが正常に動作しますが、ドキュメンテーション文字列何を理解するなど

編集：

def doc(docstr): 
    def deco(f): 
     if isinstance(f, type): 
      d = vars(f).copy() 
      d["__doc__"] = docstr 
      return type(f.__name__, f.__bases__, d) 
     f.__doc__ = docstr 
     return f 
    return deco 

：また、新しいスタイルのクラスをカバーするために、あなたはこの実装を使用することができます

__doc__は読み取り専用なので、目的のドキュメントを使用して新しいタイプのオブジェクトを作成する必要があります。簡単にするために、私はカスタムメタクラスを考慮しません（望むなら、上記のコードのf.__class__によってtypeを置き換えてください）。

また、このデコレータの使用はお勧めできません。

Answer 2

これは動作しません。 docstringは定義上、宣言に続く行の文字列です。

本当にデコレータでこれを行う場合は、ラップされた関数（またはクラス）の__doc__プロパティを設定するデコレータを作成できます。

Answer 3

本当にしたい場合は、確かに。

def doc(text): 
    def w(f): 
    f.__doc__ = text 
    return f 
    return w 

Answer 4

すでにあなたの質問に示唆したよう次のように、あなたが何かをすることができます：

from functools import wraps 

def docstring(docstr): 
    def decorator(cls): 
     @wraps(cls) 
     def wrapper(*args, **kwargs): 
      return cls(*args, **kwargs) 
     wrapper.__doc__ = docstr 
     return wrapper 
    return decorator 

@docstring("""Class docstring""") 
class MyClass(object): 
    def my_method(self): 
     pass 

print MyClass.__doc__ # Class docstring 

しかし、私は現在の構文よりも、これが特に良く見つけることはありません。