Handling Circular Imports in Pydantic models with FastAPI

I'm developing a FastAPI application organized with the following module structure.

...
│   ├── modules
│   │   ├── box
│   │   │   ├── routes.py
│   │   │   ├── services.py
│   │   │   ├── models.py # the sqlalchemy classes
│   │   │   ├── schemas.py # the pydantic schemas
│   │   ├── toy
│   │   │   ├── routes.py
│   │   │   ├── services.py
│   │   │   ├── models.py
│   │   │   ├── schemas.py

Each module contains SQLAlchemy models, Pydantic models (also called schemas), FastAPI routes, and services that handle the business logic.

In this example, I am using two modules that represent boxes and toys. Each toy is stored in one box, and each box contains multiple toys, following a classic 1 x N relationship.

With SQLAlchemy everything goes well, defining relationships is straightforward by using TYPE_CHECKING to handle circular dependencies:

# my_app.modules.box.models.py

from sqlalchemy.orm import Mapped, mapped_column, relationship
if TYPE_CHECKING:
    from my_app.modules.toy.models import Toy

class Box(Base):
    __tablename__ = "box"
    id: Mapped[int] = mapped_column(primary_key=True, autoincrement=True)

    toys: Mapped[list["Toy"]] = relationship(back_populates="box")

# my_app.modules.toy.models.py

from sqlalchemy.orm import Mapped, mapped_column, relationship
if TYPE_CHECKING:
    from my_app.modules.box.models import Box

class Toy(Base):
    __tablename__ = "toy"
    id: Mapped[int] = mapped_column(primary_key=True, autoincrement=True)
    box: Mapped["Box"] = relationship(back_populates="toys")

This setup works perfectly without raising any circular import errors. However, I encounter issues when defining the same relationships between Pydantic schemas. If I import directly the modules on my schemas.py,

# my_app.modules.box.schemas.py
from my_app.modules.toy.schemas import ToyBase

class BoxBase(BaseModel):
    id: int

class BoxResponse(BoxBase):
    toys: list[ToyBase]

# my_app.modules.toy.schemas.py
from my_app.modules.box.schemas import BoxBase

class ToyBase(BaseModel):
    id: int
    
class ToyResponse(ToyBase):
    box: BoxBase

I recieve the circular import error:

ImportError: cannot import name 'ToyBase' from partially initialized module 'my_app.modules.toy.schemas' (most likely due to a circular import)...

I also try the SQLAlchemy approach of TYPE_CHECKING and string declaration:

# my_app.modules.box.schemas.py
if TYPE_CHECKING:
    from my_app.modules.toy.schemas import ToyBase

class BoxBase(BaseModel):
    id: int

class BoxResponse(BoxBase):
    toys: list["ToyBase"]

# my_app.modules.toy.schemas.py
if TYPE_CHECKING:
    from my_app.modules.box.schemas import BoxBase

class ToyBase(BaseModel):
    id: int
    
class ToyResponse(ToyBase):
    box: "BoxBase"

But apparently, pydantic doesn't support this:

raise PydanticUndefinedAnnotation.from_name_error(e) from e
pydantic.errors.PydanticUndefinedAnnotation: name 'ToyBase' is not defined

(Some answers) suggest that the issue comes from a poor module organization. (Others) suggest, too complex and hard to understand solutions.

Maybe I'm wrong but I consider the relationship between Box and Toy something trivial and fundamental that should be manageable in any moderately complex project. For example, a straightforward use case would be to request a toy along with its containing box and vice versa, a box with all its toys. Aren't they legitimate requests?

So, my question

How can I define interrelated Pydantic schemas (BoxResponse and ToyResponse) that reference each other without encountering circular import errors? I'm looking for an clear and maintainable solution that preserves the independence of the box and toy modules, similar to how relationships are handled in SQLAlchemy models. Any suggestions or at least an explanation of why this is so difficult to achieve?

I had this same issue and spent hours trying to figure it out, in the end i ended up just not type annotating the specific circular imports and i've lived happily ever after(so far). Maybe you could benefit from doing this same ;)

That being said, there are multiple ways of fixing circular imports. As highlighted here

What you've tried so far is:

1. Normal typing; doesnt work when a child import a parent.
2. String literals such as toys:["ToyResponse"], this method still causes circular import errors because you are still importing the class to resolve the type.
3. Conditionally importing using TYPE_CHECK. This method seems promising and i believe you've almost got it but were missing one small detail, the TYPE_CHECK boolean must be checked at every place where the circular import types are being used see below:

As per the example you provided, you conditionally import your classes but you dont conditionally do the type checks on the class attributes which results in an undefined error when accessing the type.

As highlighted in the mypy docs:

The typing module defines a TYPE_CHECKING constant that is False at runtime but treated as True while type checking.

Since code inside if TYPE_CHECKING: is not executed at runtime, it provides a convenient way to tell mypy something without the code being evaluated at runtime. This is most useful for resolving import cycles.

# my_app.modules.box.schemas.py
from pydantic import BaseModel
from my_app.modules.toy.schemas import ToyResponse

class BoxResponse(BaseModel):
    id: int
    toys: list["ToyResponse"] # Type check not required here since this is the parent class

# my_app.modules.toy.schemas.py
from typing import TYPE_CHECKING
from pydantic import BaseModel

if TYPE_CHECKING:
    from my_app.modules.box.schemas import BoxResponse

class ToyResponse(BaseModel):
    id: int
    if TYPE_CHECKING:
        box: "BoxResponse"
    else:
        box 

Personally the above seems hackish.

If you have Python 3.7 and up you could also use __future__ import annotations. This will take type hints and treat them as string literals during the initial import. Which should prevent the circular import error.