Scopes

The SDK provides a Scope object which is the class model for a scope. Scopes can be parsed from strings and serialized to strings, and support programmatic manipulations to describe dependent scopes.

Scope can be constructed using its initializer, via Scope.parse, or via ScopeParser.parse().

For example, one can create a Scope object for the OIDC openid scope:

from globus_sdk.scopes import Scope

openid_scope = Scope("openid")

Scope objects primarily provide three main pieces of functionality:

• deserializing (parsing a single scope)

• serializing (stringifying)

• scope tree construction

Tree Construction

Scope objects provide a tree-like interface for constructing scopes and their dependencies. Because Scope objects are immutable, trees are constructed by building new scopes.

For example, the transfer scope dependent upon a collection scope may be constructed by means of Scope methods thusly:

from globus_sdk.scopes import GCSCollectionScopeBuilder, TransferScopes, Scope

MAPPED_COLLECTION_ID = "...ID HERE..."

# create the scope object, and get the data_access_scope as a string
data_access_scope = GCSCollectionScopeBuilder(MAPPED_COLLECTION_ID).data_access
# add data_access as an optional dependency
transfer_scope = TransferScopes.all.with_dependency(data_access_scope, optional=True)

Scopes can be used in most of the same locations where scope strings can be used, but you can also call str(scope) to get a stringified representation.

Serializing Scopes

Whenever scopes are being sent to Globus services, they need to be encoded as strings. All scope objects support this by means of their defined __str__ method. For example, the following is an example of str() and repr() usage:

>>> from globus_sdk.scopes import Scope
>>> foo = Scope("foo")
>>> bar = Scope("bar")
>>> bar = bar.with_dependency(Scope("baz"))
>>> foo = foo.with_dependency(bar)
>>> print(str(foo))
foo[bar[baz]]
>>> print(str(bar))
bar[baz]
>>> alpha = Scope("alpha")
>>> alpha = alpha.with_dependency("beta", optional=True)
>>> print(str(alpha))
alpha[*beta]
>>> print(repr(alpha))
Scope("alpha", dependencies=[Scope("beta", optional=True)])

Reference

class globus_sdk.scopes.Scope(scope_string, optional=False, dependencies=())

A scope object is a representation of a scope and its dynamic dependencies (other scopes).

A scope may be optional (also referred to as “atomically revocable”). An optional scope can be revoked without revoking consent for other scopes which were granted at the same time.

Scopes are immutable, and provide several evolver methods which produce new Scopes. In particular, with_dependency and with_dependencies create new scopes with added dependencies.

str(Scope(...)) produces a valid scope string for use in various methods.

Parameters:

• scope_string (str) – The string which will be used as the basis for this Scope

• optional (bool) – The scope may be marked as optional. This means that the scope can be declined by the user without declining consent for other scopes.

classmethod parse(scope_string)

Deserialize a scope string to a scope object.

This is the special case of parsing in which exactly one scope must be returned by the parse. If more than one scope is returned by the parse, a ValueError will be raised.

Parameters:

scope_string (str) – The string to parse

Return type:

Scope

with_dependency(other_scope)

Create a new scope with a dependency. The dependent scope relationship will be stored in the Scope and will be evident in its string representation.

Parameters:

other_scope (Scope) – The scope upon which the current scope depends.

Return type:

Scope

with_dependencies(other_scopes)

Create a new scope with added dependencies. The dependent scope relationships will be stored in the Scope and will be evident in its string representation.

Parameters:

other_scopes (Iterable[Scope]) – The scopes upon which the current scope depends.

Return type:

Scope

with_optional(optional)

Create a new scope with a different ‘optional’ value.

Parameters:

optional (bool) – Whether or not the scope is optional.

Return type:

Scope