Promote consents from 'experimental'

The consents module is moved to `globus_sdk.scopes.consents`, and docs
are updated as appropriate.

A getattr-based rename module, with deprecation warnings, is added to
`experimental`.

changelog.d/20240910_103438_sirosen_move_consents.rst

@@ -0,0 +1,5 @@
+Changed
+~~~~~~~
+
+- Consent object models have been moved from
+  ``globus_sdk.experimental.consents`` into ``globus_sdk.scopes.consents``. (:pr:`NUMBER`)

docs/experimental/consents.rst → docs/authorization/scopes_and_consents/consents.rst

@@ -1,5 +1,5 @@
 
-.. py:currentmodule:: globus_sdk.experimental.consents
+.. py:currentmodule:: globus_sdk.scopes.consents
 
 Consents
 ========
@@ -12,6 +12,23 @@ Consents are modeled as a ``ConsentForest`` full of ``ConsentTrees`` containing
 provided by a user to client applications for token grants under certain scoped
 contexts.
 
+Consent objects are provided from ``globus_sdk.scopes.consents``.
+
+They are typically produced by calling
+:meth:`globus_sdk.AuthClient.get_consents` and invoking ``to_forest()`` on
+the response. Example usage:
+
+.. code-block:: python
+
+    import globus_sdk
+    from globus_sdk.scopes.consents import ConsentForest
+
+    my_identity_id = ...
+    client = globus_sdk.AuthClient(...)
+    response = client.get_consents(my_identity_id)
+
+    consent_forest: ConsentForest = response.to_forest()
+
 Reference
 =========
 

docs/authorization/scopes_and_consents/index.rst

@@ -31,3 +31,4 @@ which make learning about and manipulating these data easier.
 
     scopes
     mutable_scopes
+    consents

docs/experimental/index.rst

@@ -16,7 +16,6 @@ Globus SDK Experimental Components
 
     auth_requirements_errors
     scope_parser
-    consents
     globus_app
 
 

src/globus_sdk/experimental/consents.py

@@ -0,0 +1,39 @@
+from __future__ import annotations
+
+import sys
+import typing as t
+
+__all__ = (
+    "Consent",
+    "ConsentTree",
+    "ConsentForest",
+    "ConsentParseError",
+    "ConsentTreeConstructionError",
+)
+
+# legacy aliases
+# (when accessed, these will emit deprecation warnings in a future release)
+if t.TYPE_CHECKING:
+    from globus_sdk.scopes.consents import (
+        Consent,
+        ConsentForest,
+        ConsentParseError,
+        ConsentTree,
+        ConsentTreeConstructionError,
+    )
+else:
+
+    def __getattr__(name: str) -> t.Any:
+        import globus_sdk.scopes.consents as consents_module
+        from globus_sdk.exc import warn_deprecated
+
+        warn_deprecated(
+            "'globus_sdk.experimental.consents' has been renamed to "
+            "'globus_sdk.scopes.consents'. "
+            f"Importing '{name}' from `globus_sdk.experimental` is deprecated."
+        )
+        value = getattr(consents_module, name, None)
+        if value is None:
+            raise AttributeError(f"module {__name__} has no attribute {name}")
+        setattr(sys.modules[__name__], name, value)
+        return value

src/globus_sdk/experimental/globus_app/_validating_token_storage.py

@@ -3,8 +3,8 @@
 import typing as t
 
 from globus_sdk import AuthClient, Scope
-from globus_sdk.experimental.consents import ConsentForest
 from globus_sdk.experimental.tokenstorage import TokenData, TokenStorage
+from globus_sdk.scopes.consents import ConsentForest
 
 from ..._types import UUIDLike
 from .errors import (

src/globus_sdk/experimental/consents/__init__.py → src/globus_sdk/scopes/consents/__init__.py

@@ -1,10 +1,10 @@
 from ._errors import ConsentParseError, ConsentTreeConstructionError
 from ._model import Consent, ConsentForest, ConsentTree
 
-__all__ = [
+__all__ = (
     "Consent",
     "ConsentTree",
     "ConsentForest",
     "ConsentParseError",
     "ConsentTreeConstructionError",
-]
+)

src/globus_sdk/experimental/consents/_model.py → src/globus_sdk/scopes/consents/_model.py

@@ -30,9 +30,9 @@
 from dataclasses import dataclass
 from datetime import datetime
 
-from globus_sdk import Scope
 from globus_sdk._types import UUIDLike
 
+from ..representation import Scope
 from ._errors import ConsentParseError, ConsentTreeConstructionError
 
 

src/globus_sdk/services/auth/response/consents.py

@@ -1,5 +1,5 @@
 from globus_sdk import IterableResponse
-from globus_sdk.experimental.consents import ConsentForest
+from globus_sdk.scopes.consents import ConsentForest
 
 
 class GetConsentsResponse(IterableResponse):
@@ -17,9 +17,5 @@ def to_forest(self) -> ConsentForest:
 
         ConsentForest is a convenience class to make interacting with the
             tree of consents simpler.
-
-        Note:
-            This interface relies on the experimental Consents data model which is
-                subject to change.
         """
         return ConsentForest(self)

tests/common/consents.py

@@ -7,7 +7,7 @@
 
 from globus_sdk import Scope
 from globus_sdk._types import UUIDLike
-from globus_sdk.experimental.consents import Consent, ConsentForest
+from globus_sdk.scopes.consents import Consent, ConsentForest
 
 ScopeRepr = namedtuple("Scope", ["id", "name"])
 

tests/unit/experimental/globus_app/test_validating_token_storage.py

@@ -9,7 +9,6 @@
 
 import globus_sdk
 from globus_sdk import MISSING, MissingType, OAuthTokenResponse, Scope
-from globus_sdk.experimental.consents import ConsentForest
 from globus_sdk.experimental.globus_app import ValidatingTokenStorage
 from globus_sdk.experimental.globus_app.errors import (
     IdentityMismatchError,
@@ -18,6 +17,7 @@
     UnmetScopeRequirementsError,
 )
 from globus_sdk.experimental.tokenstorage import MemoryTokenStorage
+from globus_sdk.scopes.consents import ConsentForest
 from tests.common import make_consent_forest
 
 

tests/unit/services/auth/test_consents.py → tests/unit/scopes/test_consents.py

@@ -5,7 +5,7 @@
 
 import pytest
 
-from globus_sdk.experimental.consents import ConsentForest, ConsentTreeConstructionError
+from globus_sdk.scopes.consents import ConsentForest, ConsentTreeConstructionError
 from tests.common import ConsentTest, ScopeRepr
 
 _zero_uuid = str(UUID(int=0))