¿Dónde puedo encontrar ejemplos adecuados de las Convenciones de Docstring PEP 257?

Question

PEP 257 says:

Inserte una línea en blanco antes y después de todos los docstrings (de una sola línea o multilínea) que documentan una clase - En términos generales, métodos de la clase están separados unos de otros por un único línea en blanco, y el docstring necesita ser desplazado del primer método por una línea en blanco; para simetría, poner una línea en blanco entre el encabezado de la clase y la docstring.

Pero parece que no encuentro ningún código que realmente implemente esto.

varios módulos estándar He comprobado entregados con Python 2.6, incluso buscaron específicamente para aquellos en los que se menciona el nombre de Guido. Pero incluso el código de la herramienta de revisión de código Rietveld no en mi humilde opinión no cumple (véase, por ejemplo http://code.google.com/p/rietveld/source/browse/upload.py):

class CondensedHelpFormatter(optparse.IndentedHelpFormatter): 
    """Frees more horizontal space by removing indentation from group 
     options and collapsing arguments between short and long, e.g. 
     '-o ARG, --opt=ARG' to -o --opt ARG""" 

    def format_heading(self, heading): 
    return "%s:\n" % heading 

Esta cadena de documentación de varias líneas no tiene una línea en blanco antes y la línea en blanco después de que se fuera de las comillas de cierre .

Esta clase de /usr/lib64/python2.6/site.py no tiene una línea en blanco antes, pero tiene una línea en blanco antes y después de las comillas de cierre.

class _Helper(object): 
    """Define the built-in 'help'. 
    This is a wrapper around pydoc.help (with a twist). 

    """ 

    def __repr__(self): 

¿Hay ejemplos disponibles para demostrar PEP 257?

Gracias de antemano

Answer 1

No es una respuesta directa, pero si quiere cumplir con PEP257 se puede utilizar una herramienta que escribí: https://github.com/halst/pep257

I demasiado se sorprendió al ver la cantidad de código (también en la biblioteca estándar) ni siquiera intenta cumplir con PEP257.

Probablemente, la mayoría de las personas piensan que su cadena de documentación de estilo tiene sentido, y también pensé que es algo incómodo para el estilo PEP257, pero después de usarlo durante un tiempo me enamoré de ella, y piensa que es la forma más hermosa de escribir documentos. Siempre sigo PEP257 en todos los aspectos que puedo, y escribí la herramienta para que más personas pudieran ver cómo pueden mejorar su estilo.

A modo de ejemplo, tuve una experiencia divertida con PEP8 y pep8 tool: cuando leí por primera PEP8 Me gustó y pensé lo sigo, pero cuando probé mi código en PEP8 que estaba sorprendida por lo lejos de PEP8: Sí, y qué mejor aspecto tiene mi código después de corregir esos errores de estilo.

espero que la gente tenga experiencia similar con pep257, y comenzar a seguir PEP257 felices para siempre.

Answer 2

Por lo que yo puedo ver, el documento se ha vinculado a dice:

insertar una línea en blanco después de todas las cadenas de documentación (de una sola línea o varias líneas) que el documento A de clase - en general , los métodos de la clase están separados entre sí por una única línea en blanco, y la docstring necesita ser compensada desde el primer método por una línea en blanco.

(el énfasis es mío)

Por lo tanto, los ejemplos se dan son los correctos, ya que tienen una línea en blanco después de que la cadena de documentación, separando así la siguiente declaración de método con una línea en blanco.