What's the difference between a Python module and a Python package?
Any Python file is a module, its name being the file's base name without the .py
extension. A package is a collection of Python modules: while a module is a single Python file, a package is a directory of Python modules containing an additional __init__.py
file, to distinguish a package from a directory that just happens to contain a bunch of Python scripts. Packages can be nested to any depth, provided that the corresponding directories contain their own __init__.py
file.
The distinction between module and package seems to hold just at the file system level. When you import a module or a package, the corresponding object created by Python is always of type module
. Note, however, when you import a package, only variables/functions/classes in the __init__.py
file of that package are directly visible, not sub-packages or modules. As an example, consider the xml
package in the Python standard library: its xml
directory contains an __init__.py
file and four sub-directories; the sub-directory etree
contains an __init__.py
file and, among others, an ElementTree.py
file. See what happens when you try to interactively import package/modules:
>>> import xml
>>> type(xml)
<type 'module'>
>>> xml.etree.ElementTree
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
AttributeError: 'module' object has no attribute 'etree'
>>> import xml.etree
>>> type(xml.etree)
<type 'module'>
>>> xml.etree.ElementTree
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
AttributeError: 'module' object has no attribute 'ElementTree'
>>> import xml.etree.ElementTree
>>> type(xml.etree.ElementTree)
<type 'module'>
>>> xml.etree.ElementTree.parse
<function parse at 0x00B135B0>
In Python there also are built-in modules, such as sys
, that are written in C, but I don't think you meant to consider those in your question.
A module is a single file (or files) that are imported under one import and used. e.g.
import my_module
A package is a collection of modules in directories that give a package hierarchy.
from my_package.timing.danger.internets import function_of_love
Documentation for modules
Introduction to packages
From the Python glossary:
It’s important to keep in mind that all packages are modules, but not all modules are packages. Or put another way, packages are just a special kind of module. Specifically, any module that contains a
__path__
attribute is considered a package.
Python files with a dash in the name, like my-file.py
, cannot be imported with a simple import
statement. Code-wise, import my-file
is the same as import my - file
which will raise an exception. Such files are better characterized as scripts whereas importable files are modules.