Configuration
One major strength of autodoc_pydantic is that every feature is completely configurable to allow maximum customization. There are two ways to configure how pydantic objects are displayed:
conf.py: Globally define the default configuration via
conf.py
which takes effect for all pydantic objects like:autodoc_pydantic_model_show_json = True autodoc_pydantic_model_show_config_summary = False
directive: Locally define specific configurations via directive options. This overrides global configuration settings:
.. autopydantic_model:: module.Model :model-show-json: True :model-show-config-summary: False
Note
The following sections describe all available configurations in separation. Each configuration is activated in isolation while the remaining are disabled to highlight actual difference.
Model
Contains all modifications for pydantic BaseModel.
Show Config Summary
Show model config summary within the class doc string. It may be meaningful when the class configuration carries some relevant information.
Configuration (added in version 0.1.0)
- conf.py:
autodoc_pydantic_model_show_config_summary
- directive:
model-show-config-summary
Available values with rendered examples
Show Validator Summary
Show all validators along with corresponding fields within the class doc string. Hyperlinks are automatically created for validators and fields. This is especially useful when dealing with large models having a lot of validators. Please note, the sort order of summary items can be configured via model-summary-list-order.
Configuration (added in version 0.1.0)
- conf.py:
autodoc_pydantic_model_show_validator_summary
- directive:
model-show-validator-summary
Available values with rendered examples
- class ModelShowValidatorsSummary(*, field: int = 1)[source]
ModelShowValidatorsSummary.
- Validators:
check
»field
- class ModelShowValidatorsSummary(*, field: int = 1)[source]
ModelShowValidatorsSummary.
class ModelShowValidatorsSummary(BaseModel):
"""ModelShowValidatorsSummary."""
field: int = 1
@field_validator('field')
def check(cls, v) -> str:
return v
Show Validator Members
Show pydantic validator methods. They can be hidden if they are irrelevant.
Configuration (added in version 0.1.0)
- conf.py:
autodoc_pydantic_model_show_validator_members
- directive:
model-show-validator-members
Available values with rendered examples
- class ModelShowValidatorMembers(*, field: int = 1)[source]
ModelShowValidatorMembers.
- attribute field: int
Field.
class ModelShowValidatorMembers(BaseModel):
"""ModelShowValidatorMembers."""
field: int = 1
"""Field."""
@field_validator('field')
def dummy(cls, v) -> str:
"""Check."""
return v
Show Field Summary
Show all fields within the class doc string. Hyperlinks are automatically created. This is especially useful when dealing with large models having a lot of fields. Please note, the sort order of summary items can be configured via model-summary-list-order.
Configuration (added in version 1.2.0)
- conf.py:
autodoc_pydantic_model_show_field_summary
- directive:
model-show-field-summary
Available values with rendered examples
- class ModelShowFieldSummary(*, field1: int = 5, field2: str = 'FooBar')[source]
ModelShowFieldSummary.
- Fields:
field1 (int)
field2 (str)
- class ModelShowFieldSummary(*, field1: int = 5, field2: str = 'FooBar')[source]
ModelShowFieldSummary.
class ModelShowFieldSummary(BaseModel):
"""ModelShowFieldSummary."""
field1: int = 5
field2: str = 'FooBar'
Summary List Order
Define the sort order within validator and field summaries (which can be activated via model-show-validator-summary and model-show-field-summary, respectively).
Configuration (added in version 1.5.0)
- conf.py:
autodoc_pydantic_model_summary_list_order
- directive:
model-summary-list-order
Available values with rendered examples
- class ModelSummaryListOrder(*, field_b: int = 1, field_a: int = 1)[source]
ModelSummaryListOrder.
- Fields:
field_a (int)
field_b (int)
- Validators:
validate_a
»field_a
validate_b
»field_b
- class ModelSummaryListOrder(*, field_b: int = 1, field_a: int = 1)[source]
ModelSummaryListOrder.
- Fields:
field_b (int)
field_a (int)
- Validators:
validate_b
»field_b
validate_a
»field_a
class ModelSummaryListOrder(BaseModel):
"""ModelSummaryListOrder."""
field_b: int = 1
field_a: int = 1
@field_validator('field_b')
def validate_b(cls, v):
return v
@field_validator('field_a')
def validate_a(cls, v):
return v
Show Undoc Members
Show undocumented members. By default, undocumented members are hidden for
standard auto
directives. For pydantic models, this is overwritten
if enabled.
Configuration (added in version 0.1.0)
- conf.py:
autodoc_pydantic_model_undoc_members
- directive:
undoc-members
Available values with rendered examples
- class ModelUndocMembers(*, field1: int = 5, field2: str = 'FooBar')[source]
ModelUndocMembers.
- attribute field1: int
- attribute field2: str
- class ModelUndocMembers(*, field1: int = 5, field2: str = 'FooBar')[source]
ModelUndocMembers.
class ModelUndocMembers(BaseModel):
"""ModelUndocMembers."""
field1: int = 5
field2: str = 'FooBar'
Note
In order to show any members at all, you need to enable
autodoc_pydantic_model_members
or set :members:
.
Show Members
Show members. By default, members are hidden for standard auto
directives. For pydantic models, this is overwritten if enabled.
Configuration (added in version 0.1.0)
- conf.py:
autodoc_pydantic_model_members
- directive:
members
Available values with rendered examples
- class ModelMembers(*, field1: int = 5, field2: str = 'FooBar')[source]
ModelMembers.
- attribute field1: int
Doc field 1
- attribute field2: str
Doc field 2
- class ModelMembers(*, field1: int = 5, field2: str = 'FooBar')[source]
ModelMembers.
class ModelMembers(BaseModel):
"""ModelMembers."""
field1: int = 5
"""Doc field 1"""
field2: str = 'FooBar'
"""Doc field 2"""
Member Order
Order members groupwise by default in the following order: fields, validators and config.
Configuration (added in version 0.1.0)
- conf.py:
autodoc_pydantic_model_member_order
- directive:
member-order
Available values with rendered examples
class ModelMemberOrder(BaseModel):
"""ModelMemberOrder."""
@field_validator('field')
def dummy(cls, v) -> str:
"""Check."""
return v
model_config = ConfigDict(frozen=False)
field: int = 1
"""Field."""
Hide ParamList
Hide parameter list within class signature which usually becomes rather overloaded once a lot fields are present. Additionally, it is redundant since fields are documented anyway.
Configuration (added in version 0.1.0)
- conf.py:
autodoc_pydantic_model_hide_paramlist
- directive:
model-hide-paramlist
Available values with rendered examples
Hide Reused Validators
Hide class methods that are created while declaring functions as reusable validators. For more information and a detailed example, please see the example page for reused validators.
Configuration (added in version 1.8.0)
- conf.py:
autodoc_pydantic_model_hide_reused_validator
- directive:
model-hide-reused-validator
Available values with rendered examples
- class ModelOne(*, name: str)[source]
- attribute name: str
Name
- class ModelOne(*, name: str)[source]
- attribute name: str
Name
- normalize_name()
Reused validator class method.
from pydantic import BaseModel, field_validator
def validation(name):
"""Validation function."""
return name
class ModelOne(BaseModel):
name: str
"""Name"""
normalize_name = field_validator('name')(validation)
"""Reused validator class method."""
Signature Prefix
Define the signature prefix for pydantic models.
Configuration (added in version 0.1.0)
- conf.py:
autodoc_pydantic_model_signature_prefix
- directive:
model-signature-prefix
Available values with rendered examples
Show Erdantic figure
Show the entity relationship diagram of the schemas using erdantic. To
use this option, you need first to install
graphviz , then install
autodoc_pydantic with the erdantic
option:
pip install autodoc_pydantic[erdantic].
Configuration (added in version 1.9.0)
- conf.py:
autodoc_pydantic_model_erdantic_figure
- directive:
model-erdantic-figure
Available values with rendered examples
- class ModelErdanticFigure(*, field1: int = 5, field2: str = 'FooBar', related: ModelErdanticFigureRelated)[source]
ModelErdanticFigure.
- class ModelErdanticFigure(*, field1: int = 5, field2: str = 'FooBar', related: ModelErdanticFigureRelated)[source]
ModelErdanticFigure.
class ModelErdanticFigure(ModelShowFieldSummary):
"""ModelErdanticFigure."""
related: ModelErdanticFigureRelated
Show Erdantic figure collapsed
Show the entity relationship diagram collapsed or not. model-erdantic-figure must be True for this to have any effect.
Configuration (added in version 1.9.0)
- conf.py:
autodoc_pydantic_model_erdantic_figure_collapsed
- directive:
model-erdantic-figure-collapsed
Available values with rendered examples
- class ModelErdanticFigure(*, field1: int = 5, field2: str = 'FooBar', related: ModelErdanticFigureRelated)[source]
ModelErdanticFigure.
Show Entity Relationship Diagram
- class ModelErdanticFigure(*, field1: int = 5, field2: str = 'FooBar', related: ModelErdanticFigureRelated)[source]
ModelErdanticFigure.
class ModelErdanticFigure(ModelShowFieldSummary):
"""ModelErdanticFigure."""
related: ModelErdanticFigureRelated
Show Schema JSON
Show the schema json representation of a pydantic model within in the class doc string as a collapsable code block.
Configuration (added in version 0.1.0)
- conf.py:
autodoc_pydantic_model_show_json
- directive:
model-show-json
Available values with rendered examples
Warning
Fields containing custom objects may not be JSON serializable. This will break the schema generation by default. However, it can be handled via Show Schema JSON Error Strategy.
Show Schema JSON Error Strategy
Define error handling in case a pydantic field breaks pydantic model schema generation. This occurs if a pydantic field is not JSON serializable.
Configuration (added in version 1.4.0)
- conf.py:
autodoc_pydantic_model_show_json_error_strategy
- directive_option:
model-show-json-error-strategy
Available values:
coerce
: Keep violating fields in resulting schema but only show the title. Do not provide a warning during doc building process.warn
(default): Keep violating fields in resulting schema but only show the title. Provide a warning during the doc building process.raise
: Raises ansphinx.errors.ExtensionError
during building process.
Settings
Contains all modifications for pydantic BaseSettings.
Show Config Summary
Show model config summary within the class doc string. It may be meaningful when the class configuration carries some relevant information.
Configuration (added in version 0.1.0)
- conf.py:
autodoc_pydantic_settings_show_config_summary
- directive:
settings-show-config-summary
Available values with rendered examples
- class SettingsShowConfigSummary(_case_sensitive: bool | None = None, _env_prefix: str | None = None, _env_file: DotenvType | None = PosixPath('.'), _env_file_encoding: str | None = None, _env_ignore_empty: bool | None = None, _env_nested_delimiter: str | None = None, _env_parse_none_str: str | None = None, _secrets_dir: str | Path | None = None)[source]
SettingsShowConfigSummary.
- Config:
title: str = FooBar
frozen: bool = False
- class SettingsShowConfigSummary(_case_sensitive: bool | None = None, _env_prefix: str | None = None, _env_file: DotenvType | None = PosixPath('.'), _env_file_encoding: str | None = None, _env_ignore_empty: bool | None = None, _env_nested_delimiter: str | None = None, _env_parse_none_str: str | None = None, _secrets_dir: str | Path | None = None)[source]
SettingsShowConfigSummary.
class SettingsShowConfigSummary(BaseSettings):
"""SettingsShowConfigSummary."""
model_config = SettingsConfigDict(title='FooBar', frozen=False)
Show Validator Summary
Show all validators along with corresponding fields within the class doc string. Hyperlinks are automatically created for validators and fields. This is especially useful when dealing with large models having a lot of validators. Please note, the sort order of summary items can be configured via settings-summary-list-order.
Configuration (added in version 0.1.0)
- conf.py:
autodoc_pydantic_settings_show_validator_summary
- directive:
settings-show-validator-summary
Available values with rendered examples
- class SettingsShowValidatorsSummary(_case_sensitive: bool | None = None, _env_prefix: str | None = None, _env_file: DotenvType | None = PosixPath('.'), _env_file_encoding: str | None = None, _env_ignore_empty: bool | None = None, _env_nested_delimiter: str | None = None, _env_parse_none_str: str | None = None, _secrets_dir: str | Path | None = None, *, field: int = 1)[source]
SettingsShowValidatorsSummary.
- Validators:
check
»field
- class SettingsShowValidatorsSummary(_case_sensitive: bool | None = None, _env_prefix: str | None = None, _env_file: DotenvType | None = PosixPath('.'), _env_file_encoding: str | None = None, _env_ignore_empty: bool | None = None, _env_nested_delimiter: str | None = None, _env_parse_none_str: str | None = None, _secrets_dir: str | Path | None = None, *, field: int = 1)[source]
SettingsShowValidatorsSummary.
class SettingsShowValidatorsSummary(BaseSettings):
"""SettingsShowValidatorsSummary."""
field: int = 1
@field_validator('field')
def check(cls, v) -> str:
return v
Show Validator Members
Show pydantic validator methods. They can be hidden if they are irrelevant.
Configuration (added in version 0.1.0)
- conf.py:
autodoc_pydantic_settings_show_validator_members
- directive:
settings-show-validator-members
Available values with rendered examples
- class SettingsShowValidatorMembers(_case_sensitive: bool | None = None, _env_prefix: str | None = None, _env_file: DotenvType | None = PosixPath('.'), _env_file_encoding: str | None = None, _env_ignore_empty: bool | None = None, _env_nested_delimiter: str | None = None, _env_parse_none_str: str | None = None, _secrets_dir: str | Path | None = None, *, field: int = 1)[source]
SettingsShowValidatorMembers.
- classmethod dummy(v) str [source]
Check.
- attribute field: int
Field.
- class SettingsShowValidatorMembers(_case_sensitive: bool | None = None, _env_prefix: str | None = None, _env_file: DotenvType | None = PosixPath('.'), _env_file_encoding: str | None = None, _env_ignore_empty: bool | None = None, _env_nested_delimiter: str | None = None, _env_parse_none_str: str | None = None, _secrets_dir: str | Path | None = None, *, field: int = 1)[source]
SettingsShowValidatorMembers.
- attribute field: int
Field.
class SettingsShowValidatorMembers(BaseSettings):
"""SettingsShowValidatorMembers."""
field: int = 1
"""Field."""
@field_validator('field')
def dummy(cls, v) -> str:
"""Check."""
return v
Show Field Summary
Show all fields within the class doc string. Hyperlinks are automatically created. This is especially useful when dealing with large models having a lot of fields. Please note, the sort order of summary items can be configured via settings-summary-list-order.
Configuration (added in version 1.2.0)
- conf.py:
autodoc_pydantic_settings_show_field_summary
- directive:
settings-show-field-summary
Available values with rendered examples
- class SettingsShowFieldSummary(_case_sensitive: bool | None = None, _env_prefix: str | None = None, _env_file: DotenvType | None = PosixPath('.'), _env_file_encoding: str | None = None, _env_ignore_empty: bool | None = None, _env_nested_delimiter: str | None = None, _env_parse_none_str: str | None = None, _secrets_dir: str | Path | None = None, *, field1: int = 5, field2: str = 'FooBar')[source]
SettingsShowFieldSummary.
- Fields:
field1 (int)
field2 (str)
- attribute field1: int
Field1.
- attribute field2: str
Field2.
- class SettingsShowFieldSummary(_case_sensitive: bool | None = None, _env_prefix: str | None = None, _env_file: DotenvType | None = PosixPath('.'), _env_file_encoding: str | None = None, _env_ignore_empty: bool | None = None, _env_nested_delimiter: str | None = None, _env_parse_none_str: str | None = None, _secrets_dir: str | Path | None = None, *, field1: int = 5, field2: str = 'FooBar')[source]
SettingsShowFieldSummary.
- attribute field1: int
Field1.
- attribute field2: str
Field2.
class SettingsShowFieldSummary(BaseSettings):
"""SettingsShowFieldSummary."""
field1: int = 5
"""Field1."""
field2: str = 'FooBar'
"""Field2."""
Summary List Order
Define the sort order within validator and field summaries (which can be activated via settings-show-validator-summary and settings-show-field-summary, respectively).
Configuration (added in version 1.5.0)
- conf.py:
autodoc_pydantic_settings_summary_list_order
- directive:
settings-summary-list-order
Available values with rendered examples
- class SettingsSummaryListOrder(_case_sensitive: bool | None = None, _env_prefix: str | None = None, _env_file: DotenvType | None = PosixPath('.'), _env_file_encoding: str | None = None, _env_ignore_empty: bool | None = None, _env_nested_delimiter: str | None = None, _env_parse_none_str: str | None = None, _secrets_dir: str | Path | None = None, *, field_b: int = 1, field_a: int = 1)[source]
SettingsSummaryListOrder.
- Fields:
field_a (int)
field_b (int)
- Validators:
validate_a
»field_a
validate_b
»field_b
- class SettingsSummaryListOrder(_case_sensitive: bool | None = None, _env_prefix: str | None = None, _env_file: DotenvType | None = PosixPath('.'), _env_file_encoding: str | None = None, _env_ignore_empty: bool | None = None, _env_nested_delimiter: str | None = None, _env_parse_none_str: str | None = None, _secrets_dir: str | Path | None = None, *, field_b: int = 1, field_a: int = 1)[source]
SettingsSummaryListOrder.
- Fields:
field_b (int)
field_a (int)
- Validators:
validate_b
»field_b
validate_a
»field_a
class SettingsSummaryListOrder(BaseSettings):
"""SettingsSummaryListOrder."""
field_b: int = 1
field_a: int = 1
@field_validator('field_b')
def validate_b(cls, v):
return v
@field_validator('field_a')
def validate_a(cls, v):
return v
Show Undoc Members
Show undocumented members. By default, undocumented members are hidden for
standard auto
directives. For pydantic settings, this is overwritten
if enabled.
Configuration (added in version 0.1.0)
- conf.py:
autodoc_pydantic_settings_undoc_members
- directive:
undoc-members
Available values with rendered examples
- class SettingsUndocMembers(_case_sensitive: bool | None = None, _env_prefix: str | None = None, _env_file: DotenvType | None = PosixPath('.'), _env_file_encoding: str | None = None, _env_ignore_empty: bool | None = None, _env_nested_delimiter: str | None = None, _env_parse_none_str: str | None = None, _secrets_dir: str | Path | None = None, *, field1: int = 5, field2: str = 'FooBar')[source]
SettingsUndocMembers.
- attribute field1: int
- attribute field2: str
- class SettingsUndocMembers(_case_sensitive: bool | None = None, _env_prefix: str | None = None, _env_file: DotenvType | None = PosixPath('.'), _env_file_encoding: str | None = None, _env_ignore_empty: bool | None = None, _env_nested_delimiter: str | None = None, _env_parse_none_str: str | None = None, _secrets_dir: str | Path | None = None, *, field1: int = 5, field2: str = 'FooBar')[source]
SettingsUndocMembers.
class SettingsUndocMembers(BaseSettings):
"""SettingsUndocMembers."""
field1: int = 5
field2: str = 'FooBar'
Note
In order to show any members at all, you need to enable
autodoc_pydantic_settings_members
or set :members:
.
Show Members
Show members. By default, members are hidden for standard auto
directives. For pydantic settingss, this is overwritten if enabled.
Configuration (added in version 0.1.0)
- conf.py:
autodoc_pydantic_settings_members
- directive:
members
Available values with rendered examples
- class SettingsMembers(_case_sensitive: bool | None = None, _env_prefix: str | None = None, _env_file: DotenvType | None = PosixPath('.'), _env_file_encoding: str | None = None, _env_ignore_empty: bool | None = None, _env_nested_delimiter: str | None = None, _env_parse_none_str: str | None = None, _secrets_dir: str | Path | None = None, *, field1: int = 5, field2: str = 'FooBar')[source]
SettingsMembers.
- attribute field1: int
Doc field 1
- attribute field2: str
Doc field 2
- class SettingsMembers(_case_sensitive: bool | None = None, _env_prefix: str | None = None, _env_file: DotenvType | None = PosixPath('.'), _env_file_encoding: str | None = None, _env_ignore_empty: bool | None = None, _env_nested_delimiter: str | None = None, _env_parse_none_str: str | None = None, _secrets_dir: str | Path | None = None, *, field1: int = 5, field2: str = 'FooBar')[source]
SettingsMembers.
class SettingsMembers(BaseSettings):
"""SettingsMembers."""
field1: int = 5
"""Doc field 1"""
field2: str = 'FooBar'
"""Doc field 2"""
Member Order
Order members groupwise by default in the following order: fields, validators and config.
Configuration (added in version 0.1.0)
- conf.py:
autodoc_pydantic_settings_member_order
- directive:
member-order
Available values with rendered examples
- class SettingsMemberOrder(_case_sensitive: bool | None = None, _env_prefix: str | None = None, _env_file: DotenvType | None = PosixPath('.'), _env_file_encoding: str | None = None, _env_ignore_empty: bool | None = None, _env_nested_delimiter: str | None = None, _env_parse_none_str: str | None = None, _secrets_dir: str | Path | None = None, *, field: int = 1)[source]
SettingsMemberOrder.
- attribute field: int
Field.
- classmethod dummy(v) str [source]
Check.
- class SettingsMemberOrder(_case_sensitive: bool | None = None, _env_prefix: str | None = None, _env_file: DotenvType | None = PosixPath('.'), _env_file_encoding: str | None = None, _env_ignore_empty: bool | None = None, _env_nested_delimiter: str | None = None, _env_parse_none_str: str | None = None, _secrets_dir: str | Path | None = None, *, field: int = 1)[source]
SettingsMemberOrder.
- classmethod dummy(v) str [source]
Check.
- attribute field: int
Field.
- class SettingsMemberOrder(_case_sensitive: bool | None = None, _env_prefix: str | None = None, _env_file: DotenvType | None = PosixPath('.'), _env_file_encoding: str | None = None, _env_ignore_empty: bool | None = None, _env_nested_delimiter: str | None = None, _env_parse_none_str: str | None = None, _secrets_dir: str | Path | None = None, *, field: int = 1)[source]
SettingsMemberOrder.
- classmethod dummy(v) str [source]
Check.
- attribute field: int
Field.
class SettingsMemberOrder(BaseSettings):
"""SettingsMemberOrder."""
@field_validator('field')
def dummy(cls, v) -> str:
"""Check."""
return v
model_config = SettingsConfigDict(frozen=False)
field: int = 1
"""Field."""
Hide ParamList
Hide parameter list within class signature which usually becomes rather overloaded once a lot fields are present. Additionally, it is redundant since fields are documented anyway.
Configuration (added in version 0.1.0)
- conf.py:
autodoc_pydantic_settings_hide_paramlist
- directive:
settings-hide-paramlist
Available values with rendered examples
- class SettingsHideParamList[source]
SettingsHideParamList.
- class SettingsHideParamList(_case_sensitive: bool | None = None, _env_prefix: str | None = None, _env_file: DotenvType | None = PosixPath('.'), _env_file_encoding: str | None = None, _env_ignore_empty: bool | None = None, _env_nested_delimiter: str | None = None, _env_parse_none_str: str | None = None, _secrets_dir: str | Path | None = None, *, field1: int = 5, field2: str = 'FooBar')[source]
SettingsHideParamList.
class SettingsHideParamList(BaseSettings):
"""SettingsHideParamList."""
field1: int = 5
field2: str = 'FooBar'
Hide Reused Validators
Hide class methods that are created while declaring functions as reusable validators. For more information and a detailed example, please see the example page for reused validators.
Configuration (added in version 1.8.0)
- conf.py:
autodoc_pydantic_settings_hide_reused_validator
- directive:
settings-hide-reused-validator
Available values with rendered examples
- class SettingOne(*, name: str)[source]
- attribute name: str
Name
- class SettingOne(*, name: str)[source]
- attribute name: str
Name
- normalize_name()
Reused validator class method.
from pydantic import BaseModel, field_validator
def validation(name):
"""Validation function."""
return name
class SettingOne(BaseModel):
name: str
"""Name"""
normalize_name = field_validator('name')(validation)
"""Reused validator class method."""
Signature Prefix
Define the signature prefix for pydantic settings.
Configuration (added in version 0.1.0)
- conf.py:
autodoc_pydantic_settings_signature_prefix
- directive:
settings-signature-prefix
Available values with rendered examples
- pydantic settings SettingsSignaturePrefix(_case_sensitive: bool | None = None, _env_prefix: str | None = None, _env_file: DotenvType | None = PosixPath('.'), _env_file_encoding: str | None = None, _env_ignore_empty: bool | None = None, _env_nested_delimiter: str | None = None, _env_parse_none_str: str | None = None, _secrets_dir: str | Path | None = None)[source]
SettingsSignaturePrefix.
- class SettingsSignaturePrefix(_case_sensitive: bool | None = None, _env_prefix: str | None = None, _env_file: DotenvType | None = PosixPath('.'), _env_file_encoding: str | None = None, _env_ignore_empty: bool | None = None, _env_nested_delimiter: str | None = None, _env_parse_none_str: str | None = None, _secrets_dir: str | Path | None = None)[source]
SettingsSignaturePrefix.
- foobar SettingsSignaturePrefix(_case_sensitive: bool | None = None, _env_prefix: str | None = None, _env_file: DotenvType | None = PosixPath('.'), _env_file_encoding: str | None = None, _env_ignore_empty: bool | None = None, _env_nested_delimiter: str | None = None, _env_parse_none_str: str | None = None, _secrets_dir: str | Path | None = None)[source]
SettingsSignaturePrefix.
class SettingsSignaturePrefix(BaseSettings):
"""SettingsSignaturePrefix."""
Show Schema JSON
Show the schema json representation of pydantic settings within in the class doc string as a collapsable code block.
Configuration (added in version 0.1.0)
- conf.py:
autodoc_pydantic_settings_show_json
- directive:
settings-show-json
Available values with rendered examples
- class SettingsShowJson(_case_sensitive: bool | None = None, _env_prefix: str | None = None, _env_file: DotenvType | None = PosixPath('.'), _env_file_encoding: str | None = None, _env_ignore_empty: bool | None = None, _env_nested_delimiter: str | None = None, _env_parse_none_str: str | None = None, _secrets_dir: str | Path | None = None)[source]
SettingsShowJson.
Show JSON schema
{ "title": "SettingsShowJson", "description": "SettingsShowJson.", "type": "object", "properties": {}, "additionalProperties": false }
- class SettingsShowJson(_case_sensitive: bool | None = None, _env_prefix: str | None = None, _env_file: DotenvType | None = PosixPath('.'), _env_file_encoding: str | None = None, _env_ignore_empty: bool | None = None, _env_nested_delimiter: str | None = None, _env_parse_none_str: str | None = None, _secrets_dir: str | Path | None = None)[source]
SettingsShowJson.
class SettingsShowJson(BaseSettings):
"""SettingsShowJson."""
Warning
Fields containing custom objects may not be JSON serializable. This will break the schema generation by default. However, it can be handled via Show Schema JSON Error Strategy.
Show Schema JSON Error Strategy
Define error handling in case a pydantic field breaks pydantic settings schema generation. This occurs if a pydantic field is not JSON serializable.
Configuration (added in version 1.4.0)
- conf.py:
autodoc_pydantic_settings_show_json_error_strategy
- directive_option:
settings-show-json-error-strategy
Available values:
coerce
: Keep violating fields in resulting schema but only show the title. Do not provide a warning during doc building process.warn
(default): Keep violating fields in resulting schema but only show the title. Provide a warning during the doc building process.raise
: Raises ansphinx.errors.ExtensionError
during building process.
Fields
List Validators
List all linked validators within doc string that process the current field. Hyperlinks to corresponding validators are automatically provided.
Configuration (added in version 0.1.0)
- conf.py:
autodoc_pydantic_field_list_validators
- directive:
field-list-validators
Available values with rendered examples
class FieldListValidators(BaseModel):
"""FieldListValidators."""
field: int = 1
"""Field."""
@field_validator('field')
def check(cls, v) -> str:
"""Check."""
return v
Docstring Policy
Define what content is displayed in the main field docstring. The following values are possible:
docstring shows the exact docstring of the python attribute.
description displays the information provided via the pydantic field’s description.
both will output the attribute’s docstring together with the pydantic field’s description.
Configuration (added in version 0.1.0)
- conf.py:
autodoc_pydantic_field_doc_policy
- directive:
field-doc-policy
Available values with rendered examples
- class FieldDocPolicy(*, field: int = 1)[source]
FieldDocPolicy.
- attribute field: int
Field.
- class FieldDocPolicy(*, field: int = 1)[source]
FieldDocPolicy.
- attribute field: int
Custom Desc.
- class FieldDocPolicy(*, field: int = 1)[source]
FieldDocPolicy.
- attribute field: int
Field.
Custom Desc.
class FieldDocPolicy(BaseModel):
"""FieldDocPolicy."""
field: int = Field(1, description='Custom Desc.')
"""Field."""
Show Constraints
Displays all constraints that are associated with the given pydantic field.
Configuration (added in version 0.1.0)
- conf.py:
autodoc_pydantic_field_show_constraints
- directive:
field-show-constraints
Available values with rendered examples
- class FieldShowConstraints(*, field: int = 1)[source]
FieldShowConstraints.
- attribute field: int
Field.
- Constraints:
ge = 0
le = 100
- class FieldShowConstraints(*, field: int = 1)[source]
FieldShowConstraints.
- attribute field: int
Field.
class FieldShowConstraints(BaseModel):
"""FieldShowConstraints."""
field: int = Field(1, ge=0, le=100)
"""Field."""
Show Alias
Provides the pydantic field’s alias in the signature.
Configuration (added in version 0.1.0)
- conf.py:
autodoc_pydantic_field_show_alias
- directive:
field-show-alias
Available values with rendered examples
- class FieldShowAlias(*, field2: int = 1)[source]
FieldShowAlias.
- attribute field: int (alias 'field2')
Field.
- class FieldShowAlias(*, field2: int = 1)[source]
FieldShowAlias.
- attribute field: int
Field.
class FieldShowAlias(BaseModel):
"""FieldShowAlias."""
field: int = Field(1, alias='field2')
"""Field."""
Show Default Value
Provides the pydantic field’s default value in the signature. Unfortunately this is not provided by standard sphinx autodoc (as of version 4.5.0).
Configuration (added in version 1.4.0)
- conf.py:
autodoc_pydantic_field_show_default
- directive:
field-show-default
Available values with rendered examples
Show Required
Add [Required]
marker for all pydantic fields that do not have a default
value. Otherwise, misleading None
is displayed when
field-show-default is enabled.
Configuration (added in version 0.1.0)
- conf.py:
autodoc_pydantic_field_show_required
- directive:
field-show-required
Available values with rendered examples
- class FieldShowRequired(*, field1: int, field2: int, field3: int, field4: int | None)[source]
FieldShowRequired.
- attribute field1: int [Required]
field1
- attribute field2: int [Required]
field2
- attribute field3: int [Required]
field3
- attribute field4: int | None [Required]
field4
- class FieldShowRequired(*, field1: int, field2: int, field3: int, field4: int | None)[source]
FieldShowRequired.
- attribute field1: int = PydanticUndefined
field1
- attribute field2: int = PydanticUndefined
field2
- attribute field3: int = PydanticUndefined
field3
- attribute field4: int | None = PydanticUndefined
field4
class FieldShowRequired(BaseModel):
"""FieldShowRequired."""
field1: int
"""field1"""
field2: int = ...
"""field2"""
field3: int = Field(default=...)
"""field3"""
field4: Optional[int]
"""field4"""
Show Optional
Add [Optional]
marker for all pydantic fields that have a
default_factory
. Otherwise, misleading None
is displayed when
field-show-default is enabled.
Configuration (added in version 1.7.0)
- conf.py:
autodoc_pydantic_field_show_optional
- directive:
field-show-optional
Available values with rendered examples
- class FieldShowOptional(*, field1: int = None, field2: int | None = None)[source]
- attribute field1: int [Optional]
field1
- attribute field2: int | None [Optional]
field2
- class FieldShowOptional(*, field1: int = None, field2: int | None = None)[source]
- attribute field1: int = PydanticUndefined
field1
- attribute field2: int | None = PydanticUndefined
field2
class FieldShowOptional(BaseModel):
"""FieldShowOptional"""
field1: int = Field(default_factory=lambda: 1)
"""field1"""
field2: Optional[int] = Field(default_factory=lambda: 1)
"""field2"""
Swap Name and Alias
Swaps field name with field alias. If field-show-alias is enabled, the original alias shows the actual field name instead.
Hint
Enabling this option will automatically interact with the following configurations by replacing the field name with the field alias:
A complete example is provided here.
Configuration (added in version 1.7.0)
- conf.py:
autodoc_pydantic_field_swap_name_and_alias
- directive:
field-swap-name-and-alias
Available values with rendered examples
- class FieldSwapNameAndAlias(*, field1: int = 1)[source]
- attribute field1: int (alias 'field 1 alias')
Field1
- class FieldSwapNameAndAlias(*, field1: int = 1)[source]
- attribute field 1 alias: int (name 'field1')
Field1
class FieldSwapNameAndAlias(BaseModel):
"""FieldSwapNameAndAlias"""
field1: int = Field(default=1, alias='field 1 alias')
"""Field1"""
Signature Prefix
Define the signature prefix for pydantic field.
Configuration (added in version 0.1.0)
- conf.py:
autodoc_pydantic_field_signature_prefix
- directive:
field-signature-prefix
Available values with rendered examples
- class FieldSignaturePrefix(*, field: int = 1)[source]
FieldSignaturePrefix.
- field field: int
Field.
- class FieldSignaturePrefix(*, field: int = 1)[source]
FieldSignaturePrefix.
- attribute field: int
Field.
- class FieldSignaturePrefix(*, field: int = 1)[source]
FieldSignaturePrefix.
- foobar field: int
Field.
class FieldSignaturePrefix(BaseModel):
"""FieldSignaturePrefix."""
field: int = 1
"""Field."""
Validators
Replace Signature
Replaces the validator signature with custom links to corresponding fields. Pydantic validator signatures usually do not carry important information and hence may be replaced. However, you may want to keep the signature patterns constant across methods. In this scenario, you may list the associated fields within the doc string via validator-list-fields.
Configuration (added in version 0.1.0)
- conf.py:
autodoc_pydantic_validator_replace_signature
- directive:
validator-replace-signature
Available values with rendered examples
class ValidatorReplaceSignature(BaseModel):
"""ValidatorReplaceSignature."""
field: int = 1
@field_validator('field')
def check(cls, v) -> str:
"""Check."""
return v
List Fields
List all fields that are processed by current validator. This provides the same information as validator-replace-signature, however it does not change the signature but adds the links in the doc string.
Configuration (added in version 0.1.0)
- conf.py:
autodoc_pydantic_validator_list_fields
- directive:
validator-list-fields
Available values with rendered examples
class ValidatorListFields(BaseModel):
"""ValidatorListFields."""
field: int = 1
@field_validator('field')
def check(cls, v) -> str:
"""Check."""
return v
Signature Prefix
Define the signature prefix for pydantic validator.
Configuration (added in version 0.1.0)
- conf.py:
autodoc_pydantic_validator_signature_prefix
- directive:
validator-signature-prefix
Available values with rendered examples
class ValidatorSignaturePrefix(BaseModel):
"""ValidatorSignaturePrefix."""
field: int = 1
@field_validator('field')
def check(cls, v) -> str:
"""Check."""
return v
General
Add Fallback CSS Class
Adds fallback css classes for HTML content generated by autodoc_pydantic
to prevent breaking themes which rely on the standard sphinx autodoc
objtype
css classes.
More concretely, the following auto-documenter directives gain the following css fallback classes:
pydantic_model -> class
pydantic_settings -> class
pydantic_field -> attribute
pydantic_validator -> method
pydantic_config -> class
For more, please see the corresponding FAQ section.
Configuration (added in version 1.6.0)
- conf.py:
autodoc_pydantic_add_fallback_css_class
Available values:
True
(default): Add fallback CSS classes.False
: Do not add fallback CSS classes.
Note
Sphinx versions prior 4.0.0
did not include the objtype
as a default
css class for the corresponding docutil nodes. autodoc_pydantic will
add the objtype
as a css class for its generated output for older sphinx
versions, too.