Chapter 5. The import system 50 The Python Language Reference, Release 3.9.5 5.2 Packages Python has only one type of module object, and all modules are of this type, regardless of whether the module is implemented in Python, C, or something else. To help organize modules and provide a naming hierarchy, Python has a concept of packages . You can think of packages as the directories on a file system and modules as files within directories, but don’t take this analogy too literally since packages and modules need not originate from the file system. For the purposes of this documentation, we’ll use this convenient analogy of directories and files. Like file system directories, packages are organized hierarchically, and packages may themselves contain subpackages, as well as regular modules. 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. All modules have a name. Subpackage names are separated from their parent package name by a dot, akin to Python’s standard attribute access syntax. Thus you might have a module called sys and a package called email , which in turn has a subpackage called$_{email.mime}$ and a module within that subpackage called$_{email.mime.text}$ . Python defines two types of packages, regular packages and namespace packages . Regular packages are traditional packages as they existed in Python 3.2 and earlier. A regular package is typically implemented as a directory contain- ing an$_{__init__.py}$ file. When a regular package is imported, this$_{__init__.py}$ file is implicitly executed, and the objects it defines are bound to names in the package’s namespace. The$_{__init__.py}$ file can contain the same Python code that any other module can contain, and Python will add some additional attributes to the module when it is imported. For example, the following file system layout defines a top level$_{parent}$package with three subpackages: 5.2.1 Regular packages Importing parent.one will implicitly execute parent/__init__.py and parent/one/__init__. $_{py}$. Subsequent imports of$_{parent.two}$ or$_{parent.three}$will execute$_{parent/two/__init__.py}$ and parent/three/__init__.py respectively. A namespace package is a composite of various portions , where each portion contributes a subpackage to the parent package. Portions may reside in different locations on the file system. Portions may also be found in zip files, on the network, or anywhere else that Python searches during import. Namespace packages may or may not correspond directly to objects on the file system; they may be virtual modules that have no concrete representation. Namespace packages do not use an ordinary list for their$_{__path__}$ attribute. They instead use a custom iterable type which will automatically perform a new search for package portions on the next import attempt within that package if the path of their parent package (or$_{sys.path}$for a top level package) changes. With namespace packages, there is no parent/__init__.py file. In fact, there may be multiple parent directories found during import search, where each one is provided by a different portion. Thus$_{parent/one}$ may not be physically located next to$_{parent/two}$ . In this case, Python will create a namespace package for the top-level$_{parent}$package whenever it or one of its subpackages is imported. See also PEP 420 for the namespace package specification. 5.2.2 Namespace packages parent/ __init__ .py one/ __init__ .py two/ __init__ .py three / __init__ .py