Section 1: Navigating Python Documentation
Table of Contents >
Chapter 5 > Section 1
It is not the goal of this course for you to "learn Python". Our focus
is on the application of a design methodology to the Python programming
language. In fact, there are some aspects of Python that we will not
consider at all in this course. However, we would like you to be able
to continue your journey with Python after the course has ended. This
will require you to navigate through and understand Python documentation.
The Python library is organized into modules. Each module provides
functionality that is related in some way. For example, the random
module provides functionality related to the generation of pseudo-random
numbers while the os module provides operations related to the
operating system.
Documentation for Python 3.x is rooted at The
Python Standard Library. This page provides a table of contents
for all of the modules in the standard library. In addition to the
standard library, the Python
Package Index provides a repository for tens of thousands of
additional Python components that are offered under various licensing
agreements.
In this section of the course, we examine selected sections of the Python
Standard Library that illustrate language that is commonly encountered
throughout. We begin our journey with the random
module. Notice that the documentation starts with a link to the source
code for this module. While studying the source code is certainly not
a requirement for learning how to use the module, it can occasionally be
instructive to take a look at how a certain function is implemented.
The documentation then provides an overview of the functionality provided by
this module. Sometimes the overview can contain language that is quite
technical - it is not necessary to understand everything that you read
here. For example, we are told that Python "uses the Mersenne Twister
as the core generator" (ref: http://docs.python.org/3/library/random.html/).
It is not necessary to understand what this core generator is or how it
works. Other parts of this section, however, contain information that
is critical if you are to correctly use the functionality provided.
For example, referring to the core generator, the documentation goes on to
say "...it is not suitable for all purposes, and is completely unsuitable
for cryptographic purposes." (ref: http://docs.python.org/3/library/random.html).
So let's not use it to encrypt passwords or other sensitive information!
The documentation then goes on to describe bookkeeping functions, functions
for integers and functions for generating numbers in specific
distributions. Let's take a look at the documentation for the randrange
function, for example:
random.randrange([start], stop[, step])¶
Return a randomly selected element from
range(start, stop, step).
This is equivalent to
choice(range(start, stop, step)), but doesn’t
actually build
a range object.
New in version 1.5.2.
(http://docs.python.org/3/library/random.html)
The first line provides information about the number of parameters that this
function consumes and the package to which it belongs. In this case,
the function belongs to the random package and takes three
parameters. Note that any parameter in square brackets is
optional. We then have a purpose statement that tells us what the
function does. Finally, there is a comment to indicate that this
function was introduced in Python version 1.5.2.
Hence, to use the randrange function, we must first import the
random module (or import randrange from random).
Given that two of the parameters are optional, we can call the function in
any of the following ways:
>>> random.randrange(4)
- to randomly select from the integers [0, 1, 2, 3]
>>> random.randrange(3, 7)
- to randomly select from the integers [3, 4, 5, 6]
>>> random.randrange(1, 10, 2)
- to randomly select from the integers [1, 3, 5, 7, 9]
At first, library documentation may look a little overwhelming but learning
to navigate and understand it is a critical part of mastering any new
programming language.