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_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.
- 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.
- class StaticInspector[source]
Bases:
object
Namespace under ModelInspector for static methods.
- 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 thisinspect
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 theirobject
attribute being correctly set after instantiation which typically holds a reference to the corresponding pydantic model and objects to be documented. Instead,object
isNone
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 theobject
is stillNone
. 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 thatobject
is then already correctly provided and theModelInspector
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
- 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_erdantic_figure()[source]
Adds an erdantic entity relation diagram to the doc of an pydantic model.
- 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
- 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.
- 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.
- add_default_value_or_marker()[source]
Adds default value or a marker for field being required or optional.
- 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.
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.
- 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.
- 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
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.
- 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_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.
- 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.