Hériter d'une classe parent docstring en tant qu'attribut __doc__

Question

Il existe une question à propos de Inherit docstrings in Python class inheritance, mais les réponses à cette question portent sur les méthodes docstrings.

Ma question est de savoir comment hériter une docstring d'une classe parente en tant qu'attribut __doc__. L'utilisation est que Django rest framework génère une belle documentation dans la version html de votre API basée sur les docstrings de vos classes d'affichage. Mais lors de l'héritage d'une classe de base (avec une docstring) dans une classe sans docstring, l'API n'affiche pas la docstring.

Il se pourrait très bien que sphinx et d'autres outils fassent la bonne chose et traitent l'héritage de docstring pour moi, mais le cadre de repos de django regarde l'attribut (vide) .__doc__.

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" 

J'ai essayé quelque chose comme super(SubClassWithoutDocstring, self).__doc__, mais aussi ne me suis un None.

Answer 1

Puisque vous ne pouvez pas attribuer un nouveau __doc__ docstring à une classe (en CPython au moins), vous devez utiliser un métaclasse:

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) 

Oui, nous sauter à travers un cerceau ou deux, mais la métaclasse ci-dessus va trouver le bon __doc__ cependant compliqué vous faites votre graphe d'héritage.

Utilisation:

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

L'alternative est de mettre __doc__ en __init__, comme une variable d'instance:

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 

Puis au moins vos instances ont une 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' 

À partir de Python 3.3 (qui a fixé issue 12773), vous peut enfin juste définir l'attribut __doc__ des classes personnalisées, donc vous pouvez utiliser un décorateur de classe à la place:

import inspect 

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

qui peut ensuite être appliquée ainsi:

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

Answer 2

Dans ce cas particulier que vous pourriez ignorez également comment l'infrastructure REST détermine le nom à utiliser pour le point de terminaison en remplaçant la méthode .get_name(). Si vous suivez cette route, vous aurez probablement besoin de définir un ensemble de classes de base pour vos vues, et de surcharger la méthode sur toute votre vue de base en utilisant une simple classe mixin.

Par exemple:

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 

Notez également que la méthode get_name est considérée comme privée, et est susceptible de changer à un moment donné dans l'avenir, donc vous devez garder un œil sur les notes de version lors de la mise à niveau, pour tout changement là-bas.

Answer 3

La façon la plus simple est d'assigner comme une variable de classe:

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__ 

Il est manuel, malheureusement, mais simple. Soit dit en passant, alors que le formatage de ne fonctionne pas comme d'habitude, il le fait avec la même méthode:

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

Vous pouvez aussi le faire en utilisant @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 

Vous pouvez même écraser un docstring.

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 

Une mise en garde, la propriété ne peut pas être héritée par d'autres classes évidemment, vous devez ajouter la propriété dans chaque classe que vous voulez écraser le docstring.

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 

Bummer! Mais définitivement plus facile que de faire la méta classe!