Modules¶
A TyPy program is its main file and every module it imports. The main
file runs as __main__ (STD-06), and each module runs once, at its first
import, as in CPython (MOD-03).
What TyPy accepts¶
| Item | Rule |
|---|---|
import m, import a.b, import a.b as c |
SMT-07 |
from m import name, with as, for a function, a class, a module variable or a submodule |
SMT-07 |
Modules as .py files under the main file's directory or a directory module-paths in typy.toml names, and packages as directories with an __init__.py |
MOD-01, MOD-02 |
Relative imports inside a package, such as from . import helper and from ..tools import text |
MOD-02 |
A module object: m.name reads and assigns a module variable, and the object can be printed, bound to another name and compared with is |
MOD-10 |
import tools.text runs tools/__init__.py, then tools/text.py, and
binds tools. A package is preferred to a module of the same name, and a
module of the program hides a standard library module of the same name,
as CPython's search order does.
from m import x copies the value x has when the import runs, while
m.x reads the variable as it is when it runs, so a later assignment in
m shows through m.x only. Reading a module variable that is not bound
yet raises AttributeError through m.x, and ImportError through
from m import x, with CPython's messages.
A module whose code raises is not kept: the next import runs its code again. An import inside a function runs when the function is called, and binds a variable of the function.
Module objects¶
A module object prints as CPython's does, with the path of the module's
file from the main file's directory, where CPython shows the absolute
path (OI-20): <module 'tools.text' from 'tools/text.py'>. A module's
__name__ is its qualified name, and the main file's is __main__:
def main() -> None:
print("running as", __name__)
if __name__ == "__main__":
main()
Lazy imports¶
A lazy import binds its names without running the module: the module runs
at the first use of one of them, as PEP 810 defines for Python 3.15
(MOD-06). lazy import m and lazy from m import name need the Python
floor 3.15, set with python-floor = "3.15" in typy.toml. At any
floor, a module-level __lazy_modules__ list makes the imports of the
modules it names lazy (MOD-07):
__lazy_modules__ = ["json_tools"]
In this program of two files, main.py prints before use, then
heavy runs, then 42:
# heavy.py
print("heavy runs")
VALUE = 42
# main.py
__lazy_modules__ = ["heavy"]
import heavy
print("before use")
print(heavy.VALUE)
An exception the module raises while it runs reaches the first use of the
name, and the next use runs the module again (MOD-08). Assigning the name
before its first use cancels its import, and the module does not run for
it. CPython 3.12 to 3.14 ignore __lazy_modules__ and run such a module
at its import, so a program whose output depends on when a module runs
prints differently there.
A lazy import is allowed at module level, also inside if, for,
while and with. As in CPython, it is E0103 inside a function, a
try statement, or with * or __future__; inside a class it is E0202,
since a class body holds only its methods.
Another module may use a name a module imports lazily, as
from app import heavy or app.heavy does: reading it runs the import
first, as in CPython. Assigning m.x = v through a lazily imported m
runs m's import before the assignment. A variable may be bound by more
than one lazy import, and its first use runs the one that ran last
(MOD-11). So may a function or a class, as the next section describes.
A name bound by more than one import¶
A function or a class may be bound by several imports, eager or lazy, such
as one in each branch of an if, and a call runs the one the import that
ran last bound, as in CPython (MOD-12). A name an import inside a block
binds raises NameError when that import has not run:
import sys
if len(sys.argv) > 9:
from math import sqrt as root
else:
from math import isqrt as root
print(root(17))
if len(sys.argv) > 9:
from math import floor
try:
print(floor(2.5))
except NameError as error:
print(error)
The arguments of such a call are checked against each function it may run. A name bound to more than one function or class read as a value, named in an annotation or used from another module is planned for 1.0 (E0201, MOD-14).
The switches of sys that change lazy imports from outside the module,
sys.set_lazy_imports, sys.set_lazy_imports_filter, their get_
companions and sys.lazy_modules, are E0202 (MOD-09): whether an import
is lazy is decided where it is written.
What is refused¶
Two modules that import each other at module level are a circular import,
E0422, shown with each import of the cycle (MOD-05). Moving one of the
imports into the function that uses the module breaks the cycle, as in
CPython (MOD-13); inside __init__ it is planned for 1.0 (E0426,
MOD-15). A name a module does not define is E0425, at compile time.
A module keeps one definition per name, as for def (STD-04). A name
that an import binds to a function or a class and that the module also
defines or assigns is E0202. Import it under another name:
from math import sqrt
def sqrt(value: float) -> float:
return value / 2
from m import * is planned for after 1.0. Standard library modules come
with their releases: math and sys in 0.3, dataclasses in 0.4, and
ctypes in 0.5 (LIB-04 to LIB-07, FFI-01); os, time and random
are planned for 1.0. typing and
collections.abc give Iterator and Iterable, typing gives
ClassVar, Final and Protocol, and types gives TracebackType
and ModuleType, for annotations (TYP-15, LIB-06). dataclasses gives
dataclass and field, as Classes describes
(CLS-05). The library reference describes
math and
sys, and
C interoperability describes ctypes. A
module planned for a later release is refused:
import time