From 0bce3fe3b9414d07fbefd4e32074f71cf0f3c133 Mon Sep 17 00:00:00 2001 From: Stephen Rosen Date: Thu, 17 Jul 2025 15:52:13 -0500 Subject: [PATCH] Make 'v1' token storage less accessible This is a small internal change which reduces the size of the ``globus_sdk.token_storage`` top-level interface. It has impact on code completions and the general developer experience when using these legacy tools. A new section is added to the upgrading guide on the changes in names (not previously covered). --- ...17_154854_sirosen_bury_v1_tokenstorage.rst | 8 ++++ .../token_caching/storage_adapters.rst | 15 ++----- docs/examples/group_listing.rst | 4 +- docs/upgrading.rst | 39 +++++++++++++++++++ src/globus_sdk/token_storage/__init__.py | 17 +------- .../tokenstorage/v1/test_simplejson_file.py | 2 +- .../functional/tokenstorage/v1/test_sqlite.py | 2 +- .../tokenstorage/v2/test_json_tokenstorage.py | 3 +- .../v2/test_sqlite_tokenstorage.py | 3 +- .../tokenstorage/v1/test_memory_adapter.py | 2 +- .../v1/test_simplejson_adapter.py | 2 +- .../tokenstorage/v1/test_sqlite_adapter.py | 2 +- 12 files changed, 64 insertions(+), 35 deletions(-) create mode 100644 changelog.d/20250717_154854_sirosen_bury_v1_tokenstorage.rst diff --git a/changelog.d/20250717_154854_sirosen_bury_v1_tokenstorage.rst b/changelog.d/20250717_154854_sirosen_bury_v1_tokenstorage.rst new file mode 100644 index 000000000..0e16c27ea --- /dev/null +++ b/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`) diff --git a/docs/authorization/token_caching/storage_adapters.rst b/docs/authorization/token_caching/storage_adapters.rst index 03ccf244e..55fd0b211 100644 --- a/docs/authorization/token_caching/storage_adapters.rst +++ b/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 ` -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" diff --git a/docs/examples/group_listing.rst b/docs/examples/group_listing.rst index e218b6286..6606abeac 100644 --- a/docs/examples/group_listing.rst +++ b/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) diff --git a/docs/upgrading.rst b/docs/upgrading.rst index 88232b9fb..6ee575c7e 100644 --- a/docs/upgrading.rst +++ b/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 ` are now only +available from ``globus_sdk.token_storage.v1``. + +Therefore, usages of the modern :ref:`token storage interface ` +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 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/src/globus_sdk/token_storage/__init__.py b/src/globus_sdk/token_storage/__init__.py index 2f6a81e07..c3e4feb5e 100644 --- a/src/globus_sdk/token_storage/__init__.py +++ b/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", diff --git a/tests/functional/tokenstorage/v1/test_simplejson_file.py b/tests/functional/tokenstorage/v1/test_simplejson_file.py index 371784f11..0343fb241 100644 --- a/tests/functional/tokenstorage/v1/test_simplejson_file.py +++ b/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" diff --git a/tests/functional/tokenstorage/v1/test_sqlite.py b/tests/functional/tokenstorage/v1/test_sqlite.py index 95361b5cf..aac50828b 100644 --- a/tests/functional/tokenstorage/v1/test_sqlite.py +++ b/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 diff --git a/tests/functional/tokenstorage/v2/test_json_tokenstorage.py b/tests/functional/tokenstorage/v2/test_json_tokenstorage.py index b383cf862..b37b4f20b 100644 --- a/tests/functional/tokenstorage/v2/test_json_tokenstorage.py +++ b/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" diff --git a/tests/functional/tokenstorage/v2/test_sqlite_tokenstorage.py b/tests/functional/tokenstorage/v2/test_sqlite_tokenstorage.py index 552f3a2d1..d907739c5 100644 --- a/tests/functional/tokenstorage/v2/test_sqlite_tokenstorage.py +++ b/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 diff --git a/tests/unit/tokenstorage/v1/test_memory_adapter.py b/tests/unit/tokenstorage/v1/test_memory_adapter.py index 9402eaaac..1062a7662 100644 --- a/tests/unit/tokenstorage/v1/test_memory_adapter.py +++ b/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(): diff --git a/tests/unit/tokenstorage/v1/test_simplejson_adapter.py b/tests/unit/tokenstorage/v1/test_simplejson_adapter.py index 88d35d28c..e27b41d77 100644 --- a/tests/unit/tokenstorage/v1/test_simplejson_adapter.py +++ b/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): diff --git a/tests/unit/tokenstorage/v1/test_sqlite_adapter.py b/tests/unit/tokenstorage/v1/test_sqlite_adapter.py index d7740af05..77bb124c4 100644 --- a/tests/unit/tokenstorage/v1/test_sqlite_adapter.py +++ b/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():