Hériter docstrings en Python héritage de classe

Je suis en train de faire quelques héritage de classe en Python. J'aimerais que chaque classe et de la classe héritée d'avoir de bonnes docstrings. Donc je pense que pour la classe héritée, j'aimerais qu'il:

  • hériter de la classe de base docstring
  • peut-être ajouter pertinentes des documents supplémentaires à la docstring

Est-il (éventuellement élégant ou pythonic) de faire ce genre de docstring de manipulation dans une classe de l'héritage de la situation? Que diriez-vous pour l'héritage multiple?

  • Je ne peux pas répondre car la question était malheureusement fermé, mais comme de Python 3.5, inspect.getdoc la recherche de l'arbre d'héritage jusqu'à ce qu'il trouve une docstring.
  • Voir cette réponse.
InformationsquelleAutor Craig McQueen | 2010-01-08
  1. 37

    Vous n'êtes pas le seul! Il y avait une discussion sur comp.lang.python sur ce il ya un moment, et une recette a été créé. Check it out ici.

    """
doc_inherit decorator
Usage:
class Foo(object):
def foo(self):
"Frobber"
pass
class Bar(Foo):
@doc_inherit
def foo(self):
pass 
Now, Bar.foo.__doc__ == Bar().foo.__doc__ == Foo.foo.__doc__ == "Frobber"
"""
from functools import wraps
class DocInherit(object):
"""
Docstring inheriting method descriptor
The class itself is also used as a decorator
"""
def __init__(self, mthd):
self.mthd = mthd
self.name = mthd.__name__
def __get__(self, obj, cls):
if obj:
return self.get_with_inst(obj, cls)
else:
return self.get_no_inst(cls)
def get_with_inst(self, obj, cls):
overridden = getattr(super(cls, obj), self.name, None)
@wraps(self.mthd, assigned=('__name__','__module__'))
def f(*args, **kwargs):
return self.mthd(obj, *args, **kwargs)
return self.use_parent_doc(f, overridden)
def get_no_inst(self, cls):
for parent in cls.__mro__[1:]:
overridden = getattr(parent, self.name, None)
if overridden: break
@wraps(self.mthd, assigned=('__name__','__module__'))
def f(*args, **kwargs):
return self.mthd(*args, **kwargs)
return self.use_parent_doc(f, overridden)
def use_parent_doc(self, func, source):
if source is None:
raise NameError, ("Can't find '%s' in parents"%self.name)
func.__doc__ = source.__doc__
return func
doc_inherit = DocInherit
    • C'est soigné pour une méthode d'hériter de la classe parente de la méthode de la docstring. Qui serait utile dans de nombreux cas, je pense. Je pensais plus à propos de la docstring pour l'ensemble de la classe, où je voudrais d'hériter et d'ajouter.
    • Ah, gotcha. Dans ce cas, la plupart des doc-génération déjà le faire pour vous.
    InformationsquelleAutor John Feminella
  2. 33

    Vous pouvez concaténer les docstrings facilement:

    class Foo(object):
"""
Foo Class.
This class foos around.
"""
pass
class Bar(Foo):
"""
Bar class, children of Foo
Use this when you want to Bar around.
parent:
""" 
__doc__ += Foo.__doc__
pass

    Cependant, ce qui est inutile. La plupart des outil de génération de documentation (Sphinx et Epydoc inclus) sera déjà tirer parent docstring, y compris pour les méthodes. Si vous n'avez pas à faire quoi que ce soit.

    • En effet, la plupart des outils de documentation le faire. Mais l'aide intégrée() fonction qui ne fonctionne pas.
    • peut-être que c'est un bug qui devrait être déclarée?
    • Sphinx ne semble pas être fait pour que moi, peut-être parce que ma mère est "privé" aka le nom commence par un trait de soulignement.
    InformationsquelleAutor nosklo
  3. 6

    Pas particulièrement élégant, mais simple et direct:

    class X(object):
"""This class has a method foo()."""
def foo(): pass
class Y(X):
__doc__ = X.__doc__ + ' Also bar().'
def bar(): pass

    Maintenant:

    >>> print Y.__doc__
This class has a method foo(). Also bar().
    • Si vous voulez faire cela pour les Init docstring ainsi, est-il un moyen de le faire dans la définition de Y? Le seul moyen que j'ai été capable de le faire est d'utiliser __init__.__doc__ = X.__init__.__doc__ + " Also another param" à la suite de la __init__ définition dans Y mais cela semble un gâchis avec la mise en forme, causant supplémentaires ajouté des espaces.
    InformationsquelleAutor Alex Martelli
  4. 5

    Mixte stile qui peut préserver à la fois l'héritage docstring la syntaxe et le préféré de la commande peut être:

    class X(object):
"""This class has a method foo()."""
def foo(): pass
class Y(X):
""" Also bar()."""
__doc__ = X.__doc__ + __doc__
def bar(): pass

    Avec la même sortie que Alex est un:

    >>> print Y.__doc__
This class has a method foo(). Also bar().

    Glace mince: jouer avec docstring pouvez faire votre module inutilisable avec python -OO, attendez un peu:

    TypeError: cannot concatenate 'str' and 'NoneType' objects
    InformationsquelleAutor naufraghi
  5. 1

    J'ai écrit custom_inherit à donner quelques simples, poids léger outils pour la manipulation de docstring de l'héritage.

    Il est également livré avec quelques beaux styles par défaut pour la fusion des différents types de docstrings (par exemple, Numpy, Google, et reste formaté docstrings). Vous pouvez également fournir votre propre style très facilement.

    Chevauchement docstring sections s'en remettent à l'enfant l'article, sinon, ils sont fusionnés ensemble, avec une belle mise en forme.

    InformationsquelleAutor Ryan Soklaski