index.rst 10.6 KB
Newer Older
1
.. _astakosclient:
2

3
Component astakosclient
4
^^^^^^^^^^^^^^^^^^^^^^^
5

6 7
The Synnefo component astakosclient_ defines a
default client for the `Astakos <astakos>`_ service. It is designed to be
8 9 10
simple and minimal, hence easy to debug and test.

It uses the user's authentication token to query Astakos for:
11 12

    * User's info
13 14
    * Usernames for given UUIDs
    * UUIDs for given usernames
15
    * User's quotas
16 17 18

It can also query Astakos with another service's (Cyclades or Pithos)
authentication token for:
19

20 21
    * Usernames for given UUIDs
    * UUIDs for given usernames
22
    * Quotas for all related resources
23 24 25
    * Issue commissions
    * Get pending commissions
    * Accept or reject commissions
26

27 28
Additionally, there are options for using the `objpool
<https://github.com/grnet/objpool>`_ library to pool the http connections.
29 30 31 32 33


Basic example
=============

34 35
The ``astakosclient`` module provides the ``AstakosClient`` class. This section
demonstrates how to get user's info using ``astakosclient``.
36 37 38 39 40

.. code-block:: python

    from astakosclient import AstakosClient

41 42
    client = AstakosClient("UQpYas7ElzWGD5yCcEXtjw",
                           "https://accounts.example.com")
43 44
    user_info = client.authenticate()
    print user_info['access']['user']['id']
45

46 47
Another example where we ask for the username of a user with UUID:
``b3de8eb0-3958-477e-als9-789af8dd352c``
48 49 50 51 52

.. code-block:: python

    from astakosclient import AstakosClient

53 54 55
    client = AstakosClient("UQpYas7ElzWGD5yCcEXtjw",
                           "https://accounts.example.com")
    username = client.get_username("b3de8eb0-3958-477e-als9-789af8dd352c")
56 57 58 59 60 61
    print username


Classes and functions
=====================

62
This section describes in depth the API of ``astakosclient``.
63 64 65 66

Astakos Client
--------------

67
*class* astakosclient.\ **AstakosClient(**\ token, auth_url,
68 69
retry=0, use_pool=False, pool_size=8, logger=None\ **)**

70 71
    Initialize an instance of **AstakosClient** given the Authentication Url
    *auth_url* and the Token *token*.
72 73 74 75 76
    Optionally one can specify if we are going to use a pool, the pool_size
    and the number of retries if the connection fails.

    This class provides the following methods:

77 78 79 80 81
    **authenticate(**\ tenant_name=None\ **)**
        It authenticates the user and returns information about the user,
        their token as well as the service endpoints one can access. In
        case of error, it raises an AstakosClientException exception.

82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114
    **get_usernames(**\ uuids\ **)**
        Given a list of UUIDs it returns a uuid_catalog, that is a dictionary
        with the given UUIDs as keys and the corresponding user names as
        values.  Invalid UUIDs will not be in the dictionary.  In case of
        error, it raises an AstakosClientException exception.

    **get_username(**\ uuid\ **)**
        Given a UUID (as string) it returns the corresponding user name (as
        string).  In case of invalid UUID it raises NoUserName exception.  In
        case of error, it raises an AstakosClientException exception.

    **service_get_usernames(**\ uuids\ **)**
        Same as get_usernames but used with service tokens.

    **service_get_username(**\ uuid\ **)**
        Same as get_username but used with service tokens.

    **get_uuids(**\ display_names\ **)**
        Given a list of usernames it returns a displayname_catalog, that is a
        dictionary with the given usernames as keys and the corresponding UUIDs
        as values.  Invalid usernames will not be in the dictionary.  In case
        of error, it raises an AstakosClientException exception.

    **get_uuid(**\ display_name\ **)**
        Given a username (as string) it returns the corresponding UUID (as
        string).  In case of invalid user name it raises NoUUID exception.  In
        case of error, it raises an AstakosClientException exception.

    **service_get_uuids(**\ uuids\ **)**
        Same as get_uuids but used with service tokens.

    **service_get_uuid(**\ uuid\ **)**
        Same as get_uuid but used with service tokens.
115

116
    **get_services()**
117 118
        Return a list of dicts with the registered services.

119 120 121
    **get_resources()**
        Return a list of dicts with the available resources

122 123 124 125 126 127
    **send_feedback(**\ message, data\ **)**
        Send some feedback to astakos service. Additional information about the
        service client status can be given in the data variable.  In case of
        success it returns nothing.  Otherwise it raises an
        AstakosClientException exception.

128 129 130
    **get_endpoints()**
        It returns the services URLs one can access. In case of error it
        raises an AstakosClientException exception.
131 132 133 134 135

    **get_quotas()**
        It returns user's current quotas (as dict of dicts). In case of error
        it raises an AstakosClientException exception.

136
    **service_get_quotas(**\ user=None, project_id=None\ **)**
137 138
        It returns all users' current quotas for the resources associated with
        the service (as dict of dicts of dicts). Optionally, one can query the
139 140 141
        quotas of a specific user with argument user=UUID (or a list of UUID).
        Likewise one can specify a project (or a list of projects). In case of
        error it raises an AstakosClientException exception.
142

143
    **service_get_project_quotas(**\ project_id=None\ **)**
144 145 146
        It returns all projects' current quotas for the resources
        associated with the service (as dict of dicts).
        Optionally, one can query the quotas of a specific project with
147
        argument project_id=UUID (or a list of UUID). In case of error it raises an
148 149
        AstakosClientException exception.

150 151 152 153 154 155
    **issue_commission_generic(**\ user_provisions, project_provisions, name="", force=False, auto_accept=False\ **)**
        Issue a commission. User provisions are specified as a dict from
        (user, project, resource) to int; project provisions as a dict from
        (project, resource) to int.
        In case of success return commission's id (int).
        Otherwise raise an AstakosClientException exception.
156 157 158 159 160 161 162 163

    **issue_one_commission(**\ holder, source, provisions, name="", force=False, auto_accept=False\ **)**
        Issue a commission. We have to specify the holder, the source and the
        provisions (a dict from string to int) and astakosclient will create
        the corresponding commission. In case of success it returns
        commission's id (int). Otherwise it raises an AstakosClientException
        exception.

164
    **issue_resource_reassignment(**\ holder, provisions, name="", force=False, auto_accept=False\ **)**
165 166
        Change resource assignment to another project

167 168 169 170 171 172 173 174 175 176 177 178 179 180 181
    **get_pending_commissions()**
        It returns the pending commissions (list of integers). In case of
        error it raises an AstakosClientException exception.

    **get_commission_info(**\ serial\ **)**
        Given the id of a pending commission return a dict of dicts containting
        informations (details) about the requested commission.  In case of
        error it raises an AstakosClientException exception.

    **commission_action(**\ serial, action\ **)**
        Given the id of a pending commission, request the specified action
        (currently one of accept, reject).  In case of success it returns
        nothing.  Otherwise it raises an AstakosClientException exception.

    **accept_commission(**\ serial\ **)**
182 183
        Accept a pending commission (see commission_action).

184
    **reject_commission(**\ serial\ **)**
185 186
        Reject a pending commission (see commission_action).

187 188 189 190 191
    **resolve_commissions(**\ accept_serials, reject_serials\ **)**
        Accept or Reject many pending commissions at once.  In case of success
        return a dict of dicts describing which commissions accepted, which
        rejected and which failed to resolved. Otherwise raise an
        AstakosClientException exception.
192

193
    **get_projects(**\ name=None, state=None, owner=None, mode=None\ **)**
194 195
        Retrieve all accessible projects

196
    **get_project(**\ project_id\ **)**
197 198
        Retrieve project description, if accessible

199
    **create_project(**\ specs\ **)**
200 201
        Submit application to create a new project

202
    **modify_project(**\ project_id, specs\ **)**
203 204
        Submit application to modify an existing project

205
    **project_action(**\ project_id, action, reason=""\ **)**
206 207
        Perform action on a project

208 209
    **application_action(**\ project_id, app_id, action, reason=""\ **)**
        Perform action on a project application
210

211
    **get_memberships(**\ project_id=None\ **)**
212 213
        Retrieve all accessible memberships

214
    **get_membership(**\ memb_id\ **)**
215 216
        Retrieve membership description, if accessible

217
    **membership_action(**\ memb_id, action, reason=""\ **)**
218 219
        Perform action on a membership

220
    **join_project(**\ project_id\ **)**
221 222
        Join a project

223
    **enroll_member(**\ project_id, email\ **)**
224
        Enroll a user in a project
225 226 227 228

Public Functions
----------------

229
**get_token_from_cookie(**\ request, cookie_name\ **)**
230 231
    Given a Django request object and an Astakos cookie name
    extract the user's token from it.
232

233 234 235 236 237
**parse_endpoints(**\ endpoints, ep_name=None, ep_type=None, ep_region=None, ep_version_id=None\ **)**
    Parse the endpoints (acquired using *get_endpoints*) and extract the ones
    needed.  Return only the endpoints that match all of the given criterias.
    If no match is found then raise NoEndpoints exception.

238 239 240 241 242 243

Exceptions and Errors
=====================

*exception* **AstakosClientException**
    Raised in case of an error. It contains an error message and the
244 245
    corresponding http status code. Other exceptions raised by astakosclient
    module are derived from this one.
246 247 248 249 250

*exception* **BadValue**
    A redefinition of ValueError exception under AstakosClientException.

*exception* **InvalidResponse**
251 252
    This exception is raised whenever the server's response is not valid json
    (cannot be parsed by simplejson library).
253 254 255 256 257 258 259 260

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

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

*exception* **Forbidden**
261 262
    The server understood the request, but is refusing to fulfill it. Status
    401.
263 264 265 266

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

267 268 269
*exception* **QuotaLimit**
    Quantity fell below zero or exceeded capacity in one of the holdings.

270
*exception* **NoUserName**
271 272
    Raised by getDisplayName and getServiceDisplayName when an invalid UUID was
    given.
273 274

*exception* **NoUUID**
275 276 277 278 279 280
    Raised by *getUUID* and *getServiceUUID* when an invalid username was
    given.

*exception* **NoEndpoints**
    Raised by *parse_endpoints* when no endpoints found matching the given
    criteria.