Python Module Lifecycle, main, and Entry Points
Introduction
A Python module’s top-level code runs when it is first loaded. The same file can also serve as a command-line program, with __name__ set to "__main__". Separating reusable definitions from startup code makes a module easier to import and use.
This lesson covers the module lifecycle in PCAP-31-03 objective 1.5, within Modules and Packages (12% of the score, 6 of 40 items). You will trace imports, shared bindings, entry-point guards, and bytecode caching.
Learning objectives
After this lesson you can:
- Describe a normal first import and explain how a repeated import reuses the cached module.
- Use
sys.modulesto check whether a module is already loaded. - Predict the value of
__name__when a file is run directly and when it is imported. - Write the
if __name__ == "__main__":entry-point idiom and explain why it is needed. - Explain the role of
__pycache__and.pycfiles. - Apply the naming conventions for public and private names, and predict the effect of
__all__onfrom module import *.
What happens when you import a module
A module is an object with its own namespace. It can be loaded from a Python file, an extension, or another loader. For the ordinary source module pricing.py in these examples:
- It looks in
sys.modules, a dictionary of modules already loaded. If"pricing"refers to a module object there, Python reuses it. A cache entry set toNoneinstead blocks the import. - On a cache miss, finders locate the module. For a top-level source module, the normal path-based finder searches
sys.path. Review Python imports and name binding for the names that this process binds. - It creates a new module object, stores it in
sys.modules["pricing"], and executes the file from top to bottom inside that object's namespace. - It binds the name
pricingin the importing file.
Step 3 is the important one. Every top-level statement of the module runs: assignments, function and class definitions, but also print() calls and any other code. A function body is not executed (it is only defined), but whatever is written at the top level is.
Create two files in the same folder.
# pricing.py
print("pricing: loading")
VAT_RATE = 0.20
def with_vat(net):
return round(net * (1 + VAT_RATE), 2)
print("pricing: ready")# shop.py
print("shop: start")
import pricing
print("shop: first import done")
import pricing
print("shop: second import done")
print(pricing.with_vat(50))Running python shop.py prints:
shop: start
pricing: loading
pricing: ready
shop: first import done
shop: second import done
60.0The messages from pricing appear once, between the two shop messages. The second import pricing finds the module in sys.modules, skips the execution and only (re)binds the name. In this ordinary import sequence, both statements refer to the same cached module object. Imports under another module name, explicit reloads, or cache manipulation can change that behavior.
Checking sys.modules
import sys
import pricing
print("pricing" in sys.modules) # True
print(sys.modules["pricing"] is pricing) # Truesys.modules maps a module name (a string) to a module object. Deleting an entry (del sys.modules["pricing"]) would make the next import execute the file again, but this is a debugging trick and not something an exam question will ask you to apply to production code. An ordinary repeated import skips execution while the same module object is cached under that name. Removing a cache entry does not invalidate existing references to the old object.
Shared state through a module
Importers that use the same cached module object share its namespace.
# counter.py
count = 0
def hit():
global count
count += 1
return count# a.py
import counter
counter.hit()# main.py
import counter
import a
counter.hit()
print(counter.count) # 2Both a.py and main.py use the same counter module object, so the two calls to hit() increment the same variable and the program prints 2.
A subtle trap appears with from counter import count. That statement binds the importer’s count name to the integer object currently referenced by counter.count. Later, hit() rebinds counter.count to a new integer. The importer’s earlier binding still refers to 0. The exam likes this: after from counter import count and two calls to counter.hit(), the local count is still 0.
__name__ and the entry-point idiom
The module namespace has an attribute called __name__. Its value depends on how the file is started:
| How the file is started | Value of __name__ inside that file |
|---|---|
python pricing.py (run as the main program) |
"__main__" |
import pricing from another file |
"pricing" |
python -m mypkg.tools |
"__main__" |
import mypkg.tools |
"mypkg.tools" |
For python pricing.py and python -m pricing, the target code runs under the name __main__. When the same file is imported later by someone else, it receives its real module name.
# whoami.py
print("__name__ is", __name__)$ python whoami.py
__name__ is __main__
$ python -c "import whoami"
__name__ is whoamiWhy this matters: reusable code with a built-in test
Imagine that pricing.py should offer a function for other programs, but should also be runnable as a small command-line demo. If you put the demo code at the top level, it runs whenever the module body is executed, including the first ordinary import. The solution is the entry-point idiom:
# pricing.py
VAT_RATE = 0.20
def with_vat(net):
return round(net * (1 + VAT_RATE), 2)
if __name__ == "__main__":
print("Demo:", with_vat(100))python pricing.pyprintsDemo: 120.0, because__name__is"__main__".import pricingprints nothing, because__name__is"pricing"and the block is skipped.
The if statement runs in both cases; only its condition changes. This is not special syntax, just a normal comparison.
Worked example: tracing two files
Problem. Given the files below, what is printed by python app.py?
# util.py
print("util:", __name__)
def hello():
print("hello from", __name__)
if __name__ == "__main__":
print("util run directly")# app.py
import util
print("app:", __name__)
util.hello()Step 1: start app.py. It is the main program, so its __name__ is "__main__". Python executes the first line, import util.
Step 2: import util. The module is new, so Python executes its top-level code. The first print shows util: util (the label, then __name__, which is "util" because the file is imported).
Step 3: the definition of hello is only a definition. Nothing is printed. The if condition compares "util" with "__main__" and is false, so util run directly is not printed.
Step 4: back in app.py. print("app:", __name__) shows app: __main__.
Step 5: call util.hello(). Inside hello, __name__ is looked up in the global namespace of util, where it is "util". It prints hello from util.
Solution.
util: util
app: __main__
hello from utilWhy other answers are wrong. Someone who thinks that __name__ always belongs to the program that is run would print hello from __main__. That ignores that a function reads the globals of the module in which it is defined, not those of the caller. Someone who forgets that imports execute top-level code would omit the first line.
The __pycache__ directory
Reading text and compiling it takes time. To avoid repeating this work, CPython can compile a source module to bytecode and save it in a folder named __pycache__ next to the source file. The file name records the interpreter version, for example pricing.cpython-311.pyc.
Key facts for the exam:
- CPython normally writes a bytecode cache for imported source modules when it has permission. Options such as
-BorPYTHONDONTWRITEBYTECODEprevent writing it. Directly executingpython shop.pydoes not create a cache for that main script. - It speeds up loading, not execution. The program does not run faster once it has started.
- Timestamp-based caches validate the source modification time and size. Hash-based caches use their configured validation policy. Normally Python regenerates invalid bytecode. A source-backed cache inside
__pycache__is not imported on its own after the source file is removed. - These generated caches are normally excluded from version control (
.gitignore). Removing them causes a later load to compile the source again where needed. - The version tag in the name lets several Python versions share one source tree without conflicts.
project/
pricing.py
shop.py
__pycache__/
pricing.cpython-311.pycNotice that shop.py has no .pyc, since shop.py was the script that was started, while pricing.py was imported.
Public and private names
Python has no keyword such as private. It relies on naming conventions that you must recognise.
| Name | Meaning |
|---|---|
rate |
public: part of the interface |
_rate |
Internal-use convention. Star import skips it unless __all__ explicitly includes it. |
__rate |
inside a class, triggers name mangling (covered in the OOP chapter); at module level it is just a name that starts with two underscores |
__rate__ |
"dunder" names reserved by Python, such as __name__ and __file__ |
A leading underscore indicates internal use by convention. import pricing; pricing._internal_helper() still works.
# inventory.py
_TAX = 0.2 # internal constant
LOW_STOCK = 5 # public constant
def _normalise(code):
return code.strip().upper()
def find(code):
return _normalise(code)>>> from inventory import *
>>> LOW_STOCK
5
>>> find(" ab ")
'AB'
>>> _TAX
NameError: name '_TAX' is not definedThe star import bound LOW_STOCK and find but ignored the two names that begin with an underscore. Importing them explicitly (from inventory import _TAX) or through the module (inventory._TAX) works, which proves that this is a convention.
Controlling star imports with __all__
A module can list exactly which names from module import * should export, using the variable __all__, a sequence of strings.
# inventory.py
__all__ = ["find", "LOW_STOCK"]
LOW_STOCK = 5
HIGH_STOCK = 500
def find(code):
return code.strip().upper()>>> from inventory import *
>>> find("x")
'X'
>>> HIGH_STOCK
NameError: name 'HIGH_STOCK' is not definedHIGH_STOCK is public by naming rules, but because __all__ exists, only the listed names are exported by the star import. Two details are often tested:
__all__affects onlyfrom module import *.import inventoryfollowed byinventory.HIGH_STOCKstill works, and so doesfrom inventory import HIGH_STOCK.- If
__all__lists a name that does not exist, the star import raises anAttributeError.
Comparing the import forms
| Statement | Names created in the importer | Runs module body? | Sees names starting with _? |
|---|---|---|---|
import inventory |
inventory |
first time only | yes, as inventory._x |
import inventory as inv |
inv |
first time only | yes, as inv._x |
from inventory import find |
find |
first time only | only if named explicitly |
from inventory import * |
listed __all__ names, or non-underscore names if absent |
first ordinary load | yes, if listed in __all__ |
All four forms reuse a successful cached import under the same name. See building regular Python packages to apply this behavior to a package tree.
Common pitfalls and exam tips
- Forgetting that top-level code runs on import. If a module prints something at top level, that text appears the first time any file imports it. Count each
printcarefully and track the order in which files are loaded. - Believing a second import re-runs the file. It does not. Look for
sys.modulesin the explanation of an answer. - Confusing the file name with
__name__. The filetools.pyis"__main__"when it is started directly. Only the imported version is"tools". - Treating an underscore as access control. A normal module permits direct access to an existing underscore-prefixed name. Star import follows
__all__when it exists. - Thinking
__all__hides names. It affects only the star form. - Assuming
__pycache__is created for the script you run. It is created for imported modules. - Confusing name binding with copying.
from m import xbindsxto the current object. Later rebinding ofm.xdoes not change that binding; mutating a shared list in place is visible through both names.
Exam tip. In a tracing question, write the output lines in the order of execution next to each file. For an ordinary successful import, mark the first use of each module name as "executes" and later uses of the cached name as "reuses". Then evaluate each
if __name__ == "__main__"condition with the real starting file in mind.
Mini case study: a report module that prints on import
A team writes report.py:
# report.py
print("Building report...")
rows = [("A", 3), ("B", 7)]
print(sum(n for _, n in rows))
def total():
return sum(n for _, n in rows)A colleague imports it from a web service and complains that "Building report..." and 10 are printed in the server logs at every start. Another colleague says that the log shows the lines only once, not for every request.
Task. Explain both observations and propose a fix.
Solution.
- The two
printstatements are top-level code, so they execute whenreportis first imported. This explains the unwanted lines in the log. - Subsequent imports (in other request handlers) find
reportinsys.modules, so the body is not executed again. This explains why the lines appear only once per process. - The fix is to move the demonstration code under a guard so that it only runs when the file is started directly:
# report.py
rows = [("A", 3), ("B", 7)]
def total():
return sum(n for _, n in rows)
if __name__ == "__main__":
print("Building report...")
print(total())Importing the module is now silent; python report.py still shows the report. If the team also wants rows to stay internal, they can rename it to _rows and publish only total with __all__ = ["total"].
Key terms
- Module: an object whose namespace holds definitions and other bindings.
sys.modules: cache mapping module names to module objects; ordinary later imports reuse a successfully loaded object under that name.__name__: attribute holding"__main__"for the starting file and the module name otherwise.- Entry point: startup code, often guarded by
if __name__ == "__main__":for direct execution orpython -m. __pycache__: folder with compiled bytecode (.pyc) of imported modules.- Private-by-convention name: a name starting with
_; star import skips it unless explicitly exported by__all__. __all__: sequence of strings selecting whatfrom module import *exports.
Summary checklist
- On an ordinary cache miss, importing a source module executes its top-level code; later imports under the same name reuse
sys.modules. - I can trace the order of
printcalls across two files. -
__name__is"__main__"for the file started directly and the module name when imported. - I can write the entry-point guard and say why it is needed.
-
__pycache__stores.pycfiles for imported modules and speeds up loading only. - I can distinguish underscore conventions from the names explicitly included by
__all__. -
__all__selects star-imported names; listing an undefined export can raise an error. -
from m import xbinds the current object and does not track later rebinding ofm.x.
Official sources
- Python Institute, PCAP-31-03 syllabus: https://pythoninstitute.org/pcap-31-03-exam-syllabus (opens in a new tab)
- Python tutorial, Modules: https://docs.python.org/3.14/tutorial/modules.html (opens in a new tab)
- The import system: https://docs.python.org/3.14/reference/import.html (opens in a new tab)
__main__, top-level code environment: https://docs.python.org/3.14/library/__main__.html (opens in a new tab)
