Autodoc-pydantic

This is a maintenance and bugfix release extending support to pydantic
v2.6, sphinx v7.2 and python 3.12 while dropping support for python 3.7
which has reached EOL.

Features

- Hide `model_computed_fields` for pydantic models.
- Hide `settings_customise_sources` for pydantic settings.

Testing

- Add pydantic 2.2/2.3/2.4/2.5/2.6 and sphinx 7.1/7.2 and python 3.12
to test matrix.
- Remove python 3.7 from test matrix.
- Remove obsolete `skip ci` condition from github actions.
- Update `conftest` to use `pathlib` instead of older Sphinx
`sphinx.testing.path` module that is being deprecated for
forward-compatibility with newer Sphinx versions.
- Fix duplicated teset name `test_non_field_attributes`.
- Add tests to cover inheritance behavior given `inherited-members`
for field and validator members and summaries.

Bugfix

- Fix incompatibity with sphinx 7.2 due to changed usage of path
objects. For more, see
[11606](https://github.com/sphinx-doc/sphinx/issues/11605).
- [176](https://github.com/mansenfranzen/autodoc_pydantic/issues/176)
Remove `sphinxcontrib/__init__.py` causing `ModuleNotFoundError`
exception in some environments. This should be a namespace package
per [PEP 420](https://peps.python.org/pep-0420/) without
`__init_.py` to match with other extensions.
- Removing deprecation warning `sphinx.util.typing.stringify`.
- Fix bug a bug while sorting members
[137](https://github.com/mansenfranzen/autodoc_pydantic/issues/137).

Internal

- Fix deprecation warning for tuple interface of `ObjectMember` in
`directives/autodocumenters.py`.
- Remove obsolete configuration options which have been removed in v2.
- Introduce `pydantic.options.exists` to check for existence of sphinx
options.

Documentation

- Add pydantic to PyPI classifiers to improve discoverability.
- Correct erdantic installation command in users coniguration section.
- Improve users FAQ regarding documentation of inherited members.

Contributors

- Thanks to [devmonkey22](https://github.com/devmonkey22) for
providing a PR to solve a nasty namespace package issue
[176](https://github.com/mansenfranzen/autodoc_pydantic/issues/176)
and [daquinteroflex](https://github.com/daquinteroflex) for testing
and providing feedback.
- Thanks to [rafa-guedes](https://github.com/rafa-guedes) for
providing a PR to fix a deprecation warning for tuple interface of
`ObjectMember` in `directives/autodocumenters.py`
[174](https://github.com/mansenfranzen/autodoc_pydantic/issues/174)
and [j-carson](https://github.com/j-carson) for reporting it.
- Thanks to [caerulescens](https://github.com/caerulescens) for
providing a PR to add pydantic to PyPI classifiers
[179](https://github.com/mansenfranzen/autodoc_pydantic/pull/179).
- Thanks to [spacemanspiff2007](https://github.com/spacemanspiff2007)
for hiding `model_computed_fields` and `settings_customise_sources`
[202](https://github.com/mansenfranzen/autodoc_pydantic/pull/202).
- Thanks to [tony](https://github.com/tony) for fixing a typo in the
erdantic docs
[200](https://github.com/mansenfranzen/autodoc_pydantic/pull/200).
- Thanks to [j-carson](https://github.com/j-carson) for providing a PR
that:
- fixes a bug while sorting members
[137](https://github.com/mansenfranzen/autodoc_pydantic/issues/137).
- fixes broken CI pipeline with Sphinx 4.\*
- removing deprecation warning
[178](https://github.com/mansenfranzen/autodoc_pydantic/issues/178).

This is a bugfix release handling an exception while documenting
pydantic models using enums.

Internal

- Simplify model field\'s constraint extraction removing dependency on
private methods.

Bugfix

- Properly handle constraint extraction avoiding exceptions due to
prior reliance on unpredictable behavior of private attributes.
- Fix incorrect type annotation string results for non-builtin types
in `intercept_type_annotations_py_gt_39`.

Testing

- Add pydantic 2.1 to test matrix.
- Add tests for various kinds of constrained types.
- Add \"no exception\" tests for specific pydantic models, such as
containing enums.

Contributors

- Thanks to [nagledb](https://github.com/nagledb) for reporting a bug
related to enums
[169](https://github.com/mansenfranzen/autodoc_pydantic/issues/169).
- Thanks to [jerryjiahaha](https://github.com/jerryjiahaha) for
providing a pull request fixing the enums bug
[170](https://github.com/mansenfranzen/autodoc_pydantic/pull/170).

This is a major release supporting pydantic v2. In June 2023, pydantic
v2 was released while introducing backwards incompatible API and
behavioral changes in comparison to pydantic v1. Supporting pydantic v2
required substantial adjustments to the codebase leading to a new major
release of autodoc_pydantic (v1.9.0 -\> v2.0.0), too.

In order to keep the codebase clean and concise, separate versions for
v1 and v2 were created. The v2 branch will eventually become the new
main branch while the code for v1 remains in the main-1.x branch.

Changed Behavior

- Documenting pydantic model configurations in isolation or as a
separate member of the pydantic model is no longer available. The
following options have been removed:
- `autodoc_pydantic_model_show_config_member`
- `autodoc_pydantic_settings_show_config_member`
- `autodoc_pydantic_config_members`
- `autodoc_pydantic_config_signature_prefix`
- All semantic changes from pydantic v1 to v2 take full effect.
**autodoc_pydantic** does not modify the underlying behavior of
pydantic in any way. Instead, it only documents whatever pydantic
exposes. Hence, all behavioral changes such as the new default
strict mode are preserved in v2.
- Sphinx `< 4.0.0` is no longer supported.

Features

- Support for pydantic v2 💫.
- Support annotated type hints.

Internal

- Adjust imports to refer to `pydantic-settings` (v2) instead of
`pydantic` (v1).
- Adjust imports to refer to `field_validator` (v2) insteaf of
`validator` (v1).
- Adjust imports to refer to `model_validator` (v2) insteaf of
`root_validator` (v1).
- Replace `pydantic.generics.GenericModel` (v1) with `typing.Generic`
(v2).
- Simplify `ValidatorAdapter` and `ValidatorInspector`.
- Simplify reused validators retrieval.
- Completely rewrite the model\'s field constraint retrieval
functionality in `inspection.FieldInspector`.
- Adjust model\'s field serializability checks in
`inspection.FieldInspector`.
- Replace `BaseModel` with `NamedTuple` for `ValidatorAdapter`.
- Remove obsolete pre/post validator attributes.
- Introduce `importlib-metadata` to fetch version number including
support for python 3.7.

Testing

- Remove all obsolete pydantic versions from test matrix.
- Remove all tests for documenting config members.
- Remove compatibility helpers for older pydantic versions.
- Remove obsolete pydantic model example which was not used anywhere.
- Adjust serializability tests to account for changed behavior in v2.
- Adjust optional/required field marker tests to account for changed
behavior in v2.
- Adjust field constraint tests to account for changed behavior in v2.
- Adjust erdantic tests to exclude the erdantic version number which
caused tests to fail upon erdantic update.

Documentation

- Add FAQ section regarding migration guide from v1 to v2.
- Remove `complete` showcase from user\'s example.
- Update READMEs with newest features and version specifiers.
- Update developer\'s setup section to address v1 to v2 changes.
- Updates user\'s installation section to address v1 to v2 changes.
- Remove all obsolete documentation on removed config documenters.
- Rename all occurences to v2 `field_validator` and `model_validator`.

Contributors

- Special thanks to [awoimbee](https://github.com/awoimbee) for
providing a draft for the v1 to v2 migration which really initiated
the work on supporting pydantic v2
[160](https://github.com/mansenfranzen/autodoc_pydantic/pull/160).
- Many thanks to [PriOliveira](https://github.com/PriOliveira) for
reviewing changes required for the v1 to v2 release
[160](https://github.com/mansenfranzen/autodoc_pydantic/pull/160).

This is a feature release adding support for entity relationship
diagrams while dropping python 3.6. Additionally, pydantic v2 is
currently excluded until support will be added. Moreover, newest sphinx
versions are added to test matrix.

Feature

- Introduce `erdantic-figure` and `erdantic-figure-collapsed`
configuration option for pydantic models to add entity relationship
diagrams to models\' documentation either in collapsed form or as an
image included to the HTML.
[148](https://github.com/mansenfranzen/autodoc_pydantic/pull/148).

Bugfix

- Run github actions on newest `ubuntu-22.04`.
- Fix pytest errors with `sphinx>=6.1` where the type returned by
`autodoc_typehints_format` changed.
- Provide upper version boundary for pydantic to exclude v2 which is
not supported, yet.

Internal

- Add `to_collapsable` to `directives.templates` that provides a
standardized interface to create a collapsable field.
- Add `erdantic` to extras dependencies.

Documentation

- Add descriptions for `erdantic-figure` and
`erdantic-figure-collapsed` options in the configuration section.
- Add an example of ERD in the example section.

Testing

- Exclude `python 3.6` in test matrix.
- Include `sphinx` 6.0, 6.1, 6.2 and 7.0 in test matrix.
- Add tests for `erdantic-figure` and `erdantic-figure-collapsed`.
- Fix github actions CI pipeline due to unsupported ubuntu while
upgrading to newest `ubuntu-22.04`.

Contributors

- Many thanks to [yves-renier](https://github.com/yves-renier) for
adding entity relationship diagrams and fixing the CI pipeline
[148](https://github.com/mansenfranzen/autodoc_pydantic/pull/148).

This is a feature and bugfix release with major internal refactorings
and added support for pydantic `1.10` and sphinx `5.1` and `5.2`.

Feature

- Introduce `hide-reused-validator` configuration option for pydantic
models and settings to hide class methods that are created while
declaring functions as reusable validators
[122](https://github.com/mansenfranzen/autodoc_pydantic/issues/122).

Bugfix

- Fix incorrect reference of reused validators
[122](https://github.com/mansenfranzen/autodoc_pydantic/issues/122).
- Provide deterministic sort order for model\'s validator summary and
field\'s validator list.
- Hide pydantic user warnings in sphinx output when testing for
pydantic field serializability.

Internal

- Add `ValidatorAdapter` that provides a standardized interface to
pydantic\'s validator objects with additional metadata (e.g. root
validator) for internal usage in autodoc_pydantic.
- Introduce `field_validator_mappings` to `inspection.ModelInspector`
which holds all mappings between fields and validators. It makes
many helper functions of `ValidatorInspector` and `FieldInspector`
obsolete. Overall, this greatly simplifies the inspection codebase.
- Add `PydanticAutoDoc.resolve_inherited_validator_reference` to allow
proper reference resolution for inherited validators.

Documentation

- Add description for `autodoc_pydantic_model_hide_reused_validator`
and `autodoc_pydantic_settings_hide_reused_validator`.
- Add example section for reused validators with detailed explanation.
- Refactor sphinx extension helper for building `autodoc_pydantic`
docs for better readability and maintainability.
- Add `example_path` to sphinx extension helper `config_description`.
- Add FAQ question regarding interoperability with `autoapi`.

Testing

- Include pydantic `1.10` and sphinx `5.1` / `5.2` in test matrix.
- Provide compatibility for new pydantic and sphinx versions.
- Fix incorrect pydantic version comparison.

Contributors

- Thanks to [GlenNicholls](https://github.com/GlenNicholls) for
reporting a bug regarding incorrect references of reused validators
[122](https://github.com/mansenfranzen/autodoc_pydantic/issues/122)
.
- Thanks to [csm10495](https://github.com/csm10495) for asking a
question regarding `autoapi` interoperability
[138](https://github.com/mansenfranzen/autodoc_pydantic/issues/138)
.

This is a bugfix release.

Bugfix

- Adjust `PydanticFieldDocumenter.can_document_member` to ignore non
pydantic fields
[123](https://github.com/mansenfranzen/autodoc_pydantic/issues/123),
[128](https://github.com/mansenfranzen/autodoc_pydantic/issues/128).
- Allow pydantic models to be documented as class attributes while
adjusting `ModelInspector.from_child_signode` to support nested
object paths
[124](https://github.com/mansenfranzen/autodoc_pydantic/issues/123),
[129](https://github.com/mansenfranzen/autodoc_pydantic/issues/128).

Contributors

- Thanks to [sneakers-the-rat](https://github.com/sneakers-the-rat)
and [PipeKnight](https://github.com/PipeKnight) for reporting a bug
when encountering attributes that are not pydantic fields
[123](https://github.com/mansenfranzen/autodoc_pydantic/issues/123),
[128](https://github.com/mansenfranzen/autodoc_pydantic/issues/128).
- Thanks to [iwishiwasaneagle](https://github.com/iwishiwasaneagle)
and [nickeldan](https://github.com/nickeldan) for reporting a bug
pydantic models were documented as class attributes or
`ModelInspector.from_child_signode` returned the incorrect model
reference
[124](https://github.com/mansenfranzen/autodoc_pydantic/issues/123),
[129](https://github.com/mansenfranzen/autodoc_pydantic/issues/128).

Internal

- Renamed `from_signode` to `from_child_signode` for better clarity.
- Added explicit check to raise an exception if loaded object in
`ModelInspector.from_child_signode` is not a pydantic model.