Nuestros programadores estrellas han agotado sus depósitos de café, buscando día y noche por la resolución, hasta que Vivian encontró la solución en Beanstalk por lo tanto hoy la compartimos contigo.
Solución:
De lo que estás hablando (creo) se llaman cadenas de documentos (Gracias Boud por el enlace).
def foo():
"""This function does absolutely nothing"""
Ahora, si escribe help(foo) del intérprete, podrás ver el string que puse en la función. También puedes acceder a eso string por foo.__doc__
Por supuesto, string los literales son solo eso: cadenas literales.
a = "This is a string literal" #the string on the right side is a string literal, "a" is a string variable.
o
foo("I'm passing this string literal to a function")
Se pueden definir de varias formas:
'single quotes'
"double quotes"
""" triple-double quotes """ #This can contain line breaks!
o incluso
#This can contain line breaks too! See?
''' triple-single
quotes '''
Bueno, puede ser útil echar un vistazo a los conceptos de expresiones, literales y cadenas.
Cadenas, expresiones y literales
En un programa, tenemos que representar varios tipos de datos. Una escribe de los datos son números enteros; otro tipo son números de coma flotante.
Un valor de algún tipo puede obtenerse de varias formas, es decir, a través de varias expresiones. Un expresión es cualquier fragmento de un programa que “crea” un valor. Por ejemplo, en la expresión de Python a continuación, el expresión2+2 produce el valor 4. El operador de asignación = pone el valor obtenido 4 en una variable llamada i:
i = 2+2
Dada la declaración anterior, la expresión a continuación produce el mismo valor 4, pero ahora esta expresión contiene sólo un variable:
i
A continuación, obtuvimos un valor por un expresión aritmética, y luego lo cedió por un variable (que también es una expresión).
Los lenguajes, sin embargo, deben proporcionar una sintaxis para producir valores básicos directamente. Por ejemplo, el 2 en la expresión anterior recupera el valor 2. Aquellas expresiones que producen valores básicos directamente se llaman literales. Ambas expresiones 2+2 y 4 arroja el mismo valor, 4, pero la segunda expresión es una forma muy básica de representar la operación, proporcionada por el lenguaje, sin necesidad de ejecutar una operación explícita, por lo que es un literal.
Literales de cadena y cadenas de varias líneas
Un tipo de datos muy importante es el texto, una secuencia de letras, dígitos y otros caracteres. Este tipo generalmente se llama string.
A string literal, de esta manera, es un literal que produce un string. En Python, esos literales están marcados de muchas formas (es decir, hay muchas sintaxis para string literales). Por ejemplo, puede poner una comilla simple o doble al principio o al final del literal:
"A string literal"
'Another string literal'
Otras formas son poner tres comillas simples o dobles en las mismas posiciones. En este caso, el literal puede abarcar varias líneas:
"""A single line string literal"""
"""A multiline
string literal"""
'''Another multiline
string literal'''
Tenga en cuenta que la sintaxis que elija para un string literal, no cambia su valor. Un solo citado string es igual a una comilla doble string con los mismos personajes y tres comillas string es igual a una cita string con el mismo contenido:
>>> "A single line string literal" == 'A single line string literal'
True
>>> """A single line string literal""" == "A single line string literal"
True
>>> # n is the character that represents a new line
>>> "A multilinenstring literal" == """A multiline
string literal"""
True
Docstrings y por qué deberían ser string literales
Lo que dice la documentación es que puede poner un string literal justo después de la declaración del método y este literal se usará como documentación, lo que usamos para llamar a docstring. No importa si usa cadenas de comillas simples o dobles, o cadenas de una o tres comillas: solo necesita ser un literal.
Considere las funciones siguientes:
def f1(value):
"Doc for f1"
return value + 1
def f2(value):
"""Doc for f2"""
return value + 2
Ahora, declarelos en su consola de Python y llame help(f1) y help(f2). Tenga en cuenta que la sintaxis del string literal no importa.
OTOH, no puede usar otras expresiones, como variables u operaciones sobre cadenas, para generar su documentación. Entonces, las cadenas en la primera línea de las funciones a continuación no hay docstring:
mydoc = "This is doc"
def f3(value):
mydoc
return value+3
def f4(value):
"This is no documentation " + "because it is concatenated"
return value+4
Debe ser literal porque el compilador fue escrito explícitamente para gestionarlo como documentación. Sin embargo, el compilador no está preparado para gestionar variables, expresiones complejas, etc. como documentación, por lo que las ignorará. En otras palabras, es por diseño.
¿Por qué utilizar cadenas de comillas triples como cadenas de documentos?
Aunque cualquier forma de string literal se puede usar en cadenas de documentos, puede considerar que la documentación generalmente incluye textos muy largos, con múltiples líneas y párrafos. Bueno, dado que incluye muchas líneas, es mejor usar las formas literales que aceptan múltiples líneas, ¿verdad? Esta es la razón por la que las cadenas de comillas triples son la forma preferida (pero no obligatoria) de escribir cadenas de documentos.
Una nota marginal
De hecho, puedes poner un string literal en cualquier lugar de una función de Python:
def flying_literals(param):
"Oh, see, a string literal!"
param += 2
"Oh, see, ANOTHER string literal!"
return param
"the above literal is irrelevant, but this one can be still MORE IRRELEVANT"
Sin embargo, solo el literal en la primera línea hace alguna diferencia (siendo la documentación). Los otros son como operaciones sin operación.
A string literal es simplemente un string dado literalmente en el código fuente. Ya sea una cadena de documentos u otra string no importa. Consulte la sección de documentación del lenguaje Python en string literales para todos los detalles, pero probablemente no los necesite ahora.
Algunos ejemplos:
"abc"
'Guido'
r"""Norwegian Blue"""