ADR-0015: Compile modules into one program, with module objects¶
Status¶
Accepted
Date¶
2026-11-11
Context¶
Releases 0.1 and 0.2 compile one module, the main file, which runs as
__main__ (STD-06). Its module-level names are locals of the module's
code, so a function cannot read them: that is E0201, planned with SMT-08.
Release 0.3 builds a program from several files (MOD-01), with packages
and relative imports (MOD-02), each module initialised once in CPython's
order (MOD-03), circular imports rejected with the cycle shown (MOD-05),
import and from ... import (SMT-07) and global (SMT-08). TYP-15 and
CST-10 need Iterator, Iterable and TracebackType from typing,
collections.abc and types. Lazy imports (MOD-06 to MOD-09) follow in
the next step of the release and build on this one.
CPython defines the behaviour to keep:
import mrunsm's code the first time and binds the namemto a module object;m.xreads the module's variable as it is now.from m import xbindsxto the valuem.xhas at that moment; a later assignment inmdoes not change it.- A module whose code raised is removed from
sys.modules, so the next import runs its code again. - A function reading a module variable that is not bound yet raises
NameError: name 'x' is not defined;m.xraisesAttributeError: module 'm' has no attribute 'x';from m import xraisesImportError: cannot import name 'x' from 'm' (path). import a.binitialisesa, thena.b, bindsa, and setsbas an attribute ofaoncea.bis initialised.- A module object is written
<module 'm' from '/abs/path/m.py'>.
Options considered¶
For where module variables live:
- Keep them as locals of the module's code, and pass them to functions. Every function would take hidden parameters, and another module could not reach them.
- Static storage for each module variable, one slot per name of its checked type, which module code, functions and other modules read and write. A name a function or another module could read before it is bound gets a flag that says whether it is bound.
For which imports may form a cycle:
- Reject every cycle of
importstatements, wherever they stand. Valid programs that import inside a function to break a cycle are rejected. - Reject a cycle of imports at module level only. An import inside a function runs later, when the program calls it, and may find a module still initialising, as in CPython; the bound flags make that safe.
For modules as values, the user chose objects with attributes known at
compile time over names that only m.x may follow. For a module's text,
the user chose the path from the project root over the absolute path,
which would make the build depend on its directory (NFR-06).
Decision¶
TyPy uses static storage for module variables and rejects module-level cycles only.
- Loading.
Project::loadreads the main file and every module it imports, at any depth and inside functions too, in the order of the qualified names. A modulea.bisa/b.pyor the packagea/b/__init__.py, found first under the main file's directory, then among the standard library modules embedded intypy, so a user module hides a standard library module of the same name, as CPython's path order does. A directory without__init__.pyis not a package. Importing the main file by its own name loads a second module from it, as CPython does. - One program. Every module compiles into the one executable. Each module's code is a function of its own, run once by its first import.
- Module variables. Each name a module binds at module level is a
module variable in static storage, of the one type the checker gives
it. Module code reads and writes it as it reads a local, with definite
assignment. A function reads it, and assigns it only after
global(SMT-08). A name a function or another module reads gets a bound flag; a read while it is unbound raises CPython's exception for that read. The variables of a module are released only when the program ends. - Initialisation. A module is not started, running or done. An import of a module that is not started runs its code, which makes it running, and done when the code returns. Code that raises leaves the module not started and raises on, so the next import runs it again. Lazy imports use the same states (MOD-06).
- Cycles. The imports at the module level of each module form a graph; a cycle in it is E0422, with each module and import of the cycle shown (MOD-05). An import inside a function or a method adds no edge.
- Module objects.
import mbinds an immortal module object of typemodule, typedType::Module(m), whose attributes are its module variables and, for a package, its initialised submodules.m.xreads the variable,m.x = vassigns it with its type,n = mbinds the same object, andiscompares modules. The text is CPython's with the path from the project root,<module 'a.b' from 'a/b.py'>, the one known difference (OI-20). A value annotatedtypes.ModuleTypeis a module whose attributes are not known, so reading one through it is E0412. - Imported names.
from m import xinitialisesm, then copies the valuexhas into the importer's own variable.from a import bimports the submodulea.bwhenabinds nob.import a.b as cbindsctoa.b. A relative import resolves against the importing module's package (MOD-02). - Names for annotations.
typingandcollections.abcgiveIteratorandIterable, andtypesgivesTracebackTypeandModuleType, for annotations only in 0.3; their use as a value is E0201, planned for 0.4 withtyping(ADR-0007). - Build cache. The key of
typy run's cache covers every module's source and the compiler's build, so no change to any file or to the compiler reuses an old binary.
Consequences¶
- A function can read the variables of its module, and with
globalassign them, at the cost of a test of the bound flag where the checker cannot see that the variable is bound. from m import xandm.xgive CPython's results whenmlater assignsx, because one copies the value and the other reads the variable.- A program whose modules import each other at module level is rejected, although CPython runs some such programs; an import moved into a function, a common way to break a cycle, is accepted.
- A module's text differs from CPython's in its path only, so the output of a program that prints a module depends on the project root and not on the machine.
typing,collections.abcandtypesexist only for annotations until 0.4.
Related requirements¶
SMT-07, SMT-08, MOD-01, MOD-02, MOD-03, MOD-05, MOD-10, TYP-15, CST-10, STD-06, NFR-06, ADR-0007, ADR-0008, ADR-0012.