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

<sphinxcontrib.autodoc_pydantic.directives.utility.NullType object at 0x7ffa51fb3f70> ModelShowConfigSummary[source]

ModelShowConfigSummary.

Config:

frozen: bool = True
title: str = FooBar

class ModelShowConfigSummary(BaseModel):
    """ModelShowConfigSummary."""

    model_config = ConfigDict(frozen=True, title='FooBar')

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

<sphinxcontrib.autodoc_pydantic.directives.utility.NullType object at 0x7ffa51fb3f70> ModelShowValidatorsSummary(*, field: int = 1)[source]

ModelShowValidatorsSummary.

Validators:

check » field

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

<sphinxcontrib.autodoc_pydantic.directives.utility.NullType object at 0x7ffa51fb3f70> ModelShowValidatorMembers(*, field: int = 1)[source]

ModelShowValidatorMembers.

<sphinxcontrib.autodoc_pydantic.directives.utility.NullType object at 0x7ffa51fb3f70> dummy(v) → str[source]: Check.

<sphinxcontrib.autodoc_pydantic.directives.utility.NullType object at 0x7ffa51fb3f70> 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

<sphinxcontrib.autodoc_pydantic.directives.utility.NullType object at 0x7ffa51fb3f70> ModelShowFieldSummary(*, field1: int = 5, field2: str = 'FooBar')[source]

ModelShowFieldSummary.

Fields:

field1 (int)
field2 (str)

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

<sphinxcontrib.autodoc_pydantic.directives.utility.NullType object at 0x7ffa51fb3f70> 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

<sphinxcontrib.autodoc_pydantic.directives.utility.NullType object at 0x7ffa51fb3f70> 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

<sphinxcontrib.autodoc_pydantic.directives.utility.NullType object at 0x7ffa51fb3f70> ModelUndocMembers(*, field1: int = 5, field2: str = 'FooBar')[source]

ModelUndocMembers.

<sphinxcontrib.autodoc_pydantic.directives.utility.NullType object at 0x7ffa51fb3f70> field1: int

<sphinxcontrib.autodoc_pydantic.directives.utility.NullType object at 0x7ffa51fb3f70> field2: str

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

<sphinxcontrib.autodoc_pydantic.directives.utility.NullType object at 0x7ffa51fb3f70> ModelMembers(*, field1: int = 5, field2: str = 'FooBar')[source]

ModelMembers.

<sphinxcontrib.autodoc_pydantic.directives.utility.NullType object at 0x7ffa51fb3f70> field1: int: Doc field 1

<sphinxcontrib.autodoc_pydantic.directives.utility.NullType object at 0x7ffa51fb3f70> field2: str: Doc field 2

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

<sphinxcontrib.autodoc_pydantic.directives.utility.NullType object at 0x7ffa51fb3f70> ModelMemberOrder(*, field: int = 1)[source]

ModelMemberOrder.

<sphinxcontrib.autodoc_pydantic.directives.utility.NullType object at 0x7ffa51fb3f70> field: int: Field.

<sphinxcontrib.autodoc_pydantic.directives.utility.NullType object at 0x7ffa51fb3f70> dummy(v) → str[source]: Check.

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

<sphinxcontrib.autodoc_pydantic.directives.utility.NullType object at 0x7ffa51fb3f70> ModelHideParamList[source]: ModelHideParamList.

class ModelHideParamList(BaseModel):
    """ModelHideParamList."""

    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_model_hide_reused_validator
directive:: model-hide-reused-validator

Available values with rendered examples

<sphinxcontrib.autodoc_pydantic.directives.utility.NullType object at 0x7ffa51fb3f70> ModelOne(*, name: str)[source]

<sphinxcontrib.autodoc_pydantic.directives.utility.NullType object at 0x7ffa51fb3f70> name: str: Name

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 model. This is especially useful when you want to distinguish pydantic models from other classes.

Hint

An empty string is also a valid value. This will remove the prefix completely.

Configuration (added in version 0.1.0)

conf.py:: autodoc_pydantic_model_signature_prefix
directive:: model-signature-prefix

Available values with rendered examples

pydantic model ModelSignaturePrefix[source]: ModelSignaturePrefix.

class ModelSignaturePrefix(BaseModel):
    """ModelSignaturePrefix."""

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

<sphinxcontrib.autodoc_pydantic.directives.utility.NullType object at 0x7ffa51fb3f70> 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

<sphinxcontrib.autodoc_pydantic.directives.utility.NullType object at 0x7ffa51fb3f70> ModelErdanticFigure(*, field1: int = 5, field2: str = 'FooBar', related: ModelErdanticFigureRelated)[source]

ModelErdanticFigure.

Show Entity Relationship Diagram

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

<sphinxcontrib.autodoc_pydantic.directives.utility.NullType object at 0x7ffa51fb3f70> ModelShowJson[source]

ModelShowJson.

Show JSON schema

{
   "title": "ModelShowJson",
   "description": "ModelShowJson.",
   "type": "object",
   "properties": {}
}

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.

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

<sphinxcontrib.autodoc_pydantic.directives.utility.NullType object at 0x7ffa51fb3f70> 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(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

<sphinxcontrib.autodoc_pydantic.directives.utility.NullType object at 0x7ffa51fb3f70> 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(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

<sphinxcontrib.autodoc_pydantic.directives.utility.NullType object at 0x7ffa51fb3f70> 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.

<sphinxcontrib.autodoc_pydantic.directives.utility.NullType object at 0x7ffa51fb3f70> dummy(v) → str[source]: Check.

<sphinxcontrib.autodoc_pydantic.directives.utility.NullType object at 0x7ffa51fb3f70> 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

<sphinxcontrib.autodoc_pydantic.directives.utility.NullType object at 0x7ffa51fb3f70> 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)

<sphinxcontrib.autodoc_pydantic.directives.utility.NullType object at 0x7ffa51fb3f70> field1: int: Field1.

<sphinxcontrib.autodoc_pydantic.directives.utility.NullType object at 0x7ffa51fb3f70> 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

<sphinxcontrib.autodoc_pydantic.directives.utility.NullType object at 0x7ffa51fb3f70> 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

<sphinxcontrib.autodoc_pydantic.directives.utility.NullType object at 0x7ffa51fb3f70> 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

<sphinxcontrib.autodoc_pydantic.directives.utility.NullType object at 0x7ffa51fb3f70> 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.

<sphinxcontrib.autodoc_pydantic.directives.utility.NullType object at 0x7ffa51fb3f70> field1: int

<sphinxcontrib.autodoc_pydantic.directives.utility.NullType object at 0x7ffa51fb3f70> field2: str

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

<sphinxcontrib.autodoc_pydantic.directives.utility.NullType object at 0x7ffa51fb3f70> 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.

<sphinxcontrib.autodoc_pydantic.directives.utility.NullType object at 0x7ffa51fb3f70> field1: int: Doc field 1

<sphinxcontrib.autodoc_pydantic.directives.utility.NullType object at 0x7ffa51fb3f70> field2: str: Doc field 2

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

<sphinxcontrib.autodoc_pydantic.directives.utility.NullType object at 0x7ffa51fb3f70> 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.

<sphinxcontrib.autodoc_pydantic.directives.utility.NullType object at 0x7ffa51fb3f70> field: int: Field.

<sphinxcontrib.autodoc_pydantic.directives.utility.NullType object at 0x7ffa51fb3f70> dummy(v) → str[source]: Check.

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

<sphinxcontrib.autodoc_pydantic.directives.utility.NullType object at 0x7ffa51fb3f70> SettingsHideParamList[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

<sphinxcontrib.autodoc_pydantic.directives.utility.NullType object at 0x7ffa51fb3f70> SettingOne(*, name: str)[source]

<sphinxcontrib.autodoc_pydantic.directives.utility.NullType object at 0x7ffa51fb3f70> name: str: Name

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. This is especially useful when you want to distinguish pydantic settings from other classes.

Hint

An empty string is also a valid value. This will remove the prefix completely.

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(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

<sphinxcontrib.autodoc_pydantic.directives.utility.NullType object at 0x7ffa51fb3f70> 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(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 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.

Configuration (added in version 0.1.0)

conf.py:: autodoc_pydantic_field_list_validators
directive:: field-list-validators

Available values with rendered examples

<sphinxcontrib.autodoc_pydantic.directives.utility.NullType object at 0x7ffa51fb3f70> FieldListValidators(*, field: int = 1)[source]

FieldListValidators.

<sphinxcontrib.autodoc_pydantic.directives.utility.NullType object at 0x7ffa51fb3f70> check(v) → str[source]: Check.

<sphinxcontrib.autodoc_pydantic.directives.utility.NullType object at 0x7ffa51fb3f70> field: int

Field.

Validated by:

check

class FieldListValidators(BaseModel):
    """FieldListValidators."""

    field: int = 1
    """Field."""

    @field_validator('field')
    def check(cls, v) -> str:
        """Check."""
        return v

Docstring Policy

This configuration determines what information appears in the documentation for each field in a model. You can select from the following options:

Available values:

docstring: Displays the original docstring from the Python attribute.
description: Shows the description provided in the Pydantic model field.
both: Includes both the attribute’s docstring and the Pydantic field’s description in the documentation.

Hint

As of Pydantic version 2.7, you can enable the model configuration setting use_attribute_docstrings. When enabled, Pydantic will use the attribute’s docstring as the field’s description by default, unless a specific description is provided. To avoid redundancy in documentation, especially when using the both option, autodoc_pydantic automatically checks for and removes any duplicate docstrings, ensuring your documentation remains clear and concise.

Configuration (added in version 0.1.0)

conf.py:: autodoc_pydantic_field_doc_policy
directive:: field-doc-policy

Available values with rendered examples

<sphinxcontrib.autodoc_pydantic.directives.utility.NullType object at 0x7ffa51fb3f70> FieldDocPolicy(*, field: int = 1)[source]

FieldDocPolicy.

<sphinxcontrib.autodoc_pydantic.directives.utility.NullType object at 0x7ffa51fb3f70> field: int: Field.

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

<sphinxcontrib.autodoc_pydantic.directives.utility.NullType object at 0x7ffa51fb3f70> FieldShowConstraints(*, field: int = 1)[source]

FieldShowConstraints.

<sphinxcontrib.autodoc_pydantic.directives.utility.NullType object at 0x7ffa51fb3f70> field: int

Field.

Constraints:

ge = 0
le = 100

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

<sphinxcontrib.autodoc_pydantic.directives.utility.NullType object at 0x7ffa51fb3f70> FieldShowAlias(*, field2: int = 1)[source]

FieldShowAlias.

<sphinxcontrib.autodoc_pydantic.directives.utility.NullType object at 0x7ffa51fb3f70> field: int (alias 'field2'): 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

<sphinxcontrib.autodoc_pydantic.directives.utility.NullType object at 0x7ffa51fb3f70> FieldShowDefault(*, field: int = 1)[source]

FieldShowDefault.

<sphinxcontrib.autodoc_pydantic.directives.utility.NullType object at 0x7ffa51fb3f70> field: int = 1: Field.

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 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

<sphinxcontrib.autodoc_pydantic.directives.utility.NullType object at 0x7ffa51fb3f70> FieldShowRequired(*, field1: int, field2: int, field3: int, field4: int | None)[source]

FieldShowRequired.

<sphinxcontrib.autodoc_pydantic.directives.utility.NullType object at 0x7ffa51fb3f70> field1: int [Required]: field1

<sphinxcontrib.autodoc_pydantic.directives.utility.NullType object at 0x7ffa51fb3f70> field2: int [Required]: field2

<sphinxcontrib.autodoc_pydantic.directives.utility.NullType object at 0x7ffa51fb3f70> field3: int [Required]: field3

<sphinxcontrib.autodoc_pydantic.directives.utility.NullType object at 0x7ffa51fb3f70> field4: int | None [Required]: 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

<sphinxcontrib.autodoc_pydantic.directives.utility.NullType object at 0x7ffa51fb3f70> FieldShowOptional(*, field1: int = None, field2: int | None = None)[source]

<sphinxcontrib.autodoc_pydantic.directives.utility.NullType object at 0x7ffa51fb3f70> field1: int [Optional]: field1

<sphinxcontrib.autodoc_pydantic.directives.utility.NullType object at 0x7ffa51fb3f70> field2: int | None [Optional]: 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:

model-show-field-summary
model-show-validator-summary
validator-replace-signature
validator-list-fields

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

<sphinxcontrib.autodoc_pydantic.directives.utility.NullType object at 0x7ffa51fb3f70> FieldSwapNameAndAlias(*, field1: int = 1)[source]

<sphinxcontrib.autodoc_pydantic.directives.utility.NullType object at 0x7ffa51fb3f70> field1: int (alias 'field 1 alias'): Field1

class FieldSwapNameAndAlias(BaseModel):
    """FieldSwapNameAndAlias"""

    field1: int = Field(default=1, alias='field 1 alias')
    """Field1"""

Signature Prefix

Define the signature prefix for pydantic fields. This is especially useful when you want to distinguish pydantic fields from other attributes.

Hint

An empty string is also a valid value. This will remove the prefix completely.

Configuration (added in version 0.1.0)

conf.py:: autodoc_pydantic_field_signature_prefix
directive:: field-signature-prefix

Available values with rendered examples

<sphinxcontrib.autodoc_pydantic.directives.utility.NullType object at 0x7ffa51fb3f70> FieldSignaturePrefix(*, field: int = 1)[source]

FieldSignaturePrefix.

field 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

<sphinxcontrib.autodoc_pydantic.directives.utility.NullType object at 0x7ffa51fb3f70> ValidatorReplaceSignature(*, field: int = 1)[source]

ValidatorReplaceSignature.

<sphinxcontrib.autodoc_pydantic.directives.utility.NullType object at 0x7ffa51fb3f70> check » field[source]: Check.

<sphinxcontrib.autodoc_pydantic.directives.utility.NullType object at 0x7ffa51fb3f70> field: int

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

<sphinxcontrib.autodoc_pydantic.directives.utility.NullType object at 0x7ffa51fb3f70> ValidatorListFields(*, field: int = 1)[source]

ValidatorListFields.

<sphinxcontrib.autodoc_pydantic.directives.utility.NullType object at 0x7ffa51fb3f70> check(v) → str[source]

Check.

Validates:

field

<sphinxcontrib.autodoc_pydantic.directives.utility.NullType object at 0x7ffa51fb3f70> field: int

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 validators. This is especially useful when you want to distinguish pydantic validators from other attributes.

Hint

An empty string is also a valid value. This will remove the prefix completely.

Configuration (added in version 0.1.0)

conf.py:: autodoc_pydantic_validator_signature_prefix
directive:: validator-signature-prefix

Available values with rendered examples

<sphinxcontrib.autodoc_pydantic.directives.utility.NullType object at 0x7ffa51fb3f70> ValidatorSignaturePrefix(*, field: int = 1)[source]

ValidatorSignaturePrefix.

validator check(v) → str[source]: Check.

<sphinxcontrib.autodoc_pydantic.directives.utility.NullType object at 0x7ffa51fb3f70> field: int

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.