Guide¶
The RestAuthClient library consists of four modules, each containing one important class:
common
containsRestAuthConnection
which represents a connection to a RestAuth service.restauth_user
contains theUser
class which represents a user in the RestAuth service.group
contains theGroup
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.