Utilizzando Python docstring sovrascrivere ed estendere i verbi in Sphinx

Question

Sto usando Sphinx per generare la documentazione dalle mie docstring, che sono formattate nello stile Sphinx . Secondo PEP-257 dovrei usare il verbo "sovrascrivere" ed "estendere" per indicare se i metodi ereditati vengono sostituiti o chiamati.

Se una classe è sottoclassi di un'altra classe e il suo comportamento è per lo più ereditato da quella classe, la sua docstring dovrebbe menzionarlo e riassumere le differenze. Utilizzare il verbo "sovrascrivere" per indicare che un metodo di sottoclasse sostituisce un metodo di superclasse e non chiama il metodo di superclasse; utilizzare il verbo "estendere" per indicare che un metodo di sottoclasse chiama il metodo della superclasse (oltre al proprio comportamento).

Dato che sono nuovo in questo, non mi è chiaro come dovrei farlo nel formato Sphinx. Uso semplicemente una delle parole nella mia descrizione o c'è una chiave del genere :return:che dovrei applicare? Questa istruzione è data a livello di sottoclasse , è lì che vanno i verbi o li aggiungo anche ai singoli metodi?

class A:
    """This is my base class."""

    def method_a(self):
        """My base method a."""
        pass

    def method_b(self):
        """My base method b."""
        pass


class B(A):
    """This is the subclass that inherits from :class: A."""

    def method_a(self):
        """This method replaces the inherited method_a."""
        print("overridden")

    def method_b(self):
        """This method calls the inherited method_b."""
        super(B, self).method_b()
        print("extended")

A cosa class Bassomiglierebbe un semplice ma corretto insieme di docstring e dei suoi metodi?

Answer 1

Un esempio direttamente dalla documentazione di Python è la defaultdictraccolta. Sostituisce solo un metodo del dizionario (il __missing__(key)metodo).

defaultdict è una sottoclasse della classe dict incorporata. Sostituisce un metodo (...) La funzionalità rimanente è la stessa della classe dict e non è documentata qui. (...) Tutti gli argomenti rimanenti vengono trattati come se fossero passati al costruttore di dict, inclusa la parola chiave argomenti.

La documentazione lo afferma esplicitamente in prosa, documenta il metodo sovrascritto e spiega la differenza nei parametri tra le firme del costruttore di superclasse e sottoclasse.

Uso semplicemente una delle parole nella mia descrizione o questa è una chiave come: ritorno: che devo applicare?

Ciò che chiami "chiave" è in realtà chiamato sezione docstring . Non esiste una "sezione docstring" specifica per indicare "override" o "extends", perché ciò è implicito. Se la sottoclasse definisce un metodo con lo stesso identico nome di un metodo della sua superclasse, quel metodo deve necessariamente sovrascrivere o estendere.

In conclusione, saresti sorpreso di sapere che la tua documentazione è effettivamente corretta. Al massimo potresti aggiungere verbalmente "overrides" ed "extends" insieme a un riferimento incrociato ai metodi della superclasse, in questo modo:

class B(A):
    """Neither method_a nor method_b are inherited.
       Both methods are redefined in this class.
    """
    def method_a(self):
        """This method overrides :meth:`A.method_a`."""
        print("overridden")

    def method_b(self):
        """This method extends :meth:`A.method_b`."""
        super().method_b()
        print("extended")

Ad esempio, mancano parametri nelle firme, la seguente risposta mostra come documentare metodi sovraccaricati ed estesi con parametri diversi .