Come devo gestire le docstring dei metodi delle sottoclassi?

0

Ho una classe astratta strutturata in un modo simile a questo:

class AbstractQuery(object, zip_code):
    def execute(self):
        """
        Retrieve information about a zip code
        The information returned will depend on the subclass
        """
        url, params = self._build_query(zip_code)
        response = requests.get(url, params=params)
        if self._is_valid(response):
            # etc.

    def _build_query(self, zip_code):
        """
        Returns a tuple (url, params) where
        url is the url of the API to query and
        params are the query params for the API call
        """
        raise NotImplementedError

    def _is_valid(self, response):
        """
        Returns True if response contains information necessary
        to continue processing
        """
        raise NotImplementedError

_build_query , ad esempio, farà sempre la stessa cosa, ci saranno solo piccole differenze di implementazione. Devo semplicemente mantenere la docstring nella classe base? Oppure copiarlo / incollarlo e violare DRY? Che cosa vorrebbe vedere un utente o un manutentore di queste classi?

    
posta JETM 18.07.2017 - 14:16
fonte

1 risposta

1

Da PEP 257 :

The docstring for a class should summarize its behavior and list the public methods and instance variables. If the class is intended to be subclassed, and has an additional interface for subclasses, this interface should be listed separately (in the docstring). The class constructor should be documented in the docstring for its init method. Individual methods should be documented by their own docstring.

If a class subclasses another class and its behavior is mostly inherited from that class, its docstring should mention this and summarize the differences. Use the verb "override" to indicate that a subclass method replaces a superclass method and does not call the superclass method; use the verb "extend" to indicate that a subclass method calls the superclass method (in addition to its own behavior).

Quindi, se vuoi seguire gli standard Python, usa il linguaggio che indica che il metodo è sovrascritto nella docstring della sottoclasse.

    
risposta data 18.07.2017 - 16:53
fonte

Leggi altre domande sui tag