Contents

• ion: Pickling of objects to JSON or XML
• config: Configuration files in the spirit of .INI files, but using either JSON or XML. Much more flexible and easier to use than ConfigParser
• sql: Convenience wrapper for SQLite and APSW.
  Includes the multithreading-friendly boodebr.sql.sqliteQ
• sql2: Common API for APSW, pysqlite and MySQL, with a focus on portable semantics and stability under high loads. Considered beta quality for now; will eventually supercede boodebr.sql
• util: General utility functions
• disthelper: Utilities that are useful when writing setup files, including replacements for some commonly needed POSIX tools.
• pyconfig: Dynamic introspection of the Python interpreter capabilities
• gui: A convenience wrapper for wxPython.
• license: The boodebr library is distributed under an OpenSource license

Installation

• boodebr.sql2:
  • Warn on mixed-case table names (not portable)
  • Removed BLOB type, not portable
  • Use InnoDB tables by default for MySQL
    
    

Version 1.5.0 (2009-09-26)

• boodebr.sql: Added sqliteConn with same API as sqliteQ for non-threaded use.
• boodebr.util.locking: Add .lock to lockfiles so it is easy to find them.
  
  

Version 1.4.1 (2009-08-16)

• Added missing import that prevented disthelper/scripts/rmfind.py from working.
  
  

Version 1.4.0 (2009-07-14)

• Added C version of JSON deserializer
  
  

Version 1.3.0 (2008-08-06)

• Added multithread/multiprocess locking semantics, boodebr.util.locking
• Updated boodebr.config to use file locking.
• makeGUID() can be called with no args
• New module boodebr.util.modules
• Fixes in boodebr.sql to enhance stability under high load
• New module boodebr.sql2 (considered beta quality for now; will eventually replace boodebr.sql)
• New module boodebr.util.threadQ provides serialization of method calls across threads.
  
  

Version 1.2.0 (2008-06-08)

• boodebr.gui
  • Redid stock images as SVG.
  • Embed stock images via img2py for easier use with py2exe.
  • Synced fixed_colsorter.py with wxPython 2.8.7.1
• boodebr.ion: Added support for pickling of complex numbers.
• boodebr.config: Added file_exits() to fileconfig objects.
• Moved test suite down one level in tree.
  
  

Version 1.1.0 (2008-03-01)

• sqliteQ.add_table_column
• sqliteQ.delete_table
• sqliteQ.delete_table_columns
• sqliteQ.get_table_columns
• sqliteQ.modify_table_column
• sqliteQ.rename_table
  
  

Version 1.0.0 (2008-02-19)

• boodebr.sql.sqliteQ
  • New module for sharing SQLite connections across multiple threads.
• boodebr.util.guid
  • A simple module for creating unique identifiers.
• API change:
  • boodebr.sql.sqlite_util.get_tables() no longer returns special sqlite_* tables names. Pass special=True to get the previous behavior.
• Other small bugfixes
  
  

Version 0.9 (2008-01-21)

• boodebr.ion:
  • An object can define __ionize__() if it just wants to flatten itself for pickling and doesn't care about being rebuilt in deionize().
  • ionize() now takes flatten_only parameter which strips out any extra attributes added during pickling (in case you are sending data to a JSON client that can't handle them).
    
    

• boodebr.config:
  • fileconfig is now threadsafe.
  • Make paths as needed when saving config file.
    
    

• boodebr.gui:
  • This is a new module (a convenience layer for wxPython).
    
    

• boodebr.sql:
  • Marked fpmsql.run() obsolete (does nothing that query() doesn't do).
  • Added defaults so that fpmsql() can be called with just a filename argument.
    
    

• Other bugfixes
  
  

Version 0.8.1 (2007-11-11)

• Pickling API
• Writing hooks
• Comparison of boodebr.ion with other serialization modules
  
  
  blog comments powered by Disqus

• Always use '?' as the placeholder for values in query strings. It will be converted as needed.
• Avoid hardcoding typenames in CREATE TABLE. The below example shows how to create a table using, all available types:
  from boodebr.sql2 import *
  
  sql = opensql(..)
  sql.create_table('foo', 
           [('id', AUTO_PRIMARY_KEY),
            ('an_int', INTEGER), ('a_float', REAL),
            ('a_text', TEXT), ('a_blob', BLOB)])
• Use INSERT like this:
  INSERT into tablename (a,b,c) values (?,?,?)
• Do NOT use the following statements inside a transaction (they cannot be portably rolled back):
  • CREATE TABLE
  • DROP TABLE
  • ALTER TABLE

Usage notes:

Background/rationale:

• You could be running under a nonstandard/alternative Python implementation (e.g. Jython, or maybe a cut-down embedded version that eliminated some features) and you want to dynamically figure out what is available.
  
  

• It seems more self-documenting to write something like:
      
  if Have_Iterators():
       ... do something with iterators ...
  Than to write:
      
  if sys.version_info[0] >= 2 and sys.version_info[1] >= 2:
       ... do something with iterators ...
  In other words, your code now says "here is the capability I need", making it more maintainable down the road than a hardcoded version match. Plus, it is more robust in the presence of a nonstandard interpreter.
  
  

• You're writing an installer, and want to pick different modules to install, based on platform.
  
  

• Some oddball (or future) version of Python might break sys.version_info (expand the number of values, etc.), so you don't want to rely on it.
  
  
  blog comments powered by Disqus

ionization hooks

deionization

Brief example

Adding __ionize__()

1. The only data structures RFC 4627 recognizes natively are dictionaries and lists. All other types have to be converted to one of these types. boodebr.ion provides a layer on top of RFC 4627 to allow full pickling (while remaining 100% compatible with JSON).
2. Due to the limitations of RFC 4627, JSON and boodebr.ion will convert tuple->list and string->unicode. All data is preserved, but the exact type may change.
3. Preserving references (espcially self-referencing data) while allowing user-defined hooks is quite difficult. Dropping this requirement allows boodebr.ion to have a much simpler design than xml.pickle. If you need this capability, use xml.pickle instead.
4. Neither JSON nor XML are binary-clean formats. boodebr.ion and xml.pickle transparently encode/decode binary data so you never have to worry about it.
5. Depending on the JSON library you use, it may allow more fine-grained control. Both boodebr.ion and xml.pickle have a hook/plugin system for fine-grained control, although xml.pickle has a more extensive (and complicated) system.
   
   
   blog comments powered by Disqus

• Wraps PyDB with iterators for nicer code
• Iterator can return rows, dicts, or objects
• Shorthand function names
• When loading objects, calls obj.__postload__() so objects can perform their own SQL->object conversions.
  
  

sqliteQ API

• Low-level querying methods
• Higher-level functions, including replacements for functionality missing from SQLite's native ALTER TABLE function.
  
  

Querying

run(cmdlist)

Run a list of commands inside a transaction.

The entire transaction is rolled back if any commands fail.

Accepts cmdlist as either:

• multiple commands: ((query,args), (query,args), ...)
• single command: (query,args)
  
  

There is no return value. Raises an exception on error.

Example:

s = sqliteQ('mydb.db')
cmds = [
   ('create table AAA (name text)', None),
   ('create table BBB (name text)', None),
   ]
s.run(cmds)

getrows(query, args=None)

Run given query and return result as a list of rows.

Example:

s = sqliteQ('mydb.db')
q = 'select id,name from MyTable where last=?'
a = ('Smith',)
for row in s.getrows(q,a):
   print "ID,name", row[0], row[1]

getobjs(query, args=None, klass=None)

Run given query and return result as a list of objects.
Objects will be of type klass, if given, or an anonymous type if not.

Example:

s = sqliteQ('mydb.db')
q = 'select id,name from MyTable where last=?'
a = ('Smith',)
for obj in s.getobjs(q,a):
   print "ID,name", obj.id, obj.name

get_tables(special=False)

Get a list of table names from database.
If special==False, filters out special sqlite_ table names.

Returns list of names.

Table-Alteration

add_table_column(table, colname, coltype, colcomment, initval=None)

Add a column to a table, creating the table if it doesn't yet exist.

table

Name of table to modify.

colname

Name for new column.

coltype

Datatype for new column.

colcomment

Comment for new column. Should be passed WITHOUT the /* */

initval

Value to fill new column with.

If an error occurs, the database is rolled-back to its original state, so the caller doesn't have to do anything but inform the user of the error (a DatabaseError exception will be raised).

There is no return value.

This will also drop any indexes on the table so you'll need to recreate those.

This limitation may be removed at some point, so I recommend you create your indexes using the form CREATE INDEX IF NOT EXISTS ...

Recent versions of SQLite offer an ALTER TABLE ADD COLUMN command. You may want to try both and see which works best for your application.

delete_table(table)

Permanently delete a table from the named database.

If an error occurs, the database is rolled-back to its original state, so the caller doesn't have to do anything but inform the user of the error (a DatabaseError exception will be raised).

delete_table_columns(table, columns)

Delete a list of columns from the given table.

If an error occurs, the database is rolled-back to its original state, so the caller doesn't have to do anything but inform the user of the error (a DatabaseError exception will be raised).

This will also drop any indexes on the table so you'll need to recreate those.

This limitation may be removed at some point, so I recommend you create your indexes using the form CREATE INDEX IF NOT EXISTS ...

get_table_columns(table)

Get a list of column names & types for the given table.

Returns a list of entries:

  (colname, coltype, colcomment)

Where:

colname

Name of column

coltype

The SQL type string

colcomment

Aggregated comments found for column (/* .. */ and/or -- will be removed.)

The list will be in the same order as the order of the SQL statements used to create the table.

Returns [] if table doesn't exist.

modify_table_column(table, cur_colname, new_colname, new_coltype=None, new_colcomment=None)

Rename and/or change the type of a column and/or associated comment.

table

Table to modify

cur_colname

Column to change

new_colname

New name for column.

new_coltype

New type for column; if None, don't change the type.

new_colcomment

New comment for column; if None, don't change comment.

If an error occurs, the database is rolled-back to its original state, so the caller doesn't have to do anything but inform the user of the error (a DatabaseError exception will be raised).

This will also drop any indexes on the table so you'll need to recreate those.

This limitation may be removed at some point, so I recommend you create your indexes using the form CREATE INDEX IF NOT EXISTS ...

rename_table(table, newname, newcomment=None)

Rename a table to newname.

If an error occurs, the database is rolled-back to its original state, so the caller doesn't have to do anything but inform the user of the error (a DatabaseError exception will be raised).

There is no return value.

This will also drop any indexes on the table so you'll need to recreate those.

This limitation may be removed at some point, so I recommend you create your indexes using the form CREATE INDEX IF NOT EXISTS ...

• Provide a simpler API for the most common cases
• ids are autogenerated & callbacks set in constructors
• I try to always write vs. this interface, so I can fix bugs/provide workarounds in one location.
• Add some common convenience functions/classes
• I prefer shortnames & everything in lowercase