Project Architecture Foundations

Beyond the Single File

So far, you've likely written Python code in single .py files. This works great for simple scripts and learning exercises. But as projects grow, stuffing everything into one file becomes chaotic. Code gets hard to find, reuse is nearly impossible, and collaborating with others turns into a nightmare.

To build professional, scalable applications, we need to organize our code logically. This isn't just about tidiness; it's about creating a structure that makes your code understandable, maintainable, and easy to extend. The first step is understanding the difference between a module and a package.

A module is simply a single Python file (.py). A package is a collection of modules, organized in a directory.

Think of a module as a single document and a package as a folder full of related documents. This folder structure allows us to group related functionality. For example, all code related to user authentication might live in an auth package, while database interactions live in a db package.

The Standard Project Layout

While you can organize files however you want, the Python community has settled on a few standard layouts. One of the most common and effective is the src layout. It clearly separates your actual source code from other project files like tests, documentation, and configuration.

Let's break this down:

my_project/: This is the root of your entire project. It contains everything related to your application.
README.md: A file that explains what your project does and how to use it.
requirements.txt: Lists the external Python libraries your project depends on.
src/: This is the most important directory. It houses all your Python source code. By placing code here, you create a clear separation between the logic of your application and the project's metadata.
src/app/: This is our main package. Inside, we have our modules.
src/app/__init__.py: This special file tells Python that the app directory should be treated as a package. It can be empty, but its presence is crucial. The __init__.py file is what makes regular imports possible.
src/app/main.py and src/app/utils.py: These are modules within our app package. main.py might contain the core application logic, while utils.py could hold helper functions used across the project.

A well-structured project makes it easier to understand, maintain, and scale your application.

Running Your Code

With our code now nested inside src/app, how do we run it? We can't just run python main.py anymore. We need a designated entry point. This is a script that knows how to initialize and start our application. Often, this is handled by a special construct: if __name__ == "__main__":.

When you run a Python file directly, the interpreter sets a special variable, __name__, to the string "__main__". If the file is imported by another module, __name__ is set to the module's name (e.g., "app.utils"). This allows us to write code that only runs when the file is executed as the main program.

# In src/app/main.py

from . import utils  # Relative import

def start_app():
    print("Application starting...")
    result = utils.add(5, 10)
    print(f"The result from utils is: {result}")

# This block only runs when main.py is executed directly.
if __name__ == "__main__":
    start_app()

To run this code, you would navigate your terminal to the src directory and execute the module using the -m flag. This tells Python to run the module as a script.

# From the 'my_project' root directory:
cd src
python -m app.main

This approach ensures that Python correctly recognizes your project's package structure, allowing imports to work as expected. Using the -m flag is the standard way to execute packages or modules within a package.

Handling Imports

As projects grow, you'll need to import code from one module into another. Python offers two ways to do this: absolute and relative imports.

Absolute imports specify the full path from the project's source root (src in our case). They are explicit and clear.

# In src/app/main.py
# Assumes you run the app from the root directory.

from app import utils

# ... rest of the code

Relative imports use dot notation to specify a path from the current module's location. A single dot (.) refers to the current package, and two dots (..) refer to the parent package.

# In src/app/main.py
# This imports utils from the same package ('app').

from . import utils

# If utils was in a parent package, you might use:
# from .. import another_package

Which one should you use? Absolute imports are often preferred because they are unambiguous. You can look at an import statement and know exactly where the module is located within the project structure. Relative imports can be convenient for modules deep within a package, but they can make it harder to understand the project's structure just by reading the code. For most cases, sticking to absolute imports is a good rule of thumb.

Ready to test your knowledge?

Quiz Questions 1/5

What is the primary role of the __init__.py file in a directory?

Quiz Questions 2/5

What is the main benefit of organizing your code using a src layout?

Organizing your code this way from the start pays off immensely. It provides a solid foundation, making your project easier to navigate, test, and grow over time.

Building Real World Python Applications