In this tutorial we have used help() a few times. It's great and you
can use it as much as you want to. For example, running help(str)
displays a nice list of all string methods and explanations of what they
do, and help(list.extend) explains what extending something to a list
does.
You can get help of many other things too. For example:
>>> stuff = []
>>> help(stuff.append)
Help on built-in function append:
append(object, /) method of builtins.list instance
Append object to the end of the list.
>>> help(print)
Help on built-in function print in module builtins:
print(...)
print(value, ..., sep=' ', end='\n', file=sys.stdout, flush=False)
Prints the values to a stream, or to sys.stdout by default.
Optional keyword arguments:
...Let's see what happens if we define a function
and call help() on that.
>>> def thing(stuff):
... return stuff * 2
...
>>> help(thing)
Help on function thing in module __main__:
thing(stuff)
>>>That sucked! We have no idea about what it does based on this. All we
know is that it takes a stuff argument.
This is when documentation strings or docstrings come in. All we need to
do is to add a string to the beginning of our function and it will show
up in help(the_function). Like this:
>>> def thing(stuff):
... "hello there"
... return stuff * 2
...
>>> help(thing)
Help on function thing in module __main__:
thing(stuff)
hello thereNote that docstrings are not comments. If you add a # comment to the
beginning of the function it won't show up in help().
When we did help(print), we got more than one line of help. Maybe we
could do that in our own docstring too?
>>> def thing():
... "This thing does stuff.\n\nIt always returns None."
...
>>> help(thing)
Help on function thing in module __main__:
thing()
This thing does stuff.
It always returns None.
>>>That's better, but how what if we want to do 5 lines of prints? Our
"stuff\n\nstuff\nstuff" thing would be really long and hard to work
with. But Python has multi-line strings too. They work like this:
>>> """bla bla bla
...
... bla bla
... bla bla bla"""
'bla bla bla\n\nbla bla\nbla bla bla'
>>>So we can write documented functions like this:
>>> def thing():
... """This thing does stuff.
...
... It always returns None.
... """
...
>>> help(thing)
Help on function thing in module __main__:
thing()
This thing does stuff.
It always returns None.
>>>It's recommended to always use """strings like this""" for docstrings,
even if the docstring is only one line long. This way it's easy to add
more stuff to it later.
Docstrings aren't actually limited to functions. You can use them for
documenting classes and their methods too. For example,
let's make a file like this and save it to test.py:
"""A test module.
It contains a class and a function.
"""
class Thing:
"""This is a test class."""
def thingy(self):
"""This is a test method."""
print("hello")
def do_hello():
"""This is a test function."""
thing = Thing()
thing.thingy()Then we can import it and call help on it:
>>> import test
>>> help(test)
Help on module testie:
NAME
testie - A test module.
DESCRIPTION
It contains a class and a function.
CLASSES
builtins.object
Thing
class Thing(builtins.object)
| This is a test class.
|
| Methods defined here:
|
| thingy(self)
| This is a test method.
|
| ----------------------------------------------------------------------
| Data descriptors defined here:
|
| __dict__
| dictionary for instance variables (if defined)
|
| __weakref__
| list of weak references to the object (if defined)
FUNCTIONS
do_hello()
This is a test function.
FILE
/home/akuli/testie.py
That's pretty cool. We just added docstrings to our code and Python made this thing out of it.
You might be wondering what __weakref__ is. You don't need to care
about it, and I think it would be better if help() would hide it.
There are different styles for writing docstrings. If you are contributing to another Python project, make sure to use the same style as rest of that project is using.
If you are starting a new project, then you can use whichever style you want, but don't "reinvent the wheel"; use an existing style instead instead of making up your own. Here are some examples of popular docstring styles to choose from:
Sphinx is the Python documentation tool that the official Python documentation uses. By default, sphinx expects you to write docstrings like this:
class Vehicles:
"""
The Vehicles object contains lots of vehicles.
:param arg: The arg is used for ...
:type arg: str
:ivar arg: This is where we store arg
:vartype arg: str
"""
def __init__(self, arg):
self.arg = arg
def cars(self, distance, destination):
"""We can't travel a certain distance in vehicles without fuels, so here's the fuels
:param distance: The amount of distance traveled
:type amount: int
:param bool destinationReached: Should the fuels be refilled to cover required distance?
:raises: :class:`RuntimeError`: Out of fuel
:returns: A Car mileage
:rtype: Cars
"""
...Google Style is meant to be easier to read and use without a tool like sphinx. Sphinx can be configured to use that with sphinx.ext.napoleon.
class Vehicles:
"""
The Vehicles object contains lots of vehicles.
Args:
arg (str): The arg is used for...
Attributes:
arg (str): This is where we store arg.
"""
def __init__(self, arg):
self.arg = arg
def cars(self, distance, destination):
"""We can't travel distance in vehicles without fuels, so here is the fuels
Args:
distance (int): The amount of distance traveled
destination (bool): Should the fuels refilled to cover the distance?
Raises:
RuntimeError: Out of fuel
Returns:
cars: A car mileage
"""
...Numpy is a large and popular Python library, and numpy developers have their own docstring style.
class Vehicles:
"""
The Vehicles object contains lots of vehicles.
Parameters
----------
arg : str
The arg is used for ...
*args
The variable arguments are used for ...
**kwargs
The keyword arguments are used for ...
Attributes
----------
arg : str
This is where we store arg.
"""
def __init__(self, arg):
self.arg = arg
def cars(self, distance, destination):
"""We can't travel distance in vehicles without fuels, so here is the fuels
Parameters
----------
distance : int
The amount of distance traveled
destination : bool
Should the fuels refilled to cover the distance?
Raises
------
RuntimeError
Out of fuel
Returns
-------
cars
A car mileage
"""
passI recommend using docstrings when writing code that other people will import.
The help() function is awesome, so it's good to make sure it's actually helpful.
If your code is not meant to be imported, docstrings are usually a good idea anyway. Other people reading your code will understand what it's doing without having to read through all of the code.
help()is awesome.- A
"""triple-quoted string"""string in the beginning of a function, class or file is a docstring. It shows up inhelp(). - Docstrings are not comments.
- Usually it's a good idea to add docstrings everywhere.
If you have trouble with this tutorial, please tell me about it and I'll make this tutorial better, or ask for help online. If you like this tutorial, please give it a star.
You may use this tutorial freely at your own risk. See LICENSE.