Merge pull request #801 from marshmallow-code/packaging

Use packaging.Version

Author: lafrech

setup.py

@@ -1,6 +1,8 @@
 import re
 from setuptools import setup, find_packages
 
+INSTALL_REQUIRES = "packaging>=21.3"
+
 EXTRAS_REQUIRE = {
     "marshmallow": ["marshmallow>=3.13.0"],
     "yaml": ["PyYAML>=3.10"],
@@ -63,6 +65,7 @@ def read(fname):
     packages=find_packages("src"),
     package_dir={"": "src"},
     include_package_data=True,
+    install_requires=INSTALL_REQUIRES,
     extras_require=EXTRAS_REQUIRE,
     license="MIT",
     zip_safe=False,

src/apispec/core.py

@@ -1,12 +1,13 @@
 """Core apispec classes and functions."""
 
 from __future__ import annotations
-from collections.abc import Sequence
-
 
-import typing
+from collections.abc import Sequence
 from copy import deepcopy
 import warnings
+import typing
+
+from packaging.version import Version
 
 from .exceptions import (
     APISpecError,
@@ -15,7 +16,7 @@
     DuplicateParameterError,
     InvalidParameterError,
 )
-from .utils import OpenAPIVersion, deepupdate, COMPONENT_SUBSECTIONS, build_reference
+from .utils import deepupdate, COMPONENT_SUBSECTIONS, build_reference
 
 if typing.TYPE_CHECKING:
     from .plugin import BasePlugin
@@ -27,6 +28,9 @@
 
 VALID_METHODS = {2: VALID_METHODS_OPENAPI_V2, 3: VALID_METHODS_OPENAPI_V3}
 
+MIN_INCLUSIVE_OPENAPI_VERSION = Version("2.0")
+MAX_EXCLUSIVE_OPENAPI_VERSION = Version("4.0")
+
 
 class Components:
     """Stores OpenAPI components
@@ -38,7 +42,7 @@ class Components:
     def __init__(
         self,
         plugins: Sequence[BasePlugin],
-        openapi_version: OpenAPIVersion,
+        openapi_version: Version,
     ) -> None:
         self._plugins = plugins
         self.openapi_version = openapi_version
@@ -405,7 +409,7 @@ class APISpec:
     :param str version: API version
     :param list|tuple plugins: Plugin instances.
         See https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#infoObject
-    :param str|OpenAPIVersion openapi_version: OpenAPI Specification version.
+    :param str openapi_version: OpenAPI Specification version.
         Should be in the form '2.x' or '3.x.x' to comply with the OpenAPI standard.
     :param options: Optional top-level keys
         See https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#openapi-object
@@ -415,15 +419,21 @@ def __init__(
         self,
         title: str,
         version: str,
-        openapi_version: OpenAPIVersion | str,
+        openapi_version: str,
         plugins: Sequence[BasePlugin] = (),
         **options: typing.Any,
     ) -> None:
         self.title = title
         self.version = version
-        self.openapi_version = OpenAPIVersion(openapi_version)
         self.options = options
         self.plugins = plugins
+        self.openapi_version = Version(openapi_version)
+        if not (
+            MIN_INCLUSIVE_OPENAPI_VERSION
+            <= self.openapi_version
+            < MAX_EXCLUSIVE_OPENAPI_VERSION
+        ):
+            raise APISpecError(f"Not a valid OpenAPI version number: {openapi_version}")
 
         # Metadata
         self._tags: list[dict] = []
@@ -444,10 +454,10 @@ def to_dict(self) -> dict[str, typing.Any]:
         if self._tags:
             ret["tags"] = self._tags
         if self.openapi_version.major < 3:
-            ret["swagger"] = self.openapi_version.vstring
+            ret["swagger"] = str(self.openapi_version)
             ret.update(self.components.to_dict())
         else:
-            ret["openapi"] = self.openapi_version.vstring
+            ret["openapi"] = str(self.openapi_version)
             components_dict = self.components.to_dict()
             if components_dict:
                 ret["components"] = components_dict

src/apispec/ext/marshmallow/__init__.py

@@ -74,11 +74,11 @@ class UserSchema(Schema):
 
 import warnings
 import typing
+from packaging.version import Version
 
 from marshmallow import Schema
 
 from apispec import BasePlugin, APISpec
-from apispec.utils import OpenAPIVersion
 from .common import resolve_schema_instance, make_schema_key, resolve_schema_cls
 from .openapi import OpenAPIConverter
 from .schema_resolver import SchemaResolver
@@ -120,7 +120,7 @@ def __init__(
         super().__init__()
         self.schema_name_resolver = schema_name_resolver or resolver
         self.spec: APISpec | None = None
-        self.openapi_version: OpenAPIVersion | None = None
+        self.openapi_version: Version | None = None
         self.converter: OpenAPIConverter | None = None
         self.resolver: SchemaResolver | None = None
 

src/apispec/ext/marshmallow/field_converter.py

@@ -11,12 +11,11 @@
 import operator
 import typing
 import warnings
+from packaging.version import Version
 
 import marshmallow
 from marshmallow.orderedset import OrderedSet
 
-from apispec.utils import OpenAPIVersion
-
 
 RegexType = type(re.compile(""))
 
@@ -90,7 +89,7 @@ class FieldConverterMixin:
     """Adds methods for converting marshmallow fields to an OpenAPI properties."""
 
     field_mapping = DEFAULT_FIELD_MAPPING
-    openapi_version: OpenAPIVersion
+    openapi_version: Version
 
     def init_attribute_functions(self):
         self.attribute_functions = [

src/apispec/ext/marshmallow/openapi.py

@@ -9,12 +9,12 @@
 
 from __future__ import annotations
 import typing
+from packaging.version import Version
 
 import marshmallow
 from marshmallow.utils import is_collection
 
 from apispec import APISpec
-from apispec.utils import OpenAPIVersion
 from apispec.exceptions import APISpecError
 from .field_converter import FieldConverterMixin
 from .common import (
@@ -40,7 +40,7 @@
 class OpenAPIConverter(FieldConverterMixin):
     """Adds methods for generating OpenAPI specification from marshmallow schemas and fields.
 
-    :param str|OpenAPIVersion openapi_version: The OpenAPI version to use.
+    :param Version openapi_version: The OpenAPI version to use.
         Should be in the form '2.x' or '3.x.x' to comply with the OpenAPI standard.
     :param callable schema_name_resolver: Callable to generate the schema definition name.
         Receives the `Schema` class and returns the name to be used in refs within
@@ -52,11 +52,11 @@ class OpenAPIConverter(FieldConverterMixin):
 
     def __init__(
         self,
-        openapi_version: OpenAPIVersion | str,
+        openapi_version: Version,
         schema_name_resolver,
         spec: APISpec,
     ) -> None:
-        self.openapi_version = OpenAPIVersion(openapi_version)
+        self.openapi_version = openapi_version
         self.schema_name_resolver = schema_name_resolver
         self.spec = spec
         self.init_attribute_functions()

src/apispec/utils.py

@@ -8,8 +8,6 @@
 import json
 import typing
 
-from distutils import version
-
 from apispec import exceptions
 
 if typing.TYPE_CHECKING:
@@ -73,7 +71,7 @@ def validate_spec(spec: APISpec) -> bool:
             "    pip install 'apispec[validation]'"
         ) from error
     parser_kwargs = {}
-    if spec.openapi_version.version[0] == 3:
+    if spec.openapi_version.major == 3:
         parser_kwargs["backend"] = "openapi-spec-validator"
     try:
         prance.BaseParser(spec_string=json.dumps(spec.to_dict()), **parser_kwargs)
@@ -83,53 +81,6 @@ def validate_spec(spec: APISpec) -> bool:
         return True
 
 
-class OpenAPIVersion(version.LooseVersion):
-    """OpenAPI version
-
-    :param str|OpenAPIVersion openapi_version: OpenAPI version
-
-    Parses an OpenAPI version expressed as string. Provides shortcut to digits
-    (major, minor, patch).
-
-        Example: ::
-
-            ver = OpenAPIVersion('3.0.2')
-            assert ver.major == 3
-            assert ver.minor == 0
-            assert ver.patch == 1
-            assert ver.vstring == '3.0.2'
-            assert str(ver) == '3.0.2'
-    """
-
-    MIN_INCLUSIVE_VERSION = version.LooseVersion("2.0")
-    MAX_EXCLUSIVE_VERSION = version.LooseVersion("4.0")
-
-    def __init__(self, openapi_version: version.LooseVersion | str) -> None:
-        if isinstance(openapi_version, version.LooseVersion):
-            openapi_version = openapi_version.vstring
-        if (
-            not self.MIN_INCLUSIVE_VERSION
-            <= openapi_version
-            < self.MAX_EXCLUSIVE_VERSION
-        ):
-            raise exceptions.APISpecError(
-                f"Not a valid OpenAPI version number: {openapi_version}"
-            )
-        super().__init__(openapi_version)
-
-    @property
-    def major(self) -> int:
-        return int(self.version[0])
-
-    @property
-    def minor(self) -> int:
-        return int(self.version[1])
-
-    @property
-    def patch(self) -> int:
-        return int(self.version[2])
-
-
 # from django.contrib.admindocs.utils
 def trim_docstring(docstring: str) -> str:
     """Uniformly trims leading/trailing whitespace from docstrings.

tests/test_core.py

@@ -148,10 +148,10 @@ def test_openapi_metadata(self, spec):
         assert metadata["info"]["version"] == "1.0.0"
         assert metadata["info"]["description"] == description
         if spec.openapi_version.major < 3:
-            assert metadata["swagger"] == spec.openapi_version.vstring
+            assert metadata["swagger"] == str(spec.openapi_version)
             assert metadata["security"] == [{"apiKey": []}]
         else:
-            assert metadata["openapi"] == spec.openapi_version.vstring
+            assert metadata["openapi"] == str(spec.openapi_version)
             security_schemes = {
                 "bearerAuth": dict(type="http", scheme="bearer", bearerFormat="JWT")
             }

tests/test_ext_marshmallow_field.py

@@ -398,7 +398,7 @@ def custom_string2properties(self, field, **kwargs):
         CustomStringField()
     )
     assert properties["x-customString"] == (
-        spec_fixture.openapi.openapi_version == "2.0"
+        spec_fixture.openapi.openapi_version.major == 2
     )
 
 

tests/test_utils.py

@@ -1,27 +1,4 @@
-import pytest
-
 from apispec import utils
-from apispec.exceptions import APISpecError
-
-
-class TestOpenAPIVersion:
-    @pytest.mark.parametrize("version", ("1.0", "4.0"))
-    def test_openapi_version_invalid_version(self, version):
-        message = "Not a valid OpenAPI version number:"
-        with pytest.raises(APISpecError, match=message):
-            utils.OpenAPIVersion(version)
-
-    @pytest.mark.parametrize("version", ("3.0.1", utils.OpenAPIVersion("3.0.1")))
-    def test_openapi_version_string_or_openapi_version_param(self, version):
-        assert utils.OpenAPIVersion(version) == utils.OpenAPIVersion("3.0.1")
-
-    def test_openapi_version_digits(self):
-        ver = utils.OpenAPIVersion("3.0.1")
-        assert ver.major == 3
-        assert ver.minor == 0
-        assert ver.patch == 1
-        assert ver.vstring == "3.0.1"
-        assert str(ver) == "3.0.1"
 
 
 def test_build_reference():