Python doc string: virgolette doppie virgolette v.s. Doppio preventivo

Question

Qual è il modo migliore per scrivere la stringa doc di Python?

""" o "

Nel libro Dive Into Python: http://www.diveintopython.net/getting_to_know_python/documenting_functions.html, l'autore fornisce il seguente esempio:

def buildConnectionString(params): 
    """Build a connection string from a dictionary of parameters. 

    Returns string.""" 

In un altro capitolo: http://www.diveintopython.net/object_oriented_framework/index.html#fileinfo.divein, l'autore fornisce un altro esempio:

def stripnulls(data): 
    "strip whitespace and nulls" 
    return data.replace("\00", "").strip() 

Entrambe le sintassi funzionano. L'unica differenza per me è che """ ci consente di scrivere documenti su più righe.

C'è qualche differenza oltre a quella?

Answer 1

Dal PEP8 Style Guide:

• PEP 257 descrive buone convenzioni docstring. Si noti che la maggior parte importante, il "" "che finisce un docstring multilinea dovrebbe essere su una linea di per sé, ad esempio:

  """Return a foobang 
  
  Optional plotz says to frobnicate the bizbaz first. 
  """ 
  

• Per uno docstrings fodera, va bene per mantenere la chiusura ''" sul stessa riga.

PEP 257 raccomanda usando apici tripli, anche per docstring di una sola riga:

• Le triple virgolette sono utilizzati anche se la stringa contenuta in una sola riga. Questo facilita l'espansione successiva.

Si noti che nemmeno la stessa libreria standard Python segue coerentemente queste raccomandazioni. Ad esempio,

• abcoll.py
• ftplib.py
• functools.py
• inspect.py

Answer 2

Sono entrambe stringhe, quindi non c'è differenza. Lo stile preferito è triple virgolette doppie (PEP 257):

Per coerenza, usare sempre """triple double quotes""" intorno docstring.

Utilizzare r"""raw triple double quotes""" se si utilizzano barre rovesciate nelle docstring. Per le docstring Unicode, utilizzare u"""Unicode triple-quoted strings""".

Answer 3

No, non proprio. Se stai scrivendo su un file, usare le virgolette triple può essere l'ideale, perché non devi usare "\ n" per andare giù di una riga.Assicurati solo che le virgolette che inizi e finiscano siano dello stesso tipo (virgolette doppie o triple). Qui è una risorsa affidabile se avete altre domande:

http://docs.python.org/release/1.5.1p1/tut/strings.html