Triple-double quote v.s. Double quote

Question

What is the preferred way to write Python doc string?

""" or "

In the book Dive Into Python, the author provides the following example:

def buildConnectionString(params):
    """Build a connection string from a dictionary of parameters.

    Returns string."""

In another chapter, the author provides another example:

def stripnulls(data):
    "strip whitespace and nulls"
    return data.replace("\00", "").strip()

Both syntax work. The only difference to me is that """ allows us to write multi-line doc.

Are there any differences other than that?

unutbu · Accepted Answer · 2015-07-24T10:47:44.260

43

From the PEP8 Style Guide:

PEP 257 describes good docstring conventions. Note that most importantly, the """ that ends a multiline docstring should be on a line by itself, e.g.:
```
"""Return a foobang

Optional plotz says to frobnicate the bizbaz first.
"""
```
For one liner docstrings, it's okay to keep the closing """ on the same line.

PEP 257 recommends using triple quotes, even for one-line docstrings:

Triple quotes are used even though the string fits on one line. This makes it easy to later expand it.

Note that not even the Python standard library itself follows these recommendations consistently. For example,

edited Jul 24 '15 at 10:47

answered Jul 14 '13 at 21:24

unutbu

842,883
184
1,785
1,677

Sounds like the author of **Dive Into Python** have been using "not-so-good" syntax across the book --- Most ending """ in the examples are not on a separate line :-) – Mingyu Jul 14 '13 at 21:33
Follow the convention if you find it useful. But I'd rather not hold it against anyone for not following this particular convention. :) – unutbu Jul 14 '13 at 21:58
Thanks, @unutbu. I like the book `Dive Into Python` a lot, and Mark Pilgrim explains things rather nicely. As you pointed out, even Python standard library does not follow this convention strictly. I guess this is one of those `nice-to-have` conventions. – Mingyu Jul 14 '13 at 22:05
The Python library is rather sloppy when it comes to *any* application of the styleguides.. :-) – Martijn Pieters Jul 14 '13 at 22:39
I do not see the clause "and preferably preceded by a blank line" in PEP8, and the example is changed accordingly. – Jitse Niesen Jul 24 '15 at 10:18
@JitseNiesen: Yes, the PEP8 recommendation has changed. Thanks for the correction. – unutbu Jul 24 '15 at 10:49

score 10 · Answer 2 · edited Jun 20 '20 at 09:12

10

They're both strings, so there is no difference. The preferred style is triple double quotes (PEP 257):

For consistency, always use """triple double quotes""" around docstrings.

Use r"""raw triple double quotes""" if you use any backslashes in your docstrings. For Unicode docstrings, use u"""Unicode triple-quoted strings""".

edited Jun 20 '20 at 09:12

Community

1
1

answered Jul 14 '13 at 21:24

Blender

289,723
53
439
496

1

The `u` shouldn't be necessary in Python 3 where all strings are Unicode by default. – Jonathan Cross Apr 16 '19 at 22:35

score 0 · Answer 3 · answered Jul 14 '13 at 21:29

0

No, not really. If you are writing to a file, using triple quotes may be ideal, because you don't have to use "\n" in order to go a line down. Just make sure the quotes you start and end with are the same type(Double or Triple quotes). Here is a reliable resource if you have any more questions:

http://docs.python.org/release/1.5.1p1/tut/strings.html

answered Jul 14 '13 at 21:29

user2514631

187
1
1
6

3

Any reason you: 1) give documentation to Python 1.5.1 (released in 1998)? 2) discourage OP from using different quotes? (I am asking, because you did not explain, while it will work: http://ideone.com/tID3uI). – Tadeck Jul 14 '13 at 21:36
@Tadeck - I for one find it very interesting to look at very old Python documentation. It's always super interesting to see how many Python's best ideas were already present before Python had even been seen by anyone other than Guido. – ArtOfWarfare Aug 09 '15 at 01:51
2

If that's the case, @ArtOfWarfare, it's a better answer if you give the context that the info here was established in that version and has not changed since. – Zim Jun 10 '20 at 18:39

Super Kai - Kazuya Ito · Answer 4 · 2022-12-12T18:16:24.843

You can also use triple-double quotes for a long SQL query to improve the readability and not to scroll right to see it as shown below:

query = """
        SELECT count(*) 
        FROM (SELECT * 
              FROM student  
              WHERE grade = 2 AND major = 'Computer Science' 
              FOR UPDATE) 
        AS result;
        """

And, if using double quotes for the SQL query above, the readability is worse and you will need to scroll right to see it as shown below:

query = "SELECT count(*) FROM (SELECT * FROM student WHERE grade = 2 AND major = 'Computer Science' FOR UPDATE) AS result;"

In addition, you can also use triple-double quotes for a GraphQL query as shown below:

query = """
        {
            products(first: 5) {
                edges {
                    node {
                    id
                    handle
                    }
                }
            }
        }"""

Triple-double quote v.s. Double quote

4 Answers4

Linked