40. PYDOC y DOCTEST

PyDOC

Escribe el siguiente programa, en el que defino dos funciones , en tu carpeta.

# -*- coding: utf-8 -*-

def suma(x, y):
    """ Calcula la suma de dos números"""
    return x +y
    
def resta(x, y):
    """ Calcula la resta de dos números"""
    return x-y

Como puedes observar , cada función tiene un comentario. Guarda el módulo con un nombre, por ejemplo, misfunciones.py

Entra en una terminal de linux, navega hasta la carpeta donde está la función y ejecuta python

En el shell de python, importa el módulo misfunciones.py. Si imprimes misfunciones.suma.__doc__ o si escribes help(misfunciones.suma) se escribe el comentario que aparece en cada función.

Para salir de "help" pulsa la tecla q.

= = =

Si se escribe en el teminal pydoc -w misfunciones.py devolverá la salida misfunciones.html, documento que podrá leerse en un navegador web
Si en el terminal, dentro de la carpeta donde están los módulos, se escribe pydoc -p 1233 , después en el navegador, podrá entrarse en la dirección http://localhost:1233 y navegar por la información de cualquier módulo si está disponible.

= = =

DOCTEST

Permite introducir código de ejemplo para que python compruebe los resultados que el programador espera que cada función ofrezca. Por ejemplo, modificando el módulo anterior misfunciones.py

# -*- coding: utf-8 -*-

import doctest

def suma(x, y):
    """ Calcula la suma de dos números
    Argumentos: 
    x -- primer sumando 
    y -- segundo sumando 

    Test:
    >>> suma(23, 45)
    68
    
    >>> suma(24,-2)
    22
    """
    return x + y
    
def resta(x, y):
    """ Calcula la resta de dos números
    
    Argumentos: 
    x -- minuendo 
    y -- sustraendo

    Test:
    >>> resta(23, 45)
    -22
    
    >>> resta(24,-2)
    26
    """
    return x - y

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

Y desde un terminal ejecutar python misfunciones.py -v
Se observará cómo se han ejecutado los tests.

= = =

Documentación

1. Sobre doctest
2. Sobre pydoc