Make the globus_sdk.token_storage namespace only present 'v2' members and rename 'v1' to 'legacy'

changelog.d/20250717_154854_sirosen_bury_v1_tokenstorage.rst

@@ -0,0 +1,8 @@
+Changed
+-------
+
+- The legacy token storage adapters are now only available from the
+  ``globus_sdk.token_storage.legacy`` subpackage.
+
+  Users are encouraged to migrate to the newer tooling available directly from
+  ``globus_sdk.token_storage``. (:pr:`NUMBER`)

docs/authorization/token_caching/storage_adapters.rst

@@ -15,7 +15,7 @@ received from authentication and token refreshes.
 Usage
 -----
 
-StorageAdapter is available under the name ``globus_sdk.token_storage``.
+StorageAdapter is available under the name ``globus_sdk.token_storage.legacy``.
 
 Storage adapters are the main objects of this subpackage. Primarily, usage
 should revolve around creating a storage adapter, potentially loading data from
@@ -27,7 +27,7 @@ For example:
 
     import os
     import globus_sdk
-    from globus_sdk.token_storage import SimpleJSONFileAdapter
+    from globus_sdk.token_storage.legacy import SimpleJSONFileAdapter
 
     my_file_adapter = SimpleJSONFileAdapter(os.path.expanduser("~/mytokens.json"))
 
@@ -76,19 +76,12 @@ For example:
     tc = globus_sdk.TransferClient(authorizer=authorizer)
 
 
-Complete Example Usage
-~~~~~~~~~~~~~~~~~~~~~~
-
-The :ref:`Group Listing With Token Storage Script <example_group_listing_with_token_storage>`
-provides a complete and runnable example which leverages ``token_storage``.
-
-
 Adapter Types
 -------------
 
-.. module:: globus_sdk.token_storage
+.. module:: globus_sdk.token_storage.legacy
 
-``globus_sdk.token_storage`` provides base classes for building your own storage
+``globus_sdk.token_storage.legacy`` provides base classes for building your own storage
 adapters, and several complete adapters.
 
 The :class:`SimpleJSONFileAdapter` is good for the "simplest possible"

docs/examples/group_listing.rst

@@ -62,8 +62,8 @@ For simplicity, the script will prompt for login on each use.
 Group Listing With Token Storage
 --------------------------------
 
-``globus_sdk.token_storage`` provides tools for managing refresh tokens. The
-following example script shows how you might use this to provide a complete
+``globus_sdk.token_storage.legacy`` provides tools for managing refresh tokens.
+The following example script shows how you might use this to provide a complete
 script which lists the current user's groups using refresh tokens.
 
 
@@ -72,7 +72,7 @@ script which lists the current user's groups using refresh tokens.
     import os
 
     from globus_sdk import GroupsClient, NativeAppAuthClient, RefreshTokenAuthorizer
-    from globus_sdk.token_storage import SimpleJSONFileAdapter
+    from globus_sdk.token_storage.legacy import SimpleJSONFileAdapter
 
     CLIENT_ID = "61338d24-54d5-408f-a10d-66c06b59f6d2"
     AUTH_CLIENT = NativeAppAuthClient(CLIENT_ID)

docs/upgrading.rst

@@ -262,6 +262,45 @@ In version 4, this has been removed, but the collection types provide
 scopes for the Globus Transfer service via ``list(TransferClient.scopes)`` or
 similar usage.
 
+Token Storage Subpackage Renamed
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The subpackage providing token storage components has been renamed and slightly
+restructured.
+
+The package name is changed from
+``globus_sdk.tokenstorage`` to ``globus_sdk.token_storage``.
+
+Furthermore, the legacy :ref:`storage adapters <storage_adapters>` are now only
+available from ``globus_sdk.token_storage.legacy``.
+
+Therefore, usages of the modern :ref:`token storage interface <token_storages>`
+should update like so:
+
+.. code-block:: python
+
+    # globus-sdk v3
+    from globus_sdk.tokenstorage import JSONTokenStorage
+
+    # globus-sdk v4
+    from globus_sdk.token_storage import JSONTokenStorage
+
+For legacy adapter usage, update like so:
+
+.. code-block:: python
+
+    # globus-sdk v3
+    from globus_sdk.tokenstorage import SimpleJSONFileAdapter
+
+    # globus-sdk v4
+    from globus_sdk.token_storage.legacy import SimpleJSONFileAdapter
+
+.. note::
+
+    The ``legacy`` interface is soft-deprecated.
+    In version 4.0.0 it will not emit deprecation warnings.
+    Future SDK versions will eventually deprecate and remove these interfaces.
+
 Deprecated Timers Aliases Removed
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

src/globus_sdk/globus_app/authorizer_factory.py

@@ -13,7 +13,7 @@
 )
 from globus_sdk.services.auth import OAuthTokenResponse
 from globus_sdk.token_storage import ValidatingTokenStorage
-from globus_sdk.token_storage.v2.validating_token_storage import MissingTokenError
+from globus_sdk.token_storage.validating_token_storage import MissingTokenError
 
 GA = t.TypeVar("GA", bound=GlobusAuthorizer)
 

src/globus_sdk/globus_app/config.py

@@ -17,7 +17,7 @@
     TokenStorage,
     TokenValidationError,
 )
-from globus_sdk.token_storage.v2.validating_token_storage import IdentityMismatchError
+from globus_sdk.token_storage.validating_token_storage import IdentityMismatchError
 
 from .protocols import (
     IDTokenDecoderProvider,

src/globus_sdk/token_storage/__init__.py

@@ -1,42 +1,27 @@
-from .v1 import (
-    FileAdapter,
-    MemoryAdapter,
-    SimpleJSONFileAdapter,
-    SQLiteAdapter,
-    StorageAdapter,
-)
-from .v2 import (
-    FileTokenStorage,
+from .base import FileTokenStorage, TokenStorage
+from .json import JSONTokenStorage
+from .memory import MemoryTokenStorage
+from .sqlite import SQLiteTokenStorage
+from .token_data import TokenStorageData
+from .validating_token_storage import (
     HasRefreshTokensValidator,
-    JSONTokenStorage,
-    MemoryTokenStorage,
     NotExpiredValidator,
     ScopeRequirementsValidator,
-    SQLiteTokenStorage,
     TokenDataValidator,
-    TokenStorage,
-    TokenStorageData,
     TokenValidationContext,
     TokenValidationError,
     UnchangingIdentityIDValidator,
     ValidatingTokenStorage,
 )
 
 __all__ = (
-    # [v1] "StorageAdapter" Constructs
-    "StorageAdapter",
-    "FileAdapter",
-    "SimpleJSONFileAdapter",
-    "SQLiteAdapter",
-    "MemoryAdapter",
-    # [v2] "TokenStorage" Constructs
     "TokenStorage",
     "TokenStorageData",
     "FileTokenStorage",
     "JSONTokenStorage",
     "SQLiteTokenStorage",
     "MemoryTokenStorage",
-    # [v2] "ValidatingTokenStorage" Constructs
+    # TokenValidationStorage constructs
     "ValidatingTokenStorage",
     "TokenValidationContext",
     "TokenDataValidator",

tests/functional/tokenstorage/v1/test_simplejson_file.py

@@ -4,7 +4,7 @@
 import pytest
 
 from globus_sdk import __version__
-from globus_sdk.token_storage import SimpleJSONFileAdapter
+from globus_sdk.token_storage.legacy import SimpleJSONFileAdapter
 
 IS_WINDOWS = os.name == "nt"
 

tests/functional/tokenstorage/v1/test_sqlite.py

@@ -1,6 +1,6 @@
 import pytest
 
-from globus_sdk.token_storage import SQLiteAdapter
+from globus_sdk.token_storage.legacy import SQLiteAdapter
 
 
 @pytest.fixture

tests/functional/tokenstorage/v2/test_json_tokenstorage.py

@@ -4,7 +4,8 @@
 import pytest
 
 from globus_sdk import __version__
-from globus_sdk.token_storage import JSONTokenStorage, SimpleJSONFileAdapter
+from globus_sdk.token_storage import JSONTokenStorage
+from globus_sdk.token_storage.legacy import SimpleJSONFileAdapter
 
 IS_WINDOWS = os.name == "nt"
 

tests/functional/tokenstorage/v2/test_sqlite_tokenstorage.py

@@ -1,7 +1,8 @@
 import pytest
 
 from globus_sdk import exc
-from globus_sdk.token_storage import SQLiteAdapter, SQLiteTokenStorage
+from globus_sdk.token_storage import SQLiteTokenStorage
+from globus_sdk.token_storage.legacy import SQLiteAdapter
 
 
 @pytest.fixture

tests/unit/globus_app/test_authorizer_factory.py

@@ -13,7 +13,7 @@
     MemoryTokenStorage,
     NotExpiredValidator,
 )
-from globus_sdk.token_storage.v2.validating_token_storage import (
+from globus_sdk.token_storage.validating_token_storage import (
     ExpiredTokenError,
     MissingTokenError,
     ValidatingTokenStorage,

tests/unit/tokenstorage/v1/test_memory_adapter.py

@@ -1,7 +1,7 @@
 import time
 from unittest import mock
 
-from globus_sdk.token_storage import MemoryAdapter
+from globus_sdk.token_storage.legacy import MemoryAdapter
 
 
 def test_memory_adapter_store_overwrites_only_new_data():

tests/unit/tokenstorage/v1/test_simplejson_adapter.py

@@ -3,7 +3,7 @@
 import pytest
 
 from globus_sdk import __version__ as sdkversion
-from globus_sdk.token_storage import SimpleJSONFileAdapter
+from globus_sdk.token_storage.legacy import SimpleJSONFileAdapter
 
 
 def test_simplejson_reading_bad_data(tmp_path):

tests/unit/tokenstorage/v1/test_sqlite_adapter.py

@@ -1,6 +1,6 @@
 import pytest
 
-from globus_sdk.token_storage import SQLiteAdapter
+from globus_sdk.token_storage.legacy import SQLiteAdapter
 
 
 def test_sqlite_reading_bad_config():

tests/unit/tokenstorage/v2/test_token_storage.py

@@ -1,7 +1,7 @@
 import pytest
 
 from globus_sdk import GlobusSDKUsageError
-from globus_sdk.token_storage.v2.base import _slugify_app_name
+from globus_sdk.token_storage.base import _slugify_app_name
 
 
 @pytest.mark.parametrize(

tests/unit/tokenstorage/v2/test_validating_token_storage.py

@@ -22,7 +22,7 @@
     UnchangingIdentityIDValidator,
     ValidatingTokenStorage,
 )
-from globus_sdk.token_storage.v2.validating_token_storage import (
+from globus_sdk.token_storage.validating_token_storage import (
     IdentityMismatchError,
     MissingIdentityError,
     MissingTokenError,