feat: improves plugin version checks

- Adds dependency on `packaging` to compare versions
- Versions expected to follow PEP 440 style specifiers
- Sorts items in `setup.py` for clarity

ref: supertokens/supertokens-node#1021

Author: namsnath

dev-requirements.txt

@@ -7,6 +7,7 @@ fastapi==0.115.5
 Flask==3.0.3
 flask-cors==5.0.0
 nest-asyncio==1.6.0
+packaging==25.0
 pdoc3==0.11.0
 pre-commit==3.5.0
 pyfakefs==5.7.4

setup.py

@@ -61,23 +61,23 @@
 }
 
 exclude_list = [
-    "tests",
-    "examples",
-    "hooks",
-    ".gitignore",
+    ".circleci",
     ".git",
+    ".github",
+    ".gitignore",
+    ".pylintrc",
+    "Makefile",
     "addDevTag",
     "addReleaseTag",
-    "frontendDriverInterfaceSupported.json",
     "coreDriverInterfaceSupported.json",
-    ".github",
-    ".circleci",
-    "html",
-    "pyrightconfig.json",
-    "Makefile",
-    ".pylintrc",
     "dev-requirements.txt",
     "docs-templates",
+    "examples",
+    "frontendDriverInterfaceSupported.json",
+    "hooks",
+    "html",
+    "pyrightconfig.json",
+    "tests",
 ]
 
 setup(
@@ -112,22 +112,23 @@
     ],
     keywords="",
     install_requires=[
+        "Deprecated<1.3.0",
         # [crypto] ensures that it installs the `cryptography` library as well
         # based on constraints specified in https://github.com/jpadilla/pyjwt/blob/master/setup.cfg#L50
         "PyJWT[crypto]>=2.5.0,<3.0.0",
-        "httpx>=0.15.0,<1.0.0",
-        "pycryptodome<3.21.0",
-        "tldextract<6.0.0",
+        "aiosmtplib>=1.1.6,<4.0.0",
         "asgiref>=3.4.1,<4",
-        "typing_extensions>=4.1.1,<5.0.0",
-        "Deprecated<1.3.0",
+        "httpx>=0.15.0,<1.0.0",
+        "packaging>=25.0,<26.0",
         "phonenumbers<9",
-        "twilio<10",
-        "aiosmtplib>=1.1.6,<4.0.0",
         "pkce<1.1.0",
+        "pycryptodome<3.21.0",
+        "pydantic>=2.10.6,<3.0.0",
         "pyotp<3",
         "python-dateutil<3",
-        "pydantic>=2.10.6,<3.0.0",
+        "tldextract<6.0.0",
+        "twilio<10",
+        "typing_extensions>=4.1.1,<5.0.0",
     ],
     python_requires=">=3.8",
     include_package_data=True,

supertokens_python/plugins.py

@@ -14,6 +14,8 @@
     runtime_checkable,
 )
 
+from packaging.specifiers import SpecifierSet
+from packaging.version import Version
 from typing_extensions import Protocol
 
 from supertokens_python.constants import VERSION
@@ -387,14 +389,14 @@ def load_plugins(
             continue
 
         if isinstance(plugin.compatible_sdk_versions, list):
-            version_constraints = plugin.compatible_sdk_versions
+            version_constraints = ",".join(plugin.compatible_sdk_versions)
         else:
-            version_constraints = [plugin.compatible_sdk_versions]
+            version_constraints = plugin.compatible_sdk_versions
 
-        if VERSION not in version_constraints:
-            # TODO: Better checks
+        if not SpecifierSet(version_constraints).contains(Version(VERSION)):
             raise Exception(
-                f"Plugin version mismatch. Version {VERSION} not in {version_constraints=} for plugin {plugin.id}"
+                f"Incompatible SDK version for plugin {plugin.id}. "
+                f"Version {VERSION} not found in compatible versions {version_constraints}"
             )
 
         # TODO: Overkill, but could topologically sort the plugins based on dependencies

tests/plugins/plugins.py

@@ -89,6 +89,7 @@ def plugin_factory(
     override_config: bool = False,
     deps: Optional[List[SuperTokensPlugin]] = None,
     add_init: bool = False,
+    compatible_sdk_versions: Optional[Union[str, List[str]]] = None,
 ):
     override_map_obj: OverrideMap = {PluginTestRecipe.recipe_id: RecipePluginOverride()}
 
@@ -110,9 +111,14 @@ def plugin_factory(
     if add_init:
         init_fn = init_factory(identifier)
 
+    if compatible_sdk_versions is None:
+        sdk_versions = f"=={VERSION}"
+    else:
+        sdk_versions = compatible_sdk_versions
+
     class Plugin(SuperTokensPlugin):
         id: str = identifier
-        compatible_sdk_versions: Union[str, List[str]] = [VERSION]
+        compatible_sdk_versions: Union[str, List[str]] = sdk_versions
         override_map: Optional[OverrideMap] = override_map_obj
         init: Any = init_fn
         dependencies: Optional[SuperTokensPluginDependencies] = dependency_factory(deps)

tests/plugins/test_plugins.py

@@ -1,5 +1,6 @@
 from functools import partial
-from typing import Any, List
+from typing import Any, List, Union
+from unittest.mock import patch
 
 from pytest import fixture, mark, param, raises
 from supertokens_python import (
@@ -450,3 +451,50 @@ async def test_route_handlers_callable(handler_response: Any, expectation: Any):
         )
 
         assert res == expected_output
+
+
+@mark.parametrize(
+    ("sdk_version", "compatible_versions", "expectation"),
+    [
+        param(
+            "1.5.0",
+            ">=1.0.0,<2.0.0",
+            outputs(None),
+            id="[Valid][1.5.0][>=1.0.0,<2.0.0] as string",
+        ),
+        param(
+            "1.5.0",
+            [">=1.0.0", "<2.0.0"],
+            outputs(None),
+            id="[Valid][1.5.0][>=1.0.0,<2.0.0] as list of strings",
+        ),
+        param(
+            "2.0.0",
+            [">=1.0.0,<2.0.0"],
+            raises(Exception, match="Incompatible SDK version for plugin plugin1."),
+            id="[Invalid][2.0.0][>=1.0.0,<2.0.0]",
+        ),
+    ],
+)
+def test_versions(
+    sdk_version: str,
+    compatible_versions: Union[str, List[str]],
+    expectation: Any,
+):
+    plugin = plugin_factory(
+        "plugin1",
+        override_functions=False,
+        override_apis=False,
+        compatible_sdk_versions=compatible_versions,
+    )
+
+    with patch("supertokens_python.plugins.VERSION", sdk_version):
+        with expectation as _:
+            partial_init(
+                recipe_list=[
+                    recipe_factory(override_functions=False, override_apis=False),
+                ],
+                experimental=SupertokensExperimentalConfig(
+                    plugins=[plugin],
+                ),
+            )