python - documentar - doc test

Python: utilizando doctests para las clases

Question

¿Es posible usar el concepto doctest de Python para las clases, no solo las funciones?

De ser así, ¿dónde pondré los doctests en el docstring de la clase o en el docstring del constructor?

Para aclarar, estoy buscando algo como:

class Test:
    """
    >>> a=Test(5)
    >>> a.multiply_by_2()
    10
    """
    def __init__(self, number):
        self._number=number

    def multiply_by_2(self):
        return self._number*2

Gracias por adelantado,

Adán

Answer 1

Creo que la documentación del módulo más doctest no explica cómo manejar esto, y debería ser mejor para explicar qué hacer.

Un patrón que descubrí para probar métodos de clase que no necesitan datos de instancia, pero que podrían necesitar acceso a datos de clase, es pasar el objeto Class en lugar de una instancia.

class Test:
    """
    >>> Test.multiply_by_3(Test,2)
    6
    """
    def __init__(self, number):
        self._number=number

    _THREE = 3
    def multiply_by_3(self, x):
        return x*self._THREE

if __name__ == "__main__":
    import doctest
    doctest.testmod()

Answer 2

El módulo doctest busca cualquier docstrings en un archivo y ejecuta cualquier código incrustado, así que sí es posible usar doctest para las clases.

En cuanto a si es mejor poner los doctests en el docstring de la clase o el constructor, creo que eso depende de lo que esté documentando exactamente.

Si el docstring da una descripción general de la clase y cómo usarla, entonces creo que es mejor ponerlo en la clase.

Si el docstring es específicamente sobre cómo crear instancias de la clase, entonces debe ir en el método __init__ .

Recuerde que la intención de los doctests es principalmente tener código de ejemplo de auto-validación en la documentación, por lo que en mi humilde opinión, el aspecto de la documentación debe tener prioridad sobre el aspecto de la prueba.

Editar:

En el ejemplo anterior, no hay código para ejecutar el doctest: ejecutar python test.py -v ejecutará el código python principal que solo define la clase.

Debe agregar esto al final del archivo:

if __name__ == "__main__":
    import doctest
    doctest.testmod()

Alternativamente, si está utilizando Python 2.6 o posterior, ejecútelo con:

python -m doctest -v test.py

Answer 3

En lugar de crear instancias del objeto en cada método, podría hacer algo como esto:

class Test:
    def multiply_by_2(self):
        """
        >>> t.multiply_by_2()
        10
        """
        return self._number*2

if __name__ == "__main__":
    import doctest
    doctest.testmod(extraglobs={''t'': Test()})

Answer 4

Te falta el código para ejecutar realmente los doctest en la parte inferior del archivo:

class Test:
    <snip>

if __name__ == "__main__":
    import doctest
    doctest.testmod()

En cuanto a dónde poner las pruebas:

• Si está probando la clase como un todo, los pondré en el docstring de la clase.
• Si está probando el constructor, los pondré en el docstring del constructor.
• Si está probando un método (como parece ser en este caso), realmente lo pondría en la carpeta de documentos de ese método.