How Are Packages Structured in Python?

A package is a directory containing an __init__.py file and one or more modules inside it. A minimal package looks like this: a directory named shapes, an __init__.py file inside it, and a module such as circle.py beside that.

The __init__.py file is what makes the directory a regular package. It is executed when the package is first imported, so it is the natural place to run package-level setup and to re-export the names you want visible at the top level — writing from .circle import area in __init__.py means users can write from shapes import area rather than reaching into the submodule.

Submodules are then reached with a dotted import. Importing shapes gives you the package, and from shapes.circle import area reaches into the submodule for a single name. Importing shapes.circle binds the submodule as an attribute of the package, which is why the submodule's name is also reachable as shapes.circle afterwards.

Two details to know. Since Python 3.3 the __init__.py file is optional — a directory without it becomes an implicit namespace package, which works but cannot run code at import time, so most projects still include it. And a package is only importable if the directory containing it is on sys.path, which is why installed packages work but a folder you just created in your project directory does not until you fix the path.

A relative import inside a package is written with a leading dot, and it is resolved relative to the package rather than the top level of sys.path.

import os
import sys
import tempfile

root = tempfile.mkdtemp()
package = os.path.join(root, "shapes")
os.makedirs(package)

with open(os.path.join(package, "__init__.py"), "w", encoding="utf-8") as handle:
    handle.write("from .circle import area\n")

with open(os.path.join(package, "circle.py"), "w", encoding="utf-8") as handle:
    handle.write("def area(radius):\n    return 3.14159 * radius ** 2\n")

sys.path.insert(0, root)

from shapes import area

print(area(1))            # 3.14159

The from .circle import area line inside __init__.py uses a single leading dot, which means the current package. A single dot means this package, two dots means the parent package, and three means the grandparent. The relative form matters because it keeps the package self-contained: the modules inside it refer to each other by their position in the package, so the package can be renamed or moved without editing its internal imports.

Two things to remember. Relative imports only work inside a package — a top-level script that uses them raises an ImportError, because there is no package to be relative to. And you cannot run a module inside a package directly with python package/module.py, because that runs it as a top-level script with no package context; the fix is to run the package with python -m package.module.