sql work

========
* combined passlib.mysql, passlib.postgres -> passlib.sqldb
  (contents were too small to be worth multiple modules)
* added helper to read postgres plaintext passwords
* added documentation for passlib.sqldb

6 files changed, 47 insertions, 4 deletions

diff --git a/docs/lib/passlib.hash.mysql_323.rst b/docs/lib/passlib.hash.mysql_323.rst
index 9d14ea7..b81acf4 100644
--- a/docs/lib/passlib.hash.mysql_323.rst
+++ b/docs/lib/passlib.hash.mysql_323.rst
@@ -22,7 +22,7 @@ purpose but verifying existing MySQL 3.2.3 - 4.0 password hashes.
 
 Usage
 =====
-Users will most likely find the frontends provided by :mod:`passlib.mysql`
+Users will most likely find the frontends provided by :mod:`passlib.sqldb`
 to be more useful than accessing this module directly.
 That aside, this module can be used directly as follows::
 
diff --git a/docs/lib/passlib.hash.mysql_41.rst b/docs/lib/passlib.hash.mysql_41.rst
index ab8a6d5..85a0b71 100644
--- a/docs/lib/passlib.hash.mysql_41.rst
+++ b/docs/lib/passlib.hash.mysql_41.rst
@@ -23,7 +23,7 @@ purpose but verifying existing MySQL 4.1+ password hashes.
 
 Usage
 =====
-Users will most likely find the frontends provided by :mod:`passlib.mysql`
+Users will most likely find the frontends provided by :mod:`passlib.sqldb`
 to be more useful than accessing this module directly.
 That aside, this module can be used directly in the same manner
 as :mod:`~passlib.hash.mysql_323`.
diff --git a/docs/lib/passlib.hash.postgres_md5.rst b/docs/lib/passlib.hash.postgres_md5.rst
index a9bbd36..bbb6d9c 100644
--- a/docs/lib/passlib.hash.postgres_md5.rst
+++ b/docs/lib/passlib.hash.postgres_md5.rst
@@ -20,7 +20,7 @@ PostgreSQL account passwords.
 
 Usage
 =====
-Users will most likely find the frontend provided by :mod:`passlib.postgres`
+Users will most likely find the frontend provided by :mod:`passlib.sqldb`
 to be more useful than accessing this module directly.
 That aside, this module can be used directly as follows::
 
diff --git a/docs/lib/passlib.hash.sun_md5_crypt.rst b/docs/lib/passlib.hash.sun_md5_crypt.rst
index c8c9d9b..e4f91b6 100644
--- a/docs/lib/passlib.hash.sun_md5_crypt.rst
+++ b/docs/lib/passlib.hash.sun_md5_crypt.rst
@@ -50,6 +50,13 @@ An alternate format, ``$md5${salt}${checksum}`` is used when the rounds value is
     Solaris seems to deviates from the :ref:`modular-crypt-format` in that
     it considers ``$`` *or* ``,`` to indicate the end of the identifier.
 
+.. warning::
+
+    One of the remaining issues with this implementation is that some
+    existing hashes found on the web use a ``$`` where this uses ``,``.
+    It is unclear whether this is an accepted alternate format or not,
+    nor whether this affects the resulting hash.
+
 Algorithm
 =========
 The algorithm used is based around the MD5 message digest and the "Muffett Coin Toss" algorithm (so named
diff --git a/docs/lib/passlib.sqldb.rst b/docs/lib/passlib.sqldb.rst
new file mode 100644
index 0000000..baf3797
--- /dev/null
+++ b/docs/lib/passlib.sqldb.rst
@@ -0,0 +1,36 @@
+============================================
+:mod:`passlib.sqldb` - SQL Database Helpers
+============================================
+
+.. module:: passlib.unix
+    :synopsis: frontend for encrypting & verifying passwords used in various sql databases
+
+PostgreSQL
+==========
+This module provides a single pre-configured :class:`CryptContext` instance
+which should be capable of recognizing passwords in modern postgres systems:
+
+.. object:: postgres_context
+
+    This object should recognize password hashes stores in postgres' pg_shadow table.
+    it can recognize :mod:`~passlib.hash.postgres_md5` hashes,
+    as well as plaintext hashes.
+    It defaults to postgres_md5 when generating new hashes.
+
+    note that the username must be provided whenever encrypting or verifying a postgres hash.
+
+MySQL
+=====
+This module provides two pre-configured :class:`CryptContext` instances
+for handling MySQL user passwords:
+
+.. object:: mysql_context
+
+    This object should recognize the new :mod:`~passlib.hash.mysql_41` hashes,
+    as well as any legacy :mod:`~passlib.hash.mysql_323` hashes.
+    It defaults to mysql_41 when generating new hashes.
+
+.. object:: mysql3_context
+
+    This object is for use with older MySQL deploys which only recognize
+    the :mod:`~passlib.hash.mysql_323` hash.
diff --git a/docs/lib/passlib.unix.rst b/docs/lib/passlib.unix.rst
index 254a8f7..6d290ad 100644
--- a/docs/lib/passlib.unix.rst
+++ b/docs/lib/passlib.unix.rst
@@ -1,5 +1,5 @@
 ============================================
-:mod:`passlib.unix` - Unix Password Frontend
+:mod:`passlib.unix` - Unix Password Handling
 ============================================
 
 .. module:: passlib.unix