Expand README.

Author: josiah-wolf-oberholtzer

README.rst

@@ -1,7 +1,13 @@
 python-cas-client
 =================
 
-A python CAS client
+A Python CAS (Central Authentication Service) client for interfacing with a CAS
+service implementation, such as https://github.com/rbCAS/CASino or
+https://github.com/apereo/cas.
+
+This project provides tools for building well-formed CAS-related URLs, parsing
+CAS XML payloads and managing the server-side session stores necessary for
+handling SLO (single logout).
 
 Installation
 ------------
@@ -18,6 +24,60 @@ Supports Python 2.7 and 3.4.
 Testing
 -------
 
+``cas_client`` uses ``tox`` to run its unit tests under Python 2.7 and 3.4.
+
 ::
 
     python-cas-client$ tox
+
+Example
+-------
+
+The following un-tested pseudo-code shows how you might use ``cas_client`` in a
+Flask project.
+
+::
+
+    from cas_client import CASClient
+    from flask import Flask, redirect, request, session, url_for
+
+    app = Flask(__name__)
+
+    app_login_url = 'http://www.my-app.com/login'
+    cas_url = 'http://cas.my-app.com'
+    cas_client = CASClient(cas_url, auth_prefix='')
+
+    @app.route('/login')
+    def login():
+        ticket = request.args.get('ticket')
+        if ticket:
+            try:
+                cas_response = cas_client.perform_service_validate(
+                    ticket=ticket,
+                    service_url=app_login_url,
+                    )
+            except:
+                # CAS server is currently broken, try again later.
+                return redirect(url_for('root'))
+            if cas_response and cas_response.success:
+                session['logged-in'] = True
+                return redirect(url_for('root'))
+        del(session['logged-in'])
+        cas_login_url = cas_client.get_login_url(service_url=app_login_url)
+        return redirect(cas_login_url)
+
+    @app.route('/logout')
+    def logout():
+        del(session['logged-in'])
+        cas_logout_url = cas_client.get_logout_url(service_url=app_login_url)
+        return redirect(cas_logout_url)
+
+    @app.route('/')
+    def root():
+        if session.get('logged-in'):
+            return 'You Are Logged In'
+        else:
+            return 'You Are Not Logged In'
+
+This pseudo-code does not handle server-side session stores or single logout,
+only the bare minimum for standard login and logout.

cas_client/_version.py

@@ -1,2 +1,2 @@
-__version_info__ = (0, 1, 0)
+__version_info__ = (0, 1, 1)
 __version__ = '.'.join(str(_) for _ in __version_info__)