FAQ
Migration guide from v1 to v2
In June 2023, pydantic v2 was released while introducing backwards incompatible API and behavioral changes in comparison to pydantic v1. Supporting pydantic v2 required substantial adjustments to the codebase leading to a new major release of autodoc_pydantic (v1.9.0 -> v2.0.0), too.
Do I need to migrate existing sphinx code?
Maybe 😋. autodoc_pydantic’s API remained stable, execpt for removing a redundant and rather exotic feature.
Specifically, the following global conf.py
configurations and their
corresponding local directive options are no longer available:
autodoc_pydantic_model_show_config_member
autodoc_pydantic_settings_show_config_member
autodoc_pydantic_config_members
autodoc_pydantic_config_signature_prefix
These enabled documenting pydantic model configurations in isolation or as a
separate member of the pydantic model (see config-class and
show-config-member). However, they are redundant and less concise in
contrast to autodoc_pydantic_model_show_config_summary
and
autodoc_pydantic_settings_show_config_summary
. Please use these instead
in order to document your model configurations.
Does autodoc_pydantic modify pydantic’s v2 semantics?
No, autodoc_pydantic does not modify the underlying behavior of pydantic in any way. Instead, it only documents whatever pydantic exposes. Hence, all behavioral changes such as the new default strict mode are preserved in v2.
Show inherited fields/validators
Pydantic models can be subclassed to inherit fields and validators from base
classes. Naturally, autodoc_pydantic should also show these members.
By default, sphinx autodoc does not include any member from base classes, though.
However, sphinx autodoc provides a directive option named :inherited-members:
which allows to include all members from all base classes except object
(see docs here).
Unfortunately, this will also include all members from pydantic.BaseModel
(e.g. copy()
, schema()
etc…) which is most likely not what one wants.
Luckily, :inherited-members:
takes a parameter which allows to exclude base classes.
Hence, when supplying BaseModel
as an argument for :inherited-members:
,
irrelevant members are ignored:
from pydantic import BaseModel, field_validator
class Base(BaseModel):
"""MyBase"""
field_on_base: str
"""Base Field"""
@field_validator("field_on_base")
def validate_field_on_base(cls, v):
"""Validate field_on_base"""
return v
class WithoutInheritedMembers(Base):
"""Without `:inherited-members: BaseModel`"""
field_on_subclass: str
"""Subclass field"""
@field_validator("field_on_subclass")
def validate_field_on_subclass(cls, v):
"""Validate field_on_subclass"""
return v
class WithInheritedMembers(Base):
"""With `:inherited-members: BaseModel`"""
field_on_subclass: str
"""Subclass field"""
@field_validator("field_on_subclass")
def validate_field_on_subclass(cls, v):
"""Validate field_on_subclass"""
return v
.. autopydantic_model:: target.faq.inherited_members.WithoutInheritedMembers
.. autopydantic_model:: target.faq.inherited_members.WithInheritedMembers
:inherited-members: BaseModel
- pydantic model WithoutInheritedMembers[source]
Without :inherited-members: BaseModel
Show JSON schema
{ "title": "WithoutInheritedMembers", "description": "Without `:inherited-members: BaseModel`", "type": "object", "properties": { "field_on_base": { "title": "Field On Base", "type": "string" }, "field_on_subclass": { "title": "Field On Subclass", "type": "string" } }, "required": [ "field_on_base", "field_on_subclass" ] }
- Fields:
- Validators:
- field field_on_subclass: str [Required]
Subclass field
- Validated by:
- validator validate_field_on_subclass » field_on_subclass[source]
Validate field_on_subclass
- pydantic model WithInheritedMembers[source]
With :inherited-members: BaseModel
Show JSON schema
{ "title": "WithInheritedMembers", "description": "With `:inherited-members: BaseModel`", "type": "object", "properties": { "field_on_base": { "title": "Field On Base", "type": "string" }, "field_on_subclass": { "title": "Field On Subclass", "type": "string" } }, "required": [ "field_on_base", "field_on_subclass" ] }
- Fields:
- Validators:
- field field_on_base: str [Required]
Base Field
- Validated by:
- field field_on_subclass: str [Required]
Subclass field
- Validated by:
- validator validate_field_on_base » field_on_base
Validate field_on_base
- validator validate_field_on_subclass » field_on_subclass[source]
Validate field_on_subclass
Note
For more, please see the corresponding github issue #32.
Exclude __init__
docstring
If a pydantic model’s documentation rendered by autodoc_pydantic
includes the docstring from the pydantic base class or from the model’s
__init__
method, it may be due to autodoc’s autoclass_content
setting in sphinx’s conf.py
.
The configuration below tells Sphinx to include both the class docstring
and that of __init__
for auto-documented classes:
autoclass_content = "both"
This behavior does also apply to autodoc_pydantic’s
auto-documenters. If you haven’t overwritten the __init__
method in your model, this will look exactly like it has
inherited the Pydantic base class docstring. In order to only
show the class docstring, change this setting back to “class”:
autoclass_content = "class"
Note
For more, please see the corresponding github issue #58.
Document models as an attribute
Pydantic models/settings can be also used and documented as class attributes, as in the following example:
from pydantic import BaseModel, field_validator
class Model(BaseModel):
"""Model Doc String."""
field: int
"""Field Doc String"""
field2: str
"""Field2 Doc String"""
@field_validator("field")
def validate(cls, v):
"""Dummy validator"""
return v
class Container:
"""Container Doc String"""
TEST_MODEL = Model
.. automodule:: target.faq.model_as_attr
:members:
- pydantic model Model[source]
Model Doc String.
Show JSON schema
{ "title": "Model", "description": "Model Doc String.", "type": "object", "properties": { "field": { "title": "Field", "type": "integer" }, "field2": { "title": "Field2", "type": "string" } }, "required": [ "field", "field2" ] }
- Fields:
- Validators:
- field field2: str [Required]
Field2 Doc String
If you auto-document this code via automodule
for example, then the pydantic model
Model
gets both documented as a standalone class and as an class attribute
of Container
. In the ladder case, plain sphinx autodoc adds an alias note
with reference to the main documentation section of Model
by default. It
does not provide more documentation related to Model
to prevent duplication
with the main class documentation.
However until version 1.5.1
, autodoc_pydantic added content like json
schema, field and validator summaries when models/settings were documented
as class attributes. This was removed in version 1.6.0
to be in line with
the default sphinx autodoc behaviour.
Note
For more, please see the corresponding github issue #78.
Broken layout for autodoc_pydantic
Depending on the theme you’re using (e.g. Jupyter-Book), you may experience a broken CSS/HTML layout for content generated by autodoc_pydantic.
This occurs because the auto-documenter’s objtype
is used as the standard
CSS class in their corresponding HTML output. For example, standard python
classes have objtype class
when being documented with sphinx autodoc.
Hence, the resulting css class is class
in the corresponding HTML output.
However, sphinx extensions with custom object types (e.g. pydantic_model
)
will replace the css class class
with pydantic_model
. If a theme relies
on standard css classes like class
, it will break.
Since version 1.6.0
this is fixed by default via
autodoc_pydantic_add_fallback_css_class
which automatically adds the default css classes that autodoc_pydantic
replaces.
Note
For more, please see the corresponding github issue #77.
Interoperability with autoapi
The autoapi package is an alternative to sphinx.ext.autodoc. It solely
relies on static code analysis while sphinx.ext.autodoc
actually imports the
python code to be documented. Moreover, autoapi
leverages custom jinja
templates to generate rst files.
Essentially, autoapi
does not rely on sphinx.ext.autodoc
whereas
autodoc_pydantic is based on it. Hence, autodoc_pydantic is not
compatible with autoapi
. In consequence, documentation generated by
autoapi
ignores autodoc_pydantic.
Note
For more, please see the corresponding github issue #138.