Usando docstring do Python, substitua e extenda verbos no Sphinx

Question

Estou usando o Sphinx para gerar documentação de meus docstrings, que são formatados no estilo Sphinx . De acordo com PEP-257, eu deveria usar o verbo "substituir" e "estender" para indicar se os métodos herdados são substituídos ou chamados.

Se uma classe cria uma subclasse de outra classe e seu comportamento é herdado principalmente dessa classe, sua docstring deve mencionar isso e resumir as diferenças. Use o verbo "substituir" para indicar que um método da subclasse substitui um método da superclasse e não chama o método da superclasse; use o verbo "estender" para indicar que um método da subclasse chama o método da superclasse (além de seu próprio comportamento).

Como sou novo nisso, não está claro para mim como devo fazer isso no formato Esfinge. Simplesmente uso uma das palavras em minha descrição ou há uma chave como :return:essa que devo aplicar? Essa instrução é dada no nível da subclasse . É para lá que os verbos vão ou devo adicioná-los aos métodos individuais também?

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")

Como seria um conjunto simples mas correto de docstrings class Be seus métodos?

Answer 1

Um exemplo direto da documentação do Python é a defaultdictcoleção. Ele substitui apenas um método de dicionário (o __missing__(key)método).

defaultdict é uma subclasse da classe dict integrada. Ele substitui um método (...) A funcionalidade restante é a mesma que para a classe dict e não está documentada aqui. (...) Todos os argumentos restantes são tratados da mesma forma como se fossem passados ​​para o construtor dict, incluindo a palavra-chave argumentos.

A documentação afirma isso explicitamente em prosa, documenta o método sobrescrito e explica a diferença nos parâmetros entre as assinaturas do construtor da superclasse e da subclasse.

Eu simplesmente uso uma das palavras em minha descrição ou esta é uma chave como: retornar: que eu preciso aplicar?

O que você chama de "chave" é, na verdade, chamado de seção docstring . Não há uma "seção docstring" específica para indicar "override" ou "extends", porque isso está implícito. Se a subclasse define um método com exatamente o mesmo nome de um método de sua superclasse, esse método está necessariamente sobrescrevendo ou estendendo.

Em conclusão, você ficaria surpreso em saber que sua documentação está realmente correta. No máximo, você pode adicionar "substituições" e "extensões" verbalmente junto com uma referência cruzada para os métodos da superclasse, assim:

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")

Seu exemplo carece de parâmetros nas assinaturas, a seguinte resposta mostra como métodos sobrecarregados e estendidos com parâmetros diferentes podem ser documentados .