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

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

6
The Synnefo component :ref:`astakosclient <astakosclient>` defines a
7 8 9 10
default client for the :ref:`Astakos <astakos>` service. It is designed to be
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 41

.. code-block:: python

    from astakosclient import AstakosClient

    client = AstakosClient("https://accounts.example.com")
42
    user_info = client.get_user_info("UQpYas7ElzWGD5yCcEXtjw")
43 44
    print user_info['username']

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

.. code-block:: python

    from astakosclient import AstakosClient

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


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

61
This section describes in depth the API of ``astakosclient``.
62 63 64 65 66 67 68 69 70 71 72 73 74

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

*class* astakosclient.\ **AstakosClient(**\ astakos_url,
retry=0, use_pool=False, pool_size=8, logger=None\ **)**

    Initialize an instance of **AstakosClient** given the *astakos_url*.
    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:

75
    **get_user_info(**\ token, usage=False\ **)**
76
        Given a user's authentication token it returns a dict with the
77 78 79 80
        correspoinding user's info. If usage is set to True more
        information about user's resources will be returned.
        In case of error raise an AstakosClientException exception.

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 85
        UUIDs as keys and the corresponding user names as values.
        Invalid UUIDs will not be in the dictionary.
86 87
        In case of error raise an AstakosClientException exception.

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 93
        In case of error raise an AstakosClientException exception.

94 95
    **service_get_usernames(**\ token, uuids\ **)**
        Same as get_usernames but called with a service's token.
96

97 98
    **service_get_username(**\ token, uuid\ **)**
        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 105 106
        Invalid usernames will not be in the dictionary.
        In case of error raise an AstakosClientException exception.

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 111 112
        In case of invalid user name raise NoUUID exception.
        In case of error raise an AstakosClientException exception.

113 114
    **service_get_uuids(**\ token, uuids\ **)**
        Same as get_uuids but called with a service's token.
115

116 117
    **service_get_uuid(**\ token, uuid\ **)**
        Same as get_uuid but called with a service's token.
118

119
    **get_services()**
120 121
        Return a list of dicts with the registered services.

122 123 124
    **get_resources()**
        Return a list of dicts with the available resources

125 126 127 128 129 130 131
    **send_feedback(**\ token, message, data\ **)**
        Using a user's authentication token send some feedback to
        astakos service. Additional information about the service
        client status can be given in the data variable.
        In case of success returns nothing.
        Otherwise raise an AstakosClientException exception.

132
    **get_endpoints(**\ token, uuid=None\ **)**
133 134 135 136
        Fallback call which receives the user token or the user uuid/token
        and returns back the token as well as information about the token
        holder and the services he/seh can access.
        In case of error raise an AstakosClientException exception.
137

138 139 140 141 142
    **get_quotas(**\ token\ **)**
        Given a user's authentication token return user's
        current quotas (as dict of dicts).
        In case of error raise an AstakosClientException exception.

143
    **service_get_quotas(**\ token, user=None\ **)**
144 145 146
        Given a service's authentication token return all users'
        current quotas for the resources associated with the service
        (as dict of dicts of dicts).
147 148
        Optionally, one can query the quotas of a specific user with
        argument user=UUID.
149 150
        In case of error raise an AstakosClientException exception.

151 152 153 154 155
    **issue_commission(**\ token, request\ **)**
        Given a service's authentication token issue a commission.
        In case of success return commission's id (int).
        Otherwise raise an AstakosClientException exception.

156
    **issue_one_commission(**\ token, holder, source, provisions, name="", force=False, auto_accept=False\ **)**
157 158
        Given a service's authentication token issue a commission.
        In this case we specify the holder, the source and the provisions
159
        (a dict from string to int) and astakosclient will create the
160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194
        corresponding commission.
        In case of success return commission's id (int).
        Otherwise raise an AstakosClientException exception.

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

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

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

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

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

    **resolve_commissions(**\ token, 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.

195 196 197 198

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

199
**get_token_from_cookie(**\ request, cookie_name\ **)**
200 201
    Given a Django request object and an Astakos cookie name
    extract the user's token from it.
202 203 204 205 206 207 208


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

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

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

*exception* **InvalidResponse**
    This exception is raised whenever the server's response is not
    valid json (cannot be parsed by simplejson library).
218 219 220 221 222 223 224 225 226 227 228 229 230 231

*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**
    The server understood the request, but is refusing to fulfill it.
    Status 401.

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

232 233 234
*exception* **QuotaLimit**
    Quantity fell below zero or exceeded capacity in one of the holdings.

235
*exception* **NoUserName**
236
    Raised by getDisplayName and getServiceDisplayName when an invalid
237
    UUID was given.
238 239 240 241

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