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 ValidatorFieldMap(field_name: str, validator_name: str, model_ref: str)[source]
Bases:
tuple
Contains single mapping of a pydantic validator and field.
- property field_name
Name of the field.
- property validator_name
Name of the validator.
- property model_ref
Reference corresponding parent pydantic model.
- property field_ref
Reference to field..
- property validator_ref
Reference to validator.
- class BaseInspectionComposite(parent: sphinxcontrib.autodoc_pydantic.inspection.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: sphinxcontrib.autodoc_pydantic.inspection.ModelInspector)[source]
Bases:
sphinxcontrib.autodoc_pydantic.inspection.BaseInspectionComposite
Provide namespace for inspection methods for fields of pydantic models.
- property validator_names: Dict[str, Set[str]]
Return mapping between all field names (keys) and their corresponding validator names (values).
- property validator_names_root: Dict[str, Set[str]]
Return mapping between all field names (keys) and their corresponding validator names (values) for root validators only.
- property validator_names_standard: Dict[str, List[str]]
Return mapping between all field names (keys) and their corresponding validator names (values) for standard validators only.
Please be aware, the asterisk field name * is used to represent all fields.
- property names: List[str]
Return field names while keeping ordering.
- get(name: str) pydantic.fields.ModelField [source]
Get the instance of ModelField 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.
- 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: sphinxcontrib.autodoc_pydantic.inspection.ModelInspector)[source]
Bases:
sphinxcontrib.autodoc_pydantic.inspection.BaseInspectionComposite
Provide namespace for inspection methods for validators of pydantic models.
- static get_names_from_wrappers(validators: Iterator[pydantic.class_validators.Validator]) Set[str] [source]
Return the actual validator names as defined in the class body from list of pydantic validator wrappers.
- Parameters
validators (list) – Wrapper objects for pydantic validators.
- property names_root_validators: Set[str]
Return all names of root validators.
- property names_asterisk_validators: Set[str]
Return all names of asterisk validators. Asterisk are defined as validators, that process all availble fields. They consist of root validators and validators with the * field target.
- property names_standard_validators: Set[str]
Return all names of standard validators which do not process all fields at once (in contrast to asterisk validators).
- property names: Set[str]
Return names of all validators of pydantic model.
- class ConfigInspector(parent: sphinxcontrib.autodoc_pydantic.inspection.ModelInspector)[source]
Bases:
sphinxcontrib.autodoc_pydantic.inspection.BaseInspectionComposite
Provide namespace for inspection methods for config class of pydantic models.
- property is_configured: bool
Check if pydantic model config was explicitly configured. If not, it defaults to the standard configuration provided by pydantic and typically does not required documentation.
- property items: Dict
Return all non private (without leading underscore _) items of pydantic configuration class.
- class ReferenceInspector(*args, **kwargs)[source]
Bases:
sphinxcontrib.autodoc_pydantic.inspection.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[sphinxcontrib.autodoc_pydantic.inspection.ValidatorFieldMap] [source]
Return mappings for given validator name.
- filter_by_field_name(name: str) List[sphinxcontrib.autodoc_pydantic.inspection.ValidatorFieldMap] [source]
Return mappings for given field name.
- class SchemaInspector(parent: sphinxcontrib.autodoc_pydantic.inspection.ModelInspector)[source]
Bases:
sphinxcontrib.autodoc_pydantic.inspection.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[pydantic.main.BaseModel])[source]
Bases:
object
Provides inspection functionality for pydantic models.
- static
alias of
sphinxcontrib.autodoc_pydantic.inspection.StaticInspector
- classmethod from_child_signode(signode: sphinx.addnodes.desc_signature) sphinxcontrib.autodoc_pydantic.inspection.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: sphinx.ext.autodoc.Documenter, is_child: bool)[source]
Bases:
object
Composite to provide single namespace to access all autodoc_pydantic relevant documenter directive functionalities.
- property options: sphinxcontrib.autodoc_pydantic.directives.options.composites.AutoDocOptions
Provides access to
PydanticDocumenterOptions
to handle global and local configuration settings.
- property inspect: sphinxcontrib.autodoc_pydantic.inspection.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.
- class PydanticModelDocumenter(*args: Any)[source]
Bases:
sphinx.ext.autodoc.ClassDocumenter
Represents specialized Documenter subclass for pydantic models.
- 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.
- format_signature(**kwargs) str [source]
If parameter list is to be hidden, return only empty signature.
- add_content(more_content: Optional[docutils.statemachine.StringList], **kwargs) None [source]
Delegate additional content creation.
- class PydanticSettingsDocumenter(*args: Any)[source]
Bases:
sphinxcontrib.autodoc_pydantic.directives.autodocumenters.PydanticModelDocumenter
Represents specialized Documenter subclass for pydantic settings.
- class PydanticFieldDocumenter(*args)[source]
Bases:
sphinx.ext.autodoc.AttributeDocumenter
Represents specialized Documenter subclass for pydantic fields.
- 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:
sphinx.ext.autodoc.MethodDocumenter
Represents specialized Documenter subclass for pydantic validators.
- classmethod can_document_member(member: Any, membername: str, isattr: bool, parent: Any) bool [source]
Filter only pydantic validators.
- class PydanticConfigClassDocumenter(*args: Any)[source]
Bases:
sphinx.ext.autodoc.ClassDocumenter
Represents specialized Documenter subclass for pydantic model configuration.
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_CONFIG = {'__doc_disable_except__': <function option_list_like>, 'config-signature-prefix': <function unchanged>, 'members': <function option_members>}
Represents added directive options for
PydanticConfigDocumenter
.
- OPTIONS_MODEL = {'__doc_disable_except__': <function option_list_like>, 'members': <function option_members>, 'model-hide-paramlist': <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-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: Union[sphinx.ext.autodoc.Documenter, docutils.parsers.rst.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]
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.
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]
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.
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:
sphinxcontrib.autodoc_pydantic.directives.options.composites.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.
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:
sphinxcontrib.autodoc_pydantic.directives.directives.PydanticDirectiveBase
,sphinx.domains.python.PyClasslike
Specialized directive for pydantic models.
- class PydanticSettings(*args)[source]
Bases:
sphinxcontrib.autodoc_pydantic.directives.directives.PydanticDirectiveBase
,sphinx.domains.python.PyClasslike
Specialized directive for pydantic settings.
- class PydanticField(*args)[source]
Bases:
sphinxcontrib.autodoc_pydantic.directives.directives.PydanticDirectiveBase
,sphinx.domains.python.PyAttribute
Specialized directive for pydantic fields.
- get_field_name(sig: str) str [source]
Get field name from signature. Borrows implementation from PyObject.handle_signature.
- add_required(signode: sphinx.addnodes.desc_signature)[source]
Add [Required] if directive option required is set.
- add_optional(signode: sphinx.addnodes.desc_signature)[source]
Add [Optional] if directive option optional is set.
- add_alias_or_name(sig: str, signode: sphinx.addnodes.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:
sphinxcontrib.autodoc_pydantic.directives.directives.PydanticDirectiveBase
,sphinx.domains.python.PyMethod
Specialized directive for pydantic validators.
- get_field_href_from_mapping(inspector: sphinxcontrib.autodoc_pydantic.inspection.ModelInspector, mapping: sphinxcontrib.autodoc_pydantic.inspection.ValidatorFieldMap) sphinx.addnodes.pending_xref [source]
Generate the field reference node aka pending_xref from given validator-field mapping while respecting field name/alias swap possibility.
- class PydanticConfigClass(*args)[source]
Bases:
sphinxcontrib.autodoc_pydantic.directives.directives.PydanticDirectiveBase
,sphinx.domains.python.PyClasslike
Specialized directive for pydantic config class.