update: standardizes __init__ exports

- Defines aliases for old override config classes for backward compatibility
- Adds `__all__` to recipe `__init__` files to explicitly declare exports
- FIxes `apply_plugins` config input/return type
- Adds ruff rule to format `__all__` exports
- Updates changelog

Author: namsnath

CHANGELOG.md

@@ -8,6 +8,49 @@ 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
+
+### 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.0] - 2025-05-27
 ### Adds Webauthn (Passkeys) support
 - Adds Webauthn recipe with support for:

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

supertokens_python/plugins.py

@@ -57,31 +57,32 @@
     from supertokens_python.recipe.webauthn.types.config import WebauthnConfig
     from supertokens_python.supertokens import SupertokensPublicConfig
 
-T = TypeVar("T")
+RecipeConfigType = TypeVar(
+    "RecipeConfigType",
+    bound=Union[
+        "AccountLinkingConfig",
+        "DashboardConfig",
+        "EmailPasswordConfig",
+        "EmailVerificationConfig",
+        "JWTConfig",
+        "MultiFactorAuthConfig",
+        "MultitenancyConfig",
+        "OAuth2ProviderConfig",
+        "OpenIdConfig",
+        "PasswordlessConfig",
+        "SessionConfig",
+        "ThirdPartyConfig",
+        "TOTPConfig",
+        "UserMetadataConfig",
+        "UserRolesConfig",
+        "WebauthnConfig",
+    ],
+)
 
 
 RecipeInterfaceType = TypeVar("RecipeInterfaceType", bound=BaseRecipeInterface)
 APIInterfaceType = TypeVar("APIInterfaceType", bound=BaseAPIInterface)
 
-RecipeConfigType = Union[
-    "AccountLinkingConfig",
-    "DashboardConfig",
-    "EmailPasswordConfig",
-    "EmailVerificationConfig",
-    "JWTConfig",
-    "MultiFactorAuthConfig",
-    "MultitenancyConfig",
-    "OAuth2ProviderConfig",
-    "OpenIdConfig",
-    "PasswordlessConfig",
-    "SessionConfig",
-    "ThirdPartyConfig",
-    "TOTPConfig",
-    "UserMetadataConfig",
-    "UserRolesConfig",
-    "WebauthnConfig",
-]
-
 
 class RecipeInitRequiredFunction(Protocol):
     def __call__(self, sdk_version: str) -> bool: ...

supertokens_python/recipe/accountlinking/__init__.py

@@ -15,15 +15,17 @@
 
 from typing import TYPE_CHECKING, Any, Awaitable, Callable, Dict, Optional, Union
 
-from ...types import User
-from . import types
-from .recipe import AccountLinkingRecipe
+from supertokens_python.types import User
 
-AccountLinkingOverrideConfig = types.AccountLinkingOverrideConfig
-RecipeLevelUser = types.RecipeLevelUser
-AccountInfoWithRecipeIdAndUserId = types.AccountInfoWithRecipeIdAndUserId
-ShouldAutomaticallyLink = types.ShouldAutomaticallyLink
-ShouldNotAutomaticallyLink = types.ShouldNotAutomaticallyLink
+from .recipe import AccountLinkingRecipe
+from .types import (
+    AccountInfoWithRecipeIdAndUserId,
+    AccountLinkingOverrideConfig,
+    InputOverrideConfig,
+    RecipeLevelUser,
+    ShouldAutomaticallyLink,
+    ShouldNotAutomaticallyLink,
+)
 
 if TYPE_CHECKING:
     from ..session.interfaces import SessionContainer
@@ -50,3 +52,15 @@ def init(
     return AccountLinkingRecipe.init(
         on_account_linked, should_do_automatic_account_linking, override
     )
+
+
+__all__ = [
+    "AccountInfoWithRecipeIdAndUserId",
+    "AccountLinkingOverrideConfig",
+    "AccountLinkingRecipe",
+    "InputOverrideConfig",  # deprecated, use AccountLinkingOverrideConfig instead
+    "RecipeLevelUser",
+    "ShouldAutomaticallyLink",
+    "ShouldNotAutomaticallyLink",
+    "init",
+]

supertokens_python/recipe/accountlinking/types.py

@@ -43,6 +43,8 @@
 NormalisedAccountLinkingOverrideConfig = BaseNormalisedOverrideConfigWithoutAPI[
     RecipeInterface
 ]
+InputOverrideConfig = AccountLinkingOverrideConfig
+"""Deprecated, use `AccountLinkingOverrideConfig` instead."""
 
 
 class AccountInfoWithRecipeId(AccountInfo):

supertokens_python/recipe/dashboard/__init__.py

@@ -16,12 +16,10 @@
 
 from typing import List, Optional
 
-from supertokens_python.recipe.dashboard import utils
 from supertokens_python.supertokens import RecipeInit
 
 from .recipe import DashboardRecipe
-
-DashboardOverrideConfig = utils.DashboardOverrideConfig
+from .utils import DashboardOverrideConfig, InputOverrideConfig
 
 
 def init(
@@ -34,3 +32,11 @@ def init(
         admins,
         override,
     )
+
+
+__all__ = [
+    "DashboardOverrideConfig",
+    "DashboardRecipe",
+    "InputOverrideConfig",  # deprecated, use DashboardOverrideConfig instead
+    "init",
+]

supertokens_python/recipe/dashboard/utils.py

@@ -81,6 +81,8 @@ def to_json(self) -> Dict[str, Any]:
 NormalisedDashboardOverrideConfig = BaseNormalisedOverrideConfig[
     RecipeInterface, APIInterface
 ]
+InputOverrideConfig = DashboardOverrideConfig
+"""Deprecated, use `DashboardOverrideConfig` instead."""
 
 
 class DashboardConfig(BaseConfig[RecipeInterface, APIInterface]):

supertokens_python/recipe/emailpassword/__init__.py

@@ -15,33 +15,46 @@
 
 from typing import TYPE_CHECKING, Union
 
-from supertokens_python.ingredients.emaildelivery import types as emaildelivery_types
-from supertokens_python.ingredients.emaildelivery.types import EmailDeliveryConfig
+from supertokens_python.ingredients.emaildelivery.types import (
+    EmailDeliveryConfig,
+    EmailDeliveryInterface,
+)
 from supertokens_python.recipe.emailpassword.types import EmailTemplateVars
 
-from . import exceptions as ex
-from . import utils
-from .emaildelivery import services as emaildelivery_services
+from .emaildelivery.services import SMTPService
 from .recipe import EmailPasswordRecipe
-
-exceptions = ex
-EmailPasswordOverrideConfig = utils.EmailPasswordOverrideConfig
-InputSignUpFeature = utils.InputSignUpFeature
-InputFormField = utils.InputFormField
-SMTPService = emaildelivery_services.SMTPService
-EmailDeliveryInterface = emaildelivery_types.EmailDeliveryInterface
+from .utils import (
+    EmailPasswordOverrideConfig,
+    InputFormField,
+    InputOverrideConfig,
+    InputSignUpFeature,
+)
 
 if TYPE_CHECKING:
     from supertokens_python.supertokens import RecipeInit
 
 
 def init(
-    sign_up_feature: Union[utils.InputSignUpFeature, None] = None,
-    override: Union[utils.EmailPasswordOverrideConfig, None] = None,
+    sign_up_feature: Union[InputSignUpFeature, None] = None,
+    override: Union[EmailPasswordOverrideConfig, None] = None,
     email_delivery: Union[EmailDeliveryConfig[EmailTemplateVars], None] = None,
 ) -> RecipeInit:
     return EmailPasswordRecipe.init(
         sign_up_feature,
         override,
         email_delivery,
     )
+
+
+__all__ = [
+    "EmailDeliveryConfig",
+    "EmailDeliveryInterface",
+    "EmailPasswordOverrideConfig",
+    "EmailPasswordRecipe",
+    "EmailTemplateVars",
+    "InputFormField",
+    "InputOverrideConfig",  # deprecated, use EmailPasswordOverrideConfig instead
+    "InputSignUpFeature",
+    "SMTPService",
+    "init",
+]

supertokens_python/recipe/emailpassword/utils.py

@@ -221,6 +221,8 @@ def validate_and_normalise_reset_password_using_token_config(
 NormalisedEmailPasswordOverrideConfig = BaseNormalisedOverrideConfig[
     RecipeInterface, APIInterface
 ]
+InputOverrideConfig = EmailPasswordOverrideConfig
+"""Deprecated, use `EmailPasswordOverrideConfig` instead."""
 
 
 class EmailPasswordConfig(BaseConfig[RecipeInterface, APIInterface]):

supertokens_python/recipe/emailverification/__init__.py

@@ -15,21 +15,13 @@
 
 from typing import TYPE_CHECKING, Optional, Union
 
-from ...ingredients.emaildelivery.types import EmailDeliveryConfig
-from . import exceptions as ex
-from . import recipe, types, utils
-from .emaildelivery import services as emaildelivery_services
-from .interfaces import TypeGetEmailForUserIdFunction
-from .recipe import EmailVerificationRecipe
-from .types import EmailTemplateVars
-from .utils import MODE_TYPE, EmailVerificationOverrideConfig
-
-InputOverrideConfig = utils.EmailVerificationOverrideConfig
-exception = ex
-SMTPService = emaildelivery_services.SMTPService
-EmailVerificationClaim = recipe.EmailVerificationClaim
-EmailDeliveryInterface = types.EmailDeliveryInterface
+from supertokens_python.ingredients.emaildelivery.types import EmailDeliveryConfig
 
+from .emaildelivery.services import SMTPService
+from .interfaces import TypeGetEmailForUserIdFunction
+from .recipe import EmailVerificationClaim, EmailVerificationRecipe
+from .types import EmailDeliveryInterface, EmailTemplateVars
+from .utils import MODE_TYPE, EmailVerificationOverrideConfig, InputOverrideConfig
 
 if TYPE_CHECKING:
     from supertokens_python.supertokens import RecipeInit
@@ -47,3 +39,16 @@ def init(
         get_email_for_recipe_user_id,
         override,
     )
+
+
+__all__ = [
+    "EmailDeliveryInterface",
+    "EmailTemplateVars",
+    "EmailVerificationClaim",
+    "EmailVerificationOverrideConfig",
+    "EmailVerificationRecipe",
+    "InputOverrideConfig",  # deprecated, use EmailVerificationOverrideConfig instead
+    "SMTPService",
+    "TypeGetEmailForUserIdFunction",
+    "init",
+]