python - Sphinx Maximum Recursion Depth Exceeded in Pydantic Models with Cyclic Dependencies - Stack Overflow

I’m using Pydantic to define models that reference each other cyclically. When I try to generate documentation using Sphinx, I get:

Recursion error:
maximum recursion depth exceeded

This issue arises when trying to document models that contain cyclic references. Below is a minimal reproducible example that illustrates my problem:

import uuid
from datetime import datetime
from typing import Optional
from pydantic import BaseModel, UUID4, Field

class ModelA(BaseModel):
    id: UUID4 = Field(default_factory=uuid.uuid4)
    related_b: Optional["ModelB"] = None  # Cyclic reference

class ModelB(BaseModel):
    id: UUID4 = Field(default_factory=uuid.uuid4)
    related_a: Optional[ModelA] = None  # Cyclic reference

class ModelC(BaseModel):
    id: UUID4 = Field(default_factory=uuid.uuid4)
    items: List[ModelA] = []  # Cyclic reference to ModelA

What I’ve Tried:

1. Setting exclude=True on fields that reference cyclic dependencies:

trades: list["Trade"] = Field([], exclude=True)

2. Using ConfigDict(arbitrary_types_allowed=True), but the issue persists.
3. Adding sys.setrecursionlimit(1500) in conf.py, which only delays the error.

Expected Behavior:

I would like Sphinx to generate OpenAPI documentation without hitting a recursion limit due to cyclic dependencies.

Any help would be greatly appreciated!