Make 'v1' token storage less accessible

changelog.d/20250717_154854_sirosen_bury_v1_tokenstorage.rst

@@ -0,0 +1,8 @@
+Changed
+-------
+
+- The legacy "v1" token storage adapters are now only available from the
+  ``globus_sdk.token_storage.v1`` subpackage.
+
+  Users are encouraged to migrate to the newer tooling available 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.v1``.
 
 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.v1 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.v1
 
-``globus_sdk.token_storage`` provides base classes for building your own storage
+``globus_sdk.token_storage.v1`` 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,7 +62,7 @@ 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
+``globus_sdk.token_storage.v1`` 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.v1 import SimpleJSONFileAdapter
 
     CLIENT_ID = "61338d24-54d5-408f-a10d-66c06b59f6d2"
     AUTH_CLIENT = NativeAppAuthClient(CLIENT_ID)

docs/upgrading.rst

@@ -232,6 +232,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.v1``.
+
+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.v1 import SimpleJSONFileAdapter
+
+.. note::
+
+    The v1 or "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/token_storage/__init__.py

@@ -1,10 +1,3 @@
-from .v1 import (
-    FileAdapter,
-    MemoryAdapter,
-    SimpleJSONFileAdapter,
-    SQLiteAdapter,
-    StorageAdapter,
-)
 from .v2 import (
     FileTokenStorage,
     HasRefreshTokensValidator,
@@ -23,20 +16,14 @@
 )
 
 __all__ = (
-    # [v1] "StorageAdapter" Constructs
-    "StorageAdapter",
-    "FileAdapter",
-    "SimpleJSONFileAdapter",
-    "SQLiteAdapter",
-    "MemoryAdapter",
-    # [v2] "TokenStorage" Constructs
+    # "TokenStorage" Constructs
     "TokenStorage",
     "TokenStorageData",
     "FileTokenStorage",
     "JSONTokenStorage",
     "SQLiteTokenStorage",
     "MemoryTokenStorage",
-    # [v2] "ValidatingTokenStorage" Constructs
+    # "ValidatingTokenStorage" 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.v1 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.v1 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.v1 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.v1 import SQLiteAdapter
 
 
 @pytest.fixture

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.v1 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.v1 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.v1 import SQLiteAdapter
 
 
 def test_sqlite_reading_bad_config():