Import statement behavior in Python - Deep Dive

Overview - Import statement behavior

What is it?

In Python, the import statement lets you bring code from one file or module into another. This means you can use functions, classes, or variables defined elsewhere without rewriting them. It helps organize code into reusable pieces. Importing runs the imported file once and makes its contents available.

Why it matters

Without import statements, every program would have to include all code in one file, making it huge and hard to manage. Imports let programmers share and reuse code easily, speeding up development and reducing mistakes. They also help keep projects organized and modular, which is crucial for teamwork and large programs.

Where it fits

Before learning imports, you should understand Python basics like variables, functions, and files. After imports, you can learn about packages, modules, and advanced topics like lazy imports or import hooks. Imports are a foundation for understanding how Python programs are structured.

Mental Model

Core Idea

An import statement is like opening a toolbox that contains tools (code) you want to use in your current project without building them yourself.

Think of it like...

Imagine you are cooking and need a special knife. Instead of buying one, you borrow it from a neighbor's kitchen. The import statement is like borrowing that knife so you can use it immediately without owning it.

┌─────────────┐       import       ┌─────────────┐
│ Current     │ ───────────────▶ │ Module File │
│ Script      │                  │ (tools)     │
└─────────────┘                  └─────────────┘
       │                              ▲
       │ uses imported tools          │
       └──────────────────────────────

Build-Up - 7 Steps

1

Foundation

Basic import syntax and usage

Concept: Learn how to write a simple import statement to use code from another file.

Suppose you have a file named math_tools.py with a function add(a, b): math_tools.py: def add(a, b): return a + b In another file, you write: import math_tools result = math_tools.add(3, 4) print(result) This imports the whole module and uses the add function with the module name prefix.

Result

7

Understanding the basic import syntax is the first step to reusing code and organizing programs into modules.

2

Foundation

Importing specific names with from

Concept: Learn how to import only certain functions or variables directly to avoid typing the module name every time.

Using the same math_tools.py, you can write: from math_tools import add result = add(5, 6) print(result) This imports only the add function directly into your file's namespace.

Result

11

Knowing how to import specific names makes code cleaner and easier to read when you only need parts of a module.

3

Intermediate

How Python finds modules to import

🤔Before reading on: do you think Python looks in your current folder first or in system folders first when importing? Commit to your answer.

Concept: Understand the search order Python uses to find the module you want to import.

When you write import math_tools, Python searches for math_tools.py or a package named math_tools in this order: 1. The current directory where your script runs. 2. Directories listed in the environment variable PYTHONPATH. 3. Standard library directories. 4. Installed third-party packages. If Python can't find the module in these places, it raises ModuleNotFoundError.

Result

Python imports the first matching module it finds in the search order.

Knowing the search order helps you organize your files and avoid conflicts or unexpected imports.

4

Intermediate

Import caching and single execution

🤔Before reading on: do you think importing the same module twice runs its code twice or only once? Commit to your answer.

Concept: Learn that Python runs a module's code only once per program run and reuses it on repeated imports.

When you import a module, Python runs its code and stores the result in a cache (sys.modules). If you import the same module again, Python uses the cached version without rerunning the code. This means: - Module-level code runs once. - Variables and functions keep their state. Example: # module.py print('Running module code') # main.py import module import module Output: Running module code Only one print appears, showing the module ran once.

Result

Module code executes once; repeated imports reuse the cached module.

Understanding import caching prevents confusion about side effects and performance when importing modules multiple times.

5

Intermediate

Relative imports inside packages

🤔Before reading on: do you think relative imports use dots to go up or down folders? Commit to your answer.

Concept: Learn how to import modules relative to the current module's location using dots.

In a package folder structure: package/ __init__.py mod1.py subpackage/ __init__.py mod2.py Inside mod2.py, to import mod1.py, you write: from .. import mod1 Here, one dot means current folder, two dots mean one folder up. Relative imports help organize large packages without hardcoding full paths.

Result

Modules import other modules relative to their location using dots.

Knowing relative imports helps maintain flexible and portable package structures.

6

Advanced

Import side effects and execution order

🤔Before reading on: do you think import statements can run code that changes program state? Commit to your answer.

Concept: Understand that importing runs the module's top-level code, which can have side effects.

When you import a module, Python executes all code at the top level (not inside functions or classes). This can: - Initialize variables - Print messages - Open files Example: # config.py print('Loading config') settings = {'debug': True} # main.py import config Output: Loading config This means imports can change program state or cause actions, so be careful with code outside functions.

Result

Importing runs top-level code, causing side effects if present.

Understanding import side effects helps avoid unexpected behavior and bugs in large projects.

7

Expert

Custom import hooks and importlib usage

🤔Before reading on: do you think Python allows changing how imports work internally? Commit to your answer.

Concept: Learn that Python's import system is customizable using import hooks and the importlib module.

Python's import system is flexible. You can: - Write custom importers to load modules from unusual places (like databases or network). - Use importlib to programmatically import modules or reload them. Example: import importlib module = importlib.import_module('math_tools') This flexibility allows advanced use cases like plugin systems or dynamic code loading.

Result

Python import system can be extended and controlled programmatically.

Knowing import internals and hooks unlocks powerful dynamic behaviors in Python applications.

Under the Hood

When Python encounters an import statement, it checks if the module is already loaded in sys.modules cache. If not, it searches directories in sys.path for the module file. It then compiles the source code to bytecode if needed, executes the module's code once, and stores the module object in sys.modules. Subsequent imports reuse this cached module. The module's namespace becomes accessible to the importer.

Why designed this way?

This design balances efficiency and flexibility. Running module code once avoids repeated work and preserves state. The search path allows modular code organization. Caching prevents performance hits. Alternatives like reloading on every import would slow programs and cause inconsistent states. The system evolved from early Python versions to support packages and dynamic loading.

┌───────────────┐
│ import stmt   │
└──────┬────────┘
       │
       ▼
┌───────────────┐
│ Check sys.modules│
│ for cached mod │
└──────┬────────┘
       │ yes
       │─────────────┐
       ▼             │
┌───────────────┐    │
│ Return cached │    │
│ module object │    │
└───────────────┘    │
                     │ no
                     ▼
             ┌───────────────┐
             │ Search sys.path│
             │ for module    │
             └──────┬────────┘
                    │
                    ▼
             ┌───────────────┐
             │ Compile & run │
             │ module code   │
             └──────┬────────┘
                    │
                    ▼
             ┌───────────────┐
             │ Store in      │
             │ sys.modules   │
             └──────┬────────┘
                    │
                    ▼
             ┌───────────────┐
             │ Provide module │
             │ namespace     │
             └───────────────┘

Myth Busters - 4 Common Misconceptions

Quick: Does importing a module twice run its code twice? Commit to yes or no.

Common Belief: Importing a module multiple times runs its code each time.

Reality: Python runs a module's code only once per program run; subsequent imports use the cached module.

Why it matters: Believing otherwise can cause confusion about side effects and lead to redundant or buggy code.

Quick: Does 'from module import *' import private names starting with underscore? Commit to yes or no.

Common Belief: Using 'from module import *' imports all names, including private ones starting with underscore.

Reality: Names starting with underscore are not imported with '*' unless explicitly listed in __all__.

Why it matters: Assuming all names are imported can cause unexpected errors or expose internal details unintentionally.

Quick: Can you import a module from any folder without adjusting sys.path or environment? Commit to yes or no.

Common Belief: You can import any Python file from any folder without setup.

Reality: Python only imports modules from folders in sys.path or PYTHONPATH; otherwise, it raises ModuleNotFoundError.

Why it matters: Not understanding this leads to import errors and wasted debugging time.

Quick: Does relative import syntax work in scripts run as __main__? Commit to yes or no.

Common Belief: Relative imports always work regardless of how the script is run.

Reality: Relative imports fail in scripts run directly as __main__; they only work inside packages.

Why it matters: Misusing relative imports causes runtime errors and confusion about module structure.

Expert Zone

1

Importing a module executes its top-level code only once, but mutable objects inside can change state across imports, which can cause subtle bugs.

2

The order of imports can affect program behavior if modules have side effects or depend on each other, so import order matters in complex projects.

3

Python's import system supports namespace packages that allow splitting a package across multiple directories, enabling flexible distribution of large projects.

When NOT to use

Avoid using relative imports in scripts intended to be run directly; instead, use absolute imports or restructure code into packages. Also, avoid 'from module import *' in production code to prevent namespace pollution and unclear dependencies.

Production Patterns

In real projects, imports are organized at the top of files, grouped by standard library, third-party, and local modules. Lazy imports inside functions improve startup time. Custom import hooks enable plugin architectures. Tools like pip and virtual environments manage package versions to avoid conflicts.

Connections

Modular programming

Import statements implement modular programming by enabling code reuse and separation.

Understanding imports deepens grasp of modular design, which improves code maintainability and collaboration.

Dependency injection

Imports provide dependencies to code, similar to how dependency injection supplies components.

Recognizing imports as a form of dependency management helps in designing flexible and testable software.

Library linking in compiled languages

Python imports are like dynamic linking of libraries in languages like C, loading code at runtime.

Knowing this connection clarifies how Python balances flexibility and performance in code reuse.

Common Pitfalls

#1 Trying to import a module that is not in the search path.

Wrong approach:

import mymodule
# mymodule.py is in a folder not listed in sys.path

Correct approach:

import sys
sys.path.append('/path/to/folder')
import mymodule

Root cause:

Not understanding that Python only searches certain directories for modules.

#2 Using relative imports in a script run directly.

Wrong approach:

from . import utils
# run as python script.py

Correct approach:

Use absolute imports or run as a module: python -m package.script

Root cause:

Misunderstanding that relative imports require the module to be part of a package.

#3 Using 'from module import *' and expecting all names imported.

Wrong approach:

from math_tools import *
print(_hidden_var)

Correct approach:

from math_tools import public_function
# or explicitly import _hidden_var if needed

Root cause:

Not knowing that names starting with underscore are excluded from wildcard imports.

Key Takeaways

Import statements let you reuse code by bringing modules into your current file.

Python runs a module's code only once and caches it for future imports to improve efficiency.

Python searches for modules in a specific order: current directory, PYTHONPATH, standard libraries, then installed packages.

Relative imports use dots to navigate package structure but only work inside packages, not in standalone scripts.

Understanding import side effects and caching helps avoid bugs and write cleaner, modular Python programs.