Skip to content

Python Modules, Packages, and Entry Points

Step 7 of 41

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:

  1. Describe a normal first import and explain how a repeated import reuses the cached module.
  2. Use sys.modules to check whether a module is already loaded.
  3. Predict the value of __name__ when a file is run directly and when it is imported.
  4. Write the if __name__ == "__main__": entry-point idiom and explain why it is needed.
  5. Explain the role of __pycache__ and .pyc files.
  6. Apply the naming conventions for public and private names, and predict the effect of __all__ on from 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:

  1. 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 to None instead blocks the import.
  2. 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.
  3. 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.
  4. It binds the name pricing in 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.

Python
# pricing.py
print("pricing: loading")

VAT_RATE = 0.20

def with_vat(net):
    return round(net * (1 + VAT_RATE), 2)

print("pricing: ready")
Python
# 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:

Text
shop: start
pricing: loading
pricing: ready
shop: first import done
shop: second import done
60.0

The 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

Python
import sys
import pricing

print("pricing" in sys.modules)        # True
print(sys.modules["pricing"] is pricing)  # True

sys.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.

Python
# counter.py
count = 0

def hit():
    global count
    count += 1
    return count
Python
# a.py
import counter
counter.hit()
Python
# main.py
import counter
import a
counter.hit()
print(counter.count)   # 2

Both 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.

Python
# whoami.py
print("__name__ is", __name__)
Text
$ python whoami.py
__name__ is __main__

$ python -c "import whoami"
__name__ is whoami

Why 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:

Python
# 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.py prints Demo: 120.0, because __name__ is "__main__".
  • import pricing prints 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?

Python
# util.py
print("util:", __name__)

def hello():
    print("hello from", __name__)

if __name__ == "__main__":
    print("util run directly")
Python
# 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.

Text
util: util
app: __main__
hello from util

Why 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 -B or PYTHONDONTWRITEBYTECODE prevent writing it. Directly executing python shop.py does 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.
Text
project/
    pricing.py
    shop.py
    __pycache__/
        pricing.cpython-311.pyc

Notice 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.

Python
# 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)
Python
>>> from inventory import *
>>> LOW_STOCK
5
>>> find(" ab ")
'AB'
>>> _TAX
NameError: name '_TAX' is not defined

The 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.

Python
# inventory.py
__all__ = ["find", "LOW_STOCK"]

LOW_STOCK = 5
HIGH_STOCK = 500

def find(code):
    return code.strip().upper()
Python
>>> from inventory import *
>>> find("x")
'X'
>>> HIGH_STOCK
NameError: name 'HIGH_STOCK' is not defined

HIGH_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 only from module import *. import inventory followed by inventory.HIGH_STOCK still works, and so does from inventory import HIGH_STOCK.
  • If __all__ lists a name that does not exist, the star import raises an AttributeError.

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 print carefully and track the order in which files are loaded.
  • Believing a second import re-runs the file. It does not. Look for sys.modules in the explanation of an answer.
  • Confusing the file name with __name__. The file tools.py is "__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 x binds x to the current object. Later rebinding of m.x does 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:

Python
# 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.

  1. The two print statements are top-level code, so they execute when report is first imported. This explains the unwanted lines in the log.
  2. Subsequent imports (in other request handlers) find report in sys.modules, so the body is not executed again. This explains why the lines appear only once per process.
  3. The fix is to move the demonstration code under a guard so that it only runs when the file is started directly:
Python
# 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 or python -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 what from 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 print calls 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 .pyc files 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 x binds the current object and does not track later rebinding of m.x.

Official sources