Creating custom modules in Python - Mechanics & Internals

Overview - Creating custom modules

What is it?

Creating custom modules in Python means writing your own files that contain functions, variables, or classes. These files can be saved and then used in other Python programs by importing them. This helps organize code into reusable parts, making programs easier to read and maintain. A module is simply a Python file with a .py extension that groups related code together.

Why it matters

Without custom modules, programmers would have to write all code in one big file, which becomes confusing and hard to fix or update. Modules let you reuse code across many projects, saving time and reducing mistakes. They also help teams work together by dividing tasks into separate files. This makes programming more efficient and less error-prone.

Where it fits

Before learning custom modules, you should know basic Python syntax, how to write functions, and how to run simple scripts. After mastering modules, you can learn about packages, which are collections of modules, and explore advanced topics like module importing tricks and creating libraries for others to use.

Mental Model

Core Idea

A custom module is like a toolbox you build yourself, storing useful tools (functions and variables) that you can carry and use in many projects.

Think of it like...

Imagine you have a toolbox at home with tools you made or customized yourself. Instead of buying new tools every time you fix something, you just grab your toolbox and use what you need. Similarly, a custom module holds your own tools (code) ready to use anytime.

┌───────────────┐
│ custom_module.py │
│ ┌─────────────┐ │
│ │ function_a  │ │
│ │ function_b  │ │
│ │ variable_x  │ │
│ └─────────────┘ │
└───────┬─────────┘
        │ import
        ▼
┌───────────────┐
│ main_program.py│
│ ┌─────────────┐ │
│ │ use tools   │ │
│ │ from module │ │
│ └─────────────┘ │
└───────────────┘

Build-Up - 7 Steps

1

Foundation

What is a Python module?

Concept: Introduce the idea that a Python module is a file containing Python code that can be reused.

A Python module is simply a file with a .py extension. Inside, you can write functions, variables, or classes. For example, create a file named my_tools.py with a function: def greet(name): return f"Hello, {name}!" This file is your module.

Result

You have a file named my_tools.py that holds reusable code.

Understanding that a module is just a file helps remove mystery and shows how easy it is to organize code.

2

Foundation

How to import a custom module

Concept: Show how to use the import statement to bring code from your module into another file.

Create another file main.py in the same folder. To use greet from my_tools.py, write: import my_tools print(my_tools.greet("Alice")) This runs the greet function from your module.

Result

Output: Hello, Alice!

Knowing how to import lets you reuse code without copying it, making programs cleaner and easier to manage.

3

Intermediate

Using from-import for cleaner code

🤔Before reading on: Do you think 'from module import function' lets you call the function without the module name? Commit to your answer.

Concept: Learn how to import specific parts of a module directly to avoid typing the module name repeatedly.

Instead of writing my_tools.greet every time, you can write: from my_tools import greet print(greet("Bob")) This imports greet directly, so you call it without the module prefix.

Result

Output: Hello, Bob!

Understanding this import style makes code shorter and easier to read, especially when using many functions from one module.

4

Intermediate

Organizing modules in folders

🤔Before reading on: Do you think Python can import modules from subfolders without extra setup? Commit to your answer.

Concept: Explain how to organize modules inside folders and how Python finds them using __init__.py files.

You can create a folder named tools and put my_tools.py inside it. To make it a package, add an empty __init__.py file in tools folder. Then import with: from tools import my_tools print(my_tools.greet("Carol")) This helps organize many modules.

Result

Output: Hello, Carol!

Knowing how to structure folders and packages helps manage large projects and share code cleanly.

5

Intermediate

Reloading modules during development

🤔Before reading on: If you change a module after importing, do you think Python automatically updates it in your program? Commit to your answer.

Concept: Teach how to reload a module in the same program session to see changes without restarting.

When you edit a module after importing, Python does not update it automatically. Use: import importlib importlib.reload(my_tools) This reloads the module so changes take effect immediately.

Result

Module updates are applied without restarting the program.

Knowing how to reload modules speeds up testing and development by avoiding restarts.

6

Advanced

Using __name__ to control module behavior

🤔Before reading on: Do you think code in a module runs automatically when imported? Commit to your answer.

Concept: Explain the special __name__ variable and how to write code that runs only when the module is executed directly, not when imported.

Inside my_tools.py, add: if __name__ == "__main__": print("Module is run directly") When you run python my_tools.py, this prints the message. But when imported, it does not run. This helps test modules safely.

Result

Code inside the if-block runs only when the module is run as a script.

Understanding __name__ prevents unwanted code execution during imports and supports module testing.

7

Expert

Customizing module search paths

🤔Before reading on: Can you import a module from any folder on your computer without changing settings? Commit to your answer.

Concept: Learn how Python finds modules and how to add your own folders to the search path using sys.path or environment variables.

Python looks for modules in folders listed in sys.path. To add a folder: import sys sys.path.append('/path/to/your/modules') Now you can import modules from that folder anywhere. Alternatively, set the PYTHONPATH environment variable before running Python.

Result

Modules outside the current folder can be imported after updating search paths.

Knowing how to control module search paths allows flexible project layouts and sharing code across projects.

Under the Hood

When you import a module, Python looks for a file with that name ending in .py in a list of folders called sys.path. It reads and runs the code inside the module once, creating a module object in memory. This object holds all functions, classes, and variables defined. When you use the module name, Python accesses these stored objects. If you import the same module again, Python uses the cached object to avoid running the code twice.

Why designed this way?

Python modules were designed to be simple files to keep the language easy to learn and use. The import system caches modules to improve performance and avoid repeated work. The sys.path list allows flexibility to find modules in different places, supporting both small scripts and large projects. This design balances simplicity, speed, and flexibility.

┌───────────────┐
│ sys.path list │
│ ┌───────────┐ │
│ │ Folder A  │ │
│ │ Folder B  │ │
│ │ Folder C  │ │
│ └───────────┘ │
└───────┬───────┘
        │
        ▼
┌─────────────────────┐
│ Python interpreter   │
│ 1. Looks for module  │
│ 2. Loads and runs it │
│ 3. Stores module obj │
└─────────┬───────────┘
          │
          ▼
┌─────────────────────┐
│ Your program uses    │
│ functions/variables  │
│ from module object   │
└─────────────────────┘

Myth Busters - 4 Common Misconceptions

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

Common Belief: Importing a module only loads function definitions but does not run any code outside functions.

Reality: Importing runs all top-level code in the module immediately, including print statements or calculations outside functions.

Why it matters: Unexpected code running on import can cause side effects or slow down programs, leading to bugs or confusion.

Quick: If you import the same module twice, does Python reload it both times? Commit to yes or no.

Common Belief: Python runs the module code every time you import it, even if imported before.

Reality: Python runs the module code only once per program run and reuses the cached module object on subsequent imports.

Why it matters: Knowing this prevents repeated side effects and improves performance by avoiding unnecessary work.

Quick: Can you import a module from any folder on your computer without setup? Commit to yes or no.

Common Belief: You can import any Python file from anywhere on your computer without changing anything.

Reality: Python only searches certain folders by default; to import from other places, you must add those folders to sys.path or PYTHONPATH.

Why it matters: Without this knowledge, beginners get import errors and think their code or Python is broken.

Quick: Does using 'from module import *' import only the functions you use? Commit to yes or no.

Common Belief: Using 'from module import *' imports only the functions or variables you actually call in your code.

Reality: It imports all public names defined in the module, which can clutter your namespace and cause name conflicts.

Why it matters: This can lead to bugs that are hard to trace and makes code harder to read and maintain.

Expert Zone

1

Modules are loaded once and cached, but if you modify a module file during runtime, Python won't see changes unless you reload it explicitly.

2

The __init__.py file in a folder marks it as a package; without it, Python treats the folder as a normal directory and won't import modules inside.

3

Relative imports inside packages use dot notation and can be tricky; understanding absolute vs relative imports is key for large projects.

When NOT to use

Custom modules are not ideal for very small scripts where a single file suffices. For complex projects, consider using packages or third-party libraries. Also, avoid modifying sys.path dynamically in production; instead, use virtual environments or install packages properly.

Production Patterns

In real projects, developers organize code into packages with clear module responsibilities. They use __init__.py to expose public APIs and write tests inside modules guarded by __name__ == '__main__'. Deployment often involves packaging modules as installable libraries with setup.py or pyproject.toml.

Connections

Software Libraries

Custom modules build the foundation for creating reusable software libraries.

Understanding modules helps grasp how large libraries are structured and shared across projects.

Operating System File Systems

Modules correspond to files and folders in the file system, linking programming to OS concepts.

Knowing how files and folders work in your OS helps understand module organization and import errors.

Human Memory Organization

Just like modules organize code, humans organize knowledge into categories and folders in their mind.

Recognizing this parallel helps appreciate why modular code is easier to remember and reuse.

Common Pitfalls

#1 Trying to import a module from a folder without __init__.py and getting ModuleNotFoundError.

Wrong approach:

from tools import my_tools
# tools folder has no __init__.py file

Correct approach:

Add an empty __init__.py file inside tools folder:
# tools/__init__.py (empty)

from tools import my_tools

Root cause:

Python requires __init__.py to recognize a folder as a package for imports.

#2 Running code inside a module unintentionally when importing it.

Wrong approach:

print("Hello from module")
# This runs on import, causing unwanted output

Correct approach:

if __name__ == "__main__":
print("Hello from module")
# Runs only when module is executed directly

Root cause:

Not using the __name__ guard causes all top-level code to run on import.

#3 Modifying a module file after importing but not seeing changes in the running program.

Wrong approach:

import my_tools
# edit my_tools.py
# call functions again without reload

Correct approach:

import importlib
importlib.reload(my_tools)
# Now changes take effect

Root cause:

Python caches imported modules and does not reload them automatically.

Key Takeaways

A Python module is a simple file that groups related code for reuse and better organization.

Importing modules lets you use code from other files without copying, making programs cleaner and easier to maintain.

The __name__ variable helps control when code inside a module runs, preventing unwanted side effects during imports.

Python searches for modules in specific folders; understanding and managing these paths is key to avoiding import errors.

Advanced use of modules includes organizing them into packages, reloading during development, and controlling import behavior for large projects.