feat: plugins (#594)

- Adds support for plugins under the `experimental` property in `SuperTokensConfig`
  - Introduces a `SupertokensPublicConfig` class to work with plugins
- Refactors the AccountLinking recipe to be automatically initialized on SuperTokens init
- Adds `is_recipe_initialized` method to check if a recipe has been initialized
- Adds new base classes for `RecipeInterface`, `APIInterface`, `Config`
  - Refactors existing config classes to follow `<Recipe>Config` and `<Recipe>NormalizedConfig`
  - Older names left in as aliases
- Standardizes `__init__` exports
  - Adds `__all__` to recipe `__init__` files to explicitly declare exports
  - Adds ruff rule to format `__all__` exports

Author: namsnath

CHANGELOG.md

@@ -8,6 +8,50 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [unreleased]
 
+## [0.31.0] - 2025-07-18
+### Adds plugins support
+- Adds an `experimental` property (`SuperTokensExperimentalConfig`) to the `SuperTokensConfig`
+  - Plugins can be configured under using the `plugins` property in the `experimental` config
+- Refactors the AccountLinking recipe to be automatically initialized on SuperTokens init
+- Adds `is_recipe_initialized` method to check if a recipe has been initialized
+
+### Breaking Changes
+- `AccountLinkingRecipe.get_instance` will now raise an exception if not initialized
+- Various config classes renamed for consistency across the codebase, and classes added where they were missing
+  - Old classes added to the recipe modules as aliases for backward compatibility, but will be removed in future versions. Prefer using the renamed classes.
+  - `InputOverrideConfig` renamed to `<Recipe>OverrideConfig`
+  - `OverrideConfig` renamed to `Normalised<Recipe>OverrideConfig`
+  - Input config classes like `<Recipe>InputConfig` renamed to `<Recipe>Config`
+  - Normalised config classes like `<Recipe>Config` renamed to `Normalised<Recipe>Config`
+  - Changed classes:
+    - AccountLinking `InputOverrideConfig` -> `AccountLinkingOverrideConfig`
+    - Dashboard `InputOverrideConfig` -> `DashboardOverrideConfig`
+    - EmailPassword
+      - `InputOverrideConfig` -> `EmailPasswordOverrideConfig`
+      - `exceptions` export removed from `__init__`, import the `exceptions` module directly
+    - EmailVerification
+      - `InputOverrideConfig` -> `EmailVerificationOverrideConfig`
+      - `exception` export removed from `__init__`, import the `exceptions` module directly
+    - JWT `OverrideConfig` -> `JWTOverrideConfig`
+    - MultiFactorAuth `OverrideConfig` -> `MultiFactorAuthOverrideConfig`
+    - Multitenancy
+      - `InputOverrideConfig` -> `MultitenancyOverrideConfig`
+      - `exceptions` export removed from `__init__`, import the `exceptions` module directly
+    - OAuth2Provider
+      - `InputOverrideConfig` -> `OAuth2ProviderOverrideConfig`
+      - `exceptions` export removed from `__init__`, import the `exceptions` module directly
+    - OpenId `InputOverrideConfig` -> `OpenIdOverrideConfig`
+    - Passwordless `InputOverrideConfig` -> `PasswordlessOverrideConfig`
+    - Session
+      - `InputOverrideConfig` -> `SessionOverrideConfig`
+      - `exceptions` export removed from `__init__`, import the `exceptions` module directly
+    - ThirdParty
+      - `InputOverrideConfig` -> `ThirdPartyOverrideConfig`
+      - `exceptions` export removed from `__init__`, import the `exceptions` module directly
+    - TOTP `OverrideConfig` -> `TOTPOverrideConfig`
+    - UserMetadata `InputOverrideConfig` -> `UserMetadataOverrideConfig`
+    - UserRoles `InputOverrideConfig` -> `UserRolesOverrideConfig`
+
 ## [0.30.1] - 2025-07-21
 - Adds missing register credential endpoint to the Webauthn recipe
 

dev-requirements.txt

@@ -7,11 +7,12 @@ 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
 pylint==3.2.7
-pyright==1.1.393
+pyright==1.1.402
 python-dotenv==1.0.1
 pytest==8.3.3
 pytest-asyncio==0.24.0

pyproject.toml

@@ -3,7 +3,10 @@ line-length = 88 # Match Black's formatting
 src = ["supertokens_python"]
 
 [tool.ruff.lint]
-extend-select = ["I"] # enable import sorting
+extend-select = [
+    "I", # enable import sorting
+    "RUF022", # Sort __all__ exports
+]
 
 [tool.ruff.format]
 quote-style = "double" # Default
@@ -18,3 +21,5 @@ include = ["supertokens_python/", "tests/", "examples/"]
 addopts = " -v -p no:warnings"
 python_paths = "."
 xfail_strict = true
+# Removes requirement to use `@mark.asyncio` on async tests
+asyncio_mode = "auto"

setup.py

@@ -61,28 +61,28 @@
 }
 
 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(
     name="supertokens_python",
-    version="0.30.1",
+    version="0.31.0",
     author="SuperTokens",
     license="Apache 2.0",
     author_email="[email protected]",
@@ -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/__init__.py

@@ -12,38 +12,61 @@
 # License for the specific language governing permissions and limitations
 # under the License.
 
-from typing import Any, Callable, Dict, List, Optional
+from typing import Any, Dict, List, Optional
 
 from typing_extensions import Literal
 
 from supertokens_python.framework.request import BaseRequest
+from supertokens_python.recipe_module import RecipeModule
 from supertokens_python.types import RecipeUserId
 
-from . import supertokens
-from .recipe_module import RecipeModule
+from .plugins import LoadPluginsResponse
+from .supertokens import (
+    AppInfo,
+    InputAppInfo,
+    RecipeInit,
+    Supertokens,
+    SupertokensConfig,
+    SupertokensExperimentalConfig,
+    SupertokensInputConfig,
+    SupertokensPublicConfig,
+)
 
-InputAppInfo = supertokens.InputAppInfo
-Supertokens = supertokens.Supertokens
-SupertokensConfig = supertokens.SupertokensConfig
-AppInfo = supertokens.AppInfo
+# Some Pydantic models need a rebuild to resolve ForwardRefs
+# Referencing imports here to prevent lint errors.
+# Caveat: These will be available for import from this module directly.
+RecipeModule  # type: ignore
+
+# LoadPluginsResponse -> SupertokensPublicConfig
+LoadPluginsResponse.model_rebuild()
+# SupertokensInputConfig -> RecipeModule
+SupertokensInputConfig.model_rebuild()
 
 
 def init(
     app_info: InputAppInfo,
     framework: Literal["fastapi", "flask", "django"],
     supertokens_config: SupertokensConfig,
-    recipe_list: List[Callable[[supertokens.AppInfo], RecipeModule]],
+    recipe_list: List[RecipeInit],
     mode: Optional[Literal["asgi", "wsgi"]] = None,
     telemetry: Optional[bool] = None,
     debug: Optional[bool] = None,
+    experimental: Optional[SupertokensExperimentalConfig] = None,
 ):
     return Supertokens.init(
-        app_info, framework, supertokens_config, recipe_list, mode, telemetry, debug
+        app_info,
+        framework,
+        supertokens_config,
+        recipe_list,
+        mode,
+        telemetry,
+        debug,
+        experimental=experimental,
     )
 
 
 def get_all_cors_headers() -> List[str]:
-    return supertokens.Supertokens.get_instance().get_all_cors_headers()
+    return Supertokens.get_instance().get_all_cors_headers()
 
 
 def get_request_from_user_context(
@@ -54,3 +77,23 @@ def get_request_from_user_context(
 
 def convert_to_recipe_user_id(user_id: str) -> RecipeUserId:
     return RecipeUserId(user_id)
+
+
+is_recipe_initialized = Supertokens.is_recipe_initialized
+
+
+__all__ = [
+    "AppInfo",
+    "InputAppInfo",
+    "RecipeInit",
+    "RecipeUserId",
+    "Supertokens",
+    "SupertokensConfig",
+    "SupertokensExperimentalConfig",
+    "SupertokensPublicConfig",
+    "convert_to_recipe_user_id",
+    "get_all_cors_headers",
+    "get_request_from_user_context",
+    "init",
+    "is_recipe_initialized",
+]

supertokens_python/constants.py

@@ -15,7 +15,7 @@
 from __future__ import annotations
 
 SUPPORTED_CDI_VERSIONS = ["5.3"]
-VERSION = "0.30.1"
+VERSION = "0.31.0"
 TELEMETRY = "/telemetry"
 USER_COUNT = "/users/count"
 USER_DELETE = "/user/remove"

supertokens_python/exceptions.py

@@ -40,3 +40,7 @@ class GeneralError(SuperTokensError):
 
 class BadInputError(SuperTokensError):
     pass
+
+
+class PluginError(SuperTokensError):
+    pass