Come documentare gli attributi di classe in Python? [chiuso]

Sto scrivendo una classe leggera i cui attributi devono essere accessibili pubblicamente e solo a volte sovrascritti in istanze specifiche. Non esiste alcuna disposizione nel linguaggio Python per la creazione di docstring per attributi di classe, o qualsiasi tipo di attributo, per quella materia. Qual è il modo previsto e supportato, dovrebbe essercene uno, per documentare questi attributi? Attualmente sto facendo questo genere di cose:

class Albatross(object):
    """A bird with a flight speed exceeding that of an unladen swallow.

    Attributes:
    """

    flight_speed = 691
    __doc__ += """
        flight_speed (691)
          The maximum speed that such a bird can attain.
    """

    nesting_grounds = "Raymond Luxury-Yacht"
    __doc__ += """
        nesting_grounds ("Raymond Luxury-Yacht")
          The locale where these birds congregate to reproduce.
    """

    def __init__(self, **keyargs):
        """Initialize the Albatross from the keyword arguments."""
        self.__dict__.update(keyargs)

Ciò risulterà nella docstring della classe contenente la sezione docstring standard iniziale, così come le righe aggiunte per ogni attributo tramite l'assegnazione aumentata a __doc__.

Sebbene questo stile non sembri essere espressamente vietato nelle linee guida dello stile della docstring , non è nemmeno menzionato come opzione. Il vantaggio qui è che fornisce un modo per documentare gli attributi insieme alle loro definizioni, creando comunque una docstring di classe presentabile ed evitando di dover scrivere commenti che reiterano le informazioni dalla docstring. Sono ancora un po 'infastidito dal fatto che devo effettivamente scrivere due volte gli attributi; Sto considerando di utilizzare le rappresentazioni di stringa dei valori nella docstring per evitare almeno la duplicazione dei valori predefiniti.

È questa una atroce violazione delle convenzioni comunitarie ad hoc? Va bene? C'è un modo migliore? Ad esempio, è possibile creare un dizionario contenente valori e docstring per gli attributi e quindi aggiungere il contenuto alla classe __dict__e docstring verso la fine della dichiarazione di classe; questo allevierebbe la necessità di digitare due volte i nomi e i valori degli attributi. modifica : quest'ultima idea è, credo, non effettivamente possibile, almeno non senza costruire dinamicamente l'intera classe dai dati, il che sembra davvero una pessima idea a meno che non ci sia qualche altra ragione per farlo.

Sono abbastanza nuovo in Python e sto ancora elaborando i dettagli dello stile di codifica, quindi anche le critiche non correlate sono benvenute.

Per evitare confusione: il termine proprietà ha un significato specifico in python. Quello di cui stai parlando è ciò che chiamiamo attributi di classe . Dal momento che vengono sempre seguiti attraverso la loro classe, trovo che abbia senso documentarli nella doc string della classe. Qualcosa come questo:

class Albatross(object):
    """A bird with a flight speed exceeding that of an unladen swallow.

    Attributes:
        flight_speed     The maximum speed that such a bird can attain.
        nesting_grounds  The locale where these birds congregate to reproduce.
    """
    flight_speed = 691
    nesting_grounds = "Throatwarbler Man Grove"

Penso che sia molto più facile per gli occhi rispetto all'approccio nel tuo esempio. Se davvero volessi che una copia dei valori degli attributi appaia nella doc string, li metterei accanto o sotto la descrizione di ogni attributo.

Tieni presente che in Python, le stringhe di documento sono membri effettivi degli oggetti che documentano, non semplicemente annotazioni del codice sorgente. Poiché le variabili degli attributi di classe non sono oggetti in sé ma riferimenti a oggetti, non hanno modo di conservare le stringhe di documentazione proprie. Immagino che potresti sostenere le stringhe di documentazione sui riferimenti, forse per descrivere "cosa dovrebbe andare qui" invece di "cosa è effettivamente qui", ma trovo che sia abbastanza facile farlo nella doc string della classe contenente.

Citi le PEP257: Convenzioni Docstring, nella sezione Cos'è una docstring si afferma:

Le stringhe letterali che si trovano altrove nel codice Python possono anche fungere da documentazione. Non sono riconosciuti dal compilatore bytecode Python e non sono accessibili come attributi oggetto di runtime (cioè non assegnati a __doc__), ma due tipi di docstrings extra possono essere estratti dagli strumenti software:

I valori letterali stringa che si verificano immediatamente dopo una semplice assegnazione al livello superiore di un modulo, una classe o un metodo __init__ sono chiamati "attributi docstrings".

E questo è spiegato in maggiore dettaglio in PEP 258: Attribute docstrings. Come spiega sopra ʇsәɹoɈ. un attributo non è un oggetto che può possedere un __doc__ quindi non appariranno in help()o pydoc. Queste docstring possono essere utilizzate solo per la documentazione generata.

Sono usati in Sphinx con la direttiva autoattribute

Sphinx può usare commenti su una riga prima di un compito o un commento speciale dopo un compito o una docstring dopo la definizione che sarà documentata automaticamente.

Potresti abusare delle proprietà in questo senso. Le proprietà contengono un getter, un setter, un deleter e una docstring . Ingenuamente, questo diventerebbe molto prolisso:

class C:
    def __init__(self):
        self._x = None

    @property
    def x(self):
        """Docstring goes here."""
        return self._x

    @x.setter
    def x(self, value):
        self._x = value

    @x.deleter
    def x(self):
        del self._x

Quindi avrai una docstring appartenente a Cx:

In [24]: print(C.x.__doc__)
Docstring goes here.

Fare questo per molti attributi è complicato, ma potresti immaginare una funzione di aiuto myprop:

def myprop(x, doc):
    def getx(self):
        return getattr(self, '_' + x)

    def setx(self, val):
        setattr(self, '_' + x, val)

    def delx(self):
        delattr(self, '_' + x)

    return property(getx, setx, delx, doc)

class C:
    a = myprop("a", "Hi, I'm A!")
    b = myprop("b", "Hi, I'm B!")

In [44]: c = C()

In [46]: c.b = 42

In [47]: c.b
Out[47]: 42

In [49]: print(C.b.__doc__)
Hi, I'm B!

Quindi, la chiamata interattiva di Pythons helpdarà:

Help on class C in module __main__:

class C
 |  Data descriptors defined here:
 |  
 |  a
 |      Hi, I'm A!
 |  
 |  b
 |      Hi, I'm B!

che penso dovrebbe essere più o meno quello che stai cercando.

Modifica : mi rendo conto ora che forse possiamo evitare di dover passare il primo argomento a myprop, perché il nome interno non ha importanza. Se le chiamate successive di myproppossono in qualche modo comunicare tra loro, potrebbe decidere automaticamente un nome di attributo interno lungo e improbabile. Sono sicuro che ci sono modi per implementarlo, ma non sono sicuro che ne valga la pena.