index.rst 9.88 KB
Newer Older
1
.. _astakosclient:
2

3
Component astakosclient
4
^^^^^^^^^^^^^^^^^^^^^^^
5

6
7
The Synnefo component astakosclient_ defines a
default client for the `Astakos <astakos>`_ service. It is designed to be
8
9
10
simple and minimal, hence easy to debug and test.

It uses the user's authentication token to query Astakos for:
11
12

    * User's info
13
14
    * Usernames for given UUIDs
    * UUIDs for given usernames
15
    * User's quotas
16
17
18

It can also query Astakos with another service's (Cyclades or Pithos)
authentication token for:
19

20
21
    * Usernames for given UUIDs
    * UUIDs for given usernames
22
    * Quotas for all related resources
23
24
25
    * Issue commissions
    * Get pending commissions
    * Accept or reject commissions
26

27
28
Additionally, there are options for using the `objpool
<https://github.com/grnet/objpool>`_ library to pool the http connections.
29
30
31
32
33


Basic example
=============

34
35
The ``astakosclient`` module provides the ``AstakosClient`` class. This section
demonstrates how to get user's info using ``astakosclient``.
36
37
38
39
40

.. code-block:: python

    from astakosclient import AstakosClient

41
42
43
    client = AstakosClient("UQpYas7ElzWGD5yCcEXtjw",
                           "https://accounts.example.com")
    user_info = client.get_user_info()
44
45
    print user_info['username']

46
47
Another example where we ask for the username of a user with UUID:
``b3de8eb0-3958-477e-als9-789af8dd352c``
48
49
50
51
52

.. code-block:: python

    from astakosclient import AstakosClient

53
54
55
    client = AstakosClient("UQpYas7ElzWGD5yCcEXtjw",
                           "https://accounts.example.com")
    username = client.get_username("b3de8eb0-3958-477e-als9-789af8dd352c")
56
57
58
59
60
61
    print username


Classes and functions
=====================

62
This section describes in depth the API of ``astakosclient``.
63
64
65
66

Astakos Client
--------------

67
*class* astakosclient.\ **AstakosClient(**\ token, auth_url,
68
69
retry=0, use_pool=False, pool_size=8, logger=None\ **)**

70
71
    Initialize an instance of **AstakosClient** given the Authentication Url
    *auth_url* and the Token *token*.
72
73
74
75
76
    Optionally one can specify if we are going to use a pool, the pool_size
    and the number of retries if the connection fails.

    This class provides the following methods:

77
78
79
    **get_user_info()**
        It returns a dict with the corresponding user's info. In case of
        error, it raises an AstakosClientException exception.
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

    **get_usernames(**\ uuids\ **)**
        Given a list of UUIDs it returns a uuid_catalog, that is a dictionary
        with the given UUIDs as keys and the corresponding user names as
        values.  Invalid UUIDs will not be in the dictionary.  In case of
        error, it raises an AstakosClientException exception.

    **get_username(**\ uuid\ **)**
        Given a UUID (as string) it returns the corresponding user name (as
        string).  In case of invalid UUID it raises NoUserName exception.  In
        case of error, it raises an AstakosClientException exception.

    **service_get_usernames(**\ uuids\ **)**
        Same as get_usernames but used with service tokens.

    **service_get_username(**\ uuid\ **)**
        Same as get_username but used with service tokens.

    **get_uuids(**\ display_names\ **)**
        Given a list of usernames it returns a displayname_catalog, that is a
        dictionary with the given usernames as keys and the corresponding UUIDs
        as values.  Invalid usernames will not be in the dictionary.  In case
        of error, it raises an AstakosClientException exception.

    **get_uuid(**\ display_name\ **)**
        Given a username (as string) it returns the corresponding UUID (as
        string).  In case of invalid user name it raises NoUUID exception.  In
        case of error, it raises an AstakosClientException exception.

    **service_get_uuids(**\ uuids\ **)**
        Same as get_uuids but used with service tokens.

    **service_get_uuid(**\ uuid\ **)**
        Same as get_uuid but used with service tokens.
114

115
    **get_services()**
116
117
        Return a list of dicts with the registered services.

118
119
120
    **get_resources()**
        Return a list of dicts with the available resources

121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
    **send_feedback(**\ message, data\ **)**
        Send some feedback to astakos service. Additional information about the
        service client status can be given in the data variable.  In case of
        success it returns nothing.  Otherwise it raises an
        AstakosClientException exception.

    **get_endpoints(**\ uuid=None\ **)**
        It returns the token as well as information about the token holder and
        the services he/she can access. In case of error it raises an
        AstakosClientException exception.

    **get_quotas()**
        It returns user's current quotas (as dict of dicts). In case of error
        it raises an AstakosClientException exception.

    **service_get_quotas(**\ user=None\ **)**
        It returns all users' current quotas for the resources associated with
        the service (as dict of dicts of dicts). Optionally, one can query the
        quotas of a specific user with argument user=UUID. In case of error it
        raises an AstakosClientException exception.

    **issue_commission(**\ request\ **)**
        Issue a commission. In case of success it returns commission's id
        (int). Otherwise it raises an AstakosClientException exception.

    **issue_one_commission(**\ holder, source, provisions, name="", force=False, auto_accept=False\ **)**
        Issue a commission. We have to specify the holder, the source and the
        provisions (a dict from string to int) and astakosclient will create
        the corresponding commission. In case of success it returns
        commission's id (int). Otherwise it raises an AstakosClientException
        exception.

    **get_pending_commissions()**
        It returns the pending commissions (list of integers). In case of
        error it raises an AstakosClientException exception.

    **get_commission_info(**\ serial\ **)**
        Given the id of a pending commission return a dict of dicts containting
        informations (details) about the requested commission.  In case of
        error it raises an AstakosClientException exception.

    **commission_action(**\ serial, action\ **)**
        Given the id of a pending commission, request the specified action
        (currently one of accept, reject).  In case of success it returns
        nothing.  Otherwise it raises an AstakosClientException exception.

    **accept_commission(**\ serial\ **)**
168
169
        Accept a pending commission (see commission_action).

170
    **reject_commission(**\ serial\ **)**
171
172
        Reject a pending commission (see commission_action).

173
174
175
176
177
    **resolve_commissions(**\ accept_serials, reject_serials\ **)**
        Accept or Reject many pending commissions at once.  In case of success
        return a dict of dicts describing which commissions accepted, which
        rejected and which failed to resolved. Otherwise raise an
        AstakosClientException exception.
178

179
    **get_projects(**\ name=None, state=None, owner=None\ **)**
180
181
        Retrieve all accessible projects

182
    **get_project(**\ project_id\ **)**
183
184
        Retrieve project description, if accessible

185
    **create_project(**\ specs\ **)**
186
187
        Submit application to create a new project

188
    **modify_project(**\ project_id, specs\ **)**
189
190
        Submit application to modify an existing project

191
    **project_action(**\ project_id, action, reason=""\ **)**
192
193
        Perform action on a project

194
    **get_applications(**\ project=None\ **)**
195
196
        Retrieve all accessible applications

197
    **get_application(**\ app_id\ **)**
198
199
        Retrieve application description, if accessible

200
    **application_action(**\ app_id, action, reason=""\ **)**
201
202
        Perform action on an application

203
    **get_memberships(**\ project=None\ **)**
204
205
        Retrieve all accessible memberships

206
    **get_membership(**\ memb_id\ **)**
207
208
        Retrieve membership description, if accessible

209
    **membership_action(**\ memb_id, action, reason=""\ **)**
210
211
        Perform action on a membership

212
    **join_project(**\ project_id\ **)**
213
214
        Join a project

215
    **enroll_member(**\ project_id, email\ **)**
216
        Enroll a user in a project
217
218
219
220

Public Functions
----------------

221
**get_token_from_cookie(**\ request, cookie_name\ **)**
222
223
    Given a Django request object and an Astakos cookie name
    extract the user's token from it.
224

225
226
227
228
229
**parse_endpoints(**\ endpoints, ep_name=None, ep_type=None, ep_region=None, ep_version_id=None\ **)**
    Parse the endpoints (acquired using *get_endpoints*) and extract the ones
    needed.  Return only the endpoints that match all of the given criterias.
    If no match is found then raise NoEndpoints exception.

230
231
232
233
234
235

Exceptions and Errors
=====================

*exception* **AstakosClientException**
    Raised in case of an error. It contains an error message and the
236
237
    corresponding http status code. Other exceptions raised by astakosclient
    module are derived from this one.
238
239
240
241
242

*exception* **BadValue**
    A redefinition of ValueError exception under AstakosClientException.

*exception* **InvalidResponse**
243
244
    This exception is raised whenever the server's response is not valid json
    (cannot be parsed by simplejson library).
245
246
247
248
249
250
251
252

*exception* **BadRequest**
    Raised in case of a Bad Request, with status 400.

*exception* **Unauthorized**
    Raised in case of Invalid token (unauthorized access), with status 401.

*exception* **Forbidden**
253
254
    The server understood the request, but is refusing to fulfill it. Status
    401.
255
256
257
258

*exception* **NotFound**
    The server has not found anything matching the Request-URI. Status 404.

259
260
261
*exception* **QuotaLimit**
    Quantity fell below zero or exceeded capacity in one of the holdings.

262
*exception* **NoUserName**
263
264
    Raised by getDisplayName and getServiceDisplayName when an invalid UUID was
    given.
265
266

*exception* **NoUUID**
267
268
269
270
271
272
    Raised by *getUUID* and *getServiceUUID* when an invalid username was
    given.

*exception* **NoEndpoints**
    Raised by *parse_endpoints* when no endpoints found matching the given
    criteria.