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
option: 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.
BaseModel¶
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).
- conf.py
autodoc_pydantic_model_show_config_summary
- option
model-show-config-summary
Available values with rendered examples:
-
class
target.configuration.
ModelShowConfigSummary
ModelShowConfigSummary.
- Config
allow_mutation: bool = True
title: str = FooBar
-
class
target.configuration.
ModelShowConfigSummary
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.
- conf.py
autodoc_pydantic_model_show_config_member
- option
model-show-config-member
Available values with rendered examples:
-
class
target.configuration.
ModelShowConfigMember
(*, field: int = 1) ModelShowConfigMember.
-
class
Config
Config.
-
allow_mutation
= True
-
-
attribute
field
: int Field.
-
class
-
class
target.configuration.
ModelShowConfigMember
(*, field: int = 1) ModelShowConfigMember.
-
attribute
field
: int Field.
-
attribute
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.
- conf.py
autodoc_pydantic_model_show_validator_summary
- option
model-show-validator-summary
Available values with rendered examples:
-
class
target.configuration.
ModelShowValidatorsSummary
(*, field: int = 1) ModelShowValidatorsSummary.
- Validators
check
»field
-
class
target.configuration.
ModelShowValidatorsSummary
(*, field: int = 1) 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.
- conf.py
autodoc_pydantic_model_show_validator_members
- option
model-show-validator-members
Available values with rendered examples:
-
class
target.configuration.
ModelShowValidatorMembers
(*, field: int = 1) ModelShowValidatorMembers.
-
classmethod
dummy
(v) → str Check.
-
attribute
field
: int Field.
-
classmethod
-
class
target.configuration.
ModelShowValidatorMembers
(*, field: int = 1) ModelShowValidatorMembers.
-
attribute
field
: int Field.
-
attribute
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.
- conf.py
autodoc_pydantic_model_show_field_summary
- option
model-show-field-summary
Available values with rendered examples:
-
class
target.configuration.
ModelShowFieldSummary
(*, field1: int = 5, field2: str = 'FooBar') ModelShowFieldSummary.
- Fields
field1 (int)
field2 (str)
-
class
target.configuration.
ModelShowFieldSummary
(*, field1: int = 5, field2: str = 'FooBar') ModelShowFieldSummary.
class ModelShowFieldSummary(BaseModel):
"""ModelShowFieldSummary."""
field1: int = 5
field2: str = "FooBar"
Show Undoc Members¶
Show undocumented members. By default, undocumented members are hidden for
standard auto
directives. For pydantic models, this is overwritten
if enabled.
- conf.py
autodoc_pydantic_model_undoc_members
- option
undoc-members
Available values with rendered examples:
-
class
target.configuration.
ModelUndocMembers
(*, field1: int = 5, field2: str = 'FooBar') ModelUndocMembers.
-
attribute
field1
: int
-
attribute
field2
: str
-
attribute
-
class
target.configuration.
ModelUndocMembers
(*, field1: int = 5, field2: str = 'FooBar') 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.
- conf.py
autodoc_pydantic_model_members
- option
members
Available values with rendered examples:
-
class
target.configuration.
ModelMembers
(*, field1: int = 5, field2: str = 'FooBar') ModelMembers.
-
attribute
field1
: int Doc field 1
-
attribute
field2
: str Doc field 2
-
attribute
-
class
target.configuration.
ModelMembers
(*, field1: int = 5, field2: str = 'FooBar') 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.
- conf.py
autodoc_pydantic_model_member_order
- option
member-order
Available values with rendered examples:
-
class
target.configuration.
ModelMemberOrder
(*, field: int = 1) ModelMemberOrder.
-
attribute
field
: int Field.
-
classmethod
dummy
(v) → str Check.
-
class
Config
Config.
-
allow_mutation
= True
-
-
attribute
-
class
target.configuration.
ModelMemberOrder
(*, field: int = 1) ModelMemberOrder.
-
classmethod
dummy
(v) → str Check.
-
class
Config
Config.
-
allow_mutation
= True
-
-
attribute
field
: int Field.
-
classmethod
-
class
target.configuration.
ModelMemberOrder
(*, field: int = 1) ModelMemberOrder.
-
class
Config
Config.
-
allow_mutation
= True
-
-
classmethod
dummy
(v) → str Check.
-
attribute
field
: int Field.
-
class
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.
- conf.py
autodoc_pydantic_model_hide_paramlist
- option
model-hide-paramlist
Available values with rendered examples:
-
class
target.configuration.
ModelHideParamList
ModelHideParamList.
-
class
target.configuration.
ModelHideParamList
(*, field1: int = 5, field2: str = 'FooBar') ModelHideParamList.
class ModelHideParamList(BaseModel):
"""ModelHideParamList."""
field1: int = 5
field2: str = "FooBar"
Signature Prefix¶
Define the signature prefix for pydantic models.
- conf.py
autodoc_pydantic_model_signature_prefix
- option
model-signature-prefix
Available values with rendered examples:
-
pydantic model
target.configuration.
ModelSignaturePrefix
ModelSignaturePrefix.
-
class
target.configuration.
ModelSignaturePrefix
ModelSignaturePrefix.
-
foobar
target.configuration.
ModelSignaturePrefix
ModelSignaturePrefix.
class ModelSignaturePrefix(BaseModel):
"""ModelSignaturePrefix."""
Show Schema JSON¶
Show the schema json representation of a pydantic model within in the class doc string as a collapsable code block.
- conf.py
autodoc_pydantic_model_show_json
- option
model-show-json
Available values with rendered examples:
-
class
target.configuration.
ModelShowJson
ModelShowJson.
Show JSON schema
{ "title": "ModelShowJson", "description": "ModelShowJson.", "type": "object", "properties": {} }
-
class
target.configuration.
ModelShowJson
ModelShowJson.
class ModelShowJson(BaseModel):
"""ModelShowJson."""
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.
- conf.py
autodoc_pydantic_model_show_json_error_strategy
- 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.
BaseSettings¶
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).
- conf.py
autodoc_pydantic_settings_show_config_summary
- option
settings-show-config-summary
Available values with rendered examples:
-
class
target.configuration.
SettingsShowConfigSummary
(_env_file: Optional[Union[pathlib.Path, str]] = '<object object>', _env_file_encoding: Optional[str] = None, _secrets_dir: Optional[Union[pathlib.Path, str]] = None) SettingsShowConfigSummary.
- Config
allow_mutation: bool = True
title: str = FooBar
-
class
target.configuration.
SettingsShowConfigSummary
(_env_file: Optional[Union[pathlib.Path, str]] = '<object object>', _env_file_encoding: Optional[str] = None, _secrets_dir: Optional[Union[pathlib.Path, str]] = None) 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.
- conf.py
autodoc_pydantic_settings_show_config_member
- option
settings-show-config-member
Available values with rendered examples:
-
class
target.configuration.
SettingsShowConfigMember
(_env_file: Optional[Union[pathlib.Path, str]] = '<object object>', _env_file_encoding: Optional[str] = None, _secrets_dir: Optional[Union[pathlib.Path, str]] = None, *, field: int = 1) SettingsShowConfigMember.
-
class
Config
Config.
-
allow_mutation
= True
-
-
attribute
field
: int Field.
-
class
-
class
target.configuration.
SettingsShowConfigMember
(_env_file: Optional[Union[pathlib.Path, str]] = '<object object>', _env_file_encoding: Optional[str] = None, _secrets_dir: Optional[Union[pathlib.Path, str]] = None, *, field: int = 1) SettingsShowConfigMember.
-
attribute
field
: int Field.
-
attribute
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.
- conf.py
autodoc_pydantic_settings_show_validator_summary
- option
settings-show-validator-summary
Available values with rendered examples:
-
class
target.configuration.
SettingsShowValidatorsSummary
(_env_file: Optional[Union[pathlib.Path, str]] = '<object object>', _env_file_encoding: Optional[str] = None, _secrets_dir: Optional[Union[pathlib.Path, str]] = None, *, field: int = 1) SettingsShowValidatorsSummary.
- Validators
check
»field
-
class
target.configuration.
SettingsShowValidatorsSummary
(_env_file: Optional[Union[pathlib.Path, str]] = '<object object>', _env_file_encoding: Optional[str] = None, _secrets_dir: Optional[Union[pathlib.Path, str]] = None, *, field: int = 1) 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.
- conf.py
autodoc_pydantic_settings_show_validator_members
- option
settings-show-validator-members
Available values with rendered examples:
-
class
target.configuration.
SettingsShowValidatorMembers
(_env_file: Optional[Union[pathlib.Path, str]] = '<object object>', _env_file_encoding: Optional[str] = None, _secrets_dir: Optional[Union[pathlib.Path, str]] = None, *, field: int = 1) SettingsShowValidatorMembers.
-
classmethod
dummy
(v) → str Check.
-
attribute
field
: int Field.
-
classmethod
-
class
target.configuration.
SettingsShowValidatorMembers
(_env_file: Optional[Union[pathlib.Path, str]] = '<object object>', _env_file_encoding: Optional[str] = None, _secrets_dir: Optional[Union[pathlib.Path, str]] = None, *, field: int = 1) SettingsShowValidatorMembers.
-
attribute
field
: int Field.
-
attribute
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.
- conf.py
autodoc_pydantic_settings_show_field_summary
- option
settings-show-field-summary
Available values with rendered examples:
-
class
target.configuration.
SettingsShowFieldSummary
(_env_file: Optional[Union[pathlib.Path, str]] = '<object object>', _env_file_encoding: Optional[str] = None, _secrets_dir: Optional[Union[pathlib.Path, str]] = None, *, field1: int = 5, field2: str = 'FooBar') SettingsShowFieldSummary.
- Fields
field1 (int)
field2 (str)
-
attribute
field1
: int Field1.
-
attribute
field2
: str Field2.
-
class
target.configuration.
SettingsShowFieldSummary
(_env_file: Optional[Union[pathlib.Path, str]] = '<object object>', _env_file_encoding: Optional[str] = None, _secrets_dir: Optional[Union[pathlib.Path, str]] = None, *, field1: int = 5, field2: str = 'FooBar') SettingsShowFieldSummary.
-
attribute
field1
: int Field1.
-
attribute
field2
: str Field2.
-
attribute
class SettingsShowFieldSummary(BaseSettings):
"""SettingsShowFieldSummary."""
field1: int = 5
"""Field1."""
field2: str = "FooBar"
"""Field2."""
Show Undoc Members¶
Show undocumented members. By default, undocumented members are hidden for
standard auto
directives. For pydantic settings, this is overwritten
if enabled.
- conf.py
autodoc_pydantic_settings_undoc_members
- option
undoc-members
Available values with rendered examples:
-
class
target.configuration.
SettingsUndocMembers
(_env_file: Optional[Union[pathlib.Path, str]] = '<object object>', _env_file_encoding: Optional[str] = None, _secrets_dir: Optional[Union[pathlib.Path, str]] = None, *, field1: int = 5, field2: str = 'FooBar') SettingsUndocMembers.
-
attribute
field1
: int
-
attribute
field2
: str
-
attribute
-
class
target.configuration.
SettingsUndocMembers
(_env_file: Optional[Union[pathlib.Path, str]] = '<object object>', _env_file_encoding: Optional[str] = None, _secrets_dir: Optional[Union[pathlib.Path, str]] = None, *, field1: int = 5, field2: str = 'FooBar') 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.
- conf.py
autodoc_pydantic_settings_members
- option
members
Available values with rendered examples:
-
class
target.configuration.
SettingsMembers
(_env_file: Optional[Union[pathlib.Path, str]] = '<object object>', _env_file_encoding: Optional[str] = None, _secrets_dir: Optional[Union[pathlib.Path, str]] = None, *, field1: int = 5, field2: str = 'FooBar') SettingsMembers.
-
attribute
field1
: int Doc field 1
-
attribute
field2
: str Doc field 2
-
attribute
-
class
target.configuration.
SettingsMembers
(_env_file: Optional[Union[pathlib.Path, str]] = '<object object>', _env_file_encoding: Optional[str] = None, _secrets_dir: Optional[Union[pathlib.Path, str]] = None, *, field1: int = 5, field2: str = 'FooBar') 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.
- conf.py
autodoc_pydantic_settings_member_order
- option
member-order
Available values with rendered examples:
-
class
target.configuration.
SettingsMemberOrder
(_env_file: Optional[Union[pathlib.Path, str]] = '<object object>', _env_file_encoding: Optional[str] = None, _secrets_dir: Optional[Union[pathlib.Path, str]] = None, *, field: int = 1) SettingsMemberOrder.
-
attribute
field
: int Field.
-
classmethod
dummy
(v) → str Check.
-
class
Config
Config.
-
allow_mutation
= True
-
-
attribute
-
class
target.configuration.
SettingsMemberOrder
(_env_file: Optional[Union[pathlib.Path, str]] = '<object object>', _env_file_encoding: Optional[str] = None, _secrets_dir: Optional[Union[pathlib.Path, str]] = None, *, field: int = 1) SettingsMemberOrder.
-
classmethod
dummy
(v) → str Check.
-
class
Config
Config.
-
allow_mutation
= True
-
-
attribute
field
: int Field.
-
classmethod
-
class
target.configuration.
SettingsMemberOrder
(_env_file: Optional[Union[pathlib.Path, str]] = '<object object>', _env_file_encoding: Optional[str] = None, _secrets_dir: Optional[Union[pathlib.Path, str]] = None, *, field: int = 1) SettingsMemberOrder.
-
class
Config
Config.
-
allow_mutation
= True
-
-
classmethod
dummy
(v) → str Check.
-
attribute
field
: int Field.
-
class
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.
- conf.py
autodoc_pydantic_settings_hide_paramlist
- option
settings-hide-paramlist
Available values with rendered examples:
-
class
target.configuration.
SettingsHideParamList
SettingsHideParamList.
-
class
target.configuration.
SettingsHideParamList
(_env_file: Optional[Union[pathlib.Path, str]] = '<object object>', _env_file_encoding: Optional[str] = None, _secrets_dir: Optional[Union[pathlib.Path, str]] = None, *, field1: int = 5, field2: str = 'FooBar') SettingsHideParamList.
class SettingsHideParamList(BaseSettings):
"""SettingsHideParamList."""
field1: int = 5
field2: str = "FooBar"
Signature Prefix¶
Define the signature prefix for pydantic settings.
- conf.py
autodoc_pydantic_settings_signature_prefix
- option
settings-signature-prefix
Available values with rendered examples:
-
pydantic settings
target.configuration.
SettingsSignaturePrefix
(_env_file: Optional[Union[pathlib.Path, str]] = '<object object>', _env_file_encoding: Optional[str] = None, _secrets_dir: Optional[Union[pathlib.Path, str]] = None) SettingsSignaturePrefix.
-
class
target.configuration.
SettingsSignaturePrefix
(_env_file: Optional[Union[pathlib.Path, str]] = '<object object>', _env_file_encoding: Optional[str] = None, _secrets_dir: Optional[Union[pathlib.Path, str]] = None) SettingsSignaturePrefix.
-
foobar
target.configuration.
SettingsSignaturePrefix
(_env_file: Optional[Union[pathlib.Path, str]] = '<object object>', _env_file_encoding: Optional[str] = None, _secrets_dir: Optional[Union[pathlib.Path, str]] = None) 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.
- conf.py
autodoc_pydantic_settings_show_json
- option
settings-show-json
Available values with rendered examples:
-
class
target.configuration.
SettingsShowJson
(_env_file: Optional[Union[pathlib.Path, str]] = '<object object>', _env_file_encoding: Optional[str] = None, _secrets_dir: Optional[Union[pathlib.Path, str]] = None) SettingsShowJson.
Show JSON schema
{ "title": "SettingsShowJson", "description": "SettingsShowJson.", "type": "object", "properties": {}, "additionalProperties": false }
-
class
target.configuration.
SettingsShowJson
(_env_file: Optional[Union[pathlib.Path, str]] = '<object object>', _env_file_encoding: Optional[str] = None, _secrets_dir: Optional[Union[pathlib.Path, str]] = None) 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.
- conf.py
autodoc_pydantic_settings_show_json_error_strategy
- 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.
- conf.py
autodoc_pydantic_field_list_validators
- option
field-list-validators
Available values with rendered examples:
-
class
target.configuration.
FieldListValidators
(*, field: int = 1) FieldListValidators.
-
classmethod
check
(v) → str Check.
-
attribute
field
: int Field.
- Validated by
check
-
classmethod
-
class
target.configuration.
FieldListValidators
(*, field: int = 1) FieldListValidators.
-
classmethod
check
(v) → str Check.
-
attribute
field
: int Field.
-
classmethod
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.
- conf.py
autodoc_pydantic_field_doc_policy
- option
field-doc-policy
Available values with rendered examples:
-
class
target.configuration.
FieldDocPolicy
(*, field: int = 1) FieldDocPolicy.
-
attribute
field
: int Field.
-
attribute
-
class
target.configuration.
FieldDocPolicy
(*, field: int = 1) FieldDocPolicy.
-
attribute
field
: int Custom Desc.
-
attribute
-
class
target.configuration.
FieldDocPolicy
(*, field: int = 1) FieldDocPolicy.
-
attribute
field
: int Field.
Custom Desc.
-
attribute
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.
- conf.py
autodoc_pydantic_field_show_constraints
- option
field-show-constraints
Available values with rendered examples:
-
class
target.configuration.
FieldShowConstraints
(*, field: target.configuration.ConstrainedIntValue = 1) FieldShowConstraints.
-
attribute
field
: int Field.
- Constraints
minimum = 0
maximum = 100
-
attribute
-
class
target.configuration.
FieldShowConstraints
(*, field: target.configuration.ConstrainedIntValue = 1) FieldShowConstraints.
-
attribute
field
: int Field.
-
attribute
class FieldShowConstraints(BaseModel):
"""FieldShowConstraints."""
field: int = Field(1, ge=0, le=100)
"""Field."""
Show Alias¶
Provides the pydantic field’s alias in the signature.
- conf.py
autodoc_pydantic_field_show_alias
- option
field-show-alias
Available values with rendered examples:
-
class
target.configuration.
FieldShowAlias
(*, field2: int = 1) FieldShowConstraints.
-
attribute
field
: int (alias 'field2') Field.
-
attribute
-
class
target.configuration.
FieldShowAlias
(*, field2: int = 1) FieldShowConstraints.
-
attribute
field
: int Field.
-
attribute
class FieldShowAlias(BaseModel):
"""FieldShowConstraints."""
field: int = Field(1, alias="field2", env="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.1.2).
- conf.py
autodoc_pydantic_field_show_default
- option
field-show-default
Available values with rendered examples:
-
class
target.configuration.
FieldShowDefault
(*, field: int = 1) FieldShowDefault.
-
attribute
field
: int = 1 Field.
-
attribute
-
class
target.configuration.
FieldShowDefault
(*, field: int = 1) FieldShowDefault.
-
attribute
field
: int Field.
-
attribute
class FieldShowDefault(BaseModel):
"""FieldShowDefault."""
field: int = 1
"""Field."""
Show Required¶
Add [Required] marker for all pydantic fields that do not have a default
value. Otherwise, misleading default values like PydanticUndefined
or
Ellipsis
are displayed when field-show-default
is enabled.
- conf.py
autodoc_pydantic_field_show_required
- option
field-show-required
Available values with rendered examples:
-
class
target.configuration.
FieldShowRequired
(*, field1: int, field2: int, field3: int) FieldShowRequired.
-
attribute
field1
: int [Required] field1
-
attribute
field2
: int [Required] field2
-
attribute
field3
: int [Required] field3
-
attribute
-
class
target.configuration.
FieldShowRequired
(*, field1: int, field2: int, field3: int) FieldShowRequired.
-
attribute
field1
: int = PydanticUndefined field1
-
attribute
field2
: int = Ellipsis field2
-
attribute
field3
: int = Ellipsis field3
-
attribute
class FieldShowRequired(BaseModel):
"""FieldShowRequired."""
field1: int
"""field1"""
field2: int = ...
"""field2"""
field3: int = Field(default=...)
"""field3"""
Signature Prefix¶
Define the signature prefix for pydantic field.
- conf.py
autodoc_pydantic_field_signature_prefix
- option
field-signature-prefix
Available values with rendered examples:
-
class
target.configuration.
FieldSignaturePrefix
(*, field: int = 1) FieldSignaturePrefix.
-
field
field
: int Field.
-
field
-
class
target.configuration.
FieldSignaturePrefix
(*, field: int = 1) FieldSignaturePrefix.
-
attribute
field
: int Field.
-
attribute
-
class
target.configuration.
FieldSignaturePrefix
(*, field: int = 1) FieldSignaturePrefix.
-
foobar
field
: int Field.
-
foobar
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.
- conf.py
autodoc_pydantic_validator_replace_signature
- option
validator-replace-signature
Available values with rendered examples:
-
class
target.configuration.
ValidatorReplaceSignature
(*, field: int = 1) ValidatorReplaceSignature.
-
classmethod
check
» field Check.
-
attribute
field
: int
-
classmethod
-
class
target.configuration.
ValidatorReplaceSignature
(*, field: int = 1) ValidatorReplaceSignature.
-
classmethod
check
(v) → str Check.
-
attribute
field
: int
-
classmethod
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.
- conf.py
autodoc_pydantic_validator_list_fields
- option
validator-list-fields
Available values with rendered examples:
-
class
target.configuration.
ValidatorListFields
(*, field: int = 1) ValidatorListFields.
-
classmethod
check
(v) → str Check.
- Validates
field
-
attribute
field
: int
-
classmethod
-
class
target.configuration.
ValidatorListFields
(*, field: int = 1) ValidatorListFields.
-
classmethod
check
(v) → str Check.
-
attribute
field
: int
-
classmethod
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.
- conf.py
autodoc_pydantic_validator_signature_prefix
- option
validator-signature-prefix
Available values with rendered examples:
-
class
target.configuration.
ValidatorSignaturePrefix
(*, field: int = 1) ValidatorSignaturePrefix.
-
validator
check
(v) → str Check.
-
attribute
field
: int
-
validator
-
class
target.configuration.
ValidatorSignaturePrefix
(*, field: int = 1) ValidatorSignaturePrefix.
-
classmethod
check
(v) → str Check.
-
attribute
field
: int
-
classmethod
-
class
target.configuration.
ValidatorSignaturePrefix
(*, field: int = 1) ValidatorSignaturePrefix.
-
foobar
check
(v) → str Check.
-
attribute
field
: int
-
foobar
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.
- conf.py
autodoc_pydantic_config_members
- option
members
Available values with rendered examples:
-
class
target.configuration.
ConfigMembers
ConfigUndocMembers.
-
class
Config
-
allow_mutation
= True Allow Mutation.
-
title
= 'foobar'
-
-
class
-
class
target.configuration.
ConfigMembers
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.
- conf.py
autodoc_pydantic_config_signature_prefix
- option
config-signature-prefix
Available values with rendered examples:
-
model
target.configuration.ConfigSignaturePrefix.
Config
Config.
-
class
target.configuration.ConfigSignaturePrefix.
Config
Config.
-
foobar
target.configuration.ConfigSignaturePrefix.
Config
Config.
class Config:
title: str = "FooBar"
allow_mutation: bool = True