35

I was just wondering what is the difference between two ways of writing Python Docstrings (__doc__):

  1. three single quotes:

    '''
Comment goes here
'''

  2. three double quotes:

    """
Comment goes here
"""

Is there any subtle difference in the way doc string could be formatted later while generating docs?

ivanleoncz
  • 9,070
  • 7
  • 57
  • 49
prashu
  • 689
  • 2
  • 7
  • 10
  • 1
    Note: A "doc string" is just a *normal* string literal as far as the Python syntax/parser cares. The same rules for `"""`, `'''`, `"`, and `'` apply. –  Oct 26 '12 at 05:34

4 Answers4

24

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.

BrenBarn
  • 242,874
  • 37
  • 412
  • 384
  • You said: "you can't use the string delimiter inside the string", but I tested it in python3: `foo = """abc"def"""` which succeeds, and foo has the value: `'abc"def'`. Also interestingly: `foo = """abc"'def"""` is also legal, producing: `'abc"\'def'`. – Eric Leschinski Jan 13 '16 at 22:14
  • 6
    @EricLeschinski: In that case, your string delimiter is `"""` (i.e., three double quotes), not `"`. – BrenBarn Jan 14 '16 at 04:07
23

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.

wim
  • 338,267
  • 99
  • 616
  • 750
9

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.

Aesthete
  • 18,622
  • 6
  • 36
  • 45
  • Thanks @Aesthete. But, I am specially interested in understanding this for doc_strings (__doc__) for functions and classes. – prashu Oct 26 '12 at 05:26
  • 2
    @prashu A doc-strring is just .. a string. It's just *convention* (perhaps stated in a PEP somewhere?) to use the `"""` or `'''` quotes, generally to make life easier or more consistent or carry on a tradition .. and it is conceivable that some poorly written code inspection tools require it (but those are broken tools). However, the exact same string literal rules apply - try it! –  Oct 26 '12 at 05:32
  • 1
    A string is a string is a string is a string in Python. – Aesthete Oct 26 '12 at 05:38
-1

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.

Philip Yip
  • 11
  • 2