Eredita una docstring della classe genitore come attributo __doc__

Question

C'è una domanda su Inherit docstrings in Python class inheritance, ma le risposte riguardano le docstring del metodo.

La mia domanda è come ereditare una docstring di una classe genitore come attributo __doc__. Il caso è che Django rest framework genera una buona documentazione nella versione html dell'API basata sulle docstring delle classi di visualizzazione. Ma quando si eredita una classe base (con una docstring) in una classe senza una docstring, l'API non mostra la docstring.

Potrebbe benissimo essere che la sfinge e altri strumenti fanno la cosa giusta e gestiscono l'ereditarietà di doctring per me, ma il framework per il resto di django esamina l'attributo (vuoto) .__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" 

Ho provato qualcosa di simile super(SubClassWithoutDocstring, self).__doc__, ma che anche solo mi ha preso un None.

Answer 1

Dal momento che non è possibile assegnare un nuovo __doc__ docstring a una classe (in CPython almeno), si dovrà utilizzare un metaclasse:

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) 

Sì, abbiamo saltare attraverso un cerchio o due, ma il metaclass di cui sopra troverà lo __doc__ corretto, ma in modo convoluto si crea il grafico dell'ereditarietà.

Usage:

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

L'alternativa è quella di impostare __doc__ in __init__, come una variabile di istanza:

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 

Allora almeno le istanze hanno un 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' 

A partire da Python 3.3 (che ha risolto issue 12773), tu può finalmente è sufficiente impostare l'attributo __doc__ di classi personalizzate, in modo quindi è possibile utilizzare un decoratore di classe, invece:

import inspect 

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

che poi possono essere applicati in tal modo:

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

Answer 2

In questo caso particolare si potrebbe sovrascrivere anche il modo in cui il framework REST determina il nome da utilizzare per l'endpoint, ignorando il metodo .get_name().

Se si intraprende quella rotta probabilmente ci si troverà a voler definire un set di classi di base per le visualizzazioni e si sostituirà al metodo su tutta la vista di base utilizzando una semplice classe di mixaggio.

Ad esempio:

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 

Si noti inoltre che il metodo get_name sono considerate private, ed è destinata a cambiare ad un certo punto, in futuro, in modo si avrebbe bisogno di tenere sotto controllo le note di rilascio per l'aggiornamento, per eventuali modifiche lì.

Answer 3

Il modo più semplice è quello di assegnarlo come una variabile di 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__ 

E 'manuale, purtroppo, ma semplice. Per inciso, mentre formattazione di stringhe non funziona come al solito, lo fa con lo stesso metodo:

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

È anche possibile farlo utilizzando @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 

È anche possibile sovrascrivere 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 

Un avvertimento, la proprietà non può essere ereditata da altre classi, evidentemente, si deve aggiungere la proprietà in ogni classe che si desidera sovrascrivere il 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! Ma sicuramente più facile che fare la cosa della meta-classe!