簡単な方法で名前付きタプルにドキュメント文字列を追加することは可能ですか？
私は試した
from collections import namedtuple
Point = namedtuple("Point", ["x", "y"])
"""
A point in 2D space
"""
# Yet another test
"""
A(nother) point in 2D space
"""
Point2 = namedtuple("Point2", ["x", "y"])
print Point.__doc__ # -> "Point(x, y)"
print Point2.__doc__ # -> "Point2(x, y)"
しかし、それはそれをカットしません。他の方法で行うことは可能ですか？
回答:
これは、からの戻り値の周りに単純な空のラッパークラスを作成することで実現できますnamedtuple。私が作成したファイルの内容（nt.py）：
from collections import namedtuple
Point_ = namedtuple("Point", ["x", "y"])
class Point(Point_):
""" A point in 2d space """
pass
次に、Python REPLで：
>>> print nt.Point.__doc__
A point in 2d space
または、次のことができます。
>>> help(nt.Point) # which outputs...
モジュールntのクラスPointに関するヘルプ： クラスPoint（Point） | 2次元空間のポイント | | メソッド解決の順序： | ポイント | ポイント | __builtin __。tuple | __builtin __。object ..。
毎回手作業で行うのが気に入らない場合は、これを行うための一種のファクトリ関数を作成するのは簡単です。
def NamedTupleWithDocstring(docstring, *ntargs):
nt = namedtuple(*ntargs)
class NT(nt):
__doc__ = docstring
return NT
Point3D = NamedTupleWithDocstring("A point in 3d space", "Point3d", ["x", "y", "z"])
p3 = Point3D(1,2,3)
print p3.__doc__
出力：
A point in 3d space
__slots__ = ()派生サブクラスに追加すると、使用することによるメモリとパフォーマンスの利点を維持できますnamedtuple
__doc__カスタマイズしたdocstringを割り当てて、元のオブジェクトに保存するだけで済みます。
Python 3では、__doc__型の属性が書き込み可能であるため、ラッパーは必要ありません。
from collections import namedtuple
Point = namedtuple('Point', 'x y')
Point.__doc__ = '''\
A 2-dimensional coordinate
x - the abscissa
y - the ordinate'''
これは、docstringがヘッダーの後に続く標準のクラス定義に密接に対応しています。
class Point():
'''A 2-dimensional coordinate
x - the abscissa
y - the ordinate'''
<class code>
これはPython2では機能しません。
AttributeError: attribute '__doc__' of 'type' objects is not writable。
同じことを疑問に思いながら、Google経由でこの古い質問に出くわしました。
クラス宣言から直接namedtuple（）を呼び出すことで、さらに整理できることを指摘したいと思います。
from collections import namedtuple
class Point(namedtuple('Point', 'x y')):
"""Here is the docstring."""
__slots__ = ()クラスに含めることが重要です。それ以外の場合は、属性__dict__用にを作成し、namedtupleの軽量性を失います。
簡単な方法で名前付きタプルにドキュメント文字列を追加することは可能ですか？
はい、いくつかの方法で。
Python 3.6以降、docstring（およびアノテーション！）を使用しclassてtyping.NamedTuple直接定義を使用できます。
from typing import NamedTuple
class Card(NamedTuple):
"""This is a card type."""
suit: str
rank: str
Python 2と比較して、空を宣言__slots__する必要はありません。Python 3.8では、サブクラスでも必要ありません。
宣言__slots__は空でないことはできないことに注意してください！
Python 3では、namedtupleのドキュメントを簡単に変更することもできます。
NT = collections.namedtuple('NT', 'foo bar')
NT.__doc__ = """:param str foo: foo name
:param list bar: List of bars to bar"""
これにより、ヘルプを呼び出すときに、それらの意図を確認できます。
Help on class NT in module __main__:
class NT(builtins.tuple)
| :param str foo: foo name
| :param list bar: List of bars to bar
...
これは、Python2で同じことを達成するのが難しいことに比べれば非常に簡単です。
Python 2では、次のことを行う必要があります
__slots__ == () 宣言__slots__は、ここでの他の答えが見逃している重要な部分です。
宣言しない場合は__slots__、インスタンスに変更可能なアドホック属性を追加して、バグを発生させる可能性があります。
class Foo(namedtuple('Foo', 'bar')):
"""no __slots__ = ()!!!"""
そして今：
>>> f = Foo('bar')
>>> f.bar
'bar'
>>> f.baz = 'what?'
>>> f.__dict__
{'baz': 'what?'}
各インスタンスは、アクセス__dict__時に個別に作成__dict__されます（__slots__他の方法で機能が妨げられることはありませんが、タプルの軽量性、不変性、および宣言された属性はすべて、namedtupleの重要な機能です）。
__repr__コマンドラインにエコーされたもので同等のオブジェクトを取得したい場合は、も必要です。
NTBase = collections.namedtuple('NTBase', 'foo bar')
class NT(NTBase):
"""
Individual foo bar, a namedtuple
:param str foo: foo name
:param list bar: List of bars to bar
"""
__slots__ = ()
__repr__別の名前でベースnamedtupleを作成する場合は、このようなものが必要です（上記のname string引数で行ったように'NTBase'）：
def __repr__(self):
return 'NT(foo={0}, bar={1})'.format(
repr(self.foo), repr(self.bar))
reprをテストするには、インスタンス化してから、パスが等しいかどうかをテストします。 eval(repr(instance))
nt = NT('foo', 'bar')
assert eval(repr(nt)) == nt
ドキュメントもに関し、そのような例を与える__slots__-私はそれに私自身のドキュメンテーション文字列を追加しています：
class Point(namedtuple('Point', 'x y')): """Docstring added here, not in original""" __slots__ = () @property def hypot(self): return (self.x ** 2 + self.y ** 2) ** 0.5 def __str__(self): return 'Point: x=%6.3f y=%6.3f hypot=%6.3f' % (self.x, self.y, self.hypot)..。
上記のサブクラス
__slots__は空のタプルに設定されます。これにより、インスタンスディクショナリの作成が防止され、メモリ要件が低く抑えられます。
これは、（ここでは示唆している別の答えのような）インプレースの使用を実証していますが、メソッド解決順序を見たときに、デバッグしている場合は、インプレースの使用は、私は元々使用して提案理由である、混乱になることがありますBase接尾辞としてベースnamedtupleの場合：
>>> Point.mro()
[<class '__main__.Point'>, <class '__main__.Point'>, <type 'tuple'>, <type 'object'>]
# ^^^^^---------------------^^^^^-- same names!
それ__dict__を使用するクラスからサブクラス化するときにの作成を防ぐには、サブクラスでそれを宣言する必要もあります。の使用に関するその他の注意事項__slots__については、この回答も参照してください。
__slots__ます。これがないと、namedtupleの軽量な価値が失われます。
Python 3.5以降、namedtupleオブジェクトのdocstringを更新できます。
whatsnewから：
Point = namedtuple('Point', ['x', 'y'])
Point.__doc__ += ': Cartesian coodinate'
Point.x.__doc__ = 'abscissa'
Point.y.__doc__ = 'ordinate'
Python 3.6以降では、次のものを使用できます。
class Point(NamedTuple):
"""
A point in 2D space
"""
x: float
y: float
受け入れられた回答で提案されているように、ラッパークラスを使用する必要はありません。文字通りdocstringを追加するだけです。
from collections import namedtuple
Point = namedtuple("Point", ["x", "y"])
Point.__doc__="A point in 2D space"
これにより、次のようになります。（使用例ipython3）：
In [1]: Point?
Type: type
String Form:<class '__main__.Point'>
Docstring: A point in 2D space
In [2]:
Voilà！
AttributeError: attribute '__doc__' of 'type' objects is not writable。
Raymond Hettingerによるnamedtupleファクトリ関数の独自のバージョンを作成し、オプションのdocstring引数を追加することができます。ただし、レシピと同じ基本的な手法を使用して独自のファクトリ関数を定義する方が簡単であり、間違いなく優れています。いずれにせよ、あなたは再利用可能なものになってしまうでしょう。
from collections import namedtuple
def my_namedtuple(typename, field_names, verbose=False,
rename=False, docstring=''):
'''Returns a new subclass of namedtuple with the supplied
docstring appended to the default one.
>>> Point = my_namedtuple('Point', 'x, y', docstring='A point in 2D space')
>>> print Point.__doc__
Point(x, y): A point in 2D space
'''
# create a base class and concatenate its docstring and the one passed
_base = namedtuple(typename, field_names, verbose, rename)
_docstring = ''.join([_base.__doc__, ': ', docstring])
# fill in template to create a no-op subclass with the combined docstring
template = '''class subclass(_base):
%(_docstring)r
pass\n''' % locals()
# execute code string in a temporary namespace
namespace = dict(_base=_base, _docstring=_docstring)
try:
exec template in namespace
except SyntaxError, e:
raise SyntaxError(e.message + ':\n' + template)
return namespace['subclass'] # subclass object created
この関数を作成して、名前付きタプルをすばやく作成し、タプルとその各パラメーターを文書化しました。
from collections import namedtuple
def named_tuple(name, description='', **kwargs):
"""
A named tuple with docstring documentation of each of its parameters
:param str name: The named tuple's name
:param str description: The named tuple's description
:param kwargs: This named tuple's parameters' data with two different ways to describe said parameters. Format:
<pre>{
str: ( # The parameter's name
str, # The parameter's type
str # The parameter's description
),
str: str, # The parameter's name: the parameter's description
... # Any other parameters
}</pre>
:return: collections.namedtuple
"""
parameter_names = list(kwargs.keys())
result = namedtuple(name, ' '.join(parameter_names))
# If there are any parameters provided (such that this is not an empty named tuple)
if len(parameter_names):
# Add line spacing before describing this named tuple's parameters
if description is not '':
description += "\n"
# Go through each parameter provided and add it to the named tuple's docstring description
for parameter_name in parameter_names:
parameter_data = kwargs[parameter_name]
# Determine whether parameter type is included along with the description or
# if only a description was provided
parameter_type = ''
if isinstance(parameter_data, str):
parameter_description = parameter_data
else:
parameter_type, parameter_description = parameter_data
description += "\n:param {type}{name}: {description}".format(
type=parameter_type + ' ' if parameter_type else '',
name=parameter_name,
description=parameter_description
)
# Change the docstring specific to this parameter
getattr(result, parameter_name).__doc__ = parameter_description
# Set the docstring description for the resulting named tuple
result.__doc__ = description
return result
次に、新しい名前付きタプルを作成できます。
MyTuple = named_tuple(
"MyTuple",
"My named tuple for x,y coordinates",
x="The x value",
y="The y value"
)
次に、記述された名前付きタプルを独自のデータでインスタンス化します。
t = MyTuple(4, 8)
print(t) # prints: MyTuple(x=4, y=8)
help(MyTuple)python3コマンドラインから実行すると、次のように表示されます。
Help on class MyTuple:
class MyTuple(builtins.tuple)
| MyTuple(x, y)
|
| My named tuple for x,y coordinates
|
| :param x: The x value
| :param y: The y value
|
| Method resolution order:
| MyTuple
| builtins.tuple
| builtins.object
|
| Methods defined here:
|
| __getnewargs__(self)
| Return self as a plain tuple. Used by copy and pickle.
|
| __repr__(self)
| Return a nicely formatted representation string
|
| _asdict(self)
| Return a new OrderedDict which maps field names to their values.
|
| _replace(_self, **kwds)
| Return a new MyTuple object replacing specified fields with new values
|
| ----------------------------------------------------------------------
| Class methods defined here:
|
| _make(iterable) from builtins.type
| Make a new MyTuple object from a sequence or iterable
|
| ----------------------------------------------------------------------
| Static methods defined here:
|
| __new__(_cls, x, y)
| Create new instance of MyTuple(x, y)
|
| ----------------------------------------------------------------------
| Data descriptors defined here:
|
| x
| The x value
|
| y
| The y value
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| _fields = ('x', 'y')
|
| _fields_defaults = {}
|
| ----------------------------------------------------------------------
| Methods inherited from builtins.tuple:
|
| __add__(self, value, /)
| Return self+value.
|
| __contains__(self, key, /)
| Return key in self.
|
| __eq__(self, value, /)
| Return self==value.
|
| __ge__(self, value, /)
| Return self>=value.
|
| __getattribute__(self, name, /)
| Return getattr(self, name).
|
| __getitem__(self, key, /)
| Return self[key].
|
| __gt__(self, value, /)
| Return self>value.
|
| __hash__(self, /)
| Return hash(self).
|
| __iter__(self, /)
| Implement iter(self).
|
| __le__(self, value, /)
| Return self<=value.
|
| __len__(self, /)
| Return len(self).
|
| __lt__(self, value, /)
| Return self<value.
|
| __mul__(self, value, /)
| Return self*value.
|
| __ne__(self, value, /)
| Return self!=value.
|
| __rmul__(self, value, /)
| Return value*self.
|
| count(self, value, /)
| Return number of occurrences of value.
|
| index(self, value, start=0, stop=9223372036854775807, /)
| Return first index of value.
|
| Raises ValueError if the value is not present.
または、次の方法でパラメータのタイプを指定することもできます。
MyTuple = named_tuple(
"MyTuple",
"My named tuple for x,y coordinates",
x=("int", "The x value"),
y=("int", "The y value")
)
いいえ、モジュール、クラス、関数（メソッドを含む）にのみドキュメント文字列を追加できます
namedtuple化は、を本格的な「オブジェクト」に変換しませんか？これにより、名前付きタプルによるパフォーマンスの向上の一部が失われますか？