Debug: Python import system and circular imports

ImportError or AttributeError caused by circular imports between Python modules.

Understanding and fixing circular imports:

# The problem:
# a.py
from b import helper  # b not fully loaded yet -> ImportError
class MyClass: ...

# b.py
from a import MyClass  # a not fully loaded yet -> ImportError
def helper(): ...

# Fix 1: Import at function level (lazy import)
# a.py
class MyClass:
    def method(self):
        from b import helper  # Import when needed
        return helper(self)

# Fix 2: Import the module, not the name
# a.py
import b
class MyClass:
    def method(self):
        return b.helper(self)

# Fix 3: Restructure - move shared code to a third module
# shared.py - no imports from a or b
class MyClass: ...
def helper(): ...

# Fix 4: TYPE_CHECKING for type hints only
from __future__ import annotations
from typing import TYPE_CHECKING
if TYPE_CHECKING:
    from b import Helper  # Only imported for type checking

Diagnose: python -v -c 'import mymodule' shows import order.

Python executes module code top-to-bottom on first import. Circular imports fail because one module is only partially initialized when the other tries to import from it.

Python projects with inter-dependent modules