root / snf-astakos-client / docs / index.rst @ f74d2b69
History | View | Annotate | Download (5.2 kB)
1 | 1acf67a7 | Ilias Tsitsimpis | .. _snf-astakos-client: |
---|---|---|---|
2 | 1acf67a7 | Ilias Tsitsimpis | |
3 | 1acf67a7 | Ilias Tsitsimpis | Component snf-astakos-client |
4 | 1acf67a7 | Ilias Tsitsimpis | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
5 | 1acf67a7 | Ilias Tsitsimpis | |
6 | 4b92d3f7 | Constantinos Venetsanopoulos | The Synnefo component :ref:`snf-astakos-client <snf-astakos-client>` 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 | 4b92d3f7 | Constantinos Venetsanopoulos | |
16 | 4b92d3f7 | Constantinos Venetsanopoulos | It can also query Astakos with another service's (Cyclades or Pithos) |
17 | 4b92d3f7 | Constantinos Venetsanopoulos | authentication token for: |
18 | 1acf67a7 | Ilias Tsitsimpis | |
19 | 4b92d3f7 | Constantinos Venetsanopoulos | * Usernames for given UUIDs |
20 | 4b92d3f7 | Constantinos Venetsanopoulos | * UUIDs for given usernames |
21 | 1acf67a7 | Ilias Tsitsimpis | |
22 | 4b92d3f7 | Constantinos Venetsanopoulos | Additionally, there are options for using the `objpool |
23 | 4b92d3f7 | Constantinos Venetsanopoulos | <https://github.com/grnet/objpool>`_ library to pool the http connections. |
24 | 1acf67a7 | Ilias Tsitsimpis | |
25 | 1acf67a7 | Ilias Tsitsimpis | |
26 | 1acf67a7 | Ilias Tsitsimpis | Basic example |
27 | 1acf67a7 | Ilias Tsitsimpis | ============= |
28 | 1acf67a7 | Ilias Tsitsimpis | |
29 | 4b92d3f7 | Constantinos Venetsanopoulos | The ``astakosclient`` module provides the ``AstakosClient`` class. This section |
30 | 4b92d3f7 | Constantinos Venetsanopoulos | demonstrates how to get user's info using ``astakosclient``. |
31 | 1acf67a7 | Ilias Tsitsimpis | |
32 | 1acf67a7 | Ilias Tsitsimpis | .. code-block:: python |
33 | 1acf67a7 | Ilias Tsitsimpis | |
34 | 1acf67a7 | Ilias Tsitsimpis | from astakosclient import AstakosClient |
35 | 1acf67a7 | Ilias Tsitsimpis | |
36 | 1acf67a7 | Ilias Tsitsimpis | client = AstakosClient("https://accounts.example.com") |
37 | f74d2b69 | Ilias Tsitsimpis | user_info = client.getUserInfo("UQpYas7ElzWGD5yCcEXtjw==") |
38 | 1acf67a7 | Ilias Tsitsimpis | print user_info['username'] |
39 | 1acf67a7 | Ilias Tsitsimpis | |
40 | 4b92d3f7 | Constantinos Venetsanopoulos | Another example where we ask for the username of a user with UUID: |
41 | 4b92d3f7 | Constantinos Venetsanopoulos | ``b3de8eb0-3958-477e-als9-789af8dd352c`` |
42 | 1acf67a7 | Ilias Tsitsimpis | |
43 | 1acf67a7 | Ilias Tsitsimpis | .. code-block:: python |
44 | 1acf67a7 | Ilias Tsitsimpis | |
45 | 1acf67a7 | Ilias Tsitsimpis | from astakosclient import AstakosClient |
46 | 1acf67a7 | Ilias Tsitsimpis | |
47 | 1acf67a7 | Ilias Tsitsimpis | client = AstakosClient("https://accounts.example.com") |
48 | 1acf67a7 | Ilias Tsitsimpis | username = client.getDisplayName("UQpYas7ElzWGD5yCcEXtjw==", |
49 | 1acf67a7 | Ilias Tsitsimpis | "b3de8eb0-3958-477e-als9-789af8dd352c") |
50 | 1acf67a7 | Ilias Tsitsimpis | print username |
51 | 1acf67a7 | Ilias Tsitsimpis | |
52 | 1acf67a7 | Ilias Tsitsimpis | |
53 | 1acf67a7 | Ilias Tsitsimpis | Classes and functions |
54 | 1acf67a7 | Ilias Tsitsimpis | ===================== |
55 | 1acf67a7 | Ilias Tsitsimpis | |
56 | 4b92d3f7 | Constantinos Venetsanopoulos | This section describes in depth the API of ``astakosclient``. |
57 | 1acf67a7 | Ilias Tsitsimpis | |
58 | 1acf67a7 | Ilias Tsitsimpis | Astakos Client |
59 | 1acf67a7 | Ilias Tsitsimpis | -------------- |
60 | 1acf67a7 | Ilias Tsitsimpis | |
61 | 1acf67a7 | Ilias Tsitsimpis | *class* astakosclient.\ **AstakosClient(**\ astakos_url, |
62 | 1acf67a7 | Ilias Tsitsimpis | retry=0, use_pool=False, pool_size=8, logger=None\ **)** |
63 | 1acf67a7 | Ilias Tsitsimpis | |
64 | 1acf67a7 | Ilias Tsitsimpis | Initialize an instance of **AstakosClient** given the *astakos_url*. |
65 | 1acf67a7 | Ilias Tsitsimpis | Optionally one can specify if we are going to use a pool, the pool_size |
66 | 1acf67a7 | Ilias Tsitsimpis | and the number of retries if the connection fails. |
67 | 1acf67a7 | Ilias Tsitsimpis | |
68 | 1acf67a7 | Ilias Tsitsimpis | This class provides the following methods: |
69 | 1acf67a7 | Ilias Tsitsimpis | |
70 | f74d2b69 | Ilias Tsitsimpis | **getUserInfo(**\ token, usage=False\ **)** |
71 | 1acf67a7 | Ilias Tsitsimpis | Given a valid authentication token it returns a dict with the |
72 | 1acf67a7 | Ilias Tsitsimpis | correspoinding user's info. If usage is set to True more |
73 | 1acf67a7 | Ilias Tsitsimpis | information about user's resources will be returned. |
74 | 1acf67a7 | Ilias Tsitsimpis | In case of error raise an AstakosClientException exception. |
75 | 1acf67a7 | Ilias Tsitsimpis | |
76 | 1acf67a7 | Ilias Tsitsimpis | **getDisplayNames(**\ token, uuids\ **)** |
77 | 4b92d3f7 | Constantinos Venetsanopoulos | Given a valid authentication token and a list of UUIDs |
78 | 1acf67a7 | Ilias Tsitsimpis | return a uuid_catalog, that is a dictionary with the given |
79 | 4b92d3f7 | Constantinos Venetsanopoulos | UUIDs as keys and the corresponding user names as values. |
80 | 4b92d3f7 | Constantinos Venetsanopoulos | Invalid UUIDs will not be in the dictionary. |
81 | 1acf67a7 | Ilias Tsitsimpis | In case of error raise an AstakosClientException exception. |
82 | 1acf67a7 | Ilias Tsitsimpis | |
83 | 1acf67a7 | Ilias Tsitsimpis | **getDisplayName(**\ token, uuid\ **)** |
84 | 4b92d3f7 | Constantinos Venetsanopoulos | Given a valid authentication token and a UUID (as string) |
85 | 1acf67a7 | Ilias Tsitsimpis | return the corresponding user name (as string). |
86 | 4b92d3f7 | Constantinos Venetsanopoulos | In case of invalid UUID raise NoDisplayName exception. |
87 | 1acf67a7 | Ilias Tsitsimpis | In case of error raise an AstakosClientException exception. |
88 | 1acf67a7 | Ilias Tsitsimpis | |
89 | 1acf67a7 | Ilias Tsitsimpis | **getServiceDisplayNames(**\ token, uuids\ **)** |
90 | 1acf67a7 | Ilias Tsitsimpis | Same as getDisplayNames but called with a service's token. |
91 | 1acf67a7 | Ilias Tsitsimpis | |
92 | 1acf67a7 | Ilias Tsitsimpis | **getServiceDisplayName(**\ token, uuid\ **)** |
93 | 1acf67a7 | Ilias Tsitsimpis | Same as getDisplayName but called with a service's token. |
94 | 1acf67a7 | Ilias Tsitsimpis | |
95 | 1acf67a7 | Ilias Tsitsimpis | **getUUIDs(**\ token, display_names\ **)** |
96 | 1acf67a7 | Ilias Tsitsimpis | Given a valid authentication token and a list of usernames |
97 | 1acf67a7 | Ilias Tsitsimpis | return a displayname_catalog, that is a dictionary with the given |
98 | 4b92d3f7 | Constantinos Venetsanopoulos | usernames as keys and the corresponding UUIDs as values. |
99 | 1acf67a7 | Ilias Tsitsimpis | Invalid usernames will not be in the dictionary. |
100 | 1acf67a7 | Ilias Tsitsimpis | In case of error raise an AstakosClientException exception. |
101 | 1acf67a7 | Ilias Tsitsimpis | |
102 | 1acf67a7 | Ilias Tsitsimpis | **getUUID(**\ token, display_name\ **)** |
103 | 1acf67a7 | Ilias Tsitsimpis | Given a valid authentication token and a username (as string) |
104 | 4b92d3f7 | Constantinos Venetsanopoulos | return the corresponding UUID (as string). |
105 | 1acf67a7 | Ilias Tsitsimpis | In case of invalid user name raise NoUUID exception. |
106 | 1acf67a7 | Ilias Tsitsimpis | In case of error raise an AstakosClientException exception. |
107 | 1acf67a7 | Ilias Tsitsimpis | |
108 | 1acf67a7 | Ilias Tsitsimpis | **getServiceUUIDs(**\ token, uuids\ **)** |
109 | 1acf67a7 | Ilias Tsitsimpis | Same as getUUIDs but called with a service's token. |
110 | 1acf67a7 | Ilias Tsitsimpis | |
111 | 1acf67a7 | Ilias Tsitsimpis | **getServiceUUID(**\ token, uuid\ **)** |
112 | 1acf67a7 | Ilias Tsitsimpis | Same as getUUID but called with a service's token. |
113 | 1acf67a7 | Ilias Tsitsimpis | |
114 | 1acf67a7 | Ilias Tsitsimpis | **getServices()** |
115 | 1acf67a7 | Ilias Tsitsimpis | Return a list of dicts with the registered services. |
116 | 1acf67a7 | Ilias Tsitsimpis | |
117 | 1acf67a7 | Ilias Tsitsimpis | |
118 | 1acf67a7 | Ilias Tsitsimpis | Public Functions |
119 | 1acf67a7 | Ilias Tsitsimpis | ---------------- |
120 | 1acf67a7 | Ilias Tsitsimpis | |
121 | 1acf67a7 | Ilias Tsitsimpis | **getTokenFromCookie(**\ request, cookie_name\ **)** |
122 | 4b92d3f7 | Constantinos Venetsanopoulos | Given a Django request object and an Astakos cookie name |
123 | 4b92d3f7 | Constantinos Venetsanopoulos | extract the user's token from it. |
124 | 1acf67a7 | Ilias Tsitsimpis | |
125 | 1acf67a7 | Ilias Tsitsimpis | |
126 | 1acf67a7 | Ilias Tsitsimpis | Exceptions and Errors |
127 | 1acf67a7 | Ilias Tsitsimpis | ===================== |
128 | 1acf67a7 | Ilias Tsitsimpis | |
129 | 1acf67a7 | Ilias Tsitsimpis | *exception* **AstakosClientException** |
130 | 1acf67a7 | Ilias Tsitsimpis | Raised in case of an error. It contains an error message and the |
131 | 1acf67a7 | Ilias Tsitsimpis | corresponding http status code. Other exceptions raise by astakosclient |
132 | 1acf67a7 | Ilias Tsitsimpis | module are derived from this one. |
133 | 1acf67a7 | Ilias Tsitsimpis | |
134 | 1acf67a7 | Ilias Tsitsimpis | *exception* **BadRequest** |
135 | 1acf67a7 | Ilias Tsitsimpis | Raised in case of a Bad Request, with status 400. |
136 | 1acf67a7 | Ilias Tsitsimpis | |
137 | 1acf67a7 | Ilias Tsitsimpis | *exception* **Unauthorized** |
138 | 1acf67a7 | Ilias Tsitsimpis | Raised in case of Invalid token (unauthorized access), with status 401. |
139 | 1acf67a7 | Ilias Tsitsimpis | |
140 | 1acf67a7 | Ilias Tsitsimpis | *exception* **Forbidden** |
141 | 1acf67a7 | Ilias Tsitsimpis | The server understood the request, but is refusing to fulfill it. |
142 | 1acf67a7 | Ilias Tsitsimpis | Status 401. |
143 | 1acf67a7 | Ilias Tsitsimpis | |
144 | 1acf67a7 | Ilias Tsitsimpis | *exception* **NotFound** |
145 | 1acf67a7 | Ilias Tsitsimpis | The server has not found anything matching the Request-URI. Status 404. |
146 | 1acf67a7 | Ilias Tsitsimpis | |
147 | 1acf67a7 | Ilias Tsitsimpis | *exception* **NoDisplayName** |
148 | 1acf67a7 | Ilias Tsitsimpis | Raised by getDisplayName and getServiceDisplayName when an invalid |
149 | 4b92d3f7 | Constantinos Venetsanopoulos | UUID was given. |
150 | 1acf67a7 | Ilias Tsitsimpis | |
151 | 1acf67a7 | Ilias Tsitsimpis | *exception* **NoUUID** |
152 | 1acf67a7 | Ilias Tsitsimpis | Raised by *getUUID* and *getServiceUUID* when an invalid |
153 | 1acf67a7 | Ilias Tsitsimpis | username was given. |