Guide

The RestAuthClient library consists of four modules, each containing one important class:

  • common contains RestAuthConnection which represents a connection to a RestAuth service.
  • restauth_user contains the User class which represents a user in the RestAuth service.
  • group contains the Group class which represents a group in the RestAuth service.
  • error is a collection of exceptions that may be thrown by the above modules and its member methods/classes.

To use RestAuth, you will always have to create a RestAuthConnection first and then use it to get users or groups.

The following example should give you a very good idea of how the library handles, error handling is skipped for the sake of clarity. Please see the Error handling section for the exceptions used in this library.

from RestAuthClient import common, restauth_user, group

# create a connection to the RestAuth service. The service must already be configured using the
# restauth-service commandline script.
conn = common.RestAuthConnection( 'https://auth.example.com', 'service', 'password' )

# create a *new* user named 'foobar', and do some interesting things:
user = restauth_user.create( conn, 'foobar', 'password' )
if not user.verify_password( 'wrong password' ):
    print( 'ERROR: User has wrong password!' ) # never happens in this example, of course

user.set_property( 'key', 'value' )
props = user.get_properties() # returns {'key': 'value'}

# If performance is critical, do not use the factory methods to get user objects, instead
# reference them directly:
user = restauth_user.User( conn, 'foobar' )
user.verify_password( 'password' )

# Groups work in much the same way as users:
group = group.get( conn, 'groupname' ) # verifies that the group exists
group.add_user( user ) # may also just be the username!
group.get_members() # returns a list with the User element

Error handling

Like all RestAuth client libraries, the python client library features many custom exceptions with a multi-leveled inheritance model. This allows you to handle problems with whatever granularity you want.

Since the Python library is the reference implementation, many other libraries feature a similar or even identical Exception class-hierarchy. Since both the RestAuth server reference implementation and RestAuthClient use the same exceptions for error handling, most exceptions are located in RestAuthCommon.error. For an introduction on how to use those exceptions, please see the error handling chapter in the RestAuthCommon documentation.

RestAuthClient provides a view additional exceptions that only make sense at the client side. Please see the error module for more documentation.