API

Structure

The following API documentation does not include all modules of autodoc_pydantic. Instead, it focuses only on modules that are relevant for documentation purposes:

autodoc_pydantic
|
|- __init__.py
|- inspection.py
|- utility.py
|
+--directives
   |- __init__.py
   |- autodocumenters.py
   |- directives.py
   |- templates.py
   |- utility.py
   |
   \--options
      |- __init__.py
      |- composites.py
      |- definition.py
      |- enums.py
      \- validators.py

For everything else, please refer to the source code directly.

Modules

inspection.py

This module is located at sphinxcontrib/autodoc_pydantic/inspection.py.

This module contains the inspection functionality for pydantic models. It is used to retrieve relevant information about fields, validators, config and schema of pydantical models.

class ValidatorAdapter(func: Callable)[source]

Bases: NamedTuple

Provide standardized interface to pydantic’s validator objects with additional metadata (e.g. root validator) for internal usage in autodoc_pydantic.

func: Callable

Alias for field number 0

property name: str

Return the validators function name.

property class_name: str | None

Return the validators class name. It might be None if validator is not bound to a class.

property module: str

Return the validators module name.

property object_path: str

Return the fully qualified object path of the validators function.

class ValidatorFieldMap(field_name: str, validator_name: str, field_ref: str, validator_ref: str)[source]

Bases: NamedTuple

Contains single mapping of a pydantic validator and field.

field_name: str

Name of the field.

validator_name: str

Name of the validator.

field_ref: str

Reference to field.

validator_ref: str

Reference to validataor.

class BaseInspectionComposite(parent: ModelInspector)[source]

Bases: object

Serves as base class for inspector composites which are coupled to ModelInspector instances. Each composite provides a separate namespace to handle different areas of pydantic models (e.g. fields and validators).

class FieldInspector(parent: ModelInspector)[source]

Bases: BaseInspectionComposite

Provide namespace for inspection methods for fields of pydantic models.

property names: List[str]

Return field names while keeping ordering.

get(name: str) FieldInfo[source]

Get the instance of FieldInfo for given field name.

get_alias_or_name(field_name: str) str[source]

Get the alias of a pydantic field if given. Otherwise, return the field name.

get_property_from_field_info(field_name: str, property_name: str) Any[source]

Get specific property value from pydantic’s field info.

get_constraints(field_name: str) Dict[str, Any][source]

Get constraints for given field_name.

is_required(field_name: str) bool[source]

Check if a given pydantic field is required/mandatory. Returns True, if a value for this field needs to provided upon model creation.

has_default_factory(field_name: str) bool[source]

Check if field has a default_factory being set. This information is used to determine if a pydantic field is optional or not.

is_json_serializable(field_name: str) bool[source]

Check if given pydantic field is JSON serializable by calling pydantic’s model.schema() method. Custom objects might not be serializable and hence would break JSON schema generation.

property non_json_serializable: List[str]

Get all fields that can’t be safely JSON serialized.

class ValidatorInspector(parent: ModelInspector)[source]

Bases: BaseInspectionComposite

Provide namespace for inspection methods for validators of pydantic models.

property values: Set[ValidatorAdapter]

Returns set of all available validators.

get_reused_validators_names() List[str][source]

Identify all reused validators. This is done implicitly by relying on the fact the reused validators are registered as unbound functions instead of bound methods.

property names: Set[str]

Return names of all validators of pydantic model.

class ConfigInspector(parent: ModelInspector)[source]

Bases: BaseInspectionComposite

Provide namespace for inspection methods for config class of pydantic models.

property is_configured: bool

Check if pydantic model config was explicitly configured.

class ReferenceInspector(*args, **kwargs)[source]

Bases: BaseInspectionComposite

Provide namespace for inspection methods for creating references mainly between pydantic fields and validators.

Importantly, mappings provides the set of all ValidatorFieldMap instances which contain all references between fields and validators.

property model_path: str

Retrieve the full path of the model.

create_model_reference(name: str) str[source]

Create reference for given attribute name returning full path including the model path.

filter_by_validator_name(name: str) List[ValidatorFieldMap][source]

Return mappings for given validator name.

filter_by_field_name(name: str) List[ValidatorFieldMap][source]

Return mappings for given field name.

class SchemaInspector(parent: ModelInspector)[source]

Bases: BaseInspectionComposite

Provide namespace for inspection methods for general properties of pydantic models.

property sanitized: Dict

Get model’s schema while handling non serializable fields. Such fields will be replaced by TypeVars.

create_sanitized_model() BaseModel[source]

Generates a new pydantic model from the original one while substituting invalid fields with typevars.

class StaticInspector[source]

Bases: object

Namespace under ModelInspector for static methods.

static is_pydantic_model(obj: Any) bool[source]

Determine if object is a valid pydantic model.

classmethod is_pydantic_field(parent: Any, field_name: str) bool[source]

Determine if given field is a pydantic field.

classmethod is_validator_by_name(name: str, obj: Any) bool[source]

Determine if a validator is present under provided name for given model.

class ModelInspector(model: Type[BaseModel])[source]

Bases: object

Provides inspection functionality for pydantic models.

static

alias of StaticInspector

get_field_validator_mapping() Dict[str, List[ValidatorAdapter]][source]

Collect all available validators keyed by their corresponding fields including post/pre root validators.

Validators are wrapped into ValidatorAdapters to provide uniform interface within autodoc_pydantic.

classmethod from_child_signode(signode: desc_signature) ModelInspector[source]

Create instance from a child signode as used within sphinx directives.

autodocumenters.py

This module is located at sphinxcontrib/autodoc_pydantic/directives/autodocumenters.py.

This module contains autodoc_pydantic’s autodocumenters.

class PydanticAutoDoc(documenter: Documenter, is_child: bool)[source]

Bases: object

Composite to provide single namespace to access all autodoc_pydantic relevant documenter directive functionalities.

property model: BaseModel

Lazily load pydantic model after initialization. For more, please read inspect doc string.

property options: AutoDocOptions

Provides access to PydanticDocumenterOptions to handle global and local configuration settings.

property inspect: ModelInspector

Provides ModelInspector to access all inspection methods. You may wonder why this inspect is a property instead of a simple attribute being defined in the __init__ method of this class. The reason is the following: auto-documenters do not have their object attribute being correctly set after instantiation which typically holds a reference to the corresponding pydantic model and objects to be documented. Instead, object is None after plain instantiation (executing __init__). However, this composite class is added during instantiation of the autodocumenter for consistency reasons. Therefore, ModelInspector can’t be created at instantiation time of this class because the object is still None. Hence, it is lazily created once the inspection methods are first required. At this point in time, it is guaranteed by the auto-documenter base class that object is then already correctly provided and the ModelInspector works as expected.

get_field_name_or_alias(field_name: str)[source]

If field-swap-name-and-alias is enabled, provide alias (if present) for given field.

get_non_inherited_members() Set[str][source]

Return all member names of autodocumented object which are prefiltered to exclude inherited members.

resolve_inherited_validator_reference(ref: str) str[source]

Provide correct validator reference in case validator is inherited and explicitly shown in docs via directive option inherited-members.

More concretely, inherited validators are not shown from parent class unless directive option inherited-members is used. The validator references may either point to the parent class or the child class. This logic is implemented here.

class PydanticModelDocumenter(*args: Any)[source]

Bases: ClassDocumenter

Represents specialized Documenter subclass for pydantic models.

objtype = 'pydantic_model'

name by which the directive is called (auto…) and the default generated directive name

priority = 25

priority if multiple documenters return True from can_document_member

classmethod can_document_member(member: Any, membername: str, isattr: bool, parent: Any) bool[source]

Filter only pydantic models.

document_members(*args, **kwargs)[source]

Modify member options before starting to document members.

hide_inherited_members()[source]

If inherited-members is set, make sure that these are excluded from the class documenter, too

hide_validator_members()[source]

Add validator names to exclude_members.

hide_reused_validators()[source]

Add reused validators to exclude_members option.

format_signature(**kwargs) str[source]

If parameter list is to be hidden, return only empty signature.

add_content(more_content: StringList | None, **kwargs) None[source]

Delegate additional content creation.

add_collapsable_schema()[source]

Adds collapse code block containing JSON schema.

add_erdantic_figure()[source]

Adds an erdantic entity relation diagram to the doc of an pydantic model.

add_config_summary()[source]

Adds summary section describing the model configuration.

add_validators_summary()[source]

Adds summary section describing all validators with corresponding fields.

add_field_summary()[source]

Adds summary section describing all fields.

class PydanticSettingsDocumenter(*args: Any)[source]

Bases: PydanticModelDocumenter

Represents specialized Documenter subclass for pydantic settings.

objtype = 'pydantic_settings'

name by which the directive is called (auto…) and the default generated directive name

priority = 25

priority if multiple documenters return True from can_document_member

classmethod can_document_member(member: Any, membername: str, isattr: bool, parent: Any) bool[source]

Filter only pydantic models.

class PydanticFieldDocumenter(*args)[source]

Bases: AttributeDocumenter

Represents specialized Documenter subclass for pydantic fields.

objtype = 'pydantic_field'

name by which the directive is called (auto…) and the default generated directive name

priority = 20

priority if multiple documenters return True from can_document_member

member_order = 0

order if autodoc_member_order is set to ‘groupwise’

classmethod can_document_member(member: Any, membername: str, isattr: bool, parent: Any) bool[source]

Filter only pydantic fields.

property pydantic_field_name: str

Provide the pydantic field name which refers to the member name of the parent pydantic model.

add_directive_header(sig: str) None[source]

Delegate header options.

property needs_required_marker: bool

Indicate if field should be marked as required.

property needs_optional_marker: bool

Indicate if field should be marked as optional.

get_default_value() str[source]

Gets the default value of pydantic field as reST.

add_default_value_or_marker()[source]

Adds default value or a marker for field being required or optional.

add_alias()[source]

Adds alias directive option.

add_content(more_content: StringList | None, **kwargs) None[source]

Delegate additional content creation.

add_constraints()[source]

Adds section showing all defined constraints.

add_description()[source]

Adds description from schema if present.

add_validators()[source]

Add section with all validators that process this field.

add_line(line: str, source: str, *lineno: int) None[source]

Intercept added rst lines to handle edge cases such as correct string representation for annotated types in python < 3.9.

class PydanticValidatorDocumenter(*args: Any)[source]

Bases: MethodDocumenter

Represents specialized Documenter subclass for pydantic validators.

objtype = 'pydantic_validator'

name by which the directive is called (auto…) and the default generated directive name

member_order = 50

order if autodoc_member_order is set to ‘groupwise’

priority = 11

priority if multiple documenters return True from can_document_member

classmethod can_document_member(member: Any, membername: str, isattr: bool, parent: Any) bool[source]

Filter only pydantic validators.

format_args(**kwargs: Any) str[source]

Return empty arguments if validator should be replaced.

add_content(more_content: StringList | None, **kwargs) None[source]

Optionally show validator content.

add_field_list()[source]

Adds a field list with all fields that are validated by this validator.

definition.py

This module is located at sphinxcontrib/autodoc_pydantic/directives/options/definition.py.

This module contains the autodocumenter’s option definitions.

OPTIONS_FIELD = {'__doc_disable_except__': <function option_list_like>, 'field-doc-policy': <function option_one_of_factory.<locals>.option_func>, 'field-list-validators': <function option_default_true>, 'field-show-alias': <function option_default_true>, 'field-show-constraints': <function option_default_true>, 'field-show-default': <function option_default_true>, 'field-show-optional': <function option_default_true>, 'field-show-required': <function option_default_true>, 'field-signature-prefix': <function unchanged>, 'field-swap-name-and-alias': <function option_default_true>}

Represents added directive options for PydanticFieldDocumenter.

OPTIONS_VALIDATOR = {'__doc_disable_except__': <function option_list_like>, 'field-swap-name-and-alias': <function option_default_true>, 'validator-list-fields': <function option_default_true>, 'validator-replace-signature': <function option_default_true>, 'validator-signature-prefix': <function unchanged>}

Represents added directive options for PydanticValidatorDocumenter.

OPTIONS_MODEL = {'__doc_disable_except__': <function option_list_like>, 'members': <function option_members>, 'model-erdantic-figure': <function option_default_true>, 'model-erdantic-figure-collapsed': <function option_default_true>, 'model-hide-paramlist': <function option_default_true>, 'model-hide-reused-validator': <function option_default_true>, 'model-show-config-member': <function option_default_true>, 'model-show-config-summary': <function option_default_true>, 'model-show-field-summary': <function option_default_true>, 'model-show-json': <function option_default_true>, 'model-show-json-error-strategy': <function option_one_of_factory.<locals>.option_func>, 'model-show-validator-members': <function option_default_true>, 'model-show-validator-summary': <function option_default_true>, 'model-signature-prefix': <function unchanged>, 'model-summary-list-order': <function option_one_of_factory.<locals>.option_func>, 'undoc-members': <function option_default_true>}

Represents added directive options for PydanticModelDocumenter.

OPTIONS_SETTINGS = {'__doc_disable_except__': <function option_list_like>, 'members': <function option_members>, 'settings-hide-paramlist': <function option_default_true>, 'settings-hide-reused-validator': <function option_default_true>, 'settings-show-config-member': <function option_default_true>, 'settings-show-config-summary': <function option_default_true>, 'settings-show-field-summary': <function option_default_true>, 'settings-show-json': <function option_default_true>, 'settings-show-json-error-strategy': <function option_one_of_factory.<locals>.option_func>, 'settings-show-validator-members': <function option_default_true>, 'settings-show-validator-summary': <function option_default_true>, 'settings-signature-prefix': <function unchanged>, 'settings-summary-list-order': <function option_one_of_factory.<locals>.option_func>, 'undoc-members': <function option_default_true>}

Represents added directive options for PydanticSettingsDocumenter.

composites.py

This module is located at sphinxcontrib/autodoc_pydantic/directives/options/composites.py.

This module contains composite helper classes for autodoc_pydantic autodocumenters and directives. They mainly intend to encapsulate the management of directive options.

class DirectiveOptions(parent: Documenter | Directive)[source]

Bases: object

Composite class providing methods to manage getting and setting configuration values from global app configuration and local directive options.

This class is tightly coupled with autodoc pydantic autodocumenters because it accesses class attributes of the parent class.

The documenter class’ option attribute is sometimes modified in order to apply autodoc pydantic’s rules (e.g. modifying :members:). Since the option attribute may be shared between documenter instances (may be a bug) in sphinx, an independent copy of the option attribute is created for every autodoc pydantic autodocumenter. This relates to #21.

add_default_options()[source]

Adds all default options.

static determine_app_cfg_name(name: str) str[source]

Provide full app environment configuration name for given option name while converting “-” to “_”.

Parameters:

name (str) – Name of the option.

Returns:

full_name – Full app environment configuration name.

Return type:

str

is_available(name: str) bool[source]

Configurations may be disabled for documentation purposes. If the directive option __doc_disable_except__ exists, it contains the only available configurations.

get_app_cfg_by_name(name: str) Any[source]

Get configuration value from app environment configuration. If name does not exist, return NONE.

get_value(name: str, prefix: bool = False, force_availability: bool = False) Any[source]

Get option value for given name. First, looks for explicit directive option values (e.g. :member-order:) which have highest priority. Second, if no directive option is given, get the default option value provided via the app environment configuration.

Parameters:
  • name (str) – Name of the option.

  • prefix (bool) – If True, add pyautodoc_prefix to name.

  • force_availability (bool) – It is disabled by default however some default configurations like model-summary-list-order need to be activated all the time.

is_false(name: str, prefix: bool = False) bool[source]

Check if option with name is False. First, looks for explicit directive option values (e.g. :member-order:) which have highest priority. Second, if no directive option is given, get the default option value provided via the app environment configuration.

Enforces result to be either True or False.

Parameters:
  • name (str) – Name of the option.

  • prefix (bool) – If True, add pyautodoc_prefix to name.

is_true(name: str, prefix: bool = False) bool[source]

Check if option with name is True. First, looks for explicit directive option values (e.g. :member-order:) which have highest priority. Second, if no directive option is given, get the default option value provided via the app environment configuration.

Enforces result to be either True or False.

Parameters:
  • name (str) – Name of the option.

  • prefix (bool) – If True, add pyautodoc_prefix to name.

exists(name: str, prefix: bool = False) bool[source]

Check if option with name is set. First, looks for explicit directive option values (e.g. :member-order:) which have highest priority. Second, if no directive option is given, get the default option value provided via the app environment configuration.

Enforces result to be either True or False.

Parameters:
  • name (str) – Name of the option.

  • prefix (bool) – If True, add pyautodoc_prefix to name.

set_default_option(name: str)[source]

Set default option value for given name from app environment configuration if an explicit directive option was not provided.

Parameters:

name (str) – Name of the option.

set_members_all()[source]

Specifically sets the :members: option to ALL if activated via app environment settings and not deactivated locally by directive option.

class AutoDocOptions(*args)[source]

Bases: DirectiveOptions

Composite class providing methods to handle getting and setting autodocumenter directive option values.

property configuration_names: Set[str]

Returns all configuration names that exist for autodoc_pydantic.

This is used by determine_app_cfg_name to identify configuration names that do not need to be prefixed. This is used when options of foreign documenters are accessed (e.g. validator documenter needs to read configuration values from field documenter).

determine_app_cfg_name(name: str) str[source]

Provide full app environment configuration name for given option name. It contains some logic to get the correct env configuration name, e.g. for pydantic model as follows:

model-show-field-list -> autodoc_pydantic_model_show_field_list undoc-members -> autodoc_pydantic_model_undoc_members field-swap-name-and-alias -> autodoc_pydantic_field_swap_name_and_alias

Parameters:

name (str) – Name of the option.

Returns:

full_name – Full app environment configuration name.

Return type:

str

add_pass_through_to_directive()[source]

Intercepts documenters add_directive_header and adds pass through.

pass_option_to_directive(name: str)[source]

Pass an autodoc option through to the generated directive.

directives.py

This module is located at sphinxcontrib/autodoc_pydantic/directives/directives.py.

This module contains autodoc_pydantic’s directives.

class PydanticDirectiveBase(*args)[source]

Bases: object

Base class for pydantic directive providing common functionality.

get_signature_prefix(sig: str) str | List[Text][source]

Overwrite original signature prefix with custom pydantic ones.

class PydanticModel(*args)[source]

Bases: PydanticDirectiveBase, PyClasslike

Specialized directive for pydantic models.

option_spec: OptionSpec = {'__doc_disable_except__': <function option_list_like>, 'annotation': <function unchanged>, 'canonical': <function unchanged>, 'final': <function flag>, 'model-signature-prefix': <function unchanged>, 'module': <function unchanged>, 'no-contents-entry': <function flag>, 'no-index': <function flag>, 'no-index-entry': <function flag>, 'no-typesetting': <function flag>, 'nocontentsentry': <function flag>, 'noindex': <function flag>, 'noindexentry': <function flag>, 'single-line-parameter-list': <function flag>, 'single-line-type-parameter-list': <function flag>}

Mapping of option names to validator functions.

class PydanticSettings(*args)[source]

Bases: PydanticDirectiveBase, PyClasslike

Specialized directive for pydantic settings.

option_spec: OptionSpec = {'__doc_disable_except__': <function option_list_like>, 'annotation': <function unchanged>, 'canonical': <function unchanged>, 'final': <function flag>, 'module': <function unchanged>, 'no-contents-entry': <function flag>, 'no-index': <function flag>, 'no-index-entry': <function flag>, 'no-typesetting': <function flag>, 'nocontentsentry': <function flag>, 'noindex': <function flag>, 'noindexentry': <function flag>, 'settings-signature-prefix': <function unchanged>, 'single-line-parameter-list': <function flag>, 'single-line-type-parameter-list': <function flag>}

Mapping of option names to validator functions.

class PydanticField(*args)[source]

Bases: PydanticDirectiveBase, PyAttribute

Specialized directive for pydantic fields.

option_spec: OptionSpec = {'__doc_disable_except__': <function option_list_like>, 'alias': <function unchanged>, 'annotation': <function unchanged>, 'canonical': <function unchanged>, 'field-show-alias': <function option_default_true>, 'field-signature-prefix': <function unchanged>, 'field-swap-name-and-alias': <function option_default_true>, 'module': <function unchanged>, 'no-contents-entry': <function flag>, 'no-index': <function flag>, 'no-index-entry': <function flag>, 'no-typesetting': <function flag>, 'nocontentsentry': <function flag>, 'noindex': <function flag>, 'noindexentry': <function flag>, 'optional': <function option_default_true>, 'required': <function option_default_true>, 'single-line-parameter-list': <function flag>, 'single-line-type-parameter-list': <function flag>, 'type': <function unchanged>, 'value': <function unchanged>}

Mapping of option names to validator functions.

get_field_name(sig: str) str[source]

Get field name from signature. Borrows implementation from PyObject.handle_signature.

add_required(signode: desc_signature)[source]

Add [Required] if directive option required is set.

add_optional(signode: desc_signature)[source]

Add [Optional] if directive option optional is set.

add_alias_or_name(sig: str, signode: desc_signature)[source]

Add alias or name to signature.

Alias is added if show-alias is enabled. Name is added if both show-alias and swap-name-and-alias is enabled.

swap_name_and_alias(sig: str, signode: desc_signature)[source]

Replaces name with alias if swap-name-and-alias is enabled.

Requires to replace existing addnodes.desc_name because name node is added within handle_signature and this can’t be intercepted or overwritten otherwise.

handle_signature(sig: str, signode: desc_signature) Tuple[str, str][source]

Optionally call add alias method.

class PydanticValidator(*args)[source]

Bases: PydanticDirectiveBase, PyMethod

Specialized directive for pydantic validators.

option_spec: OptionSpec = {'__doc_disable_except__': <function option_list_like>, 'abstractmethod': <function flag>, 'annotation': <function unchanged>, 'async': <function flag>, 'canonical': <function unchanged>, 'classmethod': <function flag>, 'field-swap-name-and-alias': <function option_default_true>, 'final': <function flag>, 'module': <function unchanged>, 'no-contents-entry': <function flag>, 'no-index': <function flag>, 'no-index-entry': <function flag>, 'no-typesetting': <function flag>, 'nocontentsentry': <function flag>, 'noindex': <function flag>, 'noindexentry': <function flag>, 'single-line-parameter-list': <function flag>, 'single-line-type-parameter-list': <function flag>, 'staticmethod': <function flag>, 'validator-replace-signature': <function option_default_true>, 'validator-signature-prefix': <function unchanged>}

Mapping of option names to validator functions.

get_field_href_from_mapping(inspector: ModelInspector, mapping: ValidatorFieldMap) pending_xref[source]

Generate the field reference node aka pending_xref from given validator-field mapping while respecting field name/alias swap possibility.

replace_return_node(signode: desc_signature)[source]

Replaces the return node with references to validated fields.

handle_signature(sig: str, signode: desc_signature) Tuple[str, str][source]

Optionally call replace return node method.