[Python] Sphinx Maximum Recursion Depth Exceeded in Pydantic Models with Cyclic Dependencies

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!

• python=3.12
• pydantic=2.10
• astroid=3.2
• sphinx-autoapi=3.2
• sphinx-autodoc-typehints=2.2
• sphinx-book-theme=1.1
• sphinx=7.3
• sphinxcontrib-openapi=0.8
• myst-parser=4.0
• graphviz=12.0
• linkify-it-py=2.0
• mistune=3.0

Continue reading...