root / astakosclient / docs / index.rst @ 25a04cdd
History | View | Annotate | Download (9.8 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, belongs_to, marker, limit\ **)** |
133 |
Given a user's authentication token, request registered |
134 |
endpoints from astakos service. If belongs_to is given (uuid) |
135 |
check that the token belongs to this user. If marker is given |
136 |
(int) return endpoints (ordered by ID) whose ID is higher than |
137 |
the marker. Limit (int) specifies the maximum number of |
138 |
endpoints to return. Return a json formatted dictionary containing |
139 |
information about registered endpoints. |
140 |
|
141 |
.. warning:: *get_endpoints* api call encodes the user's token inside |
142 |
the url. It's security unsafe to use it (both astakosclient |
143 |
and nginx tend to log requested urls). Use |
144 |
get_user_info_with_endpoints instead. |
145 |
|
146 |
**get_user_info_with_endpoints(**\ token, uuid=None\ **)** |
147 |
Fallback call which receives the user token or the user uuid/token |
148 |
and returns back the token as well as information about the token |
149 |
holder and the services he/seh can access. |
150 |
In case of error raise an AstakosClientException exception. |
151 |
|
152 |
**get_quotas(**\ token\ **)** |
153 |
Given a user's authentication token return user's |
154 |
current quotas (as dict of dicts). |
155 |
In case of error raise an AstakosClientException exception. |
156 |
|
157 |
**service_get_quotas(**\ token, user=None\ **)** |
158 |
Given a service's authentication token return all users' |
159 |
current quotas for the resources associated with the service |
160 |
(as dict of dicts of dicts). |
161 |
Optionally, one can query the quotas of a specific user with |
162 |
argument user=UUID. |
163 |
In case of error raise an AstakosClientException exception. |
164 |
|
165 |
**issue_commission(**\ token, request\ **)** |
166 |
Given a service's authentication token issue a commission. |
167 |
In case of success return commission's id (int). |
168 |
Otherwise raise an AstakosClientException exception. |
169 |
|
170 |
**issue_one_commission(**\ token, holder, source, provisions, name="", force=False, auto_accept=False\ **)** |
171 |
Given a service's authentication token issue a commission. |
172 |
In this case we specify the holder, the source and the provisions |
173 |
(a dict from string to int) and astakosclient will create the |
174 |
corresponding commission. |
175 |
In case of success return commission's id (int). |
176 |
Otherwise raise an AstakosClientException exception. |
177 |
|
178 |
**get_pending_commissions(**\ token\ **)** |
179 |
Given a service's authentication token return the pending |
180 |
commissions (list of integers). |
181 |
In case of error raise an AstakosClientException exception. |
182 |
|
183 |
**get_commission_info(**\ token, serial\ **)** |
184 |
Given a service's authentication token and the id of a |
185 |
pending commission return a dict of dicts containting |
186 |
informations (details) about the requested commission. |
187 |
In case of error raise an AstakosClientException exception. |
188 |
|
189 |
**commission_action(**\ token, serial, action\ **)** |
190 |
Given a service's authentication token and the id of a |
191 |
pending commission, request the specified action (currently |
192 |
one of accept, reject). |
193 |
In case of success returns nothing. |
194 |
Otherwise raise an AstakosClientException exception. |
195 |
|
196 |
**accept_commission(**\ token, serial\ **)** |
197 |
Accept a pending commission (see commission_action). |
198 |
|
199 |
**reject_commission(**\ token, serial\ **)** |
200 |
Reject a pending commission (see commission_action). |
201 |
|
202 |
**resolve_commissions(**\ token, accept_serials, reject_serials\ **)** |
203 |
Accept or Reject many pending commissions at once. |
204 |
In case of success return a dict of dicts describing which |
205 |
commissions accepted, which rejected and which failed to |
206 |
resolved. |
207 |
Otherwise raise an AstakosClientException exception. |
208 |
|
209 |
|
210 |
Public Functions |
211 |
---------------- |
212 |
|
213 |
**get_token_from_cookie(**\ request, cookie_name\ **)** |
214 |
Given a Django request object and an Astakos cookie name |
215 |
extract the user's token from it. |
216 |
|
217 |
|
218 |
Exceptions and Errors |
219 |
===================== |
220 |
|
221 |
*exception* **AstakosClientException** |
222 |
Raised in case of an error. It contains an error message and the |
223 |
corresponding http status code. Other exceptions raised by |
224 |
astakosclient module are derived from this one. |
225 |
|
226 |
*exception* **BadValue** |
227 |
A redefinition of ValueError exception under AstakosClientException. |
228 |
|
229 |
*exception* **InvalidResponse** |
230 |
This exception is raised whenever the server's response is not |
231 |
valid json (cannot be parsed by simplejson library). |
232 |
|
233 |
*exception* **BadRequest** |
234 |
Raised in case of a Bad Request, with status 400. |
235 |
|
236 |
*exception* **Unauthorized** |
237 |
Raised in case of Invalid token (unauthorized access), with status 401. |
238 |
|
239 |
*exception* **Forbidden** |
240 |
The server understood the request, but is refusing to fulfill it. |
241 |
Status 401. |
242 |
|
243 |
*exception* **NotFound** |
244 |
The server has not found anything matching the Request-URI. Status 404. |
245 |
|
246 |
*exception* **QuotaLimit** |
247 |
Quantity fell below zero or exceeded capacity in one of the holdings. |
248 |
|
249 |
*exception* **NoUserName** |
250 |
Raised by getDisplayName and getServiceDisplayName when an invalid |
251 |
UUID was given. |
252 |
|
253 |
*exception* **NoUUID** |
254 |
Raised by *getUUID* and *getServiceUUID* when an invalid |
255 |
username was given. |