En Esfinge, ¿hay una manera de documentar los parámetros junto con declarándolos?

Question

Yo prefiero documentar cada parámetro (según sea necesario) en la misma línea en la que declaro el parámetro con el fin de aplicar SECO

Si tengo código como este:

def foo(
        flab_nickers, # a series of under garments to process
        has_polka_dots=False,
        needs_pressing=False  # Whether the list of garments should all be pressed
   ):
    ...

¿Cómo puedo evitar la repetición de los parámetros de la cadena de documentación y retener a las explicaciones de los parámetros?

Quiero evitar:

def foo(
        flab_nickers, # a series of under garments to process
        has_polka_dots=False,
        needs_pressing=False  # Whether the list of garments should all be pressed
    ):
    '''Foo does whatever.

    * flab_nickers - a series of under garments to process
    * needs_pressing - Whether the list of garments should all be pressed.
      [Default False.]

Es esto posible en Python 2.6 o pitón 3 con algún tipo de manipulación decorador? ¿Hay alguna otra manera?

Answer 1

Me gustaría hacer esto.

A partir de este código.

def foo(
        flab_nickers, # a series of under garments to process
        has_polka_dots=False,
        needs_pressing=False  # Whether the list of garments should all be pressed
   ):
    ...

Me gustaría escribir un analizador que agarra las definiciones de parámetros de función y construye la siguiente:

def foo(
        flab_nickers, 
        has_polka_dots=False,
        needs_pressing=False,
   ):
   """foo

   :param flab_nickers: a series of under garments to process
   :type flab_nickers: list or tuple
   :param has_polka_dots: default False
   :type has_polka_dots: bool
   :param needs_pressing: default False, Whether the list of garments should all be pressed
   :type needs_pressing: bool
   """
    ...

Eso es algo de procesamiento de expresiones regulares bastante recta de avance de los patrones de varios argumentos de cadena para rellenar la plantilla de documentación.

Una gran cantidad de buena Python IDE (por ejemplo PyCharm) entender la notación por defecto Sphinx param y la bandera incluso vars / métodos en el ámbito que IDE piensa que no se ajustan al tipo declarado.

Tenga en cuenta la coma adicional en el código; Eso es sólo para hacer las cosas consistente. No hace ningún daño, y podría simplificar las cosas en el futuro.

También puede tratar de utilizar el compilador de Python para obtener un árbol de análisis, lo revisará y emitirá el código de actualización. He hecho esto para otros idiomas (no Phyton), así que sé un poco sobre él, pero no sé qué tan bien el apoyo es en Python.

Además, esta es una transformación de una sola vez.

El original en línea comentarios en la definición de la función realmente no siguen SECO porque es un comentario, en un lenguaje informal, e inutilizable por cualquier pero las herramientas más sofisticadas.

Los comentarios Sphinx están más cerca de DRY porque están en el lenguaje de marcado RST, haciéndolos mucho más fáciles de procesar el uso de herramientas de texto-análisis ordinarios en docutils.

Es sólo SECO si las herramientas pueden hacer uso de ella.

Enlaces útiles: https://pythonhosted.org/an_example_pypi_project/sphinx.html#function-definitions http://sphinx-doc.org/domains.html#id1

Answer 2

anotaciones se pretende dar respuesta a este problema, en parte en Python 3:

http://www.python.org/dev/peps/pep-3107 /

No estoy seguro de si ha habido cualquier trabajo en la aplicación de éstos en Sphinx todavía.

Answer 3

No se puede hacer eso sin un preprocesador, ya que no existen comentarios para Python una vez que la fuente ha sido compilado. Para evitar repetir siempre lo mismo, quitar los comentarios y documentar los parámetros sólo en la cadena de documentación, esta es la manera estándar para documentar sus argumentos.