Statistics
| Branch: | Tag: | Revision:

root / astakosclient / docs / index.rst @ 47bb45c0

History | View | Annotate | Download (10.3 kB)

1
.. _astakosclient:
2

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

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

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

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

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

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

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

    
30

    
31
Basic example
32
=============
33

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

    
37
.. code-block:: python
38

    
39
    from astakosclient import AstakosClient
40

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

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

    
48
.. code-block:: python
49

    
50
    from astakosclient import AstakosClient
51

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

    
57

    
58
Classes and functions
59
=====================
60

    
61
This section describes in depth the API of ``astakosclient``.
62

    
63
Astakos Client
64
--------------
65

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

    
69
    Initialize an instance of **AstakosClient** given the *astakos_url*.
70
    Optionally one can specify if we are going to use a pool, the pool_size
71
    and the number of retries if the connection fails.
72

    
73
    This class provides the following methods:
74

    
75
    **get_user_info(**\ token, usage=False\ **)**
76
        Given a user's authentication token it returns a dict with the
77
        correspoinding user's info. If usage is set to True more
78
        information about user's resources will be returned.
79
        In case of error raise an AstakosClientException exception.
80

    
81
    **get_usernames(**\ token, uuids\ **)**
82
        Given a user's authentication token and a list of UUIDs
83
        return a uuid_catalog, that is a dictionary with the given
84
        UUIDs as keys and the corresponding user names as values.
85
        Invalid UUIDs will not be in the dictionary.
86
        In case of error raise an AstakosClientException exception.
87

    
88
    **get_username(**\ token, uuid\ **)**
89
        Given a user's authentication token and a UUID (as string)
90
        return the corresponding user name (as string).
91
        In case of invalid UUID raise NoUserName exception.
92
        In case of error raise an AstakosClientException exception.
93

    
94
    **service_get_usernames(**\ token, uuids\ **)**
95
        Same as get_usernames but called with a service's token.
96

    
97
    **service_get_username(**\ token, uuid\ **)**
98
        Same as get_username but called with a service's token.
99

    
100
    **get_uuids(**\ token, display_names\ **)**
101
        Given a user's authentication token and a list of usernames
102
        return a displayname_catalog, that is a dictionary with the given
103
        usernames as keys and the corresponding UUIDs as values.
104
        Invalid usernames will not be in the dictionary.
105
        In case of error raise an AstakosClientException exception.
106

    
107
    **get_uuid(**\ token, display_name\ **)**
108
        Given a user's authentication token and a username (as string)
109
        return the corresponding UUID (as string).
110
        In case of invalid user name raise NoUUID exception.
111
        In case of error raise an AstakosClientException exception.
112

    
113
    **service_get_uuids(**\ token, uuids\ **)**
114
        Same as get_uuids but called with a service's token.
115

    
116
    **service_get_uuid(**\ token, uuid\ **)**
117
        Same as get_uuid but called with a service's token.
118

    
119
    **get_services()**
120
        Return a list of dicts with the registered services.
121

    
122
    **get_resources()**
123
        Return a list of dicts with the available resources
124

    
125
    **send_feedback(**\ token, message, data\ **)**
126
        Using a user's authentication token send some feedback to
127
        astakos service. Additional information about the service
128
        client status can be given in the data variable.
129
        In case of success returns nothing.
130
        Otherwise raise an AstakosClientException exception.
131

    
132
    **get_endpoints(**\ token, uuid=None\ **)**
133
        Fallback call which receives the user token or the user uuid/token
134
        and returns back the token as well as information about the token
135
        holder and the services he/seh can access.
136
        In case of error raise an AstakosClientException exception.
137

    
138
    **get_quotas(**\ token\ **)**
139
        Given a user's authentication token return user's
140
        current quotas (as dict of dicts).
141
        In case of error raise an AstakosClientException exception.
142

    
143
    **service_get_quotas(**\ token, user=None\ **)**
144
        Given a service's authentication token return all users'
145
        current quotas for the resources associated with the service
146
        (as dict of dicts of dicts).
147
        Optionally, one can query the quotas of a specific user with
148
        argument user=UUID.
149
        In case of error raise an AstakosClientException exception.
150

    
151
    **issue_commission(**\ token, request\ **)**
152
        Given a service's authentication token issue a commission.
153
        In case of success return commission's id (int).
154
        Otherwise raise an AstakosClientException exception.
155

    
156
    **issue_one_commission(**\ token, holder, source, provisions, name="", force=False, auto_accept=False\ **)**
157
        Given a service's authentication token issue a commission.
158
        In this case we specify the holder, the source and the provisions
159
        (a dict from string to int) and astakosclient will create the
160
        corresponding commission.
161
        In case of success return commission's id (int).
162
        Otherwise raise an AstakosClientException exception.
163

    
164
    **get_pending_commissions(**\ token\ **)**
165
        Given a service's authentication token return the pending
166
        commissions (list of integers).
167
        In case of error raise an AstakosClientException exception.
168

    
169
    **get_commission_info(**\ token, serial\ **)**
170
        Given a service's authentication token and the id of a
171
        pending commission return a dict of dicts containting
172
        informations (details) about the requested commission.
173
        In case of error raise an AstakosClientException exception.
174

    
175
    **commission_action(**\ token, serial, action\ **)**
176
        Given a service's authentication token and the id of a
177
        pending commission, request the specified action (currently
178
        one of accept, reject).
179
        In case of success returns nothing.
180
        Otherwise raise an AstakosClientException exception.
181

    
182
    **accept_commission(**\ token, serial\ **)**
183
        Accept a pending commission (see commission_action).
184

    
185
    **reject_commission(**\ token, serial\ **)**
186
        Reject a pending commission (see commission_action).
187

    
188
    **resolve_commissions(**\ token, accept_serials, reject_serials\ **)**
189
        Accept or Reject many pending commissions at once.
190
        In case of success return a dict of dicts describing which
191
        commissions accepted, which rejected and which failed to
192
        resolved.
193
        Otherwise raise an AstakosClientException exception.
194

    
195
    **get_projects(**\ token, name=None, state=None, owner=None\ **)**
196
        Retrieve all accessible projects
197

    
198
    **get_project(**\ token, project_id\ **)**
199
        Retrieve project description, if accessible
200

    
201
    **create_project(**\ token, specs\ **)**
202
        Submit application to create a new project
203

    
204
    **modify_project(**\ token, project_id, specs\ **)**
205
        Submit application to modify an existing project
206

    
207
    **project_action(**\ token, project_id, action, reason=""\ **)**
208
        Perform action on a project
209

    
210
    **get_applications(**\ token, project=None\ **)**
211
        Retrieve all accessible applications
212

    
213
    **get_application(**\ token, app_id\ **)**
214
        Retrieve application description, if accessible
215

    
216
    **application_action(**\ token, app_id, action, reason=""\ **)**
217
        Perform action on an application
218

    
219
    **get_memberships(**\ token, project=None\ **)**
220
        Retrieve all accessible memberships
221

    
222
    **get_membership(**\ token, memb_id\ **)**
223
        Retrieve membership description, if accessible
224

    
225
    **membership_action(**\ token, memb_id, action, reason=""\ **)**
226
        Perform action on a membership
227

    
228
    **join_project(**\ token, project_id\ **)**
229
        Join a project
230

    
231
    **enroll_member(**\ token, project_id, email\ **)**
232
        Enroll a user in a project
233

    
234
Public Functions
235
----------------
236

    
237
**get_token_from_cookie(**\ request, cookie_name\ **)**
238
    Given a Django request object and an Astakos cookie name
239
    extract the user's token from it.
240

    
241

    
242
Exceptions and Errors
243
=====================
244

    
245
*exception* **AstakosClientException**
246
    Raised in case of an error. It contains an error message and the
247
    corresponding http status code. Other exceptions raised by
248
    astakosclient module are derived from this one.
249

    
250
*exception* **BadValue**
251
    A redefinition of ValueError exception under AstakosClientException.
252

    
253
*exception* **InvalidResponse**
254
    This exception is raised whenever the server's response is not
255
    valid json (cannot be parsed by simplejson library).
256

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

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

    
263
*exception* **Forbidden**
264
    The server understood the request, but is refusing to fulfill it.
265
    Status 401.
266

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

    
270
*exception* **QuotaLimit**
271
    Quantity fell below zero or exceeded capacity in one of the holdings.
272

    
273
*exception* **NoUserName**
274
    Raised by getDisplayName and getServiceDisplayName when an invalid
275
    UUID was given.
276

    
277
*exception* **NoUUID**
278
    Raised by *getUUID* and *getServiceUUID* when an invalid
279
    username was given.