root / astakosclient / docs / index.rst @ 837d85bb
History | View | Annotate | Download (9.9 kB)
1 |
.. _astakosclient: |
---|---|
2 |
|
3 |
Component astakosclient |
4 |
^^^^^^^^^^^^^^^^^^^^^^^ |
5 |
|
6 |
The Synnefo component astakosclient_ defines a |
7 |
default client for the `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("UQpYas7ElzWGD5yCcEXtjw", |
42 |
"https://accounts.example.com") |
43 |
user_info = client.get_user_info() |
44 |
print user_info['username'] |
45 |
|
46 |
Another example where we ask for the username of a user with UUID: |
47 |
``b3de8eb0-3958-477e-als9-789af8dd352c`` |
48 |
|
49 |
.. code-block:: python |
50 |
|
51 |
from astakosclient import AstakosClient |
52 |
|
53 |
client = AstakosClient("UQpYas7ElzWGD5yCcEXtjw", |
54 |
"https://accounts.example.com") |
55 |
username = client.get_username("b3de8eb0-3958-477e-als9-789af8dd352c") |
56 |
print username |
57 |
|
58 |
|
59 |
Classes and functions |
60 |
===================== |
61 |
|
62 |
This section describes in depth the API of ``astakosclient``. |
63 |
|
64 |
Astakos Client |
65 |
-------------- |
66 |
|
67 |
*class* astakosclient.\ **AstakosClient(**\ token, auth_url, |
68 |
retry=0, use_pool=False, pool_size=8, logger=None\ **)** |
69 |
|
70 |
Initialize an instance of **AstakosClient** given the Authentication Url |
71 |
*auth_url* and the Token *token*. |
72 |
Optionally one can specify if we are going to use a pool, the pool_size |
73 |
and the number of retries if the connection fails. |
74 |
|
75 |
This class provides the following methods: |
76 |
|
77 |
**get_user_info()** |
78 |
It returns a dict with the corresponding user's info. In case of |
79 |
error, it raises an AstakosClientException exception. |
80 |
|
81 |
**get_usernames(**\ uuids\ **)** |
82 |
Given a list of UUIDs it returns a uuid_catalog, that is a dictionary |
83 |
with the given UUIDs as keys and the corresponding user names as |
84 |
values. Invalid UUIDs will not be in the dictionary. In case of |
85 |
error, it raises an AstakosClientException exception. |
86 |
|
87 |
**get_username(**\ uuid\ **)** |
88 |
Given a UUID (as string) it returns the corresponding user name (as |
89 |
string). In case of invalid UUID it raises NoUserName exception. In |
90 |
case of error, it raises an AstakosClientException exception. |
91 |
|
92 |
**service_get_usernames(**\ uuids\ **)** |
93 |
Same as get_usernames but used with service tokens. |
94 |
|
95 |
**service_get_username(**\ uuid\ **)** |
96 |
Same as get_username but used with service tokens. |
97 |
|
98 |
**get_uuids(**\ display_names\ **)** |
99 |
Given a list of usernames it returns a displayname_catalog, that is a |
100 |
dictionary with the given usernames as keys and the corresponding UUIDs |
101 |
as values. Invalid usernames will not be in the dictionary. In case |
102 |
of error, it raises an AstakosClientException exception. |
103 |
|
104 |
**get_uuid(**\ display_name\ **)** |
105 |
Given a username (as string) it returns the corresponding UUID (as |
106 |
string). In case of invalid user name it raises NoUUID exception. In |
107 |
case of error, it raises an AstakosClientException exception. |
108 |
|
109 |
**service_get_uuids(**\ uuids\ **)** |
110 |
Same as get_uuids but used with service tokens. |
111 |
|
112 |
**service_get_uuid(**\ uuid\ **)** |
113 |
Same as get_uuid but used with service tokens. |
114 |
|
115 |
**get_services()** |
116 |
Return a list of dicts with the registered services. |
117 |
|
118 |
**get_resources()** |
119 |
Return a list of dicts with the available resources |
120 |
|
121 |
**send_feedback(**\ message, data\ **)** |
122 |
Send some feedback to astakos service. Additional information about the |
123 |
service client status can be given in the data variable. In case of |
124 |
success it returns nothing. Otherwise it raises an |
125 |
AstakosClientException exception. |
126 |
|
127 |
**get_endpoints(**\ uuid=None\ **)** |
128 |
It returns the token as well as information about the token holder and |
129 |
the services he/she can access. In case of error it raises an |
130 |
AstakosClientException exception. |
131 |
|
132 |
**get_quotas()** |
133 |
It returns user's current quotas (as dict of dicts). In case of error |
134 |
it raises an AstakosClientException exception. |
135 |
|
136 |
**service_get_quotas(**\ user=None\ **)** |
137 |
It returns all users' current quotas for the resources associated with |
138 |
the service (as dict of dicts of dicts). Optionally, one can query the |
139 |
quotas of a specific user with argument user=UUID. In case of error it |
140 |
raises an AstakosClientException exception. |
141 |
|
142 |
**issue_commission(**\ request\ **)** |
143 |
Issue a commission. In case of success it returns commission's id |
144 |
(int). Otherwise it raises an AstakosClientException exception. |
145 |
|
146 |
**issue_one_commission(**\ holder, source, provisions, name="", force=False, auto_accept=False\ **)** |
147 |
Issue a commission. We have to specify the holder, the source and the |
148 |
provisions (a dict from string to int) and astakosclient will create |
149 |
the corresponding commission. In case of success it returns |
150 |
commission's id (int). Otherwise it raises an AstakosClientException |
151 |
exception. |
152 |
|
153 |
**get_pending_commissions()** |
154 |
It returns the pending commissions (list of integers). In case of |
155 |
error it raises an AstakosClientException exception. |
156 |
|
157 |
**get_commission_info(**\ serial\ **)** |
158 |
Given the id of a pending commission return a dict of dicts containting |
159 |
informations (details) about the requested commission. In case of |
160 |
error it raises an AstakosClientException exception. |
161 |
|
162 |
**commission_action(**\ serial, action\ **)** |
163 |
Given the id of a pending commission, request the specified action |
164 |
(currently one of accept, reject). In case of success it returns |
165 |
nothing. Otherwise it raises an AstakosClientException exception. |
166 |
|
167 |
**accept_commission(**\ serial\ **)** |
168 |
Accept a pending commission (see commission_action). |
169 |
|
170 |
**reject_commission(**\ serial\ **)** |
171 |
Reject a pending commission (see commission_action). |
172 |
|
173 |
**resolve_commissions(**\ accept_serials, reject_serials\ **)** |
174 |
Accept or Reject many pending commissions at once. In case of success |
175 |
return a dict of dicts describing which commissions accepted, which |
176 |
rejected and which failed to resolved. Otherwise raise an |
177 |
AstakosClientException exception. |
178 |
|
179 |
**get_projects(**\ name=None, state=None, owner=None\ **)** |
180 |
Retrieve all accessible projects |
181 |
|
182 |
**get_project(**\ project_id\ **)** |
183 |
Retrieve project description, if accessible |
184 |
|
185 |
**create_project(**\ specs\ **)** |
186 |
Submit application to create a new project |
187 |
|
188 |
**modify_project(**\ project_id, specs\ **)** |
189 |
Submit application to modify an existing project |
190 |
|
191 |
**project_action(**\ project_id, action, reason=""\ **)** |
192 |
Perform action on a project |
193 |
|
194 |
**get_applications(**\ project=None\ **)** |
195 |
Retrieve all accessible applications |
196 |
|
197 |
**get_application(**\ app_id\ **)** |
198 |
Retrieve application description, if accessible |
199 |
|
200 |
**application_action(**\ app_id, action, reason=""\ **)** |
201 |
Perform action on an application |
202 |
|
203 |
**get_memberships(**\ project=None\ **)** |
204 |
Retrieve all accessible memberships |
205 |
|
206 |
**get_membership(**\ memb_id\ **)** |
207 |
Retrieve membership description, if accessible |
208 |
|
209 |
**membership_action(**\ memb_id, action, reason=""\ **)** |
210 |
Perform action on a membership |
211 |
|
212 |
**join_project(**\ project_id\ **)** |
213 |
Join a project |
214 |
|
215 |
**enroll_member(**\ project_id, email\ **)** |
216 |
Enroll a user in a project |
217 |
|
218 |
Public Functions |
219 |
---------------- |
220 |
|
221 |
**get_token_from_cookie(**\ request, cookie_name\ **)** |
222 |
Given a Django request object and an Astakos cookie name |
223 |
extract the user's token from it. |
224 |
|
225 |
**parse_endpoints(**\ endpoints, ep_name=None, ep_type=None, ep_region=None, ep_version_id=None\ **)** |
226 |
Parse the endpoints (acquired using *get_endpoints*) and extract the ones |
227 |
needed. Return only the endpoints that match all of the given criterias. |
228 |
If no match is found then raise NoEndpoints exception. |
229 |
|
230 |
|
231 |
Exceptions and Errors |
232 |
===================== |
233 |
|
234 |
*exception* **AstakosClientException** |
235 |
Raised in case of an error. It contains an error message and the |
236 |
corresponding http status code. Other exceptions raised by astakosclient |
237 |
module are derived from this one. |
238 |
|
239 |
*exception* **BadValue** |
240 |
A redefinition of ValueError exception under AstakosClientException. |
241 |
|
242 |
*exception* **InvalidResponse** |
243 |
This exception is raised whenever the server's response is not valid json |
244 |
(cannot be parsed by simplejson library). |
245 |
|
246 |
*exception* **BadRequest** |
247 |
Raised in case of a Bad Request, with status 400. |
248 |
|
249 |
*exception* **Unauthorized** |
250 |
Raised in case of Invalid token (unauthorized access), with status 401. |
251 |
|
252 |
*exception* **Forbidden** |
253 |
The server understood the request, but is refusing to fulfill it. Status |
254 |
401. |
255 |
|
256 |
*exception* **NotFound** |
257 |
The server has not found anything matching the Request-URI. Status 404. |
258 |
|
259 |
*exception* **QuotaLimit** |
260 |
Quantity fell below zero or exceeded capacity in one of the holdings. |
261 |
|
262 |
*exception* **NoUserName** |
263 |
Raised by getDisplayName and getServiceDisplayName when an invalid UUID was |
264 |
given. |
265 |
|
266 |
*exception* **NoUUID** |
267 |
Raised by *getUUID* and *getServiceUUID* when an invalid username was |
268 |
given. |
269 |
|
270 |
*exception* **NoEndpoints** |
271 |
Raised by *parse_endpoints* when no endpoints found matching the given |
272 |
criteria. |