Vererben Sie eine übergeordnete Klasse docstring als __doc__ Attribut

Question

Es gibt eine Frage über Inherit docstrings in Python class inheritance, aber die Antworten dort befassen sich mit Methode Docstrings.

Meine Frage ist, wie man einen Docstring einer Elternklasse als __doc__ Attribut erbt. Der Anwendungsfall ist, dass Django rest framework nette Dokumentation in der HTML-Version Ihrer API basierend auf den Docstrings Ihrer Ansichtsklassen generiert. Wenn Sie jedoch eine Basisklasse (mit einem Docstring) in einer Klasse ohne Docstring erben, zeigt die API den Docstring nicht an.

Es kann sehr gut sein, dass Sphinx und andere Tools das Richtige tun und die Docstring-Vererbung für mich behandeln, aber django Rest Framework schaut auf das (leere) .__doc__ Attribut.

class ParentWithDocstring(object): 
    """Parent docstring""" 
    pass 


class SubClassWithoutDoctring(ParentWithDocstring): 
    pass 


parent = ParentWithDocstring() 
print parent.__doc__ # Prints "Parent docstring". 
subclass = SubClassWithoutDoctring() 
print subclass.__doc__ # Prints "None" 

Ich habe so etwas wie super(SubClassWithoutDocstring, self).__doc__ versucht, aber dass auch hat mich nur ein None.

Answer 1

Da Sie keine neue __doc__ docstring zu einer Klasse (in CPython mindestens) zuweisen können, werden Sie eine Metaklasse verwenden müssen:

import inspect 

def inheritdocstring(name, bases, attrs): 
    if not '__doc__' in attrs: 
     # create a temporary 'parent' to (greatly) simplify the MRO search 
     temp = type('temporaryclass', bases, {}) 
     for cls in inspect.getmro(temp): 
      if cls.__doc__ is not None: 
       attrs['__doc__'] = cls.__doc__ 
       break 

    return type(name, bases, attrs) 

Ja, wir durch einen zusätzlichen Reifen springen oder zwei, aber Die obige Metaklasse wird die richtige __doc__ finden, aber gewunden machen Sie Ihr Vererbungsdiagramm.

Verbrauch:

>>> class ParentWithDocstring(object): 
...  """Parent docstring""" 
... 
>>> class SubClassWithoutDocstring(ParentWithDocstring): 
...  __metaclass__ = inheritdocstring 
... 
>>> SubClassWithoutDocstring.__doc__ 
'Parent docstring' 

Die Alternative ist __doc__ in __init__, als Instanzvariable zu setzen:

def __init__(self): 
    try: 
     self.__doc__ = next(cls.__doc__ for cls in inspect.getmro(type(self)) if cls.__doc__ is not None) 
    except StopIteration: 
     pass 

Dann zumindest Ihre Instanzen haben eine docstring:

>>> class SubClassWithoutDocstring(ParentWithDocstring): 
...  def __init__(self): 
...   try: 
...    self.__doc__ = next(cls.__doc__ for cls in inspect.getmro(type(self)) if cls.__doc__ is not None) 
...   except StopIteration: 
...    pass 
... 
>>> SubClassWithoutDocstring().__doc__ 
'Parent docstring' 

Ab Python 3.3 (die behoben issue 12773), Sie kann schließlich eingestellt gerade das __doc__ Attribut von benutzerdefinierten Klassen, so ist, dann können Sie stattdessen eine Klasse Dekorateur verwenden:

>>> @inheritdocstring 
... class SubClassWithoutDocstring(ParentWithDocstring): 
...  pass 
... 
>>> SubClassWithoutDocstring.__doc__ 
'Parent docstring' 

Answer 2

Sie könnten in diesem speziellen Fall:

import inspect 

def inheritdocstring(cls): 
    for base in inspect.getmro(cls): 
     if base.__doc__ is not None: 
      cls.__doc__ = base.__doc__ 
      break 
    return cls 

die dann so angewendet werden, Überschreiben Sie auch, wie das REST-Framework den Namen für den Endpunkt festlegt, indem Sie die Methode .get_name() überschreiben.

Wenn Sie diesen Weg gehen, werden Sie wahrscheinlich eine Reihe von Basisklassen für Ihre Ansichten definieren und die Methode in Ihrer gesamten Basisansicht mit einer einfachen Mixinklasse überschreiben wollen.

Zum Beispiel:

class GetNameMixin(object): 
    def get_name(self): 
     # Your docstring-or-ancestor-docstring code here 

class ListAPIView(GetNameMixin, generics.ListAPIView): 
    pass 

class RetrieveAPIView(GetNameMixin, generics.RetrieveAPIView): 
    pass 

Beachten Sie auch, dass die get_name Methode privat betrachtet wird, und wird wahrscheinlich irgendwann in der Zukunft ändern, so müssten Sie halten Registerkarten auf den Release Notes bei der Aktualisierung, für irgendwelche Änderungen dort.

Answer 3

Der einfachste Weg ist es als Klassenvariable zuzuweisen:

class ParentWithDocstring(object): 
    """Parent docstring""" 
    pass 

class SubClassWithoutDoctring(ParentWithDocstring): 
    __doc__ = ParentWithDocstring.__doc__ 

parent = ParentWithDocstring() 
print parent.__doc__ # Prints "Parent docstring". 
subclass = SubClassWithoutDoctring() 
assert subclass.__doc__ == parent.__doc__ 

Es ist Handbuch, leider, aber unkompliziert. Übrigens, während String Formatierung nicht die übliche Art und Weise funktioniert, tut es mit der gleichen Methode:

class A(object): 
    _validTypes = (str, int) 
    __doc__ = """A accepts the following types: %s""" % str(_validTypes) 

A accepts the following types: (<type 'str'>, <type 'int'>) 

Answer 4

können Sie auch @property

class ParentWithDocstring(object): 
    """Parent docstring""" 
    pass 

class SubClassWithoutDocstring(ParentWithDocstring): 
    @property 
    def __doc__(self): 
     return None 

class SubClassWithCustomDocstring(ParentWithDocstring): 
    def __init__(self, docstring, *args, **kwargs): 
     super(SubClassWithCustomDocstring, self).__init__(*args, **kwargs) 
     self.docstring = docstring 
    @property 
    def __doc__(self): 
     return self.docstring 

>>> parent = ParentWithDocstring() 
>>> print parent.__doc__ # Prints "Parent docstring". 
Parent docstring 
>>> subclass = SubClassWithoutDocstring() 
>>> print subclass.__doc__ # Prints "None" 
None 
>>> subclass = SubClassWithCustomDocstring('foobar') 
>>> print subclass.__doc__ # Prints "foobar" 
foobar 

mit es tun können Sie sogar einen docstring überschreiben.

class SubClassOverwriteDocstring(ParentWithDocstring): 
    """Original docstring""" 
    def __init__(self, docstring, *args, **kwargs): 
     super(SubClassOverwriteDocstring, self).__init__(*args, **kwargs) 
     self.docstring = docstring 
    @property 
    def __doc__(self): 
     return self.docstring 

>>> subclass = SubClassOverwriteDocstring('new docstring') 
>>> print subclass.__doc__ # Prints "new docstring" 
new docstring 

Eine Einschränkung kann die Eigenschaft nicht offenbar von anderen Klassen geerbt werden, Sie haben die Eigenschaft, in jeder Klasse, dass Sie das docstring überschrieben werden sollen hinzuzufügen.

class SubClassBrokenDocstring(SubClassOverwriteDocstring): 
    """Broken docstring""" 
    def __init__(self, docstring, *args, **kwargs): 
     super(SubClassBrokenDocstring, self).__init__(docstring, *args, **kwargs) 

>>> subclass = SubClassBrokenDocstring("doesn't work") 
>>> print subclass.__doc__ # Prints "Broken docstring" 
Broken docstring 

Bumm! Aber definitiv einfacher als die Meta-Klasse!