Circular dependency in Python

I have two files, node.py and path.py, which define two classes, Node and Path, respectively.

Up to today, the definition for Path referenced the Node object, and therefore I had done

from node.py import *

in the path.py file.

However, as of today I created a new method for Node that references the Path object.

I had problems when trying to import path.py: I tried it, and when the program ran and called the Path method that uses Node, an exception rose about Node not being defined.

What do I do?


Importing Python Modules is a great article that explains circular imports in Python.

The easiest way to fix this is to move the path import to the end of the node module.


One other approach is importing one of the two modules only in the function where you need it in the other. Sure, this works best if you only need it in one or a small number of functions:

# in node.py 
from path import Path
class Node 
    ...

# in path.py
class Path
  def method_needs_node(): 
    from node import Node
    n = Node()
    ...

You may not need to import Path in node.py in order for Path and Node to make use of one another.

# in __init__.py  (The order of imports should not matter.)
from .node import Node
from .path import Path

# in path.py 
from . import Node
class Path
  ...

  def return_something_pathy(self): 
    ...

# in node.py
class Node
  def __init__(self, path): 
    self.path = path
    ...

  def a_node_method():
    print(self.path.return_something_pathy())

To make it clear that Node is making use of Path, add type hinting. There is a feature available starting with Python 3.7 to support forward references in type annotations, described in PEP 563.

# in node.py  (Now with type hinting.)
from __future__ import annotations

class Node
  def __init__(self, path: Path): 
    self.path = path
    ...

  def a_node_method():
    print(self.path.return_something_pathy())

I came across a Yet another solution to dig you out of a circular import hole in Python is a great blog post which taught me this.


I prefer to break a circular dependency by declaring one of the dependencies in the constructor of the other dependent class. In my view this keeps the code neater, and gives easy access to all methods who require the dependency.

So in my case I have a CustomerService and a UserService who depend on each other. I break the circular dependency as follows:

class UserService:

    def __init__(self):
        # Declared in constructor to avoid circular dependency
        from server.portal.services.admin.customer_service import CustomerService
        self.customer_service = CustomerService()

    def create_user(self, customer_id: int) -> User:
        # Now easy to access the dependency from any method
        customer = self.customer_service.get_by_id(customer_id)