File: storage_adapters.rst

package info (click to toggle)
python-globus-sdk 3.54.0-1
  • links: PTS, VCS
  • area: main
  • in suites: forky, sid, trixie
  • size: 5,032 kB
  • sloc: python: 34,226; sh: 44; makefile: 31
file content (133 lines) | stat: -rw-r--r-- 4,083 bytes parent folder | download
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
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
.. _storage_adapters:

Storage Adapters (Legacy)
=========================

.. warning::

    The class hierarchy documented here is legacy.

    We recommend using the newer class hierarchy documented at :ref:`token_storages`.

The StorageAdapter component provides a way of storing and loading the tokens
received from authentication and token refreshes.

Usage
-----

StorageAdapter is available under the name ``globus_sdk.tokenstorage``.

Storage adapters are the main objects of this subpackage. Primarily, usage
should revolve around creating a storage adapter, potentially loading data from
it, and using it as the ``on_refresh`` handler for an authorizer.

For example:

.. code-block:: python

    import os
    import globus_sdk
    from globus_sdk.tokenstorage import SimpleJSONFileAdapter

    my_file_adapter = SimpleJSONFileAdapter(os.path.expanduser("~/mytokens.json"))

    if not my_file_adapter.file_exists():
        # ... do a login flow, getting back initial tokens
        # elided for simplicity here
        token_response = ...
        # now store the tokens, and pull out the tokens for the
        # resource server we want
        my_file_adapter.store(token_response)
        by_rs = token_response.by_resource_server
        tokens = by_rs["transfer.api.globus.org"]
    else:
        # otherwise, we already did this whole song-and-dance, so just
        # load the tokens from that file
        tokens = my_file_adapter.get_token_data("transfer.api.globus.org")


    # RereshTokenAuthorizer and ClientCredentialsAuthorizer both use
    # `on_refresh` callbacks
    # this feature is therefore only relevant for those auth types
    #
    # auth_client is the internal auth client used for refreshes,
    # and which was used in the login flow
    # note that this is all normal authorizer usage wherein
    # my_file_adapter is providing the on_refresh callback
    auth_client = ...
    authorizer = globus_sdk.RefreshTokenAuthorizer(
        tokens["refresh_token"],
        auth_client,
        access_token=tokens["access_token"],
        expires_at=tokens["expires_at_seconds"],
        on_refresh=my_file_adapter.on_refresh,
    )

    # or, for client credentials
    authorizer = globus_sdk.ClientCredentialsAuthorizer(
        auth_client,
        ["urn:globus:auth:transfer.api.globus.org:all"],
        access_token=tokens["access_token"],
        expires_at=tokens["expires_at_seconds"],
        on_refresh=my_file_adapter.on_refresh,
    )

    # and then use the authorizer on a client!
    tc = globus_sdk.TransferClient(authorizer=authorizer)


Complete Example Usage
~~~~~~~~~~~~~~~~~~~~~~

The :ref:`Group Listing With Token Storage Script <example_group_listing_with_token_storage>`
provides a complete and runnable example which leverages ``tokenstorage``.


Adapter Types
-------------

.. module:: globus_sdk.tokenstorage

``globus_sdk.tokenstorage`` provides base classes for building your own storage
adapters, and several complete adapters.

The :class:`SimpleJSONFileAdapter` is good for the "simplest possible"
persistent storage, using a JSON file to store token data.

:class:`MemoryAdapter` is even simpler still, and is great for writing and
testing code which uses the ``StorageAdapter`` interface backed by an in-memory
structure.

The :class:`SQLiteAdapter` is more complex, for applications like the
globus-cli which need to store various tokens and additional configuration. In
addition to basic token storage, the :class:`SQLiteAdapter` provides for namespacing
of the token data, and for additional configuration storage.

Reference
---------

.. autoclass:: StorageAdapter
   :members:
   :member-order: bysource
   :show-inheritance:

.. autoclass:: MemoryAdapter
   :members:
   :member-order: bysource
   :show-inheritance:

.. autoclass:: FileAdapter
   :members:
   :member-order: bysource
   :show-inheritance:

.. autoclass:: SimpleJSONFileAdapter
   :members:
   :member-order: bysource
   :show-inheritance:

.. autoclass:: SQLiteAdapter
   :members:
   :member-order: bysource
   :show-inheritance: