Ajouter des docstrings aux namedtuples ?

Question

Est-il possible d'ajouter une chaîne de documentation à un namedtuple de manière simple ?

J'ai essayé

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)"

mais ça ne suffit pas. Est-il possible de procéder d'une autre manière ?

Answer 1

En Python 3, aucun wrapper n'est nécessaire, car la fonction __doc__ les attributs des types sont inscriptibles.

from collections import namedtuple

Point = namedtuple('Point', 'x y')
Point.__doc__ = '''\
A 2-dimensional coordinate

x - the abscissa
y - the ordinate'''

Cela correspond étroitement à une définition de classe standard, où la docstring suit l'en-tête.

class Point():
    '''A 2-dimensional coordinate

    x - the abscissa
    y - the ordinate'''
    <class code>

Cela ne fonctionne pas dans Python 2.

AttributeError: attribute '__doc__' of 'type' objects is not writable .

Answer 2

Je suis tombé sur cette vieille question via Google en me demandant la même chose.

Je voulais juste signaler que vous pouvez encore mieux faire le ménage en appelant namedtuple() dès la déclaration de la classe :

from collections import namedtuple

class Point(namedtuple('Point', 'x y')):
    """Here is the docstring."""

Answer 3

Pour ce faire, il suffit de créer une classe d'enveloppe simple et vide autour de la valeur renvoyée par la fonction namedtuple . Contenu d'un fichier que j'ai créé ( nt.py ):

from collections import namedtuple

Point_ = namedtuple("Point", ["x", "y"])

class Point(Point_):
    """ A point in 2d space """
    pass

Puis dans le REPL de Python :

>>> print nt.Point.__doc__
 A point in 2d space 

Ou vous pourriez le faire :

>>> help(nt.Point)  # which outputs...

Help on class Point in module nt:

class Point(Point)
 |  A point in 2d space
 |  
 |  Method resolution order:
 |      Point
 |      Point
 |      \_\_builtin\_\_.tuple
 |      \_\_builtin\_\_.object
 ...

Si vous n'aimez pas faire cela à la main à chaque fois, il est trivial d'écrire une sorte de fonction d'usine pour le faire :

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__

qui sort :

A point in 3d space

Answer 4

Vous pourriez concocter votre propre version du fonction de fabrique de tuples nommés de Raymond Hettinger et ajouter une option docstring argument.  Cependant, il serait plus facile - et sans doute meilleur - de définir votre propre fonction d'usine en utilisant la même technique de base que dans la recette.  Dans tous les cas, vous obtiendrez quelque chose de réutilisable.

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

Answer 5

Non, vous pouvez uniquement ajouter des chaînes de documents aux modules, classes et fonctions (y compris les méthodes).