Accediendo a Docstrings en Python

1. Docstrings de una línea de Python
2. Docstrings multilínea de Python

Según el glosario de Python, docstring es la primera cadena literal que aparece inmediatamente después de definir una clase, método o función.

Las docstrings definidas después de la definición de cualquier objeto a menudo se asocian con ese objeto en particular y se puede acceder usando el atributo __doc__ junto con la función print o help(). Las docstrings generalmente se definen encerrando las cadenas literales entre comillas triples simples o triples dobles, como se muestra a continuación:

def addtwo(x):
    """Takes in a number x and adds two to it."""
    return x + 2


print(addtwo.__doc__)

Producción :

Takes in a number x and adds two to it.

Una de las mejores prácticas para escribir código limpio es proporcionar una docstring que describa cómo funciona una función o módulo en particular. Además de proporcionar información vital al desarrollador, el uso de cadenas de documentación de Sphinx se puede extraer para crear documentación hermosa en diferentes formatos, como texto sin formato, HTML, ePub o PDF.

Las docstrings se clasifican en gran medida en dos categorías:

• Linea sola
• Multilínea

Docstrings de una línea de Python

Convencionalmente, las docstrings se consideran de una sola línea solo si tanto el triple-simple como el triple-doble de apertura y cierre están en la misma línea.

Las líneas individuales suelen seguir un formato similar y son menos descriptivas. En cambio, proporcionan una breve explicación de lo que hace el objeto y su valor de retorno.

Además, las docstrings de una sola línea no deben tener un espacio en blanco inicial y siempre deben comenzar con una letra mayúscula y un punto final que marque el final. El atributo __doc__ también se puede utilizar para acceder a docstrings de una sola línea, como se muestra a continuación.

def square(x):
    """Takes in a number x and returns its square."""
    return x ** 2


print(square(10))
print(square.__doc__)

Producción :

100
Takes in a number x and adds two to it.

Docstrings multilínea de Python

De manera similar, las docstrings de varias líneas también se definen mediante el encierro de cadenas literales entre comillas triples simples o triples dobles. Sin embargo, las docstrings de varias líneas generalmente siguen una estructura o formato diferente.

Las cadenas de documentación de varias líneas suelen abarcar más de una línea. La primera línea normalmente está dedicada a proporcionar únicamente una breve descripción del objeto.

Esta descripción va seguida de una línea en blanco y una descripción más detallada del parámetro, si existe, y los argumentos de retorno del objeto en las líneas siguientes. Las bibliotecas grandes como scikit learn o pandas también incluyen una sección que incluye los paquetes disponibles dentro de esa biblioteca.

Aunque las docstrings de varias líneas generalmente tienen una estructura similar, algunas diferencias dependen del tipo de objeto. En los objetos de función, las docstrings seguirían la siguiente estructura.

def add_numbers(x, y):
    """
    Function takes to arguments and returns the sum of the two

         Parameter:
                 x (int): An integer
                 y (int): Another integer

        Returns:
               sum(int): Returns an integer sum of x and y

    """
    sum = x + y
    return sum


print(add_numbers.__doc__)

Producción :

Function takes to arguments and returns the sum of the two
    
         Parameter:
                 x (int): An integer
                 y (int): Another integer
                 
        Returns:
               sum(int): Returns an integer sum of x and y

En módulos grandes como Scikit, NumPy o Pandas, las cadenas de documentación siguen el formato siguiente.

También podemos utilizar la función help() y el atributo __doc__ para acceder a las cadenas de documentación, como veremos más adelante. Podemos usar el atributo __doc__ para acceder a las cadenas de documentación en módulos como se muestra a continuación.

import pandas as pd

print(pd.__doc__)

Producción:

Las docstrings creadas bajo clases deben indicar la funcionalidad de la clase, enumerar todas las variables de instancia de esa clase específica y todos los métodos públicos. Las clases que heredan de la clase principal, también conocidas como subclases, deben tener sus cadenas de documentación a las que se puede acceder por separado.

Como se muestra a continuación, se pueden crear docstrings y acceder a ellas en clases usando el atributo __doc___.

class Car:
    """
    A class to represent a car.

    ...

    Attributes
    ----------
    manufacturer : str
        company that manufactured the car
    model : str
        model of the car
    color : str
        color of the car

    Methods
    -------
    display_info():
        Prints out the car manufacturer, model and color
    """

    def __init__(self, manufacturer, model, color):
        """
        Constructs all the attributes for the car object.

        Parameters
        ----------
                manufacturer : str
                   company that manufactured the car
                model : str
                   model of the car
                color : str
                   color of the car
        """

        self.model = model
        self.color = color
        self.manufacturer = manufacturer

    def display_info(self, color, model, manufacturer):
        """
        Prints the model of the car its color and the manufacturer.

        Parameters
        ----------
        model : str
        color : str
        manufacture: str

        Returns
        -------
        None
        """

        print(f"The {self.color} {self.model} is manufactured by {self.manufacturer}")


print(Car.__doc__)
help(Car)

Producción :

A class to represent a car.

    ...

    Attributes
    ----------
    manufacturer : str
        company that manufactured the car
    model : str
        model of the car
    color : str
        color of the car

    Methods
    -------
    display_info():
        Prints out the car manufacturer, model and color
    
Help on class Car in module __main__:

class Car(builtins.object)
 |  Car(manufacturer, model, color)
 |  
 |  A class to represent a car.
 |  
 |  ...
 |  
 |  Attributes
 |  ----------

Mientras que los docstrings de Python parecen desempeñar funciones similares para ayudar a los desarrolladores a comprender su código, los intérpretes ignoran los comentarios. En Python, los comentarios de una sola línea están precedidos por un símbolo de almohadilla y no pueden tener más de una línea.

Aunque los comentarios de varias líneas también se escriben entre comillas triples dobles o triples simples, los comentarios generalmente no siguen una estructura específica. A diferencia de las docstrings que parecen tener formatos ligeramente diferentes dependiendo de las circunstancias en las que se han utilizado, los comentarios, por otro lado, generalmente se utilizan de la misma manera independientemente del programa.