From bd6aac020d913ecbe9f43e6dbb88651319e06a42 Mon Sep 17 00:00:00 2001
From: Ken Dreyer <ktdreyer@ktdreyer.com>
Date: Mar 02 2018 23:25:36 +0000
Subject: add README


Describe the purpose of the library, and give code examples.

---

diff --git a/MANIFEST.in b/MANIFEST.in
index 673a6cd..30c21f0 100644
--- a/MANIFEST.in
+++ b/MANIFEST.in
@@ -1,2 +1,3 @@
+include README.rst
 include COPYING
 include tests/*.py
diff --git a/README.rst b/README.rst
new file mode 100644
index 0000000..ad244d5
--- /dev/null
+++ b/README.rst
@@ -0,0 +1,41 @@
+Credentials Cache Collection Utilities
+--------------------------------------
+
+This module provides Kerberos 5 credential cache collection utilities for
+Python 2.6+ and 3.
+
+When a user authenticates to a Kerberos realm (eg. with ``kinit``), the user
+has a short-lived credential in a cache (view it with ``klist``).
+
+You can use this cccolutils module to easily determine if the user has any
+valid Kerberos credentials, or what the username is for a particular Kerberos
+realm.
+
+Usage
+-----
+
+Check if the user has any valid Kerberos credentials:
+
+.. code-block:: python
+
+    import cccolutils
+
+    authenticated = cccolutils.has_creds()
+    # authenticated is True or False
+    if authenticated:
+        print('This user has a valid Kerberos ticket in any credential cache.')
+    else:
+        print('no valid Kerberos ticket in any credential cache.')
+
+Check the username for the EXAMPLE.COM realm:
+
+.. code-block:: python
+
+    import cccolutils
+
+    username = cccolutils.get_user_for_realm('EXAMPLE.COM')
+    # username is a string or None
+    if username:
+        print('The user in the EXAMPLE.COM realm is %s' % username)
+    else:
+        print('No credential for the EXAMPLE.COM realm')