Merge pull request SeequentEvo#97 from wordsworthc/extensible-oauth-scopes

Refactor oauth scopes

Author: wordsworthc

packages/evo-sdk-common/docs/examples/oauth.ipynb

@@ -56,12 +56,12 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "from evo.oauth import AuthorizationCodeAuthorizer, OAuthScopes\n",
+    "from evo.oauth import AuthorizationCodeAuthorizer, EvoScopes\n",
     "\n",
     "authorizer = AuthorizationCodeAuthorizer(\n",
     "    oauth_connector=connector,\n",
     "    redirect_url=REDIRECT_URL,\n",
-    "    scopes=OAuthScopes.all_evo | OAuthScopes.offline_access,\n",
+    "    scopes=EvoScopes.all_evo | EvoScopes.offline_access,\n",
     ")\n",
     "await authorizer.login()\n",
     "print(await authorizer.get_default_headers())"
@@ -105,10 +105,10 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "from evo.oauth import OAuthRedirectHandler, OAuthScopes\n",
+    "from evo.oauth import EvoScopes, OAuthRedirectHandler\n",
     "\n",
     "async with OAuthRedirectHandler(connector, REDIRECT_URL) as handler:\n",
-    "    result = await handler.login(OAuthScopes.all_evo | OAuthScopes.offline_access)\n",
+    "    result = await handler.login(EvoScopes.all_evo | EvoScopes.offline_access)\n",
     "\n",
     "print(f\"Access token: {result.access_token}\")"
    ]
@@ -129,7 +129,7 @@
    "outputs": [],
    "source": [
     "from evo.aio import AioTransport\n",
-    "from evo.oauth import ClientCredentialsAuthorizer, OAuthConnector, OAuthScopes\n",
+    "from evo.oauth import ClientCredentialsAuthorizer, EvoScopes, OAuthConnector\n",
     "\n",
     "# OAuth client app credentials\n",
     "# See: https://developer.seequent.com/docs/guides/getting-started/apps-and-tokens\n",
@@ -143,16 +143,49 @@
     "        client_id=CLIENT_ID,\n",
     "        client_secret=CLIENT_SECRET,\n",
     "    ),\n",
-    "    scopes=OAuthScopes.evo_discovery | OAuthScopes.evo_workspace,\n",
+    "    scopes=EvoScopes.evo_discovery | EvoScopes.evo_workspace,\n",
     ")\n",
     "\n",
     "print(await authorizer.get_default_headers())"
    ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Custom OAuth Scopes\n",
+    "\n",
+    "The `Scopes` type makes it easy to request custom OAuth scopes. You can combine predefined scope groups with custom scopes using the bitwise OR operator (`|`)."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from evo.oauth import EvoScopes, Scopes\n",
+    "\n",
+    "print(EvoScopes.default)  # Predefined default scopes\n",
+    "\n",
+    "# Predefined scopes can be combined with Scopes instances:\n",
+    "print(EvoScopes.default | Scopes(\"custom-scope1 custom-scope2\"))\n",
+    "\n",
+    "# Predefined scopes can be combined with str instances:\n",
+    "print(EvoScopes.default | \"custom-scope1 custom-scope2\")\n",
+    "\n",
+    "# Scopes instances can be combined with str instances:\n",
+    "print(Scopes(\"custom-scope1\") | \"custom-scope2\")\n",
+    "\n",
+    "# Combining scopes is commutative:\n",
+    "print(EvoScopes.default | \"custom-scope1 custom-scope2\")\n",
+    "print(\"custom-scope1 custom-scope2\" | EvoScopes.default)"
+   ]
   }
  ],
  "metadata": {
   "kernelspec": {
-   "display_name": "venv",
+   "display_name": "evo-sdk",
    "language": "python",
    "name": "python3"
   },

packages/evo-sdk-common/docs/examples/quickstart.ipynb

@@ -107,7 +107,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "from evo.oauth import ClientCredentialsAuthorizer, OAuthConnector, OAuthScopes\n",
+    "from evo.oauth import ClientCredentialsAuthorizer, EvoScopes, OAuthConnector\n",
     "\n",
     "CLIENT_NAME = \"Your Client Name\"\n",
     "CLIENT_ID = \"your-client-id\"\n",
@@ -119,7 +119,7 @@
     "        client_id=CLIENT_ID,\n",
     "        client_secret=CLIENT_SECRET,\n",
     "    ),\n",
-    "    scopes=OAuthScopes.all_evo,\n",
+    "    scopes=EvoScopes.all_evo,\n",
     ")\n",
     "\n",
     "# Authorize the client.\n",

packages/evo-sdk-common/docs/examples/workspace-client.ipynb

@@ -16,7 +16,7 @@
    "outputs": [],
    "source": [
     "from evo.aio import AioTransport\n",
-    "from evo.oauth import AuthorizationCodeAuthorizer, OAuthConnector, OAuthScopes\n",
+    "from evo.oauth import AuthorizationCodeAuthorizer, EvoScopes, OAuthConnector\n",
     "\n",
     "# OAuth client app credentials\n",
     "# See: https://developer.seequent.com/docs/guides/getting-started/apps-and-tokens\n",
@@ -36,7 +36,7 @@
     "authorizer = AuthorizationCodeAuthorizer(\n",
     "    oauth_connector=connector,\n",
     "    redirect_url=REDIRECT_URL,\n",
-    "    scopes=OAuthScopes.all_evo | OAuthScopes.offline_access,\n",
+    "    scopes=EvoScopes.all_evo | EvoScopes.offline_access,\n",
     ")\n",
     "\n",
     "# Login to the Evo platform.\n",

packages/evo-sdk-common/docs/oauth.md

@@ -39,12 +39,12 @@ The `OAuth` library provides authorizer classes to handle different OAuth flows.
 `AuthorizationCodeAuthorizer` is the simplest way to manage user access tokens. Logging in will open a browser window to the authorisation URL and wait for the user to authenticate and authorise the application. The `AuthorizationCodeAuthorizer` object allows the user access token to be used in API requests.
 
 ```python
-from evo.oauth import AuthorizationCodeAuthorizer, OAuthScopes
+from evo.oauth import AuthorizationCodeAuthorizer, EvoScopes
 
 authorizer = AuthorizationCodeAuthorizer(
     oauth_connector=connector,
     redirect_url=REDIRECT_URL,
-    scopes=OAuthScopes.all_evo | OAuthScopes.offline_access,
+    scopes=EvoScopes.all_evo | EvoScopes.offline_access,
 )
 await authorizer.login()
 print(await authorizer.get_default_headers())
@@ -68,10 +68,10 @@ print(f"The token was {'' if refreshed else 'not '}refreshed.")
 The `OAuthRedirectHandler` wraps the `OAuthConnector` and implements a localhost HTTP server to handle the OAuth redirect. This is useful for applications that cannot open a browser window, such as a command-line application. The `OAuthRedirectHandler` is an asynchronous context manager that manages the lifecycle of the HTTP server.
 
 ```python
-from evo.oauth import OAuthRedirectHandler, OAuthScopes
+from evo.oauth import OAuthRedirectHandler, EvoScopes
 
 async with OAuthRedirectHandler(connector, REDIRECT_URL) as handler:
-    result = await handler.login(OAuthScopes.offline_access)
+    result = await handler.login(EvoScopes.offline_access)
 
 print(f"Access token: {result.access_token}")
 ```
@@ -82,7 +82,7 @@ The `ClientCredientialsAuthorizer` allows you to handle service-to-service authe
 
 ```python
 from evo.aio import AioTransport
-from evo.oauth import ClientCredentialsAuthorizer, OAuthScopes, OAuthConnector
+from evo.oauth import ClientCredentialsAuthorizer, EvoScopes, OAuthConnector
 
 # OAuth client app credentials
 # See: https://developer.seequent.com/docs/guides/getting-started/apps-and-tokens
@@ -96,7 +96,7 @@ authorizer = ClientCredentialsAuthorizer(
         client_id=CLIENT_ID,
         client_secret=CLIENT_SECRET,
     ),
-    scopes=OAuthScopes.evo_discovery | OAuthScopes.evo_workspace,
+    scopes=EvoScopes.evo_discovery | EvoScopes.evo_workspace,
 )
 
 print(await authorizer.get_default_headers())

packages/evo-sdk-common/docs/quickstart.md

@@ -99,7 +99,7 @@ If you already have an access token, and don't need to worry about whether it's
 Alternatively, a client of `client credentials` grant type can use the `ClientCredentialsAuthorizer` for authorization into Evo. This allows for service to service requests, instead of user login and redirects.
 
 ```python
-from evo.oauth import OAuthConnector, ClientCredentialsAuthorizer, OAuthScopes
+from evo.oauth import OAuthConnector, ClientCredentialsAuthorizer, EvoScopes
 
 CLIENT_NAME = "Your Client Name"
 CLIENT_ID = "your-client-id"
@@ -111,7 +111,7 @@ authorizer = ClientCredentialsAuthorizer(
         client_id=CLIENT_ID,
         client_secret=CLIENT_SECRET,
     ),
-    scopes=OAuthScopes.all_evo,
+    scopes=EvoScopes.all_evo,
 )
 
 # Authorize the client.

packages/evo-sdk-common/pyproject.toml

@@ -1,7 +1,7 @@
 [project]
 name = "evo-sdk-common"
 description = "Python package that establishes a common framework for use by client libraries that interact with Seequent Evo APIs"
-version = "0.4.5"
+version = "0.5.0"
 requires-python = ">=3.10"
 license-files = ["LICENSE.md"]
 dynamic = ["readme"]

packages/evo-sdk-common/src/evo/notebooks/authorizer.py

@@ -96,7 +96,7 @@ def __init__(
         self,
         oauth_connector: oauth.OAuthConnector,
         redirect_url: str,
-        scopes: oauth.OAuthScopes,
+        scopes: oauth.AnyScopes,
         env: DotEnv,
     ) -> None:
         """

packages/evo-sdk-common/src/evo/notebooks/widgets.py

@@ -27,7 +27,7 @@
 from evo.common.exceptions import UnauthorizedException
 from evo.common.interfaces import IAuthorizer, ICache, IFeedback, ITransport
 from evo.discovery import Hub, Organization
-from evo.oauth import OAuthConnector, OAuthScopes
+from evo.oauth import AnyScopes, EvoScopes, OAuthConnector
 from evo.service_manager import ServiceManager
 from evo.workspaces import Workspace
 
@@ -283,7 +283,7 @@ def with_auth_code(
         redirect_url: str = DEFAULT_REDIRECT_URL,
         client_secret: str | None = None,
         cache_location: FileName = DEFAULT_CACHE_LOCATION,
-        oauth_scopes: OAuthScopes = OAuthScopes.all_evo | OAuthScopes.offline_access,
+        oauth_scopes: AnyScopes = EvoScopes.all_evo | EvoScopes.offline_access,
         proxy: StrOrURL | None = None,
     ) -> ServiceManagerWidget:
         """Create a ServiceManagerWidget with an authorization code authorizer.

packages/evo-sdk-common/src/evo/oauth/__init__.py

@@ -17,17 +17,20 @@
     ClientCredentialsAuthorizer,
 )
 from .connector import OAuthConnector
-from .data import AccessToken, OAuthScopes
+from .data import AccessToken, AnyScopes, EvoScopes, OAuthScopes, Scopes
 from .exceptions import OAuthError
 from .oauth_redirect_handler import OAuthRedirectHandler
 
 __all__ = [
     "AccessToken",
     "AccessTokenAuthorizer",
+    "AnyScopes",
     "AuthorizationCodeAuthorizer",
     "ClientCredentialsAuthorizer",
+    "EvoScopes",
     "OAuthConnector",
     "OAuthError",
     "OAuthRedirectHandler",
     "OAuthScopes",
+    "Scopes",
 ]

packages/evo-sdk-common/src/evo/oauth/authorizer.py

@@ -19,7 +19,7 @@
 from evo.common.interfaces import IAuthorizer
 
 from .connector import OAuthConnector
-from .data import AccessToken, OAuthScopes
+from .data import AccessToken, AnyScopes, EvoScopes, Scopes
 from .exceptions import OAuthError
 from .oauth_redirect_handler import OAuthRedirectHandler
 
@@ -37,7 +37,7 @@
 class _BaseAuthorizer(IAuthorizer, Generic[T]):
     pi_partial_implementation = True  # Suppress warning about missing interface methods.
 
-    def __init__(self, oauth_connector: OAuthConnector, scopes: OAuthScopes = OAuthScopes.default) -> None:
+    def __init__(self, oauth_connector: OAuthConnector, scopes: AnyScopes = EvoScopes.default) -> None:
         """
         :param oauth_connector: The connector to use for fetching tokens.
         :param scopes: The OAuth scopes to request.
@@ -46,9 +46,7 @@ def __init__(self, oauth_connector: OAuthConnector, scopes: OAuthScopes = OAuthS
 
         self._connector = oauth_connector
         self.__token: T | None = None
-
-        assert isinstance(scopes, OAuthScopes), "Scopes must be an instance of OAuthScopes."
-        self._scopes: OAuthScopes = scopes
+        self._scopes = Scopes(scopes)
 
     def _get_token(self) -> T | None:
         """Get the current access token, or None if the token is not available.
@@ -114,7 +112,7 @@ async def _fetch_token(self) -> AccessToken:
         """
         data = {  # The payload to send to the OAuth server in the token request.
             "grant_type": "client_credentials",
-            "scope": str(self._scopes),
+            "scope": self._scopes,
         }
 
         logger.debug("Fetching access token...")
@@ -167,7 +165,7 @@ class AuthorizationCodeAuthorizer(_BaseAuthorizer[AccessToken]):
     """
 
     def __init__(
-        self, oauth_connector: OAuthConnector, redirect_url: str, scopes: OAuthScopes = OAuthScopes.default
+        self, oauth_connector: OAuthConnector, redirect_url: str, scopes: AnyScopes = EvoScopes.default
     ) -> None:
         """
         :param oauth_connector: The OAuth connector to use for fetching tokens.