Python Packages & Namespaces

Regular Packages and init.py

A directory becomes a regular package when it contains __init__.py (an empty file suffices). Importing mypkg executes that file once, and whatever it binds becomes the package's attribute surface — re-exporting keeps call sites short.

mypkg/
├── __init__.py      # from .core import solve
├── core.py
└── utils/
    ├── __init__.py  # subpackage marker
    └── text.py

Subdirectories without __init__.py are not classic packages; since Python 3.3 they can still import as namespace packages, which behave differently when two directories on sys.path share the same name.

Absolute and Relative Imports

Inside mypkg/utils/text.py, choose one style and stay consistent:

from mypkg.core import solve      # absolute: starts from a top-level package
from ..core import solve          # relative: one dot = current package, two = parent
from . import helpers              # sibling module in the same package

Relative dots resolve against __package__, which Python sets only when the module was imported as part of a package. Running a file directly (python text.py) leaves __package__ as None, so relative imports raise ImportError. That is why executables live at the project root or behind python -m mypkg.cli.

Namespace Packages and Failure Modes

PEP 420 dropped the __init__.py requirement: a plain directory found on sys.path becomes a namespace package, and portions with the same name across multiple paths are merged. Plugins and split distributions use this intentionally; accidental use causes confusion because dir(mypkg) shows fragments assembled from several locations and tooling cannot find a single package root.

Interview traps:

• "Why does from .x import y fail?" — the file was executed as a script, so there is no parent package.
• "Namespace or regular package?" — regular when you need __init__ side effects and a single root; namespace when one logical package spans several directories.