Python modules have a typical organization. To an extent, this is defined by PEP 8, about which more information can be found at http://www.python.org/dev/peps/pep-0008/.
The first line of a module can be a #! comment; a typical version looks like the following code:
#!/usr/bin/env python3
This is used to help OS tools, such as bash, locate the Python interpreter for an executable script file. For Windows, this line may be something along the lines of #!C:Python3python.exe.
Older Python 2 modules may include a coding comment to specify the encoding for the rest of the text. This may look like the following code:
# -*- coding: utf-8 -*-
The coding comment is avoided for Python 3; the OS encoding information is adequate.
The next lines of a module should be a triple-quoted module docstring that defines the contents of the module file. As with other Python docstrings, the first paragraph of the text should be a summary. This should be followed by a more complete definition of the module's contents, purpose, and usage. This may include RST markup so that the documentation tools can produce elegant-looking results from the docstring. We'll address this in Chapter 20, Quality and Documentation.
After the docstring, we can include any version control information. For example, we might have the following code:
__version__ = "2.7.18"
This is a module global variable that we might use elsewhere in our application to determine the version number of the module. This is included after the docstring, but before the body of the module. Below this, come all of the module's import statements. Conventionally, they're in a big block at the front of the module.
After the import statements, come the various class and function definitions of the module. These are presented in whatever order is required to ensure that they work correctly and make sense to someone who is reading the code.
If the file has a lot of classes, we might find that the module is a bit hard to follow. If we find ourselves using big comment billboards to break a module into sections, this is a hint that what we're writing may be more complex than a single module.
A billboard comment looks like the following example:
################################
# FUNCTIONS RELATED TO API USE #
################################
Rather than use a billboard-style comment, it's better to decompose the module into separate modules. The billboard comment should become the docstring for a new module. In some cases, class definitions might be a good idea for decomposing a complex module.
Sometimes, global variables within a module are handy. The logging module makes use of this to keep track of all of loggers that an application might create. Another example is the way the random module creates a default instance of the Random class. This allows a number of module-level functions to provide a simple API for random numbers. We're not forced to create an instance of random.Random.
The PEP-8 conventions suggest these module globals should have ALL_CAPS style names to make them visible. Using a tool like pylint for code quality checks will result in this suggestion for global variables.
The next section compares whole modules with module items.