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:
- Normal typing; doesnt work when a child import a parent.
- String literals such as
toys:["ToyResponse"], this method still causes circular import errors because you are still importing the class to resolve the type. - Conditionally importing using
TYPE_CHECK. This method seems promising and i believe you’ve almost got it but were missing one small detail, theTYPE_CHECKboolean 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.
2
Pydantic can’t construct infinitely recursive models.
AsToyResponse is written the data you receive would have to be infinitely recursive.
{
id: "x"
box: {
id: "a"
toys: [{
id: "x"
box: {
id: "a"
toys: ... and so on
}]
}
}
This seems like a case where SQLAlchemy doesn’t attempt to process the type annotations at run time, but Pydantic is when it tries to construct the class objects causing a circular import.
One way to break the recursive definition would be to define a Toy model that doesn’t have a reference to BoxResponse in the definition and use that in BoxResponse
class BoxResponse(BaseModel):
id: int
toys: list[ToyWithoutNestedBox]
EDIT in response to question edits:
Now that the models are split into Base and Response classes, you’ll remove the circular import if you define the Base and Response classes in separate files from eachother. This is because the Base classes require no imports from other models so the Response classes are free to import them without the risk of circular imports.
2