Python Project Structure & Imports: Circular Dependencies & sys.path (2026)

Day 28: The Dependency Graph — Imports, Internals & Project Structure

45 min read Series: Logic & Legacy Day 28 / 30 Level: Senior Architecture

⏳ Context: We have a CLI entry point, robust environment configuration, and unbreakable fault tolerance. But as your system grows from 1 file to 100 files, a new enemy emerges: The Dependency Graph. If you organize your files poorly, your system will collapse under the weight of Circular Imports and ModuleNotFound errors.

"ImportError: attempted relative import with no known parent package"

Every Python developer has stared at this error, furiously adding sys.path.append('..') hacks to the top of their files to force it to work. This is duct tape. Senior Architects do not hack their import paths; they structure the directory so the interpreter inherently understands the boundaries of the system.

▶ Table of Contents 🕉️ (Click to Expand)

1. The Physics of import (The Internal Engine)
2. The Modern Standard: The src/ Layout
3. Encapsulation and the import * Sin
4. The Architect's Nightmare: Circular Imports
5. Resolving the Type Hinting Circle

1. The Physics of import (The Internal Engine)

When you type import json or from database import connect, it is not magic. Python executes a rigid, deterministic 3-step engine under the hood:

1. The Cache Check (sys.modules): Python first checks a global dictionary called sys.modules. If the module is already in there, it skips everything and just gives you the cached reference. (This is why a module's code is only ever executed ONCE, no matter how many files import it).
2. The Search (sys.path): If it's not cached, Python searches your hard drive. It looks through a list of folders called sys.path in exact order. Index 0 is always the folder of the script you ran.
3. The Execution: When it finds the file, it compiles it to bytecode (the pycache folder) and executes it top-to-bottom, storing the resulting variables and functions in memory.

The Poisoned Import Trap (Shadowing)

Because Index 0 of sys.path is your local folder, if you create a file named math.py in your project, and run import math, Python finds YOUR file before it checks the standard library. It imports your fake math file, immediately breaking your application and any third-party libraries you installed.

2. The Modern Standard: The src/ Layout

To prevent script execution from poisoning the import path, the Python community has standardized the src/ directory layout for enterprise applications.

Instead of dumping all your code next to your tests/ and your config files, you isolate the actual application inside a src/ folder. This forces you to install your package locally in editable mode so that your tests test the installed package, not the loose files.

my_enterprise_app/ ├── .env ├── pyproject.toml # Dependency management ├── tests/ # Tests live OUTSIDE the source code │ ├── conftest.py │ └── test_auth.py └── src/ └── my_app/ # The actual python package ├── init.py ├── main.py ├── api/ └── core/

With this structure, imports are always absolute from the package root: from my_app.core.database import Session. You never use messy relative imports like from ..core import database.

3. Encapsulation and the import * Sin

The most dangerous import anti-pattern is from x import *. If you do this in 5 different files, you have completely polluted the global namespace. If two modules have a function named process_data, the second one silently overwrites the first. Furthermore, when a developer reads the code, it is impossible to know which file a function came from without a heavy IDE.

Senior Architects enforce "Explicit is better than implicit." We use init.py and the all variable to create a Public API Firewall.

src/my_app/crypto/init.py

# We import the functions from our messy internal files
from .hashing import hash_password, _salt_generator
from .verification import verify_password

# The all list acts as a firewall. 
# If a junior developer attempts the forbidden 'from crypto import *', 
# Python looks at this list. It will ONLY export these two functions.
# _salt_generator remains securely encapsulated inside this directory!
all = ["hash_password", "verify_password"]

4. The Architect's Nightmare: Circular Imports

The deadliest bug in Python architecture is the Circular Dependency. It happens when File A imports File B, but File B needs something from File A. The interpreter gets caught in an infinite loop and crashes.

How to Defeat Circularity

• 1. The Architecture Fix (Extract): If A needs B and B needs A, they share a hidden domain. Extract the shared logic into File C, and have both import from C.
• 2. The Tactical Fix (Local Import): If refactoring is impossible, move the import statement inside the specific function that needs it. This delays the import until runtime, breaking the boot-time loop.

The Local Import Rescue

# users.py
class User:
def get_orders(self):
# Putting the import inside the method defers it until runtime.
# sys.modules ensures it is lightning fast after the first call.
from my_app.orders import get_by_user
return get_by_user(self.id)

5. Resolving the Type Hinting Circle

In modern Python (especially with FastAPI or Pydantic), 90% of circular imports are caused by Type Hints. File A imports File B just so it can use a class name in a type signature. The code doesn't actually need the class to run; it just needs it for the linter (Mypy).

Python provides a brilliant built-in flag to solve this: TYPE_CHECKING.

The Ghost Import (TYPE_CHECKING)

from typing import TYPE_CHECKING

# This variable is False when the code actually runs in production, 
# but it evaluates to True when your Linter (Mypy) scans the file!
if TYPE_CHECKING:
# This import is invisible at runtime. No circular loops!
from my_app.models.orders import Order

# We must wrap 'Order' in strings for forward-referencing.
def process(order: 'Order'):
pass

🛠️ Day 28 Project: The Architecture Refactor

Migrate a messy script into an enterprise structure.

• Create a src/ directory on your computer, with a system/ package inside it.
• Create two files: user.py and profile.py. Make them import each other at the top of the file. Run it and trigger the circular ImportError.
• Fix the error by utilizing the typing.TYPE_CHECKING flag to hide the import from the runtime interpreter.

🔥 PRO UPGRADE (The Export Firewall)

Create an __init__.py file inside your package. Use the __all__ array to explicitly export the User class but block access to a secret helper function in the same directory. Test it by trying to run from system import * in an outside file.

The Graph: Resolved

You now understand how Python physically locates and caches its code, the dangers of implicit imports, and how to structure directories for massive scale. Hit Follow to catch Day 29, where we take this src/ directory and turn it into an installable software package using pyproject.toml and Modern Build Tools.

← Previous

Day 27: Professional CLIs

Next →

Day 29: Packaging & pyproject.toml