root / astakosclient / docs / index.rst @ 1ce2918c
History | View | Annotate | Download (9.8 kB)
1 | fa7a3ca1 | Ilias Tsitsimpis | .. _astakosclient: |
---|---|---|---|
2 | 1acf67a7 | Ilias Tsitsimpis | |
3 | fa7a3ca1 | Ilias Tsitsimpis | Component astakosclient |
4 | f8958a97 | Ilias Tsitsimpis | ^^^^^^^^^^^^^^^^^^^^^^^ |
5 | 1acf67a7 | Ilias Tsitsimpis | |
6 | fa7a3ca1 | Ilias Tsitsimpis | The Synnefo component :ref:`astakosclient <astakosclient>` defines a |
7 | 4b92d3f7 | Constantinos Venetsanopoulos | default client for the :ref:`Astakos <astakos>` service. It is designed to be |
8 | 4b92d3f7 | Constantinos Venetsanopoulos | simple and minimal, hence easy to debug and test. |
9 | 4b92d3f7 | Constantinos Venetsanopoulos | |
10 | 4b92d3f7 | Constantinos Venetsanopoulos | It uses the user's authentication token to query Astakos for: |
11 | 1acf67a7 | Ilias Tsitsimpis | |
12 | 1acf67a7 | Ilias Tsitsimpis | * User's info |
13 | 4b92d3f7 | Constantinos Venetsanopoulos | * Usernames for given UUIDs |
14 | 4b92d3f7 | Constantinos Venetsanopoulos | * UUIDs for given usernames |
15 | 5c418e94 | Ilias Tsitsimpis | * User's quotas |
16 | 4b92d3f7 | Constantinos Venetsanopoulos | |
17 | 4b92d3f7 | Constantinos Venetsanopoulos | It can also query Astakos with another service's (Cyclades or Pithos) |
18 | 4b92d3f7 | Constantinos Venetsanopoulos | authentication token for: |
19 | 1acf67a7 | Ilias Tsitsimpis | |
20 | 4b92d3f7 | Constantinos Venetsanopoulos | * Usernames for given UUIDs |
21 | 4b92d3f7 | Constantinos Venetsanopoulos | * UUIDs for given usernames |
22 | 5b33b8e5 | Giorgos Korfiatis | * Quotas for all related resources |
23 | 5c418e94 | Ilias Tsitsimpis | * Issue commissions |
24 | 5c418e94 | Ilias Tsitsimpis | * Get pending commissions |
25 | 5c418e94 | Ilias Tsitsimpis | * Accept or reject commissions |
26 | 1acf67a7 | Ilias Tsitsimpis | |
27 | 4b92d3f7 | Constantinos Venetsanopoulos | Additionally, there are options for using the `objpool |
28 | 4b92d3f7 | Constantinos Venetsanopoulos | <https://github.com/grnet/objpool>`_ library to pool the http connections. |
29 | 1acf67a7 | Ilias Tsitsimpis | |
30 | 1acf67a7 | Ilias Tsitsimpis | |
31 | 1acf67a7 | Ilias Tsitsimpis | Basic example |
32 | 1acf67a7 | Ilias Tsitsimpis | ============= |
33 | 1acf67a7 | Ilias Tsitsimpis | |
34 | 4b92d3f7 | Constantinos Venetsanopoulos | The ``astakosclient`` module provides the ``AstakosClient`` class. This section |
35 | 4b92d3f7 | Constantinos Venetsanopoulos | demonstrates how to get user's info using ``astakosclient``. |
36 | 1acf67a7 | Ilias Tsitsimpis | |
37 | 1acf67a7 | Ilias Tsitsimpis | .. code-block:: python |
38 | 1acf67a7 | Ilias Tsitsimpis | |
39 | 1acf67a7 | Ilias Tsitsimpis | from astakosclient import AstakosClient |
40 | 1acf67a7 | Ilias Tsitsimpis | |
41 | 1acf67a7 | Ilias Tsitsimpis | client = AstakosClient("https://accounts.example.com") |
42 | 26498848 | Giorgos Korfiatis | user_info = client.get_user_info("UQpYas7ElzWGD5yCcEXtjw") |
43 | 1acf67a7 | Ilias Tsitsimpis | print user_info['username'] |
44 | 1acf67a7 | Ilias Tsitsimpis | |
45 | 4b92d3f7 | Constantinos Venetsanopoulos | Another example where we ask for the username of a user with UUID: |
46 | 4b92d3f7 | Constantinos Venetsanopoulos | ``b3de8eb0-3958-477e-als9-789af8dd352c`` |
47 | 1acf67a7 | Ilias Tsitsimpis | |
48 | 1acf67a7 | Ilias Tsitsimpis | .. code-block:: python |
49 | 1acf67a7 | Ilias Tsitsimpis | |
50 | 1acf67a7 | Ilias Tsitsimpis | from astakosclient import AstakosClient |
51 | 1acf67a7 | Ilias Tsitsimpis | |
52 | 1acf67a7 | Ilias Tsitsimpis | client = AstakosClient("https://accounts.example.com") |
53 | 26498848 | Giorgos Korfiatis | username = client.get_username("UQpYas7ElzWGD5yCcEXtjw", |
54 | 794c94e6 | Ilias Tsitsimpis | "b3de8eb0-3958-477e-als9-789af8dd352c") |
55 | 1acf67a7 | Ilias Tsitsimpis | print username |
56 | 1acf67a7 | Ilias Tsitsimpis | |
57 | 1acf67a7 | Ilias Tsitsimpis | |
58 | 1acf67a7 | Ilias Tsitsimpis | Classes and functions |
59 | 1acf67a7 | Ilias Tsitsimpis | ===================== |
60 | 1acf67a7 | Ilias Tsitsimpis | |
61 | 4b92d3f7 | Constantinos Venetsanopoulos | This section describes in depth the API of ``astakosclient``. |
62 | 1acf67a7 | Ilias Tsitsimpis | |
63 | 1acf67a7 | Ilias Tsitsimpis | Astakos Client |
64 | 1acf67a7 | Ilias Tsitsimpis | -------------- |
65 | 1acf67a7 | Ilias Tsitsimpis | |
66 | 1acf67a7 | Ilias Tsitsimpis | *class* astakosclient.\ **AstakosClient(**\ astakos_url, |
67 | 1acf67a7 | Ilias Tsitsimpis | retry=0, use_pool=False, pool_size=8, logger=None\ **)** |
68 | 1acf67a7 | Ilias Tsitsimpis | |
69 | 1acf67a7 | Ilias Tsitsimpis | Initialize an instance of **AstakosClient** given the *astakos_url*. |
70 | 1acf67a7 | Ilias Tsitsimpis | Optionally one can specify if we are going to use a pool, the pool_size |
71 | 1acf67a7 | Ilias Tsitsimpis | and the number of retries if the connection fails. |
72 | 1acf67a7 | Ilias Tsitsimpis | |
73 | 1acf67a7 | Ilias Tsitsimpis | This class provides the following methods: |
74 | 1acf67a7 | Ilias Tsitsimpis | |
75 | 794c94e6 | Ilias Tsitsimpis | **get_user_info(**\ token, usage=False\ **)** |
76 | 5c418e94 | Ilias Tsitsimpis | Given a user's authentication token it returns a dict with the |
77 | 1acf67a7 | Ilias Tsitsimpis | correspoinding user's info. If usage is set to True more |
78 | 1acf67a7 | Ilias Tsitsimpis | information about user's resources will be returned. |
79 | 1acf67a7 | Ilias Tsitsimpis | In case of error raise an AstakosClientException exception. |
80 | 1acf67a7 | Ilias Tsitsimpis | |
81 | 794c94e6 | Ilias Tsitsimpis | **get_usernames(**\ token, uuids\ **)** |
82 | 5c418e94 | Ilias Tsitsimpis | Given a user's authentication token and a list of UUIDs |
83 | 1acf67a7 | Ilias Tsitsimpis | return a uuid_catalog, that is a dictionary with the given |
84 | 4b92d3f7 | Constantinos Venetsanopoulos | UUIDs as keys and the corresponding user names as values. |
85 | 4b92d3f7 | Constantinos Venetsanopoulos | Invalid UUIDs will not be in the dictionary. |
86 | 1acf67a7 | Ilias Tsitsimpis | In case of error raise an AstakosClientException exception. |
87 | 1acf67a7 | Ilias Tsitsimpis | |
88 | 794c94e6 | Ilias Tsitsimpis | **get_username(**\ token, uuid\ **)** |
89 | 5c418e94 | Ilias Tsitsimpis | Given a user's authentication token and a UUID (as string) |
90 | 1acf67a7 | Ilias Tsitsimpis | return the corresponding user name (as string). |
91 | 794c94e6 | Ilias Tsitsimpis | In case of invalid UUID raise NoUserName exception. |
92 | 1acf67a7 | Ilias Tsitsimpis | In case of error raise an AstakosClientException exception. |
93 | 1acf67a7 | Ilias Tsitsimpis | |
94 | 794c94e6 | Ilias Tsitsimpis | **service_get_usernames(**\ token, uuids\ **)** |
95 | 794c94e6 | Ilias Tsitsimpis | Same as get_usernames but called with a service's token. |
96 | 1acf67a7 | Ilias Tsitsimpis | |
97 | 794c94e6 | Ilias Tsitsimpis | **service_get_username(**\ token, uuid\ **)** |
98 | 794c94e6 | Ilias Tsitsimpis | Same as get_username but called with a service's token. |
99 | 1acf67a7 | Ilias Tsitsimpis | |
100 | 794c94e6 | Ilias Tsitsimpis | **get_uuids(**\ token, display_names\ **)** |
101 | 5c418e94 | Ilias Tsitsimpis | Given a user's authentication token and a list of usernames |
102 | 1acf67a7 | Ilias Tsitsimpis | return a displayname_catalog, that is a dictionary with the given |
103 | 4b92d3f7 | Constantinos Venetsanopoulos | usernames as keys and the corresponding UUIDs as values. |
104 | 1acf67a7 | Ilias Tsitsimpis | Invalid usernames will not be in the dictionary. |
105 | 1acf67a7 | Ilias Tsitsimpis | In case of error raise an AstakosClientException exception. |
106 | 1acf67a7 | Ilias Tsitsimpis | |
107 | 794c94e6 | Ilias Tsitsimpis | **get_uuid(**\ token, display_name\ **)** |
108 | 5c418e94 | Ilias Tsitsimpis | Given a user's authentication token and a username (as string) |
109 | 4b92d3f7 | Constantinos Venetsanopoulos | return the corresponding UUID (as string). |
110 | 1acf67a7 | Ilias Tsitsimpis | In case of invalid user name raise NoUUID exception. |
111 | 1acf67a7 | Ilias Tsitsimpis | In case of error raise an AstakosClientException exception. |
112 | 1acf67a7 | Ilias Tsitsimpis | |
113 | 794c94e6 | Ilias Tsitsimpis | **service_get_uuids(**\ token, uuids\ **)** |
114 | 794c94e6 | Ilias Tsitsimpis | Same as get_uuids but called with a service's token. |
115 | 1acf67a7 | Ilias Tsitsimpis | |
116 | 794c94e6 | Ilias Tsitsimpis | **service_get_uuid(**\ token, uuid\ **)** |
117 | 794c94e6 | Ilias Tsitsimpis | Same as get_uuid but called with a service's token. |
118 | 1acf67a7 | Ilias Tsitsimpis | |
119 | 794c94e6 | Ilias Tsitsimpis | **get_services()** |
120 | 1acf67a7 | Ilias Tsitsimpis | Return a list of dicts with the registered services. |
121 | 1acf67a7 | Ilias Tsitsimpis | |
122 | 5c418e94 | Ilias Tsitsimpis | **get_resources()** |
123 | 5c418e94 | Ilias Tsitsimpis | Return a list of dicts with the available resources |
124 | 5c418e94 | Ilias Tsitsimpis | |
125 | f20c20fe | Ilias Tsitsimpis | **send_feedback(**\ token, message, data\ **)** |
126 | f20c20fe | Ilias Tsitsimpis | Using a user's authentication token send some feedback to |
127 | f20c20fe | Ilias Tsitsimpis | astakos service. Additional information about the service |
128 | f20c20fe | Ilias Tsitsimpis | client status can be given in the data variable. |
129 | f20c20fe | Ilias Tsitsimpis | In case of success returns nothing. |
130 | f20c20fe | Ilias Tsitsimpis | Otherwise raise an AstakosClientException exception. |
131 | f20c20fe | Ilias Tsitsimpis | |
132 | f20c20fe | Ilias Tsitsimpis | **get_endpoints(**\ token, belongs_to, marker, limit\ **)** |
133 | f20c20fe | Ilias Tsitsimpis | Given a user's authentication token, request registered |
134 | f20c20fe | Ilias Tsitsimpis | endpoints from astakos service. If belongs_to is given (uuid) |
135 | f20c20fe | Ilias Tsitsimpis | check that the token belongs to this user. If marker is given |
136 | f20c20fe | Ilias Tsitsimpis | (int) return endpoints (ordered by ID) whose ID is higher than |
137 | f20c20fe | Ilias Tsitsimpis | the marker. Limit (int) specifies the maximum number of |
138 | f20c20fe | Ilias Tsitsimpis | endpoints to return. Return a json formatted dictionary containing |
139 | f20c20fe | Ilias Tsitsimpis | information about registered endpoints. |
140 | f20c20fe | Ilias Tsitsimpis | |
141 | f20c20fe | Ilias Tsitsimpis | .. warning:: *get_endpoints* api call encodes the user's token inside |
142 | f20c20fe | Ilias Tsitsimpis | the url. It's security unsafe to use it (both astakosclient |
143 | 25a04cdd | Ilias Tsitsimpis | and nginx tend to log requested urls). Use |
144 | 25a04cdd | Ilias Tsitsimpis | get_user_info_with_endpoints instead. |
145 | 25a04cdd | Ilias Tsitsimpis | |
146 | 25a04cdd | Ilias Tsitsimpis | **get_user_info_with_endpoints(**\ token, uuid=None\ **)** |
147 | 25a04cdd | Ilias Tsitsimpis | Fallback call which receives the user token or the user uuid/token |
148 | 25a04cdd | Ilias Tsitsimpis | and returns back the token as well as information about the token |
149 | 25a04cdd | Ilias Tsitsimpis | holder and the services he/seh can access. |
150 | 25a04cdd | Ilias Tsitsimpis | In case of error raise an AstakosClientException exception. |
151 | f20c20fe | Ilias Tsitsimpis | |
152 | 5c418e94 | Ilias Tsitsimpis | **get_quotas(**\ token\ **)** |
153 | 5c418e94 | Ilias Tsitsimpis | Given a user's authentication token return user's |
154 | 5c418e94 | Ilias Tsitsimpis | current quotas (as dict of dicts). |
155 | 5c418e94 | Ilias Tsitsimpis | In case of error raise an AstakosClientException exception. |
156 | 5c418e94 | Ilias Tsitsimpis | |
157 | 271d2c4c | Giorgos Korfiatis | **service_get_quotas(**\ token, user=None\ **)** |
158 | 5b33b8e5 | Giorgos Korfiatis | Given a service's authentication token return all users' |
159 | 5b33b8e5 | Giorgos Korfiatis | current quotas for the resources associated with the service |
160 | 5b33b8e5 | Giorgos Korfiatis | (as dict of dicts of dicts). |
161 | db9f7a2b | Giorgos Korfiatis | Optionally, one can query the quotas of a specific user with |
162 | db9f7a2b | Giorgos Korfiatis | argument user=UUID. |
163 | 5b33b8e5 | Giorgos Korfiatis | In case of error raise an AstakosClientException exception. |
164 | 5b33b8e5 | Giorgos Korfiatis | |
165 | 5c418e94 | Ilias Tsitsimpis | **issue_commission(**\ token, request\ **)** |
166 | 5c418e94 | Ilias Tsitsimpis | Given a service's authentication token issue a commission. |
167 | 5c418e94 | Ilias Tsitsimpis | In case of success return commission's id (int). |
168 | 5c418e94 | Ilias Tsitsimpis | Otherwise raise an AstakosClientException exception. |
169 | 5c418e94 | Ilias Tsitsimpis | |
170 | 3a1bed03 | Giorgos Korfiatis | **issue_one_commission(**\ token, holder, source, provisions, name="", force=False, auto_accept=False\ **)** |
171 | 5c418e94 | Ilias Tsitsimpis | Given a service's authentication token issue a commission. |
172 | 5c418e94 | Ilias Tsitsimpis | In this case we specify the holder, the source and the provisions |
173 | 567f49a2 | Giorgos Korfiatis | (a dict from string to int) and astakosclient will create the |
174 | 5c418e94 | Ilias Tsitsimpis | corresponding commission. |
175 | 5c418e94 | Ilias Tsitsimpis | In case of success return commission's id (int). |
176 | 5c418e94 | Ilias Tsitsimpis | Otherwise raise an AstakosClientException exception. |
177 | 5c418e94 | Ilias Tsitsimpis | |
178 | 5c418e94 | Ilias Tsitsimpis | **get_pending_commissions(**\ token\ **)** |
179 | 5c418e94 | Ilias Tsitsimpis | Given a service's authentication token return the pending |
180 | 5c418e94 | Ilias Tsitsimpis | commissions (list of integers). |
181 | 5c418e94 | Ilias Tsitsimpis | In case of error raise an AstakosClientException exception. |
182 | 5c418e94 | Ilias Tsitsimpis | |
183 | 5c418e94 | Ilias Tsitsimpis | **get_commission_info(**\ token, serial\ **)** |
184 | 5c418e94 | Ilias Tsitsimpis | Given a service's authentication token and the id of a |
185 | 5c418e94 | Ilias Tsitsimpis | pending commission return a dict of dicts containting |
186 | 5c418e94 | Ilias Tsitsimpis | informations (details) about the requested commission. |
187 | 5c418e94 | Ilias Tsitsimpis | In case of error raise an AstakosClientException exception. |
188 | 5c418e94 | Ilias Tsitsimpis | |
189 | 5c418e94 | Ilias Tsitsimpis | **commission_action(**\ token, serial, action\ **)** |
190 | 5c418e94 | Ilias Tsitsimpis | Given a service's authentication token and the id of a |
191 | 5c418e94 | Ilias Tsitsimpis | pending commission, request the specified action (currently |
192 | 5c418e94 | Ilias Tsitsimpis | one of accept, reject). |
193 | 5c418e94 | Ilias Tsitsimpis | In case of success returns nothing. |
194 | 5c418e94 | Ilias Tsitsimpis | Otherwise raise an AstakosClientException exception. |
195 | 5c418e94 | Ilias Tsitsimpis | |
196 | 5c418e94 | Ilias Tsitsimpis | **accept_commission(**\ token, serial\ **)** |
197 | 5c418e94 | Ilias Tsitsimpis | Accept a pending commission (see commission_action). |
198 | 5c418e94 | Ilias Tsitsimpis | |
199 | 5c418e94 | Ilias Tsitsimpis | **reject_commission(**\ token, serial\ **)** |
200 | 5c418e94 | Ilias Tsitsimpis | Reject a pending commission (see commission_action). |
201 | 5c418e94 | Ilias Tsitsimpis | |
202 | 5c418e94 | Ilias Tsitsimpis | **resolve_commissions(**\ token, accept_serials, reject_serials\ **)** |
203 | 5c418e94 | Ilias Tsitsimpis | Accept or Reject many pending commissions at once. |
204 | 5c418e94 | Ilias Tsitsimpis | In case of success return a dict of dicts describing which |
205 | 5c418e94 | Ilias Tsitsimpis | commissions accepted, which rejected and which failed to |
206 | 5c418e94 | Ilias Tsitsimpis | resolved. |
207 | 5c418e94 | Ilias Tsitsimpis | Otherwise raise an AstakosClientException exception. |
208 | 5c418e94 | Ilias Tsitsimpis | |
209 | 1acf67a7 | Ilias Tsitsimpis | |
210 | 1acf67a7 | Ilias Tsitsimpis | Public Functions |
211 | 1acf67a7 | Ilias Tsitsimpis | ---------------- |
212 | 1acf67a7 | Ilias Tsitsimpis | |
213 | 794c94e6 | Ilias Tsitsimpis | **get_token_from_cookie(**\ request, cookie_name\ **)** |
214 | 4b92d3f7 | Constantinos Venetsanopoulos | Given a Django request object and an Astakos cookie name |
215 | 4b92d3f7 | Constantinos Venetsanopoulos | extract the user's token from it. |
216 | 1acf67a7 | Ilias Tsitsimpis | |
217 | 1acf67a7 | Ilias Tsitsimpis | |
218 | 1acf67a7 | Ilias Tsitsimpis | Exceptions and Errors |
219 | 1acf67a7 | Ilias Tsitsimpis | ===================== |
220 | 1acf67a7 | Ilias Tsitsimpis | |
221 | 1acf67a7 | Ilias Tsitsimpis | *exception* **AstakosClientException** |
222 | 1acf67a7 | Ilias Tsitsimpis | Raised in case of an error. It contains an error message and the |
223 | fa7a3ca1 | Ilias Tsitsimpis | corresponding http status code. Other exceptions raised by |
224 | fa7a3ca1 | Ilias Tsitsimpis | astakosclient module are derived from this one. |
225 | fa7a3ca1 | Ilias Tsitsimpis | |
226 | fa7a3ca1 | Ilias Tsitsimpis | *exception* **BadValue** |
227 | fa7a3ca1 | Ilias Tsitsimpis | A redefinition of ValueError exception under AstakosClientException. |
228 | fa7a3ca1 | Ilias Tsitsimpis | |
229 | fa7a3ca1 | Ilias Tsitsimpis | *exception* **InvalidResponse** |
230 | fa7a3ca1 | Ilias Tsitsimpis | This exception is raised whenever the server's response is not |
231 | fa7a3ca1 | Ilias Tsitsimpis | valid json (cannot be parsed by simplejson library). |
232 | 1acf67a7 | Ilias Tsitsimpis | |
233 | 1acf67a7 | Ilias Tsitsimpis | *exception* **BadRequest** |
234 | 1acf67a7 | Ilias Tsitsimpis | Raised in case of a Bad Request, with status 400. |
235 | 1acf67a7 | Ilias Tsitsimpis | |
236 | 1acf67a7 | Ilias Tsitsimpis | *exception* **Unauthorized** |
237 | 1acf67a7 | Ilias Tsitsimpis | Raised in case of Invalid token (unauthorized access), with status 401. |
238 | 1acf67a7 | Ilias Tsitsimpis | |
239 | 1acf67a7 | Ilias Tsitsimpis | *exception* **Forbidden** |
240 | 1acf67a7 | Ilias Tsitsimpis | The server understood the request, but is refusing to fulfill it. |
241 | 1acf67a7 | Ilias Tsitsimpis | Status 401. |
242 | 1acf67a7 | Ilias Tsitsimpis | |
243 | 1acf67a7 | Ilias Tsitsimpis | *exception* **NotFound** |
244 | 1acf67a7 | Ilias Tsitsimpis | The server has not found anything matching the Request-URI. Status 404. |
245 | 1acf67a7 | Ilias Tsitsimpis | |
246 | fa7a3ca1 | Ilias Tsitsimpis | *exception* **QuotaLimit** |
247 | fa7a3ca1 | Ilias Tsitsimpis | Quantity fell below zero or exceeded capacity in one of the holdings. |
248 | fa7a3ca1 | Ilias Tsitsimpis | |
249 | 794c94e6 | Ilias Tsitsimpis | *exception* **NoUserName** |
250 | 1acf67a7 | Ilias Tsitsimpis | Raised by getDisplayName and getServiceDisplayName when an invalid |
251 | 4b92d3f7 | Constantinos Venetsanopoulos | UUID was given. |
252 | 1acf67a7 | Ilias Tsitsimpis | |
253 | 1acf67a7 | Ilias Tsitsimpis | *exception* **NoUUID** |
254 | 1acf67a7 | Ilias Tsitsimpis | Raised by *getUUID* and *getServiceUUID* when an invalid |
255 | 1acf67a7 | Ilias Tsitsimpis | username was given. |