TOTP implementation mostly finalize

TOTP module reworked drastically. Should have committed this a long time ago.
Now have what is (hopefully) the final API for the TOTP module.

* Supports TOTP & HOTP
* Supports URI rendering & parsing
* Highlevel methods to handle state management, client clock skew estimation, etc.
* Unittests mostly complete (a few edge cases)
* Persistent serialization supports encrypting secrets with a password,
  to mitigate exposure of storage medium.
* Basic API documentation.

Should be suitable for following use-cases:

* lowlevel methods for implementing HOTP/TOTP on server
* highlevel methods for implementing HOTP/TOTP on server,
  and letting them handle details of tracking client state.
* methods for implementing an HOTP / TOTP client.

5 files changed, 89 insertions, 7 deletions

diff --git a/docs/conf.py b/docs/conf.py
index c5b275c..89e0b0d 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -51,18 +51,12 @@ extensions = [
     'sphinx.ext.autodoc',
     'sphinx.ext.todo',
 
-    # add autodoc support for ReST sections in class/function docstrings
-    'cloud_sptheme.ext.autodoc_sections',
-
     # adds extra ids & classes to genindex html, for additional styling
     'cloud_sptheme.ext.index_styling',
 
     # inserts toc into right hand nav bar (ala old style python docs)
     'cloud_sptheme.ext.relbar_toc',
 
-    # replace sphinx :samp: role handler with one that allows escaped {} chars
-    'cloud_sptheme.ext.escaped_samp_literals',
-
     # add "issue" role
     'cloud_sptheme.ext.issue_tracker',
 
@@ -71,6 +65,12 @@ extensions = [
 
     # modify logo per page
     'cloud_sptheme.ext.perpage',
+
+    # monkeypatch sphinx to support a few extra things we can't do with extensions.
+    'cloud_sptheme.ext.autodoc_sections',
+    'cloud_sptheme.ext.autoattribute_search_bases',
+    'cloud_sptheme.ext.docfield_markup',
+    'cloud_sptheme.ext.escaped_samp_literals',
     ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -200,7 +200,7 @@ perpage_html_logo = {
 # The name of an image file (within the static path) to use as favicon of the
 # docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
 # pixels large.
-html_favicon = "logo.ico"
+html_favicon = os.path.join("_static", "logo.ico")
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
diff --git a/docs/contents.rst b/docs/contents.rst
index 700735f..3ad2ced 100644
--- a/docs/contents.rst
+++ b/docs/contents.rst
@@ -21,6 +21,7 @@ Table Of Contents
     lib/passlib.apache
     lib/passlib.ext.django
     lib/passlib.pwd
+    lib/passlib.totp
 
     lib/passlib.exc
     lib/passlib.registry
diff --git a/docs/index.rst b/docs/index.rst
index 08d8a61..48e2b70 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -99,6 +99,9 @@ Application Helpers
     :mod:`passlib.pwd`
         Password generation helpers.
 
+    :mod:`passlib.totp`
+        TOTP / Two Factor Authentication
+
 ..
     Support Modules
     ---------------
diff --git a/docs/lib/passlib.exc.rst b/docs/lib/passlib.exc.rst
index 96be468..a82cdaf 100644
--- a/docs/lib/passlib.exc.rst
+++ b/docs/lib/passlib.exc.rst
@@ -17,6 +17,8 @@ Exceptions
 
 .. autoexception:: PasswordSizeError
 
+.. autoexception:: TokenReuseError
+
 Warnings
 ========
 .. autoexception:: PasslibWarning
diff --git a/docs/lib/passlib.totp.rst b/docs/lib/passlib.totp.rst
new file mode 100644
index 0000000..2b4aae8
--- /dev/null
+++ b/docs/lib/passlib.totp.rst
@@ -0,0 +1,76 @@
+.. module:: passlib.totp
+    :synopsis: totp / two factor authentaction
+
+=======================================================
+:mod:`passlib.totp` -- TOTP / Two Factor Authentication
+=======================================================
+
+.. versionadded:: 1.7
+
+.. todo::
+
+    This module is still a work in progress, it's API may change before release.
+
+    Things left:
+
+    * finish unittests (there are a few cases left)
+    * write narrative documentation
+    * get api documentation formatted better (whether by getting nested sections integrated into TOC,
+      or splitting nested sections out into separate sections / pages).
+    * probably want a "beta" release of passlib so people can test this a bit before 1.7.0.
+
+    Optional:
+
+    * more verification against other TOTP servers & clients.
+    * consider native pyqrcode integration (e.g. a ``to_qrcode()`` method)
+
+.. rst-class:: emphasize-children
+
+API Reference
+=============
+
+Common Interface
+----------------
+.. autoclass:: BaseOTP()
+
+TOTP (Timed-based tokens)
+-------------------------
+.. autoclass:: TOTP(key=None, format="base32", \*, new=False, \*\*kwds)
+
+Helper Classes
+..............
+
+.. autoclass:: TotpToken()
+
+.. autoclass:: TotpMatch()
+
+HOTP (Counter-based tokens)
+---------------------------
+.. note::
+
+    HOTP is used much less frequently, since it's fragile
+    (as it's much easier for the server & client to get out of sync in their token
+    count). Unless you have a particular reason, you probably want :class:`TOTP` instead.
+
+.. autoclass:: HOTP(key=None, format="base32", \*, new=False, \*\*kwds)
+
+Helper Classes
+..............
+
+.. autoclass:: HotpMatch()
+
+Deviations
+==========
+
+* The TOTP Spec [#totpspec]_ includes an potentially offset from the base time (``T0``).
+  Passlib omits this (fixing it at ``0``), but so do pretty much all other TOTP implementations.
+
+.. rubric:: Footnotes
+
+.. [#hotpspec] HOTP Specification - :rfc:`4226`
+
+.. [#totpspec] TOTP Specification - :rfc:`6238`
+
+.. [#uriformat] Google's OTPAuth URI format -
+       `<https://code.google.com/p/google-authenticator/wiki/KeyUriFormat>`_
+