Modules and Packages: Importing and Namespaces

In Python, a module is simply a single file that ends with .py. You can think of it as a recipe book – one file containing a collection of related functions, variables, and classes. For example, you might create a file called weather_utils.py that contains a function called get_temperature(city). To use that function in another program, you use the import statement. The simplest form is import weather_utils. When Python runs this line, it does two things: it runs all the code inside weather_utils.py, and it creates a new namespace (a container for names) called weather_utils. To call your function, you must then write weather_utils.get_temperature("London"). This is called 'qualifying' the name – you are explicitly telling Python to look inside the weather_utils namespace for the function. The benefit is that if you also have a function called get_temperature in your main program, they will not clash, because they live in different namespaces.

But what if you want to bring the function directly into your current namespace so you can call it as just get_temperature("London")? You use a different form: from weather_utils import get_temperature. This copies the function reference into your current namespace. The downside is that if you already have a variable named get_temperature in your main program, it will be overwritten. For PCAP-31-03, you must memorise the three main import forms: import modulename, from modulename import item, and from modulename import *. The asterisk (*) imports all names that the module defines at the top level, which is generally discouraged because it pollutes your namespace and can cause accidental name collisions.

Now, as you accumulate many modules, you will want to organise them into folders. A folder containing multiple .py files is called a package. For Python to recognise a folder as a package, the folder must contain a file named __init__.py. This file can be empty, but it signals to Python that the folder is a package that can be imported. For example, let us create a folder called shapes. Inside it, we have circle.py (with a function area(radius)) and square.py (with a function area(side)). Inside the shapes folder, we create an empty file named __init__.py. Now, from another script, we can write:

The __init__.py file can also contain code that runs when the package is first imported. For instance, you might use it to set up shared variables or to automatically import certain sub-modules so they are available immediately: from . import circle inside __init__.py would make circle available as shapes.circle without an extra explicit import.

Python has a built-in search path for modules, called sys.path. When you write import weather_utils, Python looks for a file named weather_utils.py in a list of directories. The first place it looks is the directory containing the script that was run (the current working directory). Then it checks every directory listed in the PYTHONPATH environment variable, and finally it checks standard library directories and site-packages (where third-party modules are installed). If Python cannot find the module, it raises a ModuleNotFoundError. This is a common exam trap – they might ask what happens when you try to import a module that is not in any of these locations.

Namespaces are crucial to understand. Every time you import a module, Python creates a new namespace object. When you assign a variable inside a module, that variable lives in the module's namespace. When you import using from modulename import item, the item is copied into your current namespace (the global namespace of your script). The original item in the module’s namespace remains unchanged. If you change the value of the imported item in your script, you are only changing your local copy – not the original in the module. However, if you import the module itself (import modulename) and then modify an attribute of that module (e.g., modulename.some_variable = 10), that change is visible to any other code that also imports the same module and reads that attribute. This behaviour is tested in the exam.

Finally, the __name__ variable. When you run a Python script directly, Python sets the special variable __name__ to "__main__". When a module is imported from another script, __name__ is set to the module's name (e.g., "weather_utils"). This lets you write code that only runs when the file is executed directly, not when it is imported, using the pattern if __name__ == "__main__":. The exam often asks about this.

To summarise the hierarchy: a package is a folder with __init__.py. A sub-package is a sub-folder also containing __init__.py. A module is a .py file inside any package. A function or class is defined inside a module. Each level lives in its own namespace.

Imagine you are a junior developer at a company that builds a web application for managing customer orders. The application is large, with hundreds of Python files. Without modules and packages, you would have a single massive script with tens of thousands of lines, making it impossible to maintain or collaborate. Your senior developer asks you to organise the code.

First, you create a top-level package called order_system. Inside it, you create an __init__.py file (just an empty file for now). Then you create sub-packages: order_system.models (for database-related code), order_system.views (for user interface logic), and order_system.utils (for helper functions like date parsing and email sending). Each sub-package also gets its own __init__.py file.

Inside order_system.models, you have a module called customer.py containing a Customer class. Inside order_system.views, you have order_view.py which needs to use the Customer class. So you write in order_view.py: from order_system.models.customer import Customer. But there is a catch: the project is deployed on multiple servers, and the developers need to ensure that the same structure works across all environments. You decide to make the __init__.py file in order_system.models import the Customer class directly, so that other parts of the application can simply write from order_system.models import Customer. This simplifies the import paths. Your __init__.py looks like:

from .customer import Customer

Now, a bug emerges: the Customer class needs a helper function called validate_email that lives in order_system.utils. You import it inside customer.py using from order_system.utils import validate_email. This creates a circular import risk if utils also tries to import from models. To avoid this, you restructure: you move validate_email into its own small module order_system.utils.email_utils.py and import it only inside the specific functions that need it, not at the top level of customer.py.

In your day-to-day work, you frequently need to test individual modules. You use the if __name__ == "__main__": pattern to write quick test code inside each module. For example, inside customer.py, you add:

if __name__ == "__main__":
    c = Customer("Alice", "alice@example.com")
    print(c)

This lets you run python order_system/models/customer.py directly to test that specific module, without affecting the rest of the system when it is imported normally.

When the project grows, you encounter name clashes. Another library you use, analytics_toolkit, also has a Customer class. To avoid conflict, you use the fully qualified import: from order_system.models.customer import Customer as OrderCustomer and from analytics_toolkit import Customer as AnalyticsCustomer. This 'rename on import' (using as) is a practical technique the exam expects you to know.

Finally, when deploying to production, you must ensure all __init__.py files exist, even if empty. New developers often forget this, leading to ModuleNotFoundError. As a professional, you run a linter or a pre-commit hook to check that every package directory contains __init__.py.