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 = 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: 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 and you don’t want to show the entire config class as an explicit member (see model-show-config-member).
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
- class ModelShowConfigSummary[source]
ModelShowConfigSummary.
- Config:
allow_mutation: bool = True
title: str = FooBar
- class ModelShowConfigSummary[source]
ModelShowConfigSummary.
class ModelShowConfigSummary(BaseModel):
"""ModelShowConfigSummary."""
class Config:
title: str = "FooBar"
allow_mutation: bool = True
Show Config Member
Show pydantic config class. It can be hidden if it is irrelevant or if replaced with model-show-config-summary.
Configuration (added in version 0.1.0)
- conf.py:
autodoc_pydantic_model_show_config_member
- directive:
model-show-config-member
Available values with rendered examples
- class ModelShowConfigMember(*, field: int = 1)[source]
ModelShowConfigMember.
- attribute field: int
Field.
class ModelShowConfigMember(BaseModel):
"""ModelShowConfigMember."""
field: int = 1
"""Field."""
class Config:
"""Config."""
allow_mutation = True
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
@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."""
@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
@validator("field_b")
def validate_b(cls, v):
return v
@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."""
@validator("field")
def dummy(cls, v) -> str:
"""Check."""
return v
class Config:
"""Config."""
allow_mutation = True
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
- classmethod normalize_name()
Reused validator class method.
from pydantic import BaseModel, validator
def validation(name):
"""Validation function."""
return name
class ModelOne(BaseModel):
name: str
"""Name"""
normalize_name = validator('name', allow_reuse=True)(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 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 and you don’t want to show the entire config class as an explicit member (see settings-show-config-member).
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(_env_file: Optional[Union[str, PathLike, List[Union[str, PathLike]], Tuple[Union[str, PathLike], ...]]] = '<object object>', _env_file_encoding: Optional[str] = None, _env_nested_delimiter: Optional[str] = None, _secrets_dir: Optional[Union[str, PathLike]] = None)[source]
SettingsShowConfigSummary.
- Config:
allow_mutation: bool = True
title: str = FooBar
- class SettingsShowConfigSummary(_env_file: Optional[Union[str, PathLike, List[Union[str, PathLike]], Tuple[Union[str, PathLike], ...]]] = '<object object>', _env_file_encoding: Optional[str] = None, _env_nested_delimiter: Optional[str] = None, _secrets_dir: Optional[Union[str, PathLike]] = None)[source]
SettingsShowConfigSummary.
class SettingsShowConfigSummary(BaseSettings):
"""SettingsShowConfigSummary."""
class Config:
title: str = "FooBar"
allow_mutation: bool = True
Show Config Member
Show pydantic config class. It can be hidden if it is irrelevant or if replaced with settings-show-config-summary.
Configuration (added in version 0.1.0)
- conf.py:
autodoc_pydantic_settings_show_config_member
- directive:
settings-show-config-member
Available values with rendered examples
- class SettingsShowConfigMember(_env_file: Optional[Union[str, PathLike, List[Union[str, PathLike]], Tuple[Union[str, PathLike], ...]]] = '<object object>', _env_file_encoding: Optional[str] = None, _env_nested_delimiter: Optional[str] = None, _secrets_dir: Optional[Union[str, PathLike]] = None, *, field: int = 1)[source]
SettingsShowConfigMember.
- class Config[source]
Config.
- allow_mutation = True
- attribute field: int
Field.
- class SettingsShowConfigMember(_env_file: Optional[Union[str, PathLike, List[Union[str, PathLike]], Tuple[Union[str, PathLike], ...]]] = '<object object>', _env_file_encoding: Optional[str] = None, _env_nested_delimiter: Optional[str] = None, _secrets_dir: Optional[Union[str, PathLike]] = None, *, field: int = 1)[source]
SettingsShowConfigMember.
- attribute field: int
Field.
class SettingsShowConfigMember(BaseSettings):
"""SettingsShowConfigMember."""
field: int = 1
"""Field."""
class Config:
"""Config."""
allow_mutation = True
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(_env_file: Optional[Union[str, PathLike, List[Union[str, PathLike]], Tuple[Union[str, PathLike], ...]]] = '<object object>', _env_file_encoding: Optional[str] = None, _env_nested_delimiter: Optional[str] = None, _secrets_dir: Optional[Union[str, PathLike]] = None, *, field: int = 1)[source]
SettingsShowValidatorsSummary.
- Validators:
check
»field
- class SettingsShowValidatorsSummary(_env_file: Optional[Union[str, PathLike, List[Union[str, PathLike]], Tuple[Union[str, PathLike], ...]]] = '<object object>', _env_file_encoding: Optional[str] = None, _env_nested_delimiter: Optional[str] = None, _secrets_dir: Optional[Union[str, PathLike]] = None, *, field: int = 1)[source]
SettingsShowValidatorsSummary.
class SettingsShowValidatorsSummary(BaseSettings):
"""SettingsShowValidatorsSummary."""
field: int = 1
@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(_env_file: Optional[Union[str, PathLike, List[Union[str, PathLike]], Tuple[Union[str, PathLike], ...]]] = '<object object>', _env_file_encoding: Optional[str] = None, _env_nested_delimiter: Optional[str] = None, _secrets_dir: Optional[Union[str, PathLike]] = None, *, field: int = 1)[source]
SettingsShowValidatorMembers.
- classmethod dummy(v) str [source]
Check.
- attribute field: int
Field.
- class SettingsShowValidatorMembers(_env_file: Optional[Union[str, PathLike, List[Union[str, PathLike]], Tuple[Union[str, PathLike], ...]]] = '<object object>', _env_file_encoding: Optional[str] = None, _env_nested_delimiter: Optional[str] = None, _secrets_dir: Optional[Union[str, PathLike]] = None, *, field: int = 1)[source]
SettingsShowValidatorMembers.
- attribute field: int
Field.
class SettingsShowValidatorMembers(BaseSettings):
"""SettingsShowValidatorMembers."""
field: int = 1
"""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(_env_file: Optional[Union[str, PathLike, List[Union[str, PathLike]], Tuple[Union[str, PathLike], ...]]] = '<object object>', _env_file_encoding: Optional[str] = None, _env_nested_delimiter: Optional[str] = None, _secrets_dir: Optional[Union[str, PathLike]] = None, *, field1: int = 5, field2: str = 'FooBar')[source]
SettingsShowFieldSummary.
- Fields:
field1 (int)
field2 (str)
- attribute field1: int
Field1.
- attribute field2: str
Field2.
- class SettingsShowFieldSummary(_env_file: Optional[Union[str, PathLike, List[Union[str, PathLike]], Tuple[Union[str, PathLike], ...]]] = '<object object>', _env_file_encoding: Optional[str] = None, _env_nested_delimiter: Optional[str] = None, _secrets_dir: Optional[Union[str, PathLike]] = 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(_env_file: Optional[Union[str, PathLike, List[Union[str, PathLike]], Tuple[Union[str, PathLike], ...]]] = '<object object>', _env_file_encoding: Optional[str] = None, _env_nested_delimiter: Optional[str] = None, _secrets_dir: Optional[Union[str, PathLike]] = 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(_env_file: Optional[Union[str, PathLike, List[Union[str, PathLike]], Tuple[Union[str, PathLike], ...]]] = '<object object>', _env_file_encoding: Optional[str] = None, _env_nested_delimiter: Optional[str] = None, _secrets_dir: Optional[Union[str, PathLike]] = 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
@validator("field_b")
def validate_b(cls, v):
return v
@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(_env_file: Optional[Union[str, PathLike, List[Union[str, PathLike]], Tuple[Union[str, PathLike], ...]]] = '<object object>', _env_file_encoding: Optional[str] = None, _env_nested_delimiter: Optional[str] = None, _secrets_dir: Optional[Union[str, PathLike]] = None, *, field1: int = 5, field2: str = 'FooBar')[source]
SettingsUndocMembers.
- attribute field1: int
- attribute field2: str
- class SettingsUndocMembers(_env_file: Optional[Union[str, PathLike, List[Union[str, PathLike]], Tuple[Union[str, PathLike], ...]]] = '<object object>', _env_file_encoding: Optional[str] = None, _env_nested_delimiter: Optional[str] = None, _secrets_dir: Optional[Union[str, PathLike]] = 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(_env_file: Optional[Union[str, PathLike, List[Union[str, PathLike]], Tuple[Union[str, PathLike], ...]]] = '<object object>', _env_file_encoding: Optional[str] = None, _env_nested_delimiter: Optional[str] = None, _secrets_dir: Optional[Union[str, PathLike]] = None, *, field1: int = 5, field2: str = 'FooBar')[source]
SettingsMembers.
- attribute field1: int
Doc field 1
- attribute field2: str
Doc field 2
- class SettingsMembers(_env_file: Optional[Union[str, PathLike, List[Union[str, PathLike]], Tuple[Union[str, PathLike], ...]]] = '<object object>', _env_file_encoding: Optional[str] = None, _env_nested_delimiter: Optional[str] = None, _secrets_dir: Optional[Union[str, PathLike]] = 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(_env_file: Optional[Union[str, PathLike, List[Union[str, PathLike]], Tuple[Union[str, PathLike], ...]]] = '<object object>', _env_file_encoding: Optional[str] = None, _env_nested_delimiter: Optional[str] = None, _secrets_dir: Optional[Union[str, PathLike]] = None, *, field: int = 1)[source]
SettingsMemberOrder.
- attribute field: int
Field.
- classmethod dummy(v) str [source]
Check.
- class Config[source]
Config.
- allow_mutation = True
- class SettingsMemberOrder(_env_file: Optional[Union[str, PathLike, List[Union[str, PathLike]], Tuple[Union[str, PathLike], ...]]] = '<object object>', _env_file_encoding: Optional[str] = None, _env_nested_delimiter: Optional[str] = None, _secrets_dir: Optional[Union[str, PathLike]] = None, *, field: int = 1)[source]
SettingsMemberOrder.
- classmethod dummy(v) str [source]
Check.
- class Config[source]
Config.
- allow_mutation = True
- attribute field: int
Field.
- class SettingsMemberOrder(_env_file: Optional[Union[str, PathLike, List[Union[str, PathLike]], Tuple[Union[str, PathLike], ...]]] = '<object object>', _env_file_encoding: Optional[str] = None, _env_nested_delimiter: Optional[str] = None, _secrets_dir: Optional[Union[str, PathLike]] = None, *, field: int = 1)[source]
SettingsMemberOrder.
- class Config[source]
Config.
- allow_mutation = True
- classmethod dummy(v) str [source]
Check.
- attribute field: int
Field.
class SettingsMemberOrder(BaseSettings):
"""SettingsMemberOrder."""
@validator("field")
def dummy(cls, v) -> str:
"""Check."""
return v
class Config:
"""Config."""
allow_mutation = True
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(_env_file: Optional[Union[str, PathLike, List[Union[str, PathLike]], Tuple[Union[str, PathLike], ...]]] = '<object object>', _env_file_encoding: Optional[str] = None, _env_nested_delimiter: Optional[str] = None, _secrets_dir: Optional[Union[str, PathLike]] = 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
- classmethod normalize_name()
Reused validator class method.
from pydantic import BaseModel, validator
def validation(name):
"""Validation function."""
return name
class SettingOne(BaseModel):
name: str
"""Name"""
normalize_name = validator('name', allow_reuse=True)(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(_env_file: Optional[Union[str, PathLike, List[Union[str, PathLike]], Tuple[Union[str, PathLike], ...]]] = '<object object>', _env_file_encoding: Optional[str] = None, _env_nested_delimiter: Optional[str] = None, _secrets_dir: Optional[Union[str, PathLike]] = None)[source]
SettingsSignaturePrefix.
- class SettingsSignaturePrefix(_env_file: Optional[Union[str, PathLike, List[Union[str, PathLike]], Tuple[Union[str, PathLike], ...]]] = '<object object>', _env_file_encoding: Optional[str] = None, _env_nested_delimiter: Optional[str] = None, _secrets_dir: Optional[Union[str, PathLike]] = None)[source]
SettingsSignaturePrefix.
- foobar SettingsSignaturePrefix(_env_file: Optional[Union[str, PathLike, List[Union[str, PathLike]], Tuple[Union[str, PathLike], ...]]] = '<object object>', _env_file_encoding: Optional[str] = None, _env_nested_delimiter: Optional[str] = None, _secrets_dir: Optional[Union[str, PathLike]] = 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(_env_file: Optional[Union[str, PathLike, List[Union[str, PathLike]], Tuple[Union[str, PathLike], ...]]] = '<object object>', _env_file_encoding: Optional[str] = None, _env_nested_delimiter: Optional[str] = None, _secrets_dir: Optional[Union[str, PathLike]] = None)[source]
SettingsShowJson.
Show JSON schema
{ "title": "SettingsShowJson", "description": "SettingsShowJson.", "type": "object", "properties": {}, "additionalProperties": false }
- class SettingsShowJson(_env_file: Optional[Union[str, PathLike, List[Union[str, PathLike]], Tuple[Union[str, PathLike], ...]]] = '<object object>', _env_file_encoding: Optional[str] = None, _env_nested_delimiter: Optional[str] = None, _secrets_dir: Optional[Union[str, PathLike]] = 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."""
@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: ConstrainedIntValue = 1)[source]
FieldShowConstraints.
- attribute field: int
Field.
- Constraints:
minimum = 0
maximum = 100
- class FieldShowConstraints(*, field: ConstrainedIntValue = 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)[source]
FieldShowRequired.
- attribute field1: int [Required]
field1
- attribute field2: int [Required]
field2
- attribute field3: int [Required]
field3
- class FieldShowRequired(*, field1: int, field2: int, field3: int)[source]
FieldShowRequired.
- attribute field1: int = None
field1
- attribute field2: int = None
field2
- attribute field3: int = None
field3
class FieldShowRequired(BaseModel):
"""FieldShowRequired."""
field1: int
"""field1"""
field2: int = ...
"""field2"""
field3: int = Field(default=...)
"""field3"""
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: Optional[int] = None)[source]
- attribute field1: int [Optional]
field1
- attribute field2: Optional[int] [Optional]
field2
- class FieldShowOptional(*, field1: int = None, field2: Optional[int] = None)[source]
- attribute field1: int = None
field1
- attribute field2: Optional[int] = None
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(**extra_data: Any)[source]
- attribute field1: int (alias 'field 1 alias')
Field1
- class FieldSwapNameAndAlias(**extra_data: Any)[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
@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
@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
@validator("field")
def check(cls, v) -> str:
"""Check."""
return v
Config Class
Show Members
Show members. By default, members are hidden for standard auto
directives. For pydantic class config, this is overwritten if enabled.
Configuration (added in version 0.1.0)
- conf.py:
autodoc_pydantic_config_members
- directive:
members
Available values with rendered examples
- class ConfigMembers[source]
ConfigUndocMembers.
class ConfigMembers(BaseModel):
"""ConfigUndocMembers."""
class Config:
allow_mutation = True
"""Allow Mutation."""
title = "foobar"
Note
By default, all undocumented members are shown for the Config class.
The directive option :undoc-members:
is added automatically.
Signature Prefix
Define the signature prefix for config class.
Configuration (added in version 0.1.0)
- conf.py:
autodoc_pydantic_config_signature_prefix
- directive:
config-signature-prefix
Available values with rendered examples
- model Config
Config.
- class Config
Config.
- foobar Config
Config.
class Config:
title: str = "FooBar"
allow_mutation: bool = True
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.