From 98711f3db050eda7d7367f546680930dbee4b103 Mon Sep 17 00:00:00 2001 From: Stephen Rosen Date: Thu, 17 Jul 2025 15:52:13 -0500 Subject: [PATCH 1/2] Make legacy token storage less accessible 1. Rename the `v1` subpackage to `legacy` 2. Update the top-level `globus_sdk.token_storage` interface to only list "v2" (i.e. non-legacy) interfaces 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 | 6 +-- docs/upgrading.rst | 39 +++++++++++++++++++ src/globus_sdk/token_storage/__init__.py | 17 +------- .../token_storage/{v1 => legacy}/__init__.py | 0 .../token_storage/{v1 => legacy}/base.py | 0 .../{v1 => legacy}/file_adapters.py | 0 .../{v1 => legacy}/memory_adapter.py | 0 .../{v1 => legacy}/sqlite_adapter.py | 0 .../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 +- 17 files changed, 65 insertions(+), 36 deletions(-) create mode 100644 changelog.d/20250717_154854_sirosen_bury_v1_tokenstorage.rst rename src/globus_sdk/token_storage/{v1 => legacy}/__init__.py (100%) rename src/globus_sdk/token_storage/{v1 => legacy}/base.py (100%) rename src/globus_sdk/token_storage/{v1 => legacy}/file_adapters.py (100%) rename src/globus_sdk/token_storage/{v1 => legacy}/memory_adapter.py (100%) rename src/globus_sdk/token_storage/{v1 => legacy}/sqlite_adapter.py (100%) 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..78ab5490c --- /dev/null +++ b/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`) diff --git a/docs/authorization/token_caching/storage_adapters.rst b/docs/authorization/token_caching/storage_adapters.rst index 03ccf244e..a7969250a 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.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 ` -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" diff --git a/docs/examples/group_listing.rst b/docs/examples/group_listing.rst index e218b6286..0e9ca4724 100644 --- a/docs/examples/group_listing.rst +++ b/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) diff --git a/docs/upgrading.rst b/docs/upgrading.rst index f8fbd41c3..d9da53640 100644 --- a/docs/upgrading.rst +++ b/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 ` are now only +available from ``globus_sdk.token_storage.legacy``. + +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.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 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 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/src/globus_sdk/token_storage/v1/__init__.py b/src/globus_sdk/token_storage/legacy/__init__.py similarity index 100% rename from src/globus_sdk/token_storage/v1/__init__.py rename to src/globus_sdk/token_storage/legacy/__init__.py diff --git a/src/globus_sdk/token_storage/v1/base.py b/src/globus_sdk/token_storage/legacy/base.py similarity index 100% rename from src/globus_sdk/token_storage/v1/base.py rename to src/globus_sdk/token_storage/legacy/base.py diff --git a/src/globus_sdk/token_storage/v1/file_adapters.py b/src/globus_sdk/token_storage/legacy/file_adapters.py similarity index 100% rename from src/globus_sdk/token_storage/v1/file_adapters.py rename to src/globus_sdk/token_storage/legacy/file_adapters.py diff --git a/src/globus_sdk/token_storage/v1/memory_adapter.py b/src/globus_sdk/token_storage/legacy/memory_adapter.py similarity index 100% rename from src/globus_sdk/token_storage/v1/memory_adapter.py rename to src/globus_sdk/token_storage/legacy/memory_adapter.py diff --git a/src/globus_sdk/token_storage/v1/sqlite_adapter.py b/src/globus_sdk/token_storage/legacy/sqlite_adapter.py similarity index 100% rename from src/globus_sdk/token_storage/v1/sqlite_adapter.py rename to src/globus_sdk/token_storage/legacy/sqlite_adapter.py diff --git a/tests/functional/tokenstorage/v1/test_simplejson_file.py b/tests/functional/tokenstorage/v1/test_simplejson_file.py index 371784f11..b2eb8730c 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.legacy 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..ebcaca67e 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.legacy 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..dc78b4f6b 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.legacy 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..21c505efb 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.legacy 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..9a8bd0390 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.legacy 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..fd09b238a 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.legacy 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..be0cb5cb7 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.legacy import SQLiteAdapter def test_sqlite_reading_bad_config(): From 8732e91d42bda3823d0b393d4f8b22324c68ae0d Mon Sep 17 00:00:00 2001 From: Stephen Rosen Date: Mon, 28 Jul 2025 12:54:29 -0500 Subject: [PATCH 2/2] Move 'v2' token_storage up a level All of the 'v2' entities move up one nesting level, now that the 'v1' items are renamed as 'legacy'. --- .../globus_app/authorizer_factory.py | 2 +- src/globus_sdk/globus_app/config.py | 2 +- src/globus_sdk/token_storage/__init__.py | 16 ++++----- src/globus_sdk/token_storage/{v2 => }/base.py | 0 src/globus_sdk/token_storage/{v2 => }/json.py | 0 .../token_storage/{v2 => }/memory.py | 0 .../token_storage/{v2 => }/sqlite.py | 0 .../token_storage/{v2 => }/token_data.py | 0 src/globus_sdk/token_storage/v2/__init__.py | 33 ------------------- .../validating_token_storage/__init__.py | 0 .../validating_token_storage/context.py | 0 .../validating_token_storage/errors.py | 0 .../validating_token_storage/storage.py | 0 .../validating_token_storage/validators.py | 0 .../globus_app/test_authorizer_factory.py | 2 +- .../tokenstorage/v2/test_token_storage.py | 2 +- .../v2/test_validating_token_storage.py | 2 +- 17 files changed, 12 insertions(+), 47 deletions(-) rename src/globus_sdk/token_storage/{v2 => }/base.py (100%) rename src/globus_sdk/token_storage/{v2 => }/json.py (100%) rename src/globus_sdk/token_storage/{v2 => }/memory.py (100%) rename src/globus_sdk/token_storage/{v2 => }/sqlite.py (100%) rename src/globus_sdk/token_storage/{v2 => }/token_data.py (100%) delete mode 100644 src/globus_sdk/token_storage/v2/__init__.py rename src/globus_sdk/token_storage/{v2 => }/validating_token_storage/__init__.py (100%) rename src/globus_sdk/token_storage/{v2 => }/validating_token_storage/context.py (100%) rename src/globus_sdk/token_storage/{v2 => }/validating_token_storage/errors.py (100%) rename src/globus_sdk/token_storage/{v2 => }/validating_token_storage/storage.py (100%) rename src/globus_sdk/token_storage/{v2 => }/validating_token_storage/validators.py (100%) diff --git a/src/globus_sdk/globus_app/authorizer_factory.py b/src/globus_sdk/globus_app/authorizer_factory.py index 349505777..5ed78d4ad 100644 --- a/src/globus_sdk/globus_app/authorizer_factory.py +++ b/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) diff --git a/src/globus_sdk/globus_app/config.py b/src/globus_sdk/globus_app/config.py index 22f01f3db..8c713ee1b 100644 --- a/src/globus_sdk/globus_app/config.py +++ b/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, diff --git a/src/globus_sdk/token_storage/__init__.py b/src/globus_sdk/token_storage/__init__.py index c3e4feb5e..707f0798c 100644 --- a/src/globus_sdk/token_storage/__init__.py +++ b/src/globus_sdk/token_storage/__init__.py @@ -1,14 +1,13 @@ -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, @@ -16,14 +15,13 @@ ) __all__ = ( - # "TokenStorage" Constructs "TokenStorage", "TokenStorageData", "FileTokenStorage", "JSONTokenStorage", "SQLiteTokenStorage", "MemoryTokenStorage", - # "ValidatingTokenStorage" Constructs + # TokenValidationStorage constructs "ValidatingTokenStorage", "TokenValidationContext", "TokenDataValidator", diff --git a/src/globus_sdk/token_storage/v2/base.py b/src/globus_sdk/token_storage/base.py similarity index 100% rename from src/globus_sdk/token_storage/v2/base.py rename to src/globus_sdk/token_storage/base.py diff --git a/src/globus_sdk/token_storage/v2/json.py b/src/globus_sdk/token_storage/json.py similarity index 100% rename from src/globus_sdk/token_storage/v2/json.py rename to src/globus_sdk/token_storage/json.py diff --git a/src/globus_sdk/token_storage/v2/memory.py b/src/globus_sdk/token_storage/memory.py similarity index 100% rename from src/globus_sdk/token_storage/v2/memory.py rename to src/globus_sdk/token_storage/memory.py diff --git a/src/globus_sdk/token_storage/v2/sqlite.py b/src/globus_sdk/token_storage/sqlite.py similarity index 100% rename from src/globus_sdk/token_storage/v2/sqlite.py rename to src/globus_sdk/token_storage/sqlite.py diff --git a/src/globus_sdk/token_storage/v2/token_data.py b/src/globus_sdk/token_storage/token_data.py similarity index 100% rename from src/globus_sdk/token_storage/v2/token_data.py rename to src/globus_sdk/token_storage/token_data.py diff --git a/src/globus_sdk/token_storage/v2/__init__.py b/src/globus_sdk/token_storage/v2/__init__.py deleted file mode 100644 index 707f0798c..000000000 --- a/src/globus_sdk/token_storage/v2/__init__.py +++ /dev/null @@ -1,33 +0,0 @@ -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, - NotExpiredValidator, - ScopeRequirementsValidator, - TokenDataValidator, - TokenValidationContext, - TokenValidationError, - UnchangingIdentityIDValidator, - ValidatingTokenStorage, -) - -__all__ = ( - "TokenStorage", - "TokenStorageData", - "FileTokenStorage", - "JSONTokenStorage", - "SQLiteTokenStorage", - "MemoryTokenStorage", - # TokenValidationStorage constructs - "ValidatingTokenStorage", - "TokenValidationContext", - "TokenDataValidator", - "TokenValidationError", - "HasRefreshTokensValidator", - "NotExpiredValidator", - "ScopeRequirementsValidator", - "UnchangingIdentityIDValidator", -) diff --git a/src/globus_sdk/token_storage/v2/validating_token_storage/__init__.py b/src/globus_sdk/token_storage/validating_token_storage/__init__.py similarity index 100% rename from src/globus_sdk/token_storage/v2/validating_token_storage/__init__.py rename to src/globus_sdk/token_storage/validating_token_storage/__init__.py diff --git a/src/globus_sdk/token_storage/v2/validating_token_storage/context.py b/src/globus_sdk/token_storage/validating_token_storage/context.py similarity index 100% rename from src/globus_sdk/token_storage/v2/validating_token_storage/context.py rename to src/globus_sdk/token_storage/validating_token_storage/context.py diff --git a/src/globus_sdk/token_storage/v2/validating_token_storage/errors.py b/src/globus_sdk/token_storage/validating_token_storage/errors.py similarity index 100% rename from src/globus_sdk/token_storage/v2/validating_token_storage/errors.py rename to src/globus_sdk/token_storage/validating_token_storage/errors.py diff --git a/src/globus_sdk/token_storage/v2/validating_token_storage/storage.py b/src/globus_sdk/token_storage/validating_token_storage/storage.py similarity index 100% rename from src/globus_sdk/token_storage/v2/validating_token_storage/storage.py rename to src/globus_sdk/token_storage/validating_token_storage/storage.py diff --git a/src/globus_sdk/token_storage/v2/validating_token_storage/validators.py b/src/globus_sdk/token_storage/validating_token_storage/validators.py similarity index 100% rename from src/globus_sdk/token_storage/v2/validating_token_storage/validators.py rename to src/globus_sdk/token_storage/validating_token_storage/validators.py diff --git a/tests/unit/globus_app/test_authorizer_factory.py b/tests/unit/globus_app/test_authorizer_factory.py index cb38521d9..3982d0f51 100644 --- a/tests/unit/globus_app/test_authorizer_factory.py +++ b/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, diff --git a/tests/unit/tokenstorage/v2/test_token_storage.py b/tests/unit/tokenstorage/v2/test_token_storage.py index 8b25e5548..66f8ab3d3 100644 --- a/tests/unit/tokenstorage/v2/test_token_storage.py +++ b/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( diff --git a/tests/unit/tokenstorage/v2/test_validating_token_storage.py b/tests/unit/tokenstorage/v2/test_validating_token_storage.py index f7ab0046a..d1203e960 100644 --- a/tests/unit/tokenstorage/v2/test_validating_token_storage.py +++ b/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,