From 21e304de48eb24f7c7aad0557290e5402a95cb50 Mon Sep 17 00:00:00 2001
From: Laurens Van Houtven <lvh@laurensvh.be>
Date: Mon, 2 Mar 2009 12:10:18 +0100
Subject: [PATCH] SQLiteHandler: doc improvements + api update

The SQLiteHandler now supports **kwargs and passes them on to the constructor of its superclass. This means it now supports all those fancy new features like per-handler logging.

Also improved the docs for it. A lot :-)
---
 code/breadcrumb/server/handlers/sqlite.py | 45 ++++++++++++++++++++++++++-----
 1 file changed, 38 insertions(+), 7 deletions(-)

diff --git a/code/breadcrumb/server/handlers/sqlite.py b/code/breadcrumb/server/handlers/sqlite.py
index 507e888..6b9a778 100644
--- a/code/breadcrumb/server/handlers/sqlite.py
+++ b/code/breadcrumb/server/handlers/sqlite.py
@@ -21,31 +21,62 @@ import logging
 import base
 
 class SQLiteHandler(base.BaseHandler):
-    """ A handler that writes new data points to a SQLite database. """
+    """A handler that writes new data points to a SQLite database.
+    
+    This uses the ``sqlite3`` module, which is a builtin on recent versions of
+    Python. It (obviously) still requires you to install SQLite itself.
 
-    def __init__(self, filename = "breadcrumb.db"):
-        BaseHandler.__init__(self, identifiers = ('\x10', '\x12'))
+    This handler is not entirely deprecated, but using the SQLAlchemy-based
+    handler is strongly preferred.
+
+    :parameter: ``filename`` (string)
+
+        The filename of the SQLite database.
+
+    :parameter: ``table`` (string)
+        
+        The name of the table in the SQLite database.
+
+    :parameter: ``initialize`` (boolean)
+        
+        If this evaluates to True (default), creates the database table. Useful
+        for new files.
+    """
+
+    def __init__(self,
+                 filename = "breadcrumb.db",
+                 table = 'breadcrumb', initialize = True,
+                 **kwargs):
+        BaseHandler.__init__(self, identifiers = ('\x10', '\x12'), **kwargs)
                 
         self.connection = sqlite3.connect(filename)
         self.cursor = self.connection.cursor()
         
-        self.table = 'breadcrumb'
+        self.table = tablename
+
+        if initialize:
+            create_table()
 
     def create_table(self):
-        """Initialises the database by creating the right tables."""
+        """Prepares the database for incoming points by creating the table."""
         
         sql = "create table %s (time int, lat real, lon real)" % self.table
         self._execute(sql)
 
     def newpoint(self, point):
-        """ Adds a point to the database. """
+        """Adds a point to the database.
+        
+        :parameter: ``point`` (dict)
+
+            The point that will be added to the database.
+        """
         
         sql = "insert into %s values ('%s', '%s', '%s')"\
             % (self.table, timestamp, latitude, longitude)
         self._execute(sql)
 
     def _execute(self, sql):
-        """ Executes a given SQL string. """
+        """Executes a given SQL string."""
         logging.debug("sqlitehandler, executing: %s" % sql)
         self.cursor.execute(sql)
         self.connection.commit()
-- 
2.11.4.GIT