pytools.api.DocValidator#

class pytools.api.DocValidator(*, root_dir, validate_protected=None, exclude_from_parameter_validation=None, additional_tests=None)[source]#

Validates docstrings and type hints in all Python sources in a given directory tree.

By default, only validates public classes, methods, and functions, and class initializers (__init__). Protected classes, methods, and functions are only validated if their name is provided in parameter validate_protected.

Parameters

root_dir (str) – the root directory of all Python files to be validated
validate_protected (Optional[Iterable[str]]) – names of protected functions and methods to be validated (default: ('__init__',))
exclude_from_parameter_validation (Union[str, Pattern[str], None]) – do not validate parameter documentation and type hints for classes, methods or functions whose full name (including the module prefix) matches the given regular expression
additional_tests (Optional[Iterable[DocTest]]) – additional documentation tests to run on each API element

Method summary

validate_doc

Validate documentation, including docstrings and type annotations.

Attribute summary

`DEFAULT_VALIDATE_PROTECTED`	The default value for parameter `validate_protected`.
`DEFAULT_VALIDATION_TESTS`	Default collection of documentation tests to run during validation.
`root_dir`	The root directory of all Python files to be validated.
`validate_protected`	Names of protected functions and methods to be validated.
`exclude_from_parameter_validation`	Names of modules for which parameter documentation and type hints should not be validated.
`validation_errors`	A dictionary mapping definitions to lists of errors identified during validation.
`validation_tests`	The documentation tests to run on each definition during validation.

Definitions

validate_doc()[source]#

Validate documentation, including docstrings and type annotations.

Return type: bool
Returns: True if the validation was successful; False if the validation failed

DEFAULT_VALIDATE_PROTECTED = ('__init__',)#: The default value for parameter validate_protected.

DEFAULT_VALIDATION_TESTS: tuple[doc.DocTest, ...] = (HasDocstring(), HasMatchingParameterDoc(), HasWellFormedDocstring(), HasTypeHints())#: Default collection of documentation tests to run during validation.

exclude_from_parameter_validation: Optional[re.Pattern[str]]#: Names of modules for which parameter documentation and type hints should not be validated.

root_dir: str#: The root directory of all Python files to be validated.

validate_protected: tuple[str, ...]#: Names of protected functions and methods to be validated.

validation_errors: dict[str, list[str]]#: A dictionary mapping definitions to lists of errors identified during validation.

validation_tests: tuple[doc.DocTest, ...]#: The documentation tests to run on each definition during validation.

pytools.api.AllTracker

pytools.api.MissingClassMeta