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

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.

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

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.

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)

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

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

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

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.

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.

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": {}
}

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 an sphinx.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

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.

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

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.

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.

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

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

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

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.

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.

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
}

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 an sphinx.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

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.

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

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.

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.

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

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.

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

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

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

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'

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.