Update README

The readme has been updated to represent the current state of
the project.

Closes #8

README.txt

@@ -1,29 +1,37 @@
-========
-PyGSSAPI
-========
+=============
+Python-GSSAPI
+=============
 
 .. role:: python(code)
    :language: python
 
 .. role:: bash(code)
    :language: bash
 
-PyGSSAPI provides both low-level and high level wrappers around the GSSAPI
+Python-GSSAPI provides both low-level and high level wrappers around the GSSAPI
 C libraries.  While it focuses on the Kerberos mechanism, it should also be
-useable with other GSSAPI mechanisms that do not rely on mechanism-specific
-C values that cannot easily be translated into Python.
+useable with other GSSAPI mechanisms.
 
 Requirements
 ============
 
+Basic
+-----
+
 * A working implementation of GSSAPI (such as from MIT Kerberos)
   which includes header files
 
 * a C compiler (such as GCC)
 
-* Cython (*NEW*, to compile from scratch)
+* either the `enum34` Python package or Python 3.4+
+
+Compiling from Scratch
+----------------------
+
+To compile from scratch, you will need Cython >= 0.21.1.
 
-* the `flufl.enum` Python package
+For Running the Tests
+---------------------
 
 * the `nose` package (for tests)
 
@@ -32,12 +40,12 @@ Requirements
 Installation
 ============
 
-Easy Way 
+Easy Way
 --------
 
 .. code-block:: bash
 
-    $ pip install pygssapi
+    $ pip install gssapi
 
 From the Git Repo
 -----------------
@@ -51,119 +59,69 @@ From the Git Repo
 Tests
 =====
 
-I have written some tests of PyGSSAPI; they live in the `gssapi.tests`
-directory.  Currently the basic :python:`gssapi.raw` commands and
-:python:`gssapi.client.BasicGSSClient` have been tested.  Before running
-the tests, a valid 'host/[FQDN]' (e.g. 'host/some.domain') must have been
-:bash:`kinit`-ed.  If you run :bash:`tox`, it will do this for you (you will
-likely need to run :bash:`tox` with :bash:`sudo`).
-
-.. code-block:: bash
-
-   $ sudo tox
-
-or 
-
-.. code-block:: bash
-
-   $ sudo kinit host/some.domain -k
-   $ sudo setup.py nosetests
+The tests for for Python-GSSAPI live in `gssapi.tests`.  In order to
+run the tests, you must have an MIT Kerberos installation (including
+the KDC).  The tests create a self-contained Kerberos setup, so running
+the tests will not interfere with any existing Kerberos installations.
 
 Structure
 =========
 
-PyGSSAPI is composed of two parts: the low-level, C-style wrapper and the
-high-level, Python-style wrapper (which is a wrapper around the low-level
-API).  Modules written in C are denoted by '(C)', whereas those written
-in Python are denoted '(Py)'
+Python-GSSAPI is composed of two parts: a low-level C-style API which
+thinly wraps the underlying RFC 2744 methods, and a high-level, Pythonic
+API (which is itself a wrapper around the low-level API).  Examples may
+be found in the `examples` directory.
 
 Low-Level API
 -------------
 
 The low-level API lives in `gssapi.raw`.  The methods contained therein
-are designed to match closely with the original GSSAPI C methods.  They
-follow the given format:
+are designed to match closely with the original GSSAPI C methods.  All
+relevant methods and classes may be imported directly from `gssapi.raw`.
+Extension methods will only be imported if they are present.  The low-level
+API follows the given format:
 
-* Names are camelCased versions of the C method names, with the 
-  :python:`gssapi_` prefix removed
+* Names match the RFC 2744 specification, with the :python:`gssapi_`
+  prefix removed
 
-* Parameters which use C int constants as enums have 
-  :python:`flufl.enum.IntEnum` classes defined, and thus may be passed
+* Parameters which use C int constants as enums have
+  :python:`enum.IntEnum` classes defined, and thus may be passed
   either the enum members or integers
 
 * In cases where a specific constant is passed in the C API to represent
   a default value, :python:`None` should be passed instead
 
-* In cases where non-integer C constants are passed, `flufl.enum.Enum`
-  classes are defined for common values
+* In cases where non-integer constants would be used in the API (i.e.
+  OIDs), enum-like objects have been defined containing named references
+  to values specified in RFC 2744.
 
-* Major and minor error codes are returned via :python:`gssapi.raw.GSSError`
+* Major and minor error codes are returned by raising
+  :python:`gssapi.raw.GSSError`.  The major error codes have exceptions
+  defined in in `gssapi.raw.exceptions` to make it easier to catch specific
+  errors or categories of errors.
 
-* All other relevant output values are returned in a tuple in the return
-  value of the method (in cases where a non-error major status code may
-  be returned, an additional member of the tuple is provided)
+* All other relevant output values are returned via named tuples.
 
-Structure
-~~~~~~~~~
-
-gssapi : /
-    base : /
-        *includes all sub-packages automatically*
-
-        impl : (C)
-            core C-API methods
-        status_utils : (C)
-            utilities for dealing with status codes
-        types : (Py)
-            Enumerations and Exception Types
+High-Level API
+--------------
 
-Examples
-~~~~~~~~
+The high-level API lives directly under :python:`gssapi`.  The classes
+contained in each file are designed to provide a more Pythonic, Object-Oriented
+view of GSSAPI.  The exceptions from the low-level API, plus several additional
+exceptions, live in `gssapi.exceptions`.  The rest of the classes may be
+imported directly from `gssapi`.  Only classes are exported by `gssapi` --
+all functions are methods of classes in the high-level API.
 
-.. code-block:: python
+Please note that QoP is not supported in the high-level API, since it has been
+deprecated.
 
-    import gssapi.raw as gb
+Extensions
+----------
 
-TODO(sross): provide more examples
+In addition to RFC 2743/2744, Python-GSSAPI also has support for:
 
-High-Level API
---------------
+* RFC 5588 (GSS-API Extension for Storing Delegated Credentials)
 
-The high-level API lives directly under :python:`gssapi`.  The classes 
-contained in each file are designed to provide a more Python, Object-Oriented
-view of GSSAPI.  Currently, they are designed for the basic GSSAPI tasks, but
-will be expanded upon in the future.
+* (Additional) Credential Store Extension
 
-Structure
-~~~~~~~~~
-
-gssapi : /
-    client : (Py)
-        *basic clients*
-
-        BasicGSSClient
-            a client capable of performing basic GSS negotiation/encryption
-        BasicSASLGSSClient
-            a helper class to simplify working with SASL GSSAPI
-    type_wrappers : (Py)
-        provides useful wrappers around some Python capsule objects
-
-Examples
-~~~~~~~~
-
-.. code-block:: python
-
-    import gssapi.client as gss
-
-    client = gss.BasicGSSClient('vnc@some.host', security_type='encrypted')
-
-    init_token = client.setupBaseSecurityContext()
-    # send to server, get response back...
-    next_token = client.updateSecurityContext(server_resp)
-    # encrypt a message
-    msg_enc = client.encrypt('WARNING: this is secret')
-    # send the message, get response back...
-    msg_unenc = client.decrypt(server_encrypted_message)
-
-    # freeing of resources (such as deleting the security context and releasing
-    # the names) is handled automatically
+* Services4User