Saltar a contenido
 No os perd谩is mi futuro contenido, seguidme en y Youtube 馃榿

Docstrings

En Python todos los objetos cuentan con una variable especial llamada doc gracias a la que podemos describir para qu茅 sirven los y c贸mo se usan los objetos. Estas variables reciben el nombre de docstrings, cadenas de documentaci贸n.

Funciones

Python implementa un sistema muy sencillo para establecer el valor de las docstrings, 煤nicamente tenemos que crear un comentario en la primera l铆nea despu茅s de la declaraci贸n.

Note

def hola(arg):
    """Este es el docstring de la funci贸n"""
    print("Hola", arg, "!")

hola("H茅ctor")
Hola H茅ctor !

Para consultar la documentaci贸n es tan sencillo como utilizar la funci贸n reservada help y pasarle el objeto:

Note

help(hola)
Help on function hola in module __main__:

hola(arg)
    Este es el docstring de la funci贸n

Clases y m茅todos

De la misma forma podemos establecer la documentaci贸n de la clase despu茅s de la definici贸n, y de los m茅todos, como si fueran funciones:

Note

class Clase:
    """ Este es el docstring de la clase"""
    def __init__(self):
        """Este es el docstring del inicializador de clase"""
    def metodo(self):
        """Este es el docstring del metodo de clase"""

o = Clase()
help(o)
Help on Clase in module __main__ object:

class Clase(builtins.object)
 |  Este es el docstring de la clase
 |  
 |  Methods defined here:
 |  
 |  __init__(self)
 |      Este es el docstring del inicializador de clase
 |  
 |  metodo(self)
 |      Este es el docstring del metodo de clase

Scripts y m贸dulos

Cuando tenemos un script o m贸dulo, la primera l铆nea del mismo har谩 referencia al docstring del m贸dulo, en 茅l deber铆amos explicar el funcionamiento del mismo:

Note

"""Este es el docstring del m贸dulo"""
def despedir():
    """Este es el docstring de la funci贸n despedir"""
    print("Adi贸s! Me despido desde la funci贸n despedir() del m贸dulo prueba")
def saludar():
    """Este es el docstring de la funci贸n saludar"""
    print("Hola! Te saludo desde la funci贸n saludar() del m贸dulo prueba")

Note

import mi_modulo

help(mi_modulo)
Help on module mi_modulo:

NAME
    mi_modulo - Este es el docstring del m贸dulo
FUNCTIONS
    despedir()
        Este es el docstring de la funci贸n despedir
    saludar()
        Este es el docstring de la funci贸n saludar

Note

help(mi_modulo.despedir)
Help on function despedir in module mi_modulo:

despedir()
    Este es el docstring de la funci贸n despedir

Como dato curioso, tambi茅n podemos listar las variables y funciones del m贸dulo con dir():

Note

dir(mi_modulo)
['__builtins__',
 '__cached__',
 '__doc__',
 '__file__',
 '__loader__',
 '__name__',
 '__package__',
 '__spec__',
 'despedir',
 'saludar']

Como vemos muchas de ellas son especiales, seguro que muchas os suenan, os invito a comprobar sus valores:

Note

print(mi_modulo.__name__)     # Nombre del m贸dulo
print(mi_modulo.__doc__)      # Docstring del m贸dulo
print(mi_modulo.__package__)  # Nombre del paquete del m贸dulo
'mi_modulo'
Este es el docstring del m贸dulo

Paquetes

En el caso de los paquetes el docstring debemos establecerlo en la primera l铆nea del inicializador init:

Note

"""Este es el docstring de mi_paquete"""
import mi_paquete

help(mi_paquete)
Help on package mi_paquete:

NAME
    mi_paquete - Este es el docstring de mi_paquete
PACKAGE CONTENTS
    adios (package)
    hola (package)

Ejemplos

Pod茅is aprender a crear buena documentaci贸n tomando como referencia contenido de las librer铆as internas de Python:

Note

help(print)
Help on built-in function print in module builtins:

print(...)
    print(value, ..., sep=' ', end='\n', file=sys.stdout, flush=False)
    Prints the values to a stream, or to sys.stdout by default.
    Optional keyword arguments:
    file:  a file-like object (stream); defaults to the current sys.stdout.
    sep:   string inserted between values, default a space.
    end:   string appended after the last value, default a newline.
    flush: whether to forcibly flush the stream.

Note

help(len)
Help on built-in function len in module builtins:

len(obj, /)
    Return the number of items in a container.

Note

help(str)
Help on class str in module builtins:

class str(object)
 |  str(object='') -> str
 |  str(bytes_or_buffer[, encoding[, errors]]) -> str

Note

import datetime

help(datetime)
Help on module datetime:

NAME
    datetime - Fast implementation of the datetime type.
CLASSES
    builtins.object
        date
            datetime

Recordad, una buena documentaci贸n siempre dar谩 respuesta a las dos preguntas:

  • 驴Para qu茅 sirve?
  • 驴C贸mo se utiliza?

脷ltima edici贸n: 6 de Octubre de 2018