How does Python assemble a namespace package's __path__ from several sys.path entries?

### The walk, step by step When a name is not already in `sys.modules`, the import system asks each finder on the meta path, and the path-based finder walks `sys.path` entry by entry. For a top-level name `ingest`, each entry gets three checks in a fixed priority: 1. `ingest/__init__.py` present → a regular package. **Terminate**: this is the answer. 2. `ingest.py` or a matching extension module → a module. **Terminate**. 3. A directory `ingest/` with no `__init__.py` → **record it as a portion and keep walking.** The same three checks apply within a single entry, which is why a `ingest.py` file next to a bare `ingest/` directory in the *same* directory wins: the namespace portion never terminates the search, so anything concrete beats it. Only when the walk exhausts `sys.path` with a non-empty list of recorded portions is the namespace package created, its `__path__` holding the portions in the order the entries appeared on `sys.path`. For a *sub*package the mechanics are identical, except the search runs over the parent's `__path__` rather than `sys.path`. So a nested namespace inside a namespace works the same way, one level down. ### __path__ is dynamic, and that matters A regular package's `__path__` is a plain list containing one directory. A namespace package's is a special object that remembers the parent path it was computed from and **recomputes the portions whenever that parent path changes**. Practically: import `ingest`, then append another directory containing `ingest/shipper.py` to `sys.path`, and `import ingest.shipper` works straight away — no `importlib.reload`, no cache busting. The same dynamism is why a `.pth` file or a path manipulation that runs at startup can add portions the first import never saw. It also means `__path__` is genuinely mutable state that other code can disturb. Mutating `sys.path` at runtime is already a smell; with namespace packages, it silently changes *which* files a package is made of. ### Ordering and collisions Submodule resolution walks `__path__` in order and takes the first hit, so portions must own **disjoint** submodule names. If two portions both ship `ingest/parser.py`, whichever came earlier on `sys.path` wins and the other is dead code — no warning, no error. That is the strongest argument for treating a shared namespace as a governed thing: one owner per submodule name, enforced by review or by CI rather than by hope. A subtler collision is the one that removes the namespace entirely. If any single distribution installs `ingest/__init__.py`, rule 1 fires at that entry and the whole namespace collapses to that one regular package: every other portion becomes unimportable, and the error surfaces as `ModuleNotFoundError: No module named 'ingest.shipper'` in code that has worked for months. Adding an `__init__.py` to a shared namespace is therefore a breaking change to every other distribution in it. ### Inspecting it `list(pkg.__path__)` is the direct read — the number of entries tells you how many portions merged, and the paths tell you which installed trees they came from. `pkg.__spec__.submodule_search_locations` is the same information on the spec, and `importlib.util.find_spec("pkg")` gets it without importing. When a submodule is missing, the useful question is not "is it installed?" but "is its directory in `__path__`?" — usually it is not, because a regular package terminated the walk early or the distribution landed on a `sys.path` entry that is not actually on the path in that environment. ### Cost Because a portion never terminates the search, resolving a namespace package touches **every remaining `sys.path` entry**, and each entry means a directory listing (cached, but still). On a short path this is noise. On a long path — many `.pth` additions, network or archive entries — it is a real startup cost, and it is a reason not to make top-level namespaces out of habit. A regular package, by contrast, short-circuits at the first entry that has it. ### The mental model Think of the walk as looking for one concrete answer and collecting consolation prizes on the way. Any concrete answer ends it. If there is no concrete answer, the consolation prizes are glued together, in path order, into one package whose contents are the union of the directories — and the union is recomputed, not frozen, every time the path underneath it changes.