Articles of docstring

Herramienta para verificar automáticamente el estilo de la cadena de documentos de acuerdo con PEP257

Las herramientas como pep8 pueden verificar el estilo del código fuente, pero no comprueban si las cadenas de documentación están ajustadas de acuerdo con pep257 , pep287 . ¿Hay tales herramientas? Actualizar Decidí implementar una herramienta de análisis estático por mi cuenta, ver: https://github.com/GreenSteam/pep257 En este momento, la mayor parte de pep257 está cubierta. El […]

¿Cómo puedo hacer referencia a un parámetro documentado de la función Python usando el marcado Sphinx?

Me gustaría hacer referencia a un parámetro de función previamente documentado en otra parte de una cadena de documentación de Python. Considere el siguiente ejemplo (ciertamente completamente artificial): def foo(bar): “””Perform foo action :param bar: The bar parameter “”” def nested(): “””Some nested function that depends on enclosing scope’s bar parameter. I’d like to reference […]

Triple-doble cita vs Doble cita

¿Cuál es la forma preferida de escribir la cadena doc de Python? “”” o ” En el libro Dive Into Python , el autor proporciona el siguiente ejemplo: def buildConnectionString(params): “””Build a connection string from a dictionary of parameters. Returns string.””” En otro capítulo , el autor proporciona otro ejemplo: def stripnulls(data): “strip whitespace and […]

¿Cómo express varios tipos para un solo parámetro o un valor de retorno en las cadenas de documentos procesadas por Sphinx?

A veces, una función en Python puede aceptar un argumento de un tipo flexible. O puede devolver un valor de un tipo flexible. Ahora no puedo recordar un buen ejemplo de tal función en este momento, por lo tanto, estoy demostrando cómo se ve esa función con un ejemplo de juguete a continuación. Quiero saber […]

Formato de tabla csv en las cadenas de documentación de Python (Sphinx): múltiples líneas en una celda

Estoy usando Sphinx para documentar un proyecto de Python. Parece que hay un poco de inconsistencia con la directiva .. csv-table:: . El problema principal es una nueva línea en una celda. Y mi cuestionable salud mental. El siguiente código: .. csv-table:: :header: Header1, Header2, Header3 A, B, “These lines appear as one line, even […]

Cómo especificar diferentes tipos de retorno en la cadena de documentación de Python

Actualmente estoy escribiendo documentación para mi paquete de Python usando Sphinx y el complemento autodoc. Para un valor de retorno de una función, por ejemplo, puedo escribir :returns: int: count que le dice a sphinx que hay un valor de retorno de tipo int, conteo llamado Ahora tengo una función que me permite predecesores de […]

¿Cómo documentar atributos de clase en Python?

Estoy escribiendo una clase ligera cuyos atributos están destinados a ser de acceso público, y solo a veces se anulan en instancias específicas. No hay ninguna disposición en el lenguaje Python para crear cadenas de documentos para atributos de clase, o cualquier tipo de atributos, para el caso. ¿Cuál es la forma aceptada, debería haber […]

¿Por qué python docstring se interpreta de manera diferente del comentario?

Digamos, tengo una función como esta: def myFunc(): # useful function to calculate stuff Esto producirá un error de sangría, a menos que agregue un pass : def myFunc(): # useful function to calculate stuff pass Sin embargo, si sustituyo un comentario con docstring, no es necesario ningún pass : def myFunc(): “””useful function to […]

¿Cuál es la ventaja de tener literales de cadena multilínea y de una sola línea en python?

Sé que las cadenas de comillas triples se utilizan como cadenas de documentación, pero ¿hay una necesidad real de tener dos literales de cadena? ¿Hay algún caso de uso cuando la identificación entre una línea y una línea múltiple sea útil? en Clojure tenemos 1 cadena literal, es multilínea y la usamos como cadena de […]

Implementando una propiedad de clase que preserva la cadena de documentos.

Tengo un descriptor que convierte un método en una propiedad en el nivel de clase: class classproperty(object): def __init__(self, getter): self.getter = getter self.__doc__ = getter.__doc__ def __get__(self, instance, owner): return self.getter(owner) Utilizado de esta manera: class A(object): @classproperty def test(cls): “docstring” return “Test” Sin embargo, ahora no puedo acceder al atributo __doc__ (lo cual […]