Add tests and docs.

Author: Ramiro Morales

docs/_mssql_examples.rst

@@ -87,9 +87,9 @@ An example of exception handling
 
     import _mssql
 
+    conn = _mssql.connect(server='SQL01', user='user', password='password',
+                          database='mydatabase')
     try:
-        conn = _mssql.connect(server='SQL01', user='user', password='password',
-                              database='mydatabase')
         conn.execute_non_query('CREATE TABLE t1(id INT, name VARCHAR(50))')
     except _mssql.MssqlDatabaseException as e:
         if e.number == 2714 and e.severity == 16:
@@ -99,4 +99,36 @@ An example of exception handling
     finally:
         conn.close()
 
+Custom message handlers
+=======================
+
+You can provide your own message handler callback function that will be called
+by the stack with informative messages send by the server. Set it by `_mssql`
+connection by using the `set_msghandler` method:
+
+.. code-block:: python
+
+    import _mssql
+
+    def my_msg_handler(msgstate, severity, srvname, procname, line, msgtext):
+        """
+        Our custom handler -- It simpy prints a string to stdout assembled from
+        the pieces of information sent by the server.
+        """
+        print("my_msg_handler: msgstate = %d, severity = %d, procname = '%s', "
+              "line = %d, msgtext = '%s'" % (msgstate, severity, procname,
+                                             line, msgtext))
+
+    conn = _mssql.connect(server='SQL01', user='user', password='password')
+    try:
+        conn.set_msghandler(my_msg_handler)  # Install our custom handler
+        cnx.execute_non_query("USE mydatabase")  # It gets called at this point
+    finally:
+        conn.close()
+
+Something similar to this would be printed to the standard output::
+
+    my_msg_handler: msgstate = x, severity = y, procname = '', line = 1, msgtext = 'Changed database context to 'mydatabase'.'
+
+
 .. todo:: Add an example of invoking a Stored Procedure using ``_mssql``.

docs/ref/_mssql.rst

@@ -251,6 +251,20 @@ Functions
    These methods facilitate the Python iterator protocol. You most likely will not
    call them directly, but indirectly by using iterators.
 
+.. method:: MSSQLConnection.set_msghandler(handler)
+
+   This method allows setting a message handler function for the connection to
+   allow a client to gain access to the messages returned from the server.
+
+   The signature of the message handler function *handler* passed to this
+   method must be::
+
+        def my_msg_handler(msgstate, severity, srvname, procname, line, msgtext):
+            # The body of the message handler.
+
+   *msgstate*, *severity* and *line* will be integers, *srvname*, *procname* and
+   *msgtext* will be strings.
+
 ``MSSQLStoredProcedure`` class
 ==============================
 

tests/test_user_msghandler.py

@@ -0,0 +1,136 @@
+try:
+    import unittest2 as unittest
+except ImportError:
+    import unittest
+
+from .helpers import config, mssqlconn
+
+msgs = []
+
+
+def user_msg_handler1(msgstate, severity, srvname, procname, line, msgtext):
+    global msgs
+    entry = ("msg_handler1: msgstate = %d, severity = %d, procname = '%s', "
+             "line = %d, msgtext = '%s'") % (msgstate, severity, procname, line, msgtext)
+    msgs.append(entry)
+
+
+def user_msg_handler2(msgstate, severity, srvname, procname, line, msgtext):
+    global msgs
+    entry = ("msg_handler2: msgstate = %d, severity = %d, procname = '%s', "
+             "line = %d, msgtext = '%s'") % (msgstate, severity, procname, line, msgtext)
+    msgs.append(entry)
+
+
+def wrong_signature_msg_handler():
+    pass
+
+
+class TestUserMsgHandler(unittest.TestCase):
+
+    def test_basic_functionality(self):
+        cnx = mssqlconn()
+        try:
+            cnx.set_msghandler(user_msg_handler1)
+            msgs_before = len(msgs)
+            cnx.execute_non_query("USE master")
+            msgs_after = len(msgs)
+            delta = msgs_after - msgs_before
+            self.assertEqual(delta, 1)
+            expect = ("msg_handler1: msgstate = 1, severity = 0, procname = ''"
+                      ", line = 1, msgtext = 'Changed database context to 'master'.'")
+            self.assertEqual(expect, msgs[msgs_after - 1])
+        finally:
+            cnx.close()
+
+    def test_set_handler_to_none(self):
+        cnx = mssqlconn()
+        try:
+            cnx.set_msghandler(None)
+            msgs_before = len(msgs)
+            cnx.execute_non_query("USE master")
+            msgs_after = len(msgs)
+            delta = msgs_after - msgs_before
+            self.assertEqual(delta, 0)
+        finally:
+            cnx.close()
+
+    def test_change_handler(self):
+        cnx = mssqlconn()
+        try:
+            cnx.set_msghandler(user_msg_handler1)
+            msgs_before = len(msgs)
+            cnx.execute_non_query("USE master")
+            msgs_after = len(msgs)
+            delta = msgs_after - msgs_before
+            self.assertEqual(delta, 1)
+            expect = ("msg_handler1: msgstate = 1, severity = 0, procname = ''"
+                      ", line = 1, msgtext = 'Changed database context to 'master'.'")
+            self.assertEqual(expect, msgs[msgs_after - 1])
+
+            cnx.set_msghandler(user_msg_handler2)
+            msgs_before = len(msgs)
+            cnx.execute_non_query("USE %s" % config.database)
+            msgs_after = len(msgs)
+            delta = msgs_after - msgs_before
+            self.assertEqual(delta, 1)
+            expect = ("msg_handler2: msgstate = 1, severity = 0, procname = ''"
+                      ", line = 1, msgtext = 'Changed database context to '%s'.'") % config.database
+            self.assertEqual(expect, msgs[msgs_after - 1])
+        finally:
+            cnx.close()
+
+    def test_per_conn_handlers(self):
+        cnx1 = mssqlconn()
+        cnx2 = mssqlconn()
+        try:
+            cnx1.set_msghandler(user_msg_handler1)
+            msgs_before = len(msgs)
+            cnx1.execute_non_query("USE master")
+            msgs_after = len(msgs)
+            delta = msgs_after - msgs_before
+            self.assertEqual(delta, 1)
+            expect = ("msg_handler1: msgstate = 1, severity = 0, procname = ''"
+                      ", line = 1, msgtext = 'Changed database context to 'master'.'")
+            self.assertEqual(expect, msgs[msgs_after - 1])
+
+            cnx2.set_msghandler(user_msg_handler2)
+            msgs_before = len(msgs)
+            cnx2.execute_non_query("USE %s" % config.database)
+            msgs_after = len(msgs)
+            delta = msgs_after - msgs_before
+            self.assertEqual(delta, 1)
+            expect = ("msg_handler2: msgstate = 1, severity = 0, procname = ''"
+                      ", line = 1, msgtext = 'Changed database context to '%s'.'") % config.database
+            self.assertEqual(expect, msgs[msgs_after - 1])
+        finally:
+            cnx1.close()
+            cnx2.close()
+
+    @staticmethod
+    def user_msg_handler3(msgstate, severity, srvname, procname, line, msgtext):
+        global msgs
+        entry = ("msg_handler3 called")
+        msgs.append(entry)
+
+    def test_static_method_handler(self):
+        cnx = mssqlconn()
+        try:
+            cnx.set_msghandler(self.user_msg_handler3)
+            msgs_before = len(msgs)
+            cnx.execute_non_query("USE master")
+            msgs_after = len(msgs)
+            delta = msgs_after - msgs_before
+            self.assertEqual(delta, 1)
+            expect = ("msg_handler3 called")
+            self.assertEqual(expect, msgs[msgs_after - 1])
+        finally:
+            cnx.close()
+
+    def test_wrong_signature_handler(self):
+        cnx = mssqlconn()
+        try:
+            cnx.set_msghandler(wrong_signature_msg_handler)
+            cnx.execute_non_query("USE master")
+        finally:
+            cnx.close()