.. _scopes: Scopes and ScopeBuilders ======================== OAuth2 Scopes for various Globus services are represented by ``ScopeBuilder`` objects. A number of pre-set scope builders are provided and populated with useful data, and they are also accessible via the relevant client classes. Direct Use (as constants) ------------------------- To use the scope builders directly, import from ``globus_sdk.scopes``. For example, one might use the Transfer "all" scope during a login flow like so: .. code-block:: python import globus_sdk from globus_sdk.scopes import TransferScopes CLIENT_ID = "" client = globus_sdk.NativeAppAuthClient(CLIENT_ID) client.oauth2_start_flow(requested_scopes=[TransferScopes.all]) ... As Client Class Attributes -------------------------- Because the scopes for a token are associated with some concrete client which will use that token, it makes sense to associate a scope with a client class. The Globus SDK does this by providing the ``ScopeBuilder`` for a service as an attribute of the client. For example, .. code-block:: python import globus_sdk CLIENT_ID = "" client = globus_sdk.NativeAppAuthClient(CLIENT_ID) client.oauth2_start_flow(requested_scopes=[globus_sdk.TransferClient.scopes.all]) ... # or, potentially, after there is a concrete client _tc = globus_sdk.TransferClient() client.oauth2_start_flow(requested_scopes=[_tc.scopes.all]) Using a Scope Builder to Get Matching Tokens -------------------------------------------- A ``ScopeBuilder`` contains the resource server name used to get token data from a token response. To elaborate on the above example: .. code-block:: python import globus_sdk from globus_sdk.scopes import TransferScopes CLIENT_ID = "" client = globus_sdk.NativeAppAuthClient(CLIENT_ID) client.oauth2_start_flow(requested_scopes=[TransferScopes.all]) authorize_url = client.oauth2_get_authorize_url() print("Please go to this URL and login:", authorize_url) auth_code = input("Please enter the code you get after login here: ").strip() token_response = client.oauth2_exchange_code_for_tokens(auth_code) # use the `resource_server` of a ScopeBuilder to grab the associated token # data from the response tokendata = token_response.by_resource_server[TransferScopes.resource_server] MutableScope objects -------------------- In order to support optional and dependent scopes, an additional type is provided by ``globus_sdk.scopes``: the ``MutableScope`` class. ``MutableScope`` can be constructed directly, from full scope strings, or via a ``ScopeBuilder``'s ``make_mutable`` method, given a scope's short name. For example, one can create a ``MutableScope`` from the Groups "all" scope as follows: .. code-block:: python from globus_sdk.scopes import GroupsScopes scope = GroupsScopes.make_mutable("all") MutableScopes provide the most value when handling scope dependencies. For example, given a Globus Connect Server Mapped Collection, it may be desirable to construct a "data_access" scope as an optional dependency for the Transfer Scope. To do so, one first creates the mutable scope object, then adds the dependency to it: .. code-block:: python from globus_sdk.scopes import GCSCollectionScopeBuilder, TransferScopes MAPPED_COLLECTION_ID = "...ID HERE..." transfer_scope = TransferScopes.make_mutable("all") transfer_scope.add_dependency( GCSCollectionScopeBuilder(MAPPED_COLLECTION_ID).data_access, optional=True ) ``MutableScope``\s can be used in most of the same locations where scope strings can be used, but you can also call ``str()`` on them to get a stringified representation. ScopeBuilder Types and Constants -------------------------------- .. autoclass:: globus_sdk.scopes.ScopeBuilder :members: :show-inheritance: .. autoclass:: globus_sdk.scopes.GCSEndpointScopeBuilder :members: :show-inheritance: .. autoclass:: globus_sdk.scopes.GCSCollectionScopeBuilder :members: :show-inheritance: .. autoclass:: globus_sdk.scopes.MutableScope :members: :show-inheritance: .. autodata:: globus_sdk.scopes.AuthScopes :annotation: .. autodata:: globus_sdk.scopes.GroupsScopes :annotation: .. autodata:: globus_sdk.scopes.NexusScopes :annotation: .. autodata:: globus_sdk.scopes.SearchScopes :annotation: .. autodata:: globus_sdk.scopes.TransferScopes :annotation: