Statistics
| Branch: | Tag: | Revision:

root / astakosclient / docs / index.rst @ f20c20fe

History | View | Annotate | Download (9.5 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).
144

    
145
    **get_quotas(**\ token\ **)**
146
        Given a user's authentication token return user's
147
        current quotas (as dict of dicts).
148
        In case of error raise an AstakosClientException exception.
149

    
150
    **service_get_quotas(**\ token, user=None\ **)**
151
        Given a service's authentication token return all users'
152
        current quotas for the resources associated with the service
153
        (as dict of dicts of dicts).
154
        Optionally, one can query the quotas of a specific user with
155
        argument user=UUID.
156
        In case of error raise an AstakosClientException exception.
157

    
158
    **issue_commission(**\ token, request\ **)**
159
        Given a service's authentication token issue a commission.
160
        In case of success return commission's id (int).
161
        Otherwise raise an AstakosClientException exception.
162

    
163
    **issue_one_commission(**\ token, holder, source, provisions, name="", force=False, auto_accept=False\ **)**
164
        Given a service's authentication token issue a commission.
165
        In this case we specify the holder, the source and the provisions
166
        (a dict from string to int) and astakosclient will create the
167
        corresponding commission.
168
        In case of success return commission's id (int).
169
        Otherwise raise an AstakosClientException exception.
170

    
171
    **get_pending_commissions(**\ token\ **)**
172
        Given a service's authentication token return the pending
173
        commissions (list of integers).
174
        In case of error raise an AstakosClientException exception.
175

    
176
    **get_commission_info(**\ token, serial\ **)**
177
        Given a service's authentication token and the id of a
178
        pending commission return a dict of dicts containting
179
        informations (details) about the requested commission.
180
        In case of error raise an AstakosClientException exception.
181

    
182
    **commission_action(**\ token, serial, action\ **)**
183
        Given a service's authentication token and the id of a
184
        pending commission, request the specified action (currently
185
        one of accept, reject).
186
        In case of success returns nothing.
187
        Otherwise raise an AstakosClientException exception.
188

    
189
    **accept_commission(**\ token, serial\ **)**
190
        Accept a pending commission (see commission_action).
191

    
192
    **reject_commission(**\ token, serial\ **)**
193
        Reject a pending commission (see commission_action).
194

    
195
    **resolve_commissions(**\ token, accept_serials, reject_serials\ **)**
196
        Accept or Reject many pending commissions at once.
197
        In case of success return a dict of dicts describing which
198
        commissions accepted, which rejected and which failed to
199
        resolved.
200
        Otherwise raise an AstakosClientException exception.
201

    
202

    
203
Public Functions
204
----------------
205

    
206
**get_token_from_cookie(**\ request, cookie_name\ **)**
207
    Given a Django request object and an Astakos cookie name
208
    extract the user's token from it.
209

    
210

    
211
Exceptions and Errors
212
=====================
213

    
214
*exception* **AstakosClientException**
215
    Raised in case of an error. It contains an error message and the
216
    corresponding http status code. Other exceptions raised by
217
    astakosclient module are derived from this one.
218

    
219
*exception* **BadValue**
220
    A redefinition of ValueError exception under AstakosClientException.
221

    
222
*exception* **InvalidResponse**
223
    This exception is raised whenever the server's response is not
224
    valid json (cannot be parsed by simplejson library).
225

    
226
*exception* **BadRequest**
227
    Raised in case of a Bad Request, with status 400.
228

    
229
*exception* **Unauthorized**
230
    Raised in case of Invalid token (unauthorized access), with status 401.
231

    
232
*exception* **Forbidden**
233
    The server understood the request, but is refusing to fulfill it.
234
    Status 401.
235

    
236
*exception* **NotFound**
237
    The server has not found anything matching the Request-URI. Status 404.
238

    
239
*exception* **QuotaLimit**
240
    Quantity fell below zero or exceeded capacity in one of the holdings.
241

    
242
*exception* **NoUserName**
243
    Raised by getDisplayName and getServiceDisplayName when an invalid
244
    UUID was given.
245

    
246
*exception* **NoUUID**
247
    Raised by *getUUID* and *getServiceUUID* when an invalid
248
    username was given.