Statistics
| Branch: | Tag: | Revision:

root / astakosclient / docs / index.rst @ db9f7a2b

History | View | Annotate | Download (8.4 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
    **get_quotas(**\ token\ **)**
126
        Given a user's authentication token return user's
127
        current quotas (as dict of dicts).
128
        In case of error raise an AstakosClientException exception.
129

    
130
    **get_service_quotas(**\ token, user=None\ **)**
131
        Given a service's authentication token return all users'
132
        current quotas for the resources associated with the service
133
        (as dict of dicts of dicts).
134
        Optionally, one can query the quotas of a specific user with
135
        argument user=UUID.
136
        In case of error raise an AstakosClientException exception.
137

    
138
    **issue_commission(**\ token, request\ **)**
139
        Given a service's authentication token issue a commission.
140
        In case of success return commission's id (int).
141
        Otherwise raise an AstakosClientException exception.
142

    
143
    **issue_one_commission(**\ token, holder, source, provisions, force=False, auto_accept=False\ **)**
144
        Given a service's authentication token issue a commission.
145
        In this case we specify the holder, the source and the provisions
146
        (a list of (string, int)) and astakosclient will create the
147
        corresponding commission.
148
        In case of success return commission's id (int).
149
        Otherwise raise an AstakosClientException exception.
150

    
151
    **get_pending_commissions(**\ token\ **)**
152
        Given a service's authentication token return the pending
153
        commissions (list of integers).
154
        In case of error raise an AstakosClientException exception.
155

    
156
    **get_commission_info(**\ token, serial\ **)**
157
        Given a service's authentication token and the id of a
158
        pending commission return a dict of dicts containting
159
        informations (details) about the requested commission.
160
        In case of error raise an AstakosClientException exception.
161

    
162
    **commission_action(**\ token, serial, action\ **)**
163
        Given a service's authentication token and the id of a
164
        pending commission, request the specified action (currently
165
        one of accept, reject).
166
        In case of success returns nothing.
167
        Otherwise raise an AstakosClientException exception.
168

    
169
    **accept_commission(**\ token, serial\ **)**
170
        Accept a pending commission (see commission_action).
171

    
172
    **reject_commission(**\ token, serial\ **)**
173
        Reject a pending commission (see commission_action).
174

    
175
    **resolve_commissions(**\ token, accept_serials, reject_serials\ **)**
176
        Accept or Reject many pending commissions at once.
177
        In case of success return a dict of dicts describing which
178
        commissions accepted, which rejected and which failed to
179
        resolved.
180
        Otherwise raise an AstakosClientException exception.
181

    
182

    
183
Public Functions
184
----------------
185

    
186
**get_token_from_cookie(**\ request, cookie_name\ **)**
187
    Given a Django request object and an Astakos cookie name
188
    extract the user's token from it.
189

    
190

    
191
Exceptions and Errors
192
=====================
193

    
194
*exception* **AstakosClientException**
195
    Raised in case of an error. It contains an error message and the
196
    corresponding http status code. Other exceptions raised by
197
    astakosclient module are derived from this one.
198

    
199
*exception* **BadValue**
200
    A redefinition of ValueError exception under AstakosClientException.
201

    
202
*exception* **InvalidResponse**
203
    This exception is raised whenever the server's response is not
204
    valid json (cannot be parsed by simplejson library).
205

    
206
*exception* **BadRequest**
207
    Raised in case of a Bad Request, with status 400.
208

    
209
*exception* **Unauthorized**
210
    Raised in case of Invalid token (unauthorized access), with status 401.
211

    
212
*exception* **Forbidden**
213
    The server understood the request, but is refusing to fulfill it.
214
    Status 401.
215

    
216
*exception* **NotFound**
217
    The server has not found anything matching the Request-URI. Status 404.
218

    
219
*exception* **QuotaLimit**
220
    Quantity fell below zero or exceeded capacity in one of the holdings.
221

    
222
*exception* **NoUserName**
223
    Raised by getDisplayName and getServiceDisplayName when an invalid
224
    UUID was given.
225

    
226
*exception* **NoUUID**
227
    Raised by *getUUID* and *getServiceUUID* when an invalid
228
    username was given.