String literal with triple quotes in function definitions

A string literal is simply a string given literally in the source code. Whether it is a docstring or another string does not matter. See the Python language documentation section on string literals for all the details, but you probably don't need these details now.

A few examples:

"abc"
'Guido'
r"""Norwegian Blue"""

What you're talking about (I think) are called docstrings (Thanks Boud for the link).

def foo():
    """This function does absolutely nothing"""

Now, if you type help(foo) from the interpreter, you'll get to see the string that I put in the function. You can also access that string by foo.__doc__

Of course, string literals are just that -- literal strings.

a = "This is a string literal"  #the string on the right side is a string literal, "a" is a string variable.

or

foo("I'm passing this string literal to a function")

They can be defined in a bunch of ways:

'single quotes'
"double quotes"
""" triple-double quotes """  #This can contain line breaks!

or even 

#This can contain line breaks too!  See?
''' triple-single 
    quotes '''

Well, it can be helpful to take a look at the concepts of expressions, literals, and strings.

Strings, expressions, and literals

In a program, we have to represent various types of data. One type of data is integer numbers; another type is floating-point numbers.

A value of some type can be yielded in various ways, i.e., through various expressions. An expression is any snippet of a program that "creates" a value. For example, in the Python expression below, the expression 2+2 yields the value 4. The assignment operator = puts the yielded value 4 in a variable named i:

i = 2+2

Given the statement above, the expression below yields the same value 4, but now this expression contains only a variable:

i

Below, we yielded a value by an arithmetic expression, and then yielded it by a variable (which is also an expression).

Languages, however, should provide a syntax to yield basic values directly. For example, the 2 in the expression above retrieves the value 2. Expressions that yield basic values directly are called literals. Both expressions 2+2 and 4 yield the same value, 4, but the second expression is a very basic way to represent the operation, provided by the language, with no need of executing an explicit operation, so it is a literal.

String literals and multiline strings

A very important type of data is text, a sequence of letters, digits, and other characters. This type is usually called string.

A string literal, in this way, is a literal that yields a string. In Python, those literals are marked by many ways (i.e, there are many syntaxes for string literals). You can for example put a single or double quote at either the beginning or the end of the literal:

"A string literal"

'Another string literal'

Other ways are to put three single or double quotes in the same positions. In this case, the literal can span through multiple lines:

"""A single line string literal"""

"""A multiline
string literal"""

'''Another multiline
string literal'''

Note that whatever syntax you choose to a string literal, it does not change its value. A single-quoted string is equal to a double-quoted string with the same characters, and a three-quote string is equal to a one-quote string with the same content:

>>> "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 and why should they be string literals

What the documentation is saying is that you can put a string literal just after the method declaration and this literal will be used as documentation - what we use to call a docstring. It does not matter if you use single- or double-quoted strings, or one- or three-quote strings either: it just needs to be a literal.

Consider the functions below:

def f1(value):
    "Doc for f1"
    return value + 1

def f2(value):
    """Doc for f2"""
    return value + 2

Now, declare them in your python console and call help(f1) and help(f2). Note that the syntax of the string literal does not matter.

OTOH, you cannot use other expressions, such as variables or operations over strings, for generating your documentation. So the strings at the first line of the functions below are no 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

It should be a literal because the compiler was written explicitly to manage it as documentation. However, the compiler is not prepared to manage variables, complex expressions, etc. as documentation, so it will ignore them. In other words, it is by design.

Why use triple quote strings as docstrings?

Although any form of string literal can be used in docstrings, you may consider that documentation usually includes very long texts, with multiple lines and paragraphs. Well, since it includes many lines, better to use the literal forms which accept multiple lines, right? This is the reason why triple-quote strings are the preferred (but not mandatory) way of writing docstrings.

A marginal note

Actually, you can put a string literal in any place of a Python function:

 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"

However, only the literal in the first line makes some difference (being the documentation). The other ones are no-ops.

Tags:

Python

String

Literals

Recent Posts