sábado, 1 de febrero de 2014

Docstrings


Documentando el código


Las cadenas de documentación o docstrings son textos que se escriben entre triples comillas dentro de los programas para documentarlos. Cuando se desarrolla un proyecto donde colaboran varias personas contar con información clara y precisa que facilite la comprensión del código es imprescindible y beneficia a todos los participantes y al propio proyecto.

Las funciones, clases y módulos deben ir convenientemente documentados. La información de las docstrings estará disponible cuando se edite el código y, también, durante la ejecución de los programas:

def area_trapecio(BaseMayor, BaseMenor, Altura):
    '''area_trapecio: Calcula el área de un trapecio.
    area_trapecio = (BaseMayor + BaseMenor) * Altura / 2''' 
    return (BaseMayor + BaseMenor) * Altura / 2
  
print(area_trapecio(10,4,4))  # Resultado: 28
print(area_trapecio.__doc__) 

La sentencia print(area_trapecio.__doc__) muestra la información de la docstrings:

area_trapecio: Calcula el área de un trapecio.
area_trapecio=(BaseMayor+BaseMenor)*Altura/2

Para recuperar la información de las docstrings en el modo interactivo utilizaremos la función help(); y en la línea de comandos haremos uso del comando pydoc3:


>>>help(area_trapecio)

$ pydoc3 os

Es frecuente agrupar varias funciones en un mismo archivo (módulo) acompañadas con información escrita suficiente que explique cómo utilizarlas, para que pueda ser consultada en cualquier momento por los programadores.

En el siguiente archivo (geometriaplana.py) se incluyen varias funciones para calcular el área de algunas figuras geométricas; de forma que puedan utilizarse en cualquier programa que escribamos con posterioridad, Las funciones incluyen documentación que explica brevemente para qué sirven y especifican los argumentos que utilizan:

geometriaplana.py:

'''Funciones de geometría plana
   Para el cálculo del área de las siguientes figuras:
   
'''

from math import pi

def area_cuadrado(Lado):
    '''Función area_cuadrado: Calcula área de un cuadrado.
    area_cuadrado = Lado ** 2 '''
    return (Lado ** 2)

def area_rectangulo(Base, Altura):
    '''Función area_rectangulo: Calcula área de un rectángulo.
    area_rectangulo = Base * Altura '''
    return (Base * Altura)

def area_triangulo(Base, Altura):
    '''Función area_triangulo: Calcula área de un triángulo.
    area_triangulo = Base * Altura / 2 '''
    return (Base * Altura / 2)

def area_paralelogramo(Base, Altura):
    '''Función area_paralelogramo: Calcula área de un paralelogramo.
    area_paralelogramo = Base * Altura '''
    return (Base * Altura)

def area_trapecio(BaseMayor, BaseMenor, Altura):
    '''Función area_trapecio: Calcula área de un trapecio.
    area_trapecio = (BaseMayor + BaseMenor) * Altura / 2'''
    return (BaseMayor + BaseMenor) * Altura / 2
   
def area_circulo(Radio):
    '''Función area_circulo: Calcula área de un circulo.
    area_ciruculo = Pi * Radio ** 2 '''
    return (pi * Radio ** 2)

 

Ver documentación en la consola



$ pydoc3 geometriaplana



Guardar la documentación en formato HTML


$ pydoc3 -w geometriaplana

La opción -w hará que se cree un archivo con la documentación en formato HTML.



Buscar documentación indicando una palabra clave


$ pydoc3 -k geometria

Resultado:
geometriaplana

Iniciar servicio web con documentación en el puerto indicado


$ pydoc3 -p 8080

A continuación, iniciar navegador web y acceder a la siguiente URL:

http://localhost:8080


Utilizar funciones en programas y acceder a documentación


#!/usr/bin/env python
# -*- coding: utf-8 -*-
#
#  calculoareas.py
# 

from geometriaplana import *  

def main():
    print(area_paralelogramo.__name__)
    print(area_paralelogramo.__doc__) 
    print("Ejemplo area_paralelogramo(6,4):", 
          area_paralelogramo(6,4),"\n")  # Resultado: 28
 
    print(area_cuadrado.__name__) 
    print(area_cuadrado.__doc__)
    print("Ejemplo area_cuadrado(5):", 
          area_cuadrado(5),"\n")  # Resultado: 25
    return 0

if __name__ == '__main__':
    main()

En el programa (calculoareas.py) se importa el módulo anterior (geometriaplana.py) para realizar algunos cálculo de áreas y, a continuación, acceder al nombre de la función que se utiliza en un momento dado (__name__) y a su documentación (__doc__).


Al ejecutar el programa obtendríamos la siguiente salida:


Si utilizamos las consolas IPython 3 QT Console o del entorno de desarrollo IDLE en las que se ofrece información mientras se escriben los comandos Python; cuando escribamos las funciones aparecerá la documentación incluida en las docstrings: