Why does a data-file path built from __file__ break under a zip import?

### What `__file__` actually is `__file__` is not a promise of a real file. It is an attribute the loader sets on the module object to describe where it got the code. For the ordinary filesystem loader it is an absolute path you can open, which is why the habit of computing sibling paths from it forms so easily: ```python import os SCHEMA = os.path.join(os.path.dirname(__file__), "schemas", "job.json") ``` This is correct exactly as long as the assumption behind it holds: that the module came from a directory on a mounted filesystem. ### Where the assumption breaks Python can import from places that are not directories. `sys.path` entries may be zip archives, handled by the standard library's zip importer; a `zipapp` bundle is one zip containing the whole application; interpreters embedded in another process may serve modules from a frozen table or a custom loader. In the zip case `__file__` is still set, and that is precisely the trap -- the string exists and looks plausible: ``` /opt/converter.pyz/converter/__init__.py ``` There is no directory named `converter.pyz`; it is a file. Asking the operating system to look inside it fails, typically with `NotADirectoryError` on Linux and macOS and a `FileNotFoundError` on Windows -- both subclasses of `OSError`. The code did not crash at import time and did not crash in your tests. It crashes the first time a request needs the schema, in whatever deployment happens to use an archive. With some loaders `__file__` is absent altogether, and the failure mode changes to `AttributeError` at import time. Neither variant can be fixed by defensive path arithmetic, because there is no path to arrive at. ### The mechanism that replaces it `importlib.resources` inverts the question. Instead of asking the filesystem where the module lives, it asks the *loader* for the resource. `files("converter")` returns a traversable object -- an abstraction with a small path-like surface, whose protocol lives in `importlib.resources.abc`: ```python from importlib.resources import files schema = files("converter").joinpath("schemas/job.json").read_text(encoding="utf-8") ``` The traversable supports `.joinpath()` and the `/` operator, `.is_file()`, `.is_dir()`, `.iterdir()`, `.name`, and the three readers `.read_text()`, `.read_bytes()` and `.open()`. Crucially it is **not** a filesystem path object and does not pretend to be one: there is no `.resolve()`, no `os.path` interoperability, and it may correspond to no path at all. That is the honesty that makes it portable. A zip-backed traversable reads bytes out of the archive; a directory-backed one reads from disk; the calling code is unchanged. The anchor argument is the *importable* package name, not the distribution name -- another place where Python's two senses of "package" cause confusion. A project installed as `document-converter` whose package is `converter` is anchored by `files("converter")`. An older loader-based helper, `pkgutil.get_data(package, resource)`, solves the same problem by returning bytes and is fine for a single read, but it lacks the traversal, directory iteration and text-decoding surface of the newer API. ### Why this is not merely theoretical A document-conversion worker that runs perfectly from a virtual environment can be repackaged as a single-file bundle for deployment, or vendored into a runtime that serves modules from an archive, and nothing about that decision touches your source. The `__file__` habit converts a deployment-format change into an application bug, discovered late and blamed on the packaging step. The same class of failure appears when code is frozen into a single-file executable, when a build tool prunes source directories, or when a resource is read from a namespace package spread across several directories -- a case where "the directory of the module" is not even well defined. ### Migration and testing The change is usually mechanical: replace each path computation with a `files()` anchor plus a read, and delete the module-level constant that held the path. Do the reads lazily rather than at import time, so a missing resource surfaces with a clear error at a defined point rather than during interpreter start-up. Test it by running the test suite against the package installed from a built wheel, and -- if archives are a real deployment target -- by building the bundle in CI and running one smoke command from it. A test that patches `__file__` or reaches into the source tree is testing your checkout, not your artefact. ### The remaining need for a real path Some consumers cannot take bytes: a subprocess that accepts a filename, or a library that wants the operating system to open the file itself. The resource API has a separate mechanism for materialising a traversable as a real path when that is genuinely required -- and it is a context manager precisely because the path may only exist for the duration of the block.