Colons at beginning of lines in Python comments

Question

What's the function of the colon : before return here? Is that a style thing in Python?

def close(self):
    """ Close this connection.
    :returns: None
    """
    self.conn.close()
    return

Answer 1

Because it is in a docstring (enclosed in triple quotes) it is just like a comment and doesn't do anything other than document your code.

There are various conventions of writing docstrings - this is one of them (the reST format used by Sphinx).

The colons are typically used to describe what parameters the function expects and what the function returns, like so:

"""
This is a reST style.

:param param1: this is a first param
:param param2: this is a second param
:returns: this is a description of what is returned
:raises keyError: raises an exception
"""

In this case it says that the function is expected to return None.

See this post for more details on the various conventions.