What's the difference on docstrings with triple SINGLE quotes and triple DOUBLE quotes?
Question:
I was just wondering what is the difference between two ways of writing Python Docstrings (__doc__):
-
three single quotes:
'''
Comment goes here
'''
-
three double quotes:
"""
Comment goes here
"""
Is there any subtle difference in the way doc string could be formatted later while generating docs?
Answers:
Choose whatever style you want. Personally I use single quotes everywhere I can in Python.
The documentation states:
"String literals can be enclosed in matching single quotes (') or double quotes (")."
It doesn’t matter which one you decide to use. What does matter, is that you stick with your decision. It is good practice to choose a style and stick with it.
No. They are the same. The only difference is that the first one can contain a sequence of three unescaped double quotes, while the second can contain a sequence of three unescaped single quotes. (In other words, because the delimiters are different, there is a slight difference in what characters you can use inside them.)
Docstrings are just regular strings, and in Python there is no difference between the different string delimiters, except that, of course, you can’t use the string delimiter inside the string.
The informational document PEP 257 — Docstring Conventions recommends to use """triple double-quotes""" for consistency, and all their examples show the same:
For consistency, always use """triple double quotes""" around
docstrings. Use r"""raw triple double quotes""" if you use any
backslashes in your docstrings.
Whether to use single quotes or double quotes is only a stylistic issue in practice. There will be no difference in formatting when generating and publishing docs from these strings.
In Python both single ' ' and double " " quotes can be used to enclose the characters in a string.
For conventional strings by default, single quotations should be used, making your code more consistent with Pythons documentation. For example:
chr(97)
Returns:
'a'
When the string contains a string literal, double quotations should be used. For example "the str is 'hello'".
The triple single quotes are used for a multi-line comment:
text = '''Takes a singular word
and returns its plural.
'''
If the multi-line string contains a string literal, triple double quotations should be used:
text = """Takes a singular word
and returns its plural.
e.g. 'apple' becomes 'apples'.
"""
That being said PEP 257 recommends always using triple double quotations """ """ for docstrings for consistency. The reason it recommends using triple double quotations, even if it is a single line docstring is it makes it easier to expand the docstring into multiple lines later on.
Likewise because docstrings themselves are more likely to contain string literals, using triple double quotations also makes it easier to expand later on. The simple example below shows a one line docstring:
def plural(word, /):
assert isinstance(word, str)
"""Takes a singular word and returns its plural."""
return word + 's'
This can later be expanded:
def plural(word, /):
assert isinstance(word, str)
"""Takes a singular word and returns its plural.
e.g. 'apple' becomes 'apples'.
Parameters
----------
word : str
singular str.
Returns
-------
str
plural str.
"""
return word + 's'
Raymond Hettinger a Python core developer has made the argument that single quotations should be used where possible as the language itself prefers using single quotations. He has however noticed that the Python community itself seems to move towards a preference for use of double quotations.
He has noted that this is likely due to programmers who have migrated from languages such as C++ which use single quotes for a character 'a' and double quotes for a string "apples". I initially came from MATLAB to Python for data science and also initially tended to favour double quotations for the same reason. This habit was reinforced as most of the data science tutorials I followed also favoured double quotations. It is better practice to be consistent with the Python language itself where possible, so I now follow Raymond Hettinger’s recommendation to use single quotations for a regular string, double quotations for a string containing a string literal and use triple double quotations for a docstring.
I was just wondering what is the difference between two ways of writing Python Docstrings (__doc__):
-
three single quotes:
''' Comment goes here ''' -
three double quotes:
""" Comment goes here """
Is there any subtle difference in the way doc string could be formatted later while generating docs?
Choose whatever style you want. Personally I use single quotes everywhere I can in Python.
The documentation states:
"String literals can be enclosed in matching single quotes (') or double quotes (")."
It doesn’t matter which one you decide to use. What does matter, is that you stick with your decision. It is good practice to choose a style and stick with it.
No. They are the same. The only difference is that the first one can contain a sequence of three unescaped double quotes, while the second can contain a sequence of three unescaped single quotes. (In other words, because the delimiters are different, there is a slight difference in what characters you can use inside them.)
Docstrings are just regular strings, and in Python there is no difference between the different string delimiters, except that, of course, you can’t use the string delimiter inside the string.
The informational document PEP 257 — Docstring Conventions recommends to use """triple double-quotes""" for consistency, and all their examples show the same:
For consistency, always use
"""triple double quotes"""around
docstrings. User"""raw triple double quotes"""if you use any
backslashes in your docstrings.
Whether to use single quotes or double quotes is only a stylistic issue in practice. There will be no difference in formatting when generating and publishing docs from these strings.
In Python both single ' ' and double " " quotes can be used to enclose the characters in a string.
For conventional strings by default, single quotations should be used, making your code more consistent with Pythons documentation. For example:
chr(97)
Returns:
'a'
When the string contains a string literal, double quotations should be used. For example "the str is 'hello'".
The triple single quotes are used for a multi-line comment:
text = '''Takes a singular word
and returns its plural.
'''
If the multi-line string contains a string literal, triple double quotations should be used:
text = """Takes a singular word
and returns its plural.
e.g. 'apple' becomes 'apples'.
"""
That being said PEP 257 recommends always using triple double quotations """ """ for docstrings for consistency. The reason it recommends using triple double quotations, even if it is a single line docstring is it makes it easier to expand the docstring into multiple lines later on.
Likewise because docstrings themselves are more likely to contain string literals, using triple double quotations also makes it easier to expand later on. The simple example below shows a one line docstring:
def plural(word, /):
assert isinstance(word, str)
"""Takes a singular word and returns its plural."""
return word + 's'
This can later be expanded:
def plural(word, /):
assert isinstance(word, str)
"""Takes a singular word and returns its plural.
e.g. 'apple' becomes 'apples'.
Parameters
----------
word : str
singular str.
Returns
-------
str
plural str.
"""
return word + 's'
Raymond Hettinger a Python core developer has made the argument that single quotations should be used where possible as the language itself prefers using single quotations. He has however noticed that the Python community itself seems to move towards a preference for use of double quotations.
He has noted that this is likely due to programmers who have migrated from languages such as C++ which use single quotes for a character 'a' and double quotes for a string "apples". I initially came from MATLAB to Python for data science and also initially tended to favour double quotations for the same reason. This habit was reinforced as most of the data science tutorials I followed also favoured double quotations. It is better practice to be consistent with the Python language itself where possible, so I now follow Raymond Hettinger’s recommendation to use single quotations for a regular string, double quotations for a string containing a string literal and use triple double quotations for a docstring.