È appropriato utilizzare le sezioni docstring 'return' e 'args' per specificare gli stati HTTP ei parametri URL?

Question

È appropriato utilizzare le sezioni docstring 'return' e 'args' per specificare gli stati HTTP ei parametri URL?

#1 da (2 voti)

0

Sto lavorando a un progetto di applicazione web che utilizza Tornado come front-end web. Attualmente sono in procinto di scrivere documenti e aggiungere docstrings al codice base con Pydoc.

Come framework API per le applicazioni, le applicazioni Tornado sono strutturate con ciascun endpoint dell'API con una classe handler e ogni classe handler ha un metodo Python separato per ogni metodo di richiesta HTTP che l'endpoint dovrebbe gestire. Questi metodi Python hanno sempre una firma del formato get(self) , post(self) , put(self) , ecc., E non accettano alcun argomento.

Istintivamente, voglio usare Pydoc in questo modo:

class MyHandler(tornado.web.RequestHandler):
    def get(self):
         '''
         Gets stuff given some parameters.

         Args:
             some_param: data about x sent by the client.
             other_param: data about y sent by the client.

         Returns:
             HTTP 200 if everything's OK.
             HTTP 404 if other_param can't be found.
             HTTP 500 if some_param results in a database error.
         '''
         x = self.get_argument('some_param')
         y = self.get_argument('other_param')
         # ...

... Ma non sono sicuro che questa sia pratica comune (o migliore), dal momento che sto documentando i parametri URL e i codici di stato HTTP come se fossero parametri formali e valori di ritorno per una funzione che non ha né.

Si tratta di un uso accettabile o comune di docstring nelle app Web? In caso contrario, qual è il modo corretto di documentare i gestori e i loro metodi?

coding-standards python documentation

posta Jules 07.02.2017 - 09:07

fonte

1 risposta

Leggi altre domande sui tag coding-standards python documentation

Come profilare il mio codice usando la mia classe che misura il tempo? Come mappare entità e modello di dominio quando si rimuovono le cose

score 2 · Answer 1

In primo luogo, ecco il PEP sulle convenzioni di docstring su Python (così 'Ottiene elementi dati alcuni parametri . "continua sulla riga sopra e c'è una riga vuota dopo la docstring: D).

Nella mia mente, la docstring per get dovrebbe essere specificamente su get , quindi se non accetta argomenti e non restituisce nulla, non ci sarà la sezione 'Argomenti' o 'Resi' nella docstring. Se questo è il caso, e ci sono argomenti da passare a MyHandler che influenzano la funzione di get , allora questa informazione dovrebbe essere messa nella docstring della classe in questo modo:

class MyHandler(tornado.web.RequestHandler):
    '''Handle the internet.

    MyHandler(some_param, other_param).get():
        Get the internet and handle it.

        Args:
            some_param: data about x sent by the client.
            other_param: data about y sent by the client.

    MyHandler().get():
        Get the internet and mishandle it.

    Never mishandle the internet.
    '''

    def get(self):
        '''Gets stuff given some parameters.

        Returns:
            HTTP 200 if everything's OK.
            HTTP 404 if other_param can't be found.
            HTTP 500 if some_param results in a database error.
        '''

        x = ...

Ci sono anche casi in cui non vorrai docstring: se la classe genitore ha già una docstring sufficiente per get (questo non sembra essere il caso per RequestHandler ).