[Python-checkins] r66245 - in sandbox/trunk/dbm_sqlite: Doc Doc/library Doc/library/dbm.rst Lib Lib/dbm Lib/dbm/sqlite.py Lib/test Lib/test/test_dbm_sqlite.py

Sat Sep 6 04:54:02 CEST 2008

Author: skip.montanaro
Date: Sat Sep 6 04:54:02 2008
New Revision: 66245
Log:
Make a sandbox project out of this
Added:
 sandbox/trunk/dbm_sqlite/
 sandbox/trunk/dbm_sqlite/Doc/
 sandbox/trunk/dbm_sqlite/Doc/library/
 sandbox/trunk/dbm_sqlite/Doc/library/dbm.rst (contents, props changed)
 sandbox/trunk/dbm_sqlite/Lib/
 sandbox/trunk/dbm_sqlite/Lib/dbm/
 sandbox/trunk/dbm_sqlite/Lib/dbm/sqlite.py (contents, props changed)
 sandbox/trunk/dbm_sqlite/Lib/test/
 sandbox/trunk/dbm_sqlite/Lib/test/test_dbm_sqlite.py (contents, props changed)
Added: sandbox/trunk/dbm_sqlite/Doc/library/dbm.rst
==============================================================================

--- (empty file)
+++ sandbox/trunk/dbm_sqlite/Doc/library/dbm.rst	Sat Sep 6 04:54:02 2008
@@ -0,0 +1,325 @@
+:mod:`dbm` --- Interfaces to Unix "databases"
+=============================================
+
+.. module:: dbm
+ :synopsis: Interfaces to various Unix "database" formats.
+
+:mod:`dbm` is a generic interface to variants of the DBM database ---
+:mod:`dbm.bsd` (requires :mod:`bsddb`), :mod:`dbm.gnu`, or :mod:`dbm.ndbm`. If
+none of these modules is installed, the slow-but-simple implementation in module
+:mod:`dbm.dumb` will be used.
+
+
+.. exception:: error
+
+ A tuple containing the exceptions that can be raised by each of the supported
+ modules, with a unique exception also named :exc:`dbm.error` as the first
+ item --- the latter is used when :exc:`dbm.error` is raised.
+
+
+.. function:: whichdb(filename)
+
+ This functionattempts to guess which of the several simple database modules
+ available --- :mod:`dbm.bsd`, :mod:`dbm.gnu`, :mod:`dbm.ndbm` or
+ :mod:`dbm.dumb` --- should be used to open a given file.
+
+ Returns one of the following values: ``None`` if the file can't be opened
+ because it's unreadable or doesn't exist; the empty string (``''``) if the
+ file's format can't be guessed; or a string containing the required module
+ name, such as ``'dbm.ndbm'`` or ``'dbm.gnu'``.
+
+
+.. function:: open(filename[, flag[, mode]])
+
+ Open the database file *filename* and return a corresponding object.
+
+ If the database file already exists, the :func:`whichdb` function is used to
+ determine its type and the appropriate module is used; if it does not exist,
+ the first module listed above that can be imported is used.
+
+ The optional *flag* argument can be ``'r'`` to open an existing database for
+ reading only, ``'w'`` to open an existing database for reading and writing,
+ ``'c'`` to create the database if it doesn't exist, or ``'n'``, which will
+ always create a new empty database. If not specified, the default value is
+ ``'r'``.
+
+ The optional *mode* argument is the Unix mode of the file, used only when the
+ database has to be created. It defaults to octal ``0o666`` (and will be
+ modified by the prevailing umask).
+
+
+The object returned by :func:`open` supports most of the same functionality as
+dictionaries; keys and their corresponding values can be stored, retrieved, and
+deleted, and the :keyword:`in` operator and the :meth:`keys` method are
+available. Keys and values must always be strings.
+
+The following example records some hostnames and a corresponding title, and
+then prints out the contents of the database::
+
+ import dbm
+
+ # Open database, creating it if necessary.
+ db = dbm.open('cache', 'c')
+
+ # Record some values
+ db['www.python.org'] = 'Python Website'
+ db['www.cnn.com'] = 'Cable News Network'
+
+ # Loop through contents. Other dictionary methods
+ # such as .keys(), .values() also work.
+ for k, v in db.iteritems():
+ print(k, '\t', v)
+
+ # Storing a non-string key or value will raise an exception (most
+ # likely a TypeError).
+ db['www.yahoo.com'] = 4
+
+ # Close when done.
+ db.close()
+
+
+.. seealso::
+
+ Module :mod:`shelve`
+ Persistence module which stores non-string data.
+
+
+The individual submodules are described in the following sections.
+
+
+:mod:`dbm.gnu` --- GNU's reinterpretation of dbm
+------------------------------------------------
+
+.. module:: dbm.gnu
+ :platform: Unix
+ :synopsis: GNU's reinterpretation of dbm.
+
+
+This module is quite similar to the :mod:`dbm` module, but uses the GNU library
+``gdbm`` instead to provide some additional functionality. Please note that the
+file formats created by ``gdbm`` and ``dbm`` are incompatible.
+
+The :mod:`dbm.gnu` module provides an interface to the GNU DBM library.
+``gdbm`` objects behave like mappings (dictionaries), except that keys and
+values are always strings. Printing a :mod:`dbm.gnu` object doesn't print the
+keys and values, and the :meth:`items` and :meth:`values` methods are not
+supported.
+
+.. exception:: error
+
+ Raised on ``gdbm``\ -specific errors, such as I/O errors. :exc:`KeyError` is
+ raised for general mapping errors like specifying an incorrect key.
+
+
+.. function:: open(filename, [flag, [mode]])
+
+ Open a ``gdbm`` database and return a :class:`gdbm` object. The *filename*
+ argument is the name of the database file.
+
+ The optional *flag* argument can be:
+
+ +---------+-------------------------------------------+
+ | Value | Meaning |
+ +=========+===========================================+
+ | ``'r'`` | Open existing database for reading only |
+ | | (default) |
+ +---------+-------------------------------------------+
+ | ``'w'`` | Open existing database for reading and |
+ | | writing |
+ +---------+-------------------------------------------+
+ | ``'c'`` | Open database for reading and writing, |
+ | | creating it if it doesn't exist |
+ +---------+-------------------------------------------+
+ | ``'n'`` | Always create a new, empty database, open |
+ | | for reading and writing |
+ +---------+-------------------------------------------+
+
+ The following additional characters may be appended to the flag to control
+ how the database is opened:
+
+ +---------+--------------------------------------------+
+ | Value | Meaning |
+ +=========+============================================+
+ | ``'f'`` | Open the database in fast mode. Writes |
+ | | to the database will not be synchronized. |
+ +---------+--------------------------------------------+
+ | ``'s'`` | Synchronized mode. This will cause changes |
+ | | to the database to be immediately written |
+ | | to the file. |
+ +---------+--------------------------------------------+
+ | ``'u'`` | Do not lock database. |
+ +---------+--------------------------------------------+
+
+ Not all flags are valid for all versions of ``gdbm``. The module constant
+ :const:`open_flags` is a string of supported flag characters. The exception
+ :exc:`error` is raised if an invalid flag is specified.
+
+ The optional *mode* argument is the Unix mode of the file, used only when the
+ database has to be created. It defaults to octal ``0o666``.
+
+ In addition to the dictionary-like methods, ``gdbm`` objects have the
+ following methods:
+
+ .. method:: gdbm.firstkey()
+
+ It's possible to loop over every key in the database using this method and the
+ :meth:`nextkey` method. The traversal is ordered by ``gdbm``'s internal
+ hash values, and won't be sorted by the key values. This method returns
+ the starting key.
+
+ .. method:: gdbm.nextkey(key)
+
+ Returns the key that follows *key* in the traversal. The following code prints
+ every key in the database ``db``, without having to create a list in memory that
+ contains them all::
+
+ k = db.firstkey()
+ while k != None:
+ print(k)
+ k = db.nextkey(k)
+
+ .. method:: gdbm.reorganize()
+
+ If you have carried out a lot of deletions and would like to shrink the space
+ used by the ``gdbm`` file, this routine will reorganize the database. ``gdbm``
+ will not shorten the length of a database file except by using this
+ reorganization; otherwise, deleted file space will be kept and reused as new
+ (key, value) pairs are added.
+
+ .. method:: gdbm.sync()
+
+ When the database has been opened in fast mode, this method forces any
+ unwritten data to be written to the disk.
+
+
+:mod:`dbm.ndbm` --- Interface based on ndbm
+-------------------------------------------
+
+.. module:: dbm.ndbm
+ :platform: Unix
+ :synopsis: The standard "database" interface, based on ndbm.
+
+
+The :mod:`dbm.ndbm` module provides an interface to the Unix "(n)dbm" library.
+Dbm objects behave like mappings (dictionaries), except that keys and values are
+always strings. Printing a dbm object doesn't print the keys and values, and the
+:meth:`items` and :meth:`values` methods are not supported.
+
+This module can be used with the "classic" ndbm interface, the BSD DB
+compatibility interface, or the GNU GDBM compatibility interface. On Unix, the
+:program:`configure` script will attempt to locate the appropriate header file
+to simplify building this module.
+
+.. exception:: error
+
+ Raised on dbm-specific errors, such as I/O errors. :exc:`KeyError` is raised
+ for general mapping errors like specifying an incorrect key.
+
+
+.. data:: library
+
+ Name of the ``ndbm`` implementation library used.
+
+
+.. function:: open(filename[, flag[, mode]])
+
+ Open a dbm database and return a dbm object. The *filename* argument is the
+ name of the database file (without the :file:`.dir` or :file:`.pag` extensions;
+ note that the BSD DB implementation of the interface will append the extension
+ :file:`.db` and only create one file).
+
+ The optional *flag* argument must be one of these values:
+
+ +---------+-------------------------------------------+
+ | Value | Meaning |
+ +=========+===========================================+
+ | ``'r'`` | Open existing database for reading only |
+ | | (default) |
+ +---------+-------------------------------------------+
+ | ``'w'`` | Open existing database for reading and |
+ | | writing |
+ +---------+-------------------------------------------+
+ | ``'c'`` | Open database for reading and writing, |
+ | | creating it if it doesn't exist |
+ +---------+-------------------------------------------+
+ | ``'n'`` | Always create a new, empty database, open |
+ | | for reading and writing |
+ +---------+-------------------------------------------+
+
+ The optional *mode* argument is the Unix mode of the file, used only when the
+ database has to be created. It defaults to octal ``0o666`` (and will be
+ modified by the prevailing umask).
+
+
+
+:mod:`dbm.sqlite` --- Interface based on sqlite3
+------------------------------------------------
+
+.. module:: dbm.sqlite
+ :synopsis: Portable implementation of the simple DBM interface.
+
+
+The :mod:`dbm.sqlite` module provides a dict-like file interface similar to
+the other modules in the dbm package, though the underlying file storage is
+managed using the sqlite3 module and is thus portable across all platforms
+which support the sqlite3 package. dbm.sqlite objects behave like mappings
+(dictionaries), except that keys and values are always strings. Printing a
+dbm object doesn't print the keys and values.
+
+.. function:: open(filename[, flag[, mode]])
+
+ Open a sqlite3 database and return a dbm object. The *filename* argument
+ is the name of the database file. The flag and mode arguments are
+ ignored.
+
+
+:mod:`dbm.dumb` --- Portable DBM implementation
+-----------------------------------------------
+
+.. module:: dbm.dumb
+ :synopsis: Portable implementation of the simple DBM interface.
+
+.. index:: single: databases
+
+.. note::
+
+ The :mod:`dbm.dumb` module is intended as a last resort fallback for the
+ :mod:`dbm` module when no more robust module is available. The :mod:`dbm.dumb`
+ module is not written for speed and is not nearly as heavily used as the other
+ database modules.
+
+The :mod:`dbm.dumb` module provides a persistent dictionary-like interface which
+is written entirely in Python. Unlike other modules such as :mod:`gdbm` and
+:mod:`bsddb`, no external library is required. As with other persistent
+mappings, the keys and values must always be strings.
+
+The module defines the following:
+
+
+.. exception:: error
+
+ Raised on dbm.dumb-specific errors, such as I/O errors. :exc:`KeyError` is
+ raised for general mapping errors like specifying an incorrect key.
+
+
+.. function:: open(filename[, flag[, mode]])
+
+ Open a dumbdbm database and return a dumbdbm object. The *filename* argument is
+ the basename of the database file (without any specific extensions). When a
+ dumbdbm database is created, files with :file:`.dat` and :file:`.dir` extensions
+ are created.
+
+ The optional *flag* argument is currently ignored; the database is always opened
+ for update, and will be created if it does not exist.
+
+ The optional *mode* argument is the Unix mode of the file, used only when the
+ database has to be created. It defaults to octal ``0o666`` (and will be modified
+ by the prevailing umask).
+
+ In addition to the methods provided by the :class:`collections.MutableMapping` class,
+ :class:`dumbdbm` objects provide the following method:
+
+ .. method:: dumbdbm.sync()
+
+ Synchronize the on-disk directory and data files. This method is called
+ by the :meth:`Shelve.sync` method.
Added: sandbox/trunk/dbm_sqlite/Lib/dbm/sqlite.py
==============================================================================
--- (empty file)
+++ sandbox/trunk/dbm_sqlite/Lib/dbm/sqlite.py	Sat Sep 6 04:54:02 2008
@@ -0,0 +1,120 @@
+"""
+A dbm clone using sqlite under the covers.
+
+XXX TO DO:
+
+Everything.
+"""
+
+import sqlite3
+import collections
+
+__all__ = ["error", "open"]
+
+error = sqlite3.OperationalError
+
+class _Database(collections.MutableMapping):
+ def __init__(self, filename, mode):
+ self._mode = mode
+ self._filename = filename
+ self._conn = sqlite3.connect(filename)
+ self.initialize_table()
+
+ def initialize_table(self):
+ c = self._conn.cursor()
+ try:
+ c.execute("select count(key) from dict")
+ except sqlite3.OperationalError:
+ c.execute("""create table dict (key text, value text)""")
+ self._conn.commit()
+ finally:
+ c.close()
+
+ def __getitem__(self, key):
+ c = self._conn.cursor()
+ try:
+ c.execute("select value from dict"
+ " where key = ?", (key,))
+ rows = list(c)
+ if not rows:
+ raise KeyError(key)
+ return rows[0][0]
+ finally:
+ c.close()
+
+ def __setitem__(self, key, val):
+ del self[key]
+ c = self._conn.cursor()
+ try:
+ c.execute("insert into dict"
+ " (key, value) values (?, ?)", (key, val))
+ self._conn.commit()
+ finally:
+ c.close()
+
+ def __delitem__(self, key):
+ c = self._conn.cursor()
+ try:
+ c.execute("delete from dict where key = ?", (key,))
+ self._conn.commit()
+ finally:
+ c.close()
+
+ def keys(self):
+ c = self._conn.cursor()
+ try:
+ c.execute("select key from dict order by key")
+ return [e[0] for e in c]
+ finally:
+ c.close()
+
+ def values(self):
+ c = self._conn.cursor()
+ try:
+ c.execute("select value from dict order by key")
+ return [e[0] for e in c]
+ finally:
+ c.close()
+
+ def items(self):
+ c = self._conn.cursor()
+ try:
+ c.execute("select key, value from dict order by key")
+ return list(c)
+ finally:
+ c.close()
+
+ def __contains__(self, key):
+ c = self._conn.cursor()
+ try:
+ c.execute("select value from dict"
+ " where key = ?", (key,))
+ return not not list(c)
+ finally:
+ c.close()
+
+ def iterkeys(self):
+ return iter(self.keys())
+ __iter__ = iterkeys
+
+ def iteritems(self):
+ return iter(self.items())
+
+ def itervalues(self):
+ return iter(self.values())
+
+ def __len__(self):
+ c = self._conn.cursor()
+ try:
+ c.execute("select count(key) from dict")
+ return int(list(c)[0])
+ finally:
+ c.close()
+
+ def close(self):
+ if self._conn is not None:
+ self._conn.close()
+ self._conn = None
+
+def open(file, flag=None, mode=0o666):
+ return _Database(file, mode)
Added: sandbox/trunk/dbm_sqlite/Lib/test/test_dbm_sqlite.py
==============================================================================
--- (empty file)
+++ sandbox/trunk/dbm_sqlite/Lib/test/test_dbm_sqlite.py	Sat Sep 6 04:54:02 2008
@@ -0,0 +1,148 @@
+#! /usr/bin/env python
+"""Test script for the dbm.sqlite module
+ by Skip Montanaro, based on the 3.0 dumbdbm test module.
+"""
+
+import io
+import os
+import unittest
+import dbm.sqlite
+from test import support
+
+_fname = support.TESTFN
+
+def _delete_files():
+ try:
+ os.unlink(_fname)
+ except OSError:
+ pass
+
+class DbmSQLiteTestCase(unittest.TestCase):
+ _dict = {'0': b'',
+ 'a': b'Python:',
+ 'b': b'Programming',
+ 'c': b'the',
+ 'd': b'way',
+ 'f': b'Guido',
+ 'g': b'intended',
+ }
+
+ def test_sqlite_creation(self):
+ f = dbm.sqlite.open(_fname, 'c')
+ self.assertEqual(list(f.keys()), [])
+ for key in self._dict:
+ f[key.encode("ascii")] = self._dict[key]
+ self.read_helper(f)
+ f.close()
+
+ def test_close_twice(self):
+ f = dbm.sqlite.open(_fname)
+ f[b'a'] = b'b'
+ self.assertEqual(f[b'a'], b'b')
+ f.close()
+ f.close()
+
+ def test_sqlite_modification(self):
+ self.init_db()
+ f = dbm.sqlite.open(_fname, 'w')
+ self._dict['g'] = f[b'g'] = b"indented"
+ self.read_helper(f)
+ f.close()
+
+ def test_sqlite_read(self):
+ self.init_db()
+ f = dbm.sqlite.open(_fname, 'r')
+ self.read_helper(f)
+ f.close()
+
+ def test_sqlite_keys(self):
+ self.init_db()
+ f = dbm.sqlite.open(_fname)
+ keys = self.keys_helper(f)
+ f.close()
+
+ def test_write_contains(self):
+ f = dbm.sqlite.open(_fname)
+ f[b'1'] = b'hello'
+ self.assertTrue(b'1' in f)
+ f.close()
+
+ def test_write_write_read(self):
+ # test for bug #482460
+ f = dbm.sqlite.open(_fname)
+ f[b'1'] = b'hello'
+ f[b'1'] = b'hello2'
+ f.close()
+ f = dbm.sqlite.open(_fname)
+ self.assertEqual(f[b'1'], b'hello2')
+ f.close()
+
+ def read_helper(self, f):
+ keys = self.keys_helper(f)
+ for key in self._dict:
+ self.assertEqual(self._dict[key], f[key.encode("ascii")])
+
+ def init_db(self):
+ f = dbm.sqlite.open(_fname, 'w')
+ for k in self._dict:
+ f[k.encode("ascii")] = self._dict[k]
+ f.close()
+
+ def keys_helper(self, f):
+ keys = sorted(k.decode("ascii") for k in f.keys())
+ dkeys = sorted(self._dict.keys())
+ self.assertEqual(keys, dkeys)
+ return keys
+
+ # Perform randomized operations. This doesn't make assumptions about
+ # what *might* fail.
+ def test_random(self):
+ import random
+ d = {} # mirror the database
+ for dummy in range(5):
+ f = dbm.sqlite.open(_fname)
+ for dummy in range(100):
+ k = random.choice('abcdefghijklm')
+ if random.random() < 0.2:
+ if k in d:
+ del d[k]
+ del f[k.encode("ascii")]
+ else:
+ v = (random.choice((b'a', b'b', b'c')) *
+ random.randrange(100))
+ d[k] = v
+ f[k.encode("ascii")] = v
+ if not (d[k], v == f[k.encode("ascii")] == d[k]):
+ print("v:", v, "f[k]:", f[k.encode("ascii")],
+ "d[k]:")
+ self.assertEqual(f[k.encode("ascii")], v)
+ f.close()
+
+ f = dbm.sqlite.open(_fname)
+ expected = sorted((k.encode("latin-1"), v) for k, v in d.items())
+ got = sorted(f.items())
+ self.assertEqual(expected, got)
+ f.close()
+
+ def test_keys_values_items(self):
+ f = dbm.sqlite.open(_fname, 'c')
+ self.assertEqual(list(f.keys()), [])
+ for key in self._dict:
+ f[key.encode("ascii")] = self._dict[key]
+ self.assertEqual(list(zip(f.keys(), f.values())),
+ f.items())
+ f.close()
+ def tearDown(self):
+ _delete_files()
+
+ def setUp(self):
+ _delete_files()
+
+def test_main():
+ try:
+ support.run_unittest(DbmSQLiteTestCase)
+ finally:
+ _delete_files()
+
+if __name__ == "__main__":
+ test_main()
