3. Nomenclature and definitions

This section sets the scene for the rest of the document, with definitions and glossary of terms used later in the manual.

3.1. Python versions

A number of different versions, or releases, of Python are available for a Debian system. These include legacy releases, current releases, and beta or future releases of Python. The list of currently supported versions of Python can be found in the file /usr/share/python/debian_default. The file is in plain text, divided into sections with headings in square brackets. In each section there are lists of variables and values, one per line, in the format variable = value. The variable default-version in the section "DEFAULT" gives the current default Python package name, and the variable supported-versions contains a space separated list of package names corresponding to the supported versions of Python in the distribution.

In this manual, we consider the term versions to be "feature" releases -- consisting of a major and a minor version (sub minor versions are not distinguished).

3.1.1. The Default Python version

At any given time, one version of Python supported by the Debian distribution is designated as the "default" version. The package python will contain the current default version. [1] All other versions of Python available in Debian would be called pythonX.Y

The python must provide a symbolic link from the executable /usr/bin/python to the appropriate binary file /usr/bin/pythonX.Y.

3.2. Categorization of Python software

Program/script

This consists of software directly called by an end user of external program, and is independently interpreted by the Python interpreter. Usually starts with the magic bytes "#!", with the interpreter being /usr/bin/python* or /usr/bin/env python*.

Modules

This is code included in python "programs/scripts", and not invoked directly (serving as library modules in compiled languages).

Modules can be categorized under two orthogonal criteria: firstly, based on the whether or not they are implemented purely in python, like so:

Pure Python Module

These are python source code, to be interpreted by the Python interpreter just like program/script code is, and may work across many versions of Python.

Extension Module

Extensions are C code compiled for a specific version of Python, and so may only be used by one version of Python.

Another way of categorizing modules is based on whether or not they are available for use by third party scripts/modules.

Public

Public modules are available for use in other Python scripts or modules using the import directive. They are installed in one of the directories:

/usr/lib/pythonX.Y

This directory is reserved for official python modules. No other package apart from upstream official Python modules should install modules in this directory.

/usr/lib/pythonX.Y/site-packages

This is where most add-on modules live. Often, packages do not directly install modules here, but instead use utility packages like python-central and python-support to byte compile and install modules as needed.

/var/lib/python-support/pythonX.Y

Packages using python-support actually have their packages linked in from this directory, but no package should directly install modules there directly. See the documentation for python-support for details.

Packages may install public Python modules in directories specific to Python packaging utilities -- which specify the directories under which such modules should be dropped, and the the structure of these directories is defined by the utilities themselves. Please note that these directories are not in the path for Python, and are not available for modules to be imported from. At the time of writing, such utility specific directories include:

/usr/share/pycentral
/usr/share/python-support

.

Private

Private modules are modules that are used internally by a program, and are generally only accessible to that specific program or suite of programs included in the same package. They are not intended to be shared with third party programs. They are installed in special directories, for example:

/usr/lib/<package>
/usr/share/<package>
/usr/lib/games/<package>
/usr/share/games/<package>

Notes

[1]

Usually, the default Debian Python version is the latest stable upstream release that can be integrated in the distribution.