Littéral de chaîne avec des guillemets triples dans les définitions de fonction
Je suis le tutoriel Python) et, à un moment donné, ils expliquent comment la première instruction d'une fonction peut être un littéral de chaîne. Pour ce qui est de l'exemple, ce littéral de chaîne semble être terminé Trois "s, donnant le exemple
"""Print a Fibonacci series up to n."""
Selon cette documentation, cela servirait principalement à créer une sorte de documentation produite automatiquement.
Je me demande donc si quelqu'un ici pourrait m'expliquer en quoi consistent exactement ces littéraux en chaîne?
Ce dont vous parlez (je pense) s’appelle docstrings (Merci Boud pour le lien).
def foo():
"""This function does absolutely nothing"""
Maintenant, si vous tapez help(foo) à partir de l'interpréteur, vous verrez la chaîne que j'ai mise dans la fonction. Vous pouvez également accéder à cette chaîne par foo.__doc__
Bien sûr, les littéraux de chaîne ne sont que cela - des chaînes littérales.
a = "This is a string literal" #the string on the right side is a string literal, "a" is a string variable.
ou
foo("I'm passing this string literal to a function")
Ils peuvent être définis de différentes manières:
'single quotes'
"double quotes"
""" triple-double quotes """ #This can contain line breaks!
ou même
#This can contain line breaks too! See?
''' triple-single
quotes '''
Eh bien, il peut être utile de jeter un regard sur les concepts d’expressions, de littéraux et de chaînes.
Chaînes, expressions et littéraux
Dans un programme, nous devons représenter divers types de données. Un type des données sont des nombres entiers; Les autres types sont des nombres à virgule flottante.
Une valeur d'un certain type peut être générée de différentes manières, c'est-à-dire par le biais de divers expressions. Un expression est un extrait de programme qui "crée" une valeur. Par exemple, l'expression Python ci-dessous génère la valeur 4 et la met dans une variable. La valeur a été générée par expression2+2:
i = 2+2
Étant donné la déclaration ci-dessus, l'expression expression ci-dessous donne la même valeur 4, mais cette expression ne contient plus qu'une variable:
i
Ci-dessous, j'ai généré une valeur par un expression arithmétique et l'ai récupérée par un variable (qui est également une expression).
Les langues, cependant, devraient fournir une syntaxe permettant de générer directement des valeurs de base. Par exemple, le 2 Dans l'expression ci-dessus récupère la valeur 2. Les expressions donnant directement des valeurs de base s'appellent littéraux. Les deux expressions 2+2 Et 4 Donnent la même valeur, 4, mais la deuxième expression le donne directement, donc c'est un littéral.
Littéraux de chaîne et chaînes multilignes
Un type de données très important est le texte, une séquence de lettres, chiffres et autres caractères. Ce type s'appelle généralement chaîne.
Un chaîne littérale, de cette manière, est un littéral qui produit une chaîne. En Python, ces littéraux sont marqués de plusieurs manières (par exemple, il existe de nombreuses syntaxes pour les littéraux de chaîne). Vous pouvez par exemple mettre un guillemet simple ou double au début ou à la fin du littéral:
"A string literal"
'Another string literal'
Vous pouvez également mettre trois guillemets simples ou doubles dans les mêmes positions. Dans ce cas, le littéral peut s'étendre sur plusieurs lignes:
"""A single line string literal"""
"""A multiline
string literal"""
'''Another multiline
string literal'''
Notez que quelle que soit la syntaxe choisie pour un littéral de chaîne, sa valeur ne change pas. Une chaîne entre guillemets est égale à une chaîne à guillemets double avec les mêmes caractères, et une chaîne à trois guillemets est égale à une chaîne à guillemets avec le même contenu:
>>> "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 multiline\nstring literal" == """A multiline
string literal"""
True
Docstrings et pourquoi devraient-ils être des littéraux de chaîne
Ce que dit la documentation, c'est que vous pouvez mettre un littéral chaîne juste après la déclaration de la méthode. Ce littéral sera utilisé comme documentation - ce que nous utilisons pour appeler docstring. Peu importe que vous utilisiez des chaînes à une ou deux guillemets, ou des chaînes à une ou trois guillemets: il doit simplement s'agir d'un littéral.
Considérez les fonctions ci-dessous:
def f1(value):
"Doc for f1"
return value + 1
def f2(value):
"""Doc for f2"""
return value + 2
Maintenant, déclarez-les dans votre console python et appelez help(f1) et help(f2). Notez que la syntaxe du littéral chaîne n'a pas d'importance.
OTOH, vous ne pouvez pas utiliser d'autres expressions, telles que des variables ou des opérations sur des chaînes, pour générer votre documentation. Donc les chaînes sur la première ligne des fonctions ci-dessous ne sont pas 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
Ce devrait être un littéral car le compilateur a été écrit explicitement pour le gérer en tant que documentation. Cependant, le compilateur n'est pas prêt à gérer les variables, expressions complexes, etc. en tant que documentation, il les ignorera donc. En d'autres termes, c'est par conception.
Pourquoi utiliser des chaînes de triples guillemets comme docstrings?
Bien que toute forme de littéral de chaîne puisse être utilisée dans les docstrings, vous pouvez considérer que la documentation comprend généralement des textes très longs, comportant plusieurs lignes et paragraphes. Eh bien, comme il comprend de nombreuses lignes, il vaut mieux utiliser les formes littérales qui acceptent plusieurs lignes, non? C'est la raison pour laquelle les chaînes à trois guillemets sont le moyen préféré (mais non obligatoire) d'écrire des docstrings.
Une note marginale
En fait, vous pouvez mettre un littéral chaîne à n'importe quel endroit d'une fonction 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"
Cependant, seul le littéral de la première ligne fait une différence (en tant que documentation). Les autres ne sont comme aucune opération d'opération.
Un littéral de chaîne est simplement une chaîne donnée littéralement dans le code source. Qu'il s'agisse d'une docstring ou d'une autre chaîne n'a pas d'importance. Consultez la section section de la documentation en langage Python sur les littéraux de chaîne pour obtenir tous les détails, mais vous n’avez probablement pas besoin de ces détails maintenant.
Quelques exemples:
"abc"
'Guido'
r"""Norwegian Blue"""
Un littéral de chaîne est une chaîne dans l'une des nombreuses options de citation, qui n'est affectée à aucune variable.
Alors,
"String" # string literal
'string' # string literal
"""
Multiline
String
Literal
"""
foo = "string variable"
Lorsque vous avez un littéral de chaîne immédiatement après un bloc def, il devient partie intégrante de la documentation de cette méthode et est appelé docstring
def foo(hello):
"""This is part of the documentation for foo"""
Voici comment vous l'utiliseriez:
>>> def foo(hello):
... """This is the docstring"""
... pass
...
>>> foo.__doc__
'This is the docstring'
Dans Python, il existe plusieurs méthodes pour diviser des chaînes en plusieurs lignes. Le littéral de chaîne est l’un d’entre eux, par exemple:
s = """Hello,
world"""
print(s)
>>> Hello,
>>> world #Notice, that spaces used in the literal are kept.
Mais comme vous l'avez bien remarqué, les littéraux de chaîne sont généralement présents dans la documentation en ligne.
class MyClass(object):
"""This is my class it does this and that.
It has some cool features and I may tell you about them below.
"""
def my_method(self):
"""This is a brief description of my method."""
def important_method(self):
"""Because this method is important, I'm going to tell you
a lot about it. For example...
"""
Avant que vous ne posiez la question, voici une bonne méthode pour diviser les chaînes sur plusieurs lignes: Python parenthèse:
s = ('This is a very very long string. '
'I have to split it to multiple lines. '
'Whoa! It works!')
print(s)
>>> This is a very very long string. I have to split it to multiple lines. Whoa! It works!
Vous aurez peut-être besoin de cela pour suivre le PEP-8, qui stipule que "tu ne devras pas dépasser 80 caractères par ligne".
Happy Python piratage!
Ce sont des chaînes comme n'importe quelle autre chaîne avec des paires de ', ", ''' ou """ autour d'eux.
La forme recommandée est la triple double citation:
def some_function(s):
"""this is documentation for some_function"""
print(s)