1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
|
.. _scopes:
.. currentmodule:: globus_sdk.scopes
Scopes
======
The SDK provides a ``Scope`` object which is the class model for a scope.
``Scope``\s 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
:meth:`ScopeParser.parse`.
For example, one can create a ``Scope`` object for the OIDC ``openid`` scope:
.. code-block:: python
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:
.. code-block:: python
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)
``Scope``\s 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:
.. code-block:: pycon
>>> 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
~~~~~~~~~
.. autoclass:: Scope
:members:
:member-order: bysource
|
