Describe Pydantic and semver in "Advanced topics"

tomschr · calebstewart · tomschr · commit 73bd190a1cb0 · 2022-01-28T17:21:15.000+01:00
Related to issue #343 Co-authored-by: Caleb Stewart <calebstewart@users.noreply.github.com>
diff --git a/changelog.d/343.doc.rst b/changelog.d/343.doc.rst
@@ -0,0 +1,2 @@
+Describe combining Pydantic with semver in the "Advanced topic"
+section.
diff --git a/docs/advanced/combine-pydantic-and-semver.rst b/docs/advanced/combine-pydantic-and-semver.rst
@@ -0,0 +1,53 @@
+Combining Pydantic and semver
+=============================
+
+According to its homepage, `Pydantic <https://pydantic-docs.helpmanual.io>`_
+"enforces type hints at runtime, and provides user friendly errors when data
+is invalid."
+
+To work with Pydantic, use the following steps:
+
+
+1. Derive a new class from :class:`~semver.version.Version`
+   first and add the magic methods :py:meth:`__get_validators__`
+   and :py:meth:`__modify_schema__` like this:
+
+    .. code-block:: python
+
+        from semver import Version
+
+        class PydanticVersion(Version):
+            @classmethod
+            def __get_validators__(cls):
+                """Return a list of validator methods for pydantic models."""
+                yield cls.parse
+
+            @classmethod
+            def __modify_schema__(cls, field_schema):
+                """Inject/mutate the pydantic field schema in-place."""
+                field_schema.update(examples=["1.0.2",
+                                              "2.15.3-alpha",
+                                              "21.3.15-beta+12345",
+                                              ]
+                                    )
+
+2. Create a new model (in this example :class:`MyModel`) and derive
+   it from :class:`pydantic.BaseModel`:
+
+    .. code-block:: python
+
+        import pydantic
+
+        class MyModel(pydantic.BaseModel):
+            version: PydanticVersion
+
+3. Use your model like this:
+
+    .. code-block:: python
+
+        model = MyModel.parse_obj({"version": "1.2.3"})
+
+   The attribute :py:attr:`model.version` will be an instance of
+   :class:`~semver.version.Version`.
+   If the version is invalid, the construction will raise a
+   :py:exc:`pydantic.ValidationError`.
diff --git a/docs/advanced/index.rst b/docs/advanced/index.rst
@@ -2,9 +2,9 @@ Advanced topics
 ===============
 
 
-
 .. toctree::
 
     deal-with-invalid-versions
     create-subclasses-from-version
-    display-deprecation-warnings
+    display-deprecation-warnings
+    combine-pydantic-and-semver

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,2 @@`
	`1`	`+Describe combining Pydantic with semver in the "Advanced topic"`
	`2`	`+section.`