Python

API docs and installation manual

1. About this document

Section 2, “Compilation and Installation” describes the compilation, installation and general usage of WhiteDB Python bindings.

Section 3, “wgdb.so (wgdb.pyd) module”, describes the immediate low level API provided by the wgdb module. This API (in most cases) directly wraps functions provided by libwgdb.

Section 4, “whitedb.py module (high level API)” describes the DBI-style API, which is designed for convinience of usage and is not speed-optimized at the moment (start there if you just want to know how to put stuff into the database using Python).

The examples in this document were create using Python 2. They should be syntactically correct for Python 3, but can produce slightly different output (particularly, the print statement vs the print() function).

2. Compilation and Installation

2.1. Compiling Python bindings

Python module is not compiled by default. ./configure --with-python enables the compilation (provided that the configure script is able to locate the Python.h file in the system. If not, it is assumed that Python is not properly installed and WhiteDB will be compiled without Python bindings).

When building manually, use the separate scripts in Python directory. Check that the Python path in compile.sh (compile.bat for Windows) matches your system. On non-Windows systems, also check that the config.h file in the top level directory exists. If not, cp config-gcc.h config.h will provide a default one.

2.2. Installation

The high level whitedb.py module expects to find the compiled wgdb.so module in the same directory it resides in. To install the modules, they can be copied to Python site-packages directory manually.

2.3. Compatibility

Minimum version of Python required: 2.5. Other tested versions: 2.6, 2.7 and 3.3. Note that Python 3 is supported but is not extensively tested yet.

3. wgdb.so (wgdb.pyd) module

3.1. Attaching and deleting a database

FUNCTIONS
   attach_database(shmname='', size=0, local=0)
       Connect to a shared memory database. If the database with the
       given name does not exist, it is created. If local is non-zero,
       the parameter shmname is ignored and the database is created in
       local memory instead.
attach_existing_database(shmname)
    Connect to a shared memory database. Fails if the database with the
    given name does not exist.
delete_database(shmname)
    Delete a shared memory database.
detach_database(db)
    Detach from shared memory database. If the database is in the
    local memory, it is deleted.

attach_database() allows keyword arguments. If either database name or size are omitted, default values are used. Note that the shared memory name is expected to be converted by strtol().

detach_database() tells the system that the current process is no longer interested in reading the shared memory. This allows the system to free the shared memory (applies to SysV IPC model - not Win32). In case of a local database, the allocated memory is freed on all systems.

Examples:

>>> a=wgdb.attach_database()
>>> b=wgdb.attach_database("1001")
>>> c=wgdb.attach_database(size=3000000)
>>> d=wgdb.attach_database(size=500000, shmname="9999")
>>> d=wgdb.attach_database(local=1)
>>> wgdb.detach_database(d)

attach_existing_database() requires that a shared memory base with the given name exists.

>>> d=wgdb.attach_existing_database("1002")
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
wgdb.error: Failed to attach to database.
>>> d=wgdb.attach_existing_database()

delete_database() takes a single argument. If this is omitted, the default value will be used.

>>> wgdb.delete_database("1001")
>>> wgdb.delete_database()

3.2. Exception handling.

wgdb module defines a wgdb.error exception object that can be used in error handling:

>>> try:
...  a=wgdb.attach_database()
... except wgdb.error, msg:
...  print ('wgdb error')
... except:
...  print ('other error')
...

3.3. Creating and manipulating records

FUNCTIONS
   create_record(db, length)
       Create a record with given length.
create_raw_record(db, length)
    Create a record without indexing the fields.
delete_record(db, rec)
    Delete a record.
get_first_record(db)
    Fetch first record from database.
get_next_record(db, rec)
    Fetch next record from database.
get_record_len(db, rec)
    Get record length (number of fields).
is_record(rec)
    Determine if object is a WhiteDB record.

db is an object returned by wgdb.attach_database(). rec is an object returned by get_first_record() or other similar functions that return a record.

Examples:

>>> d=wgdb.attach_database()
...
>>> a=wgdb.create_record(d,5)
>>> a
<WhiteDB record at b6908df8>
>>> b=wgdb.create_record(d,3)
>>> b
<WhiteDB record at b6908e10>
>>> rec=wgdb.get_first_record(d)
>>> wgdb.get_record_len(d,rec)
5
>>> rec
<WhiteDB record at b6908df8>
>>> rec=wgdb.get_next_record(d,rec)
>>> wgdb.get_record_len(d,rec)
3
>>> rec
<WhiteDB record at b6908e10>
>>> rec=wgdb.get_next_record(d,rec)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
wgdb.error: Failed to fetch a record.

3.4. Writing and reading field contents.

wgdb module handles data type conversion between Python and WhiteDB. Field contents will be converted to Python object when reading data and again encoded into field data when writing to database.

Currently supported types include: None, int, float, string (regular 0-terminated string. Raw binary data is not allowed), record.

Setting a field to None is equivalent to clearing the field data. Similarly, unwritten fields will be returned to Python as containing None.

FUNCTIONS
   get_field(db, rec, fieldnr)
       Get field data decoded to corresponding Python type.
set_field(db, rec, fieldnr, data, encoding=0, ext_str="")
    Set field value.
set_new_field(db, rec, fieldnr, data, encoding=0, ext_str="")
    Set field value (assumes no previous content).

db is an object returned by wgdb.attach_database(). rec is an object returned by get_first_record() or other similar functions that return a record.

Encoding (or field type) is an optional keyword argument. If it is omitted, the type of the field is determined by the Python type. Following encoding types are defined by the wgdb module:

BLOBTYPE
CHARTYPE      - Python string (length 1, longer is allowed but ignored)
DATETYPE      - datetime.date()
DOUBLETYPE    - default encoding for Python float
FIXPOINTTYPE  - Python float (small, low precision real numbers)
INTTYPE       - default encoding for Python int
NULLTYPE      - Python None
RECORDTYPE    - wgdb.Record type.
STRTYPE       - default encoding for Python string
TIMETYPE      - datetime.time()
URITYPE       - Python string. ext_str defines URI prefix
XMLLITERALTYPE - Python string. ext_str defines type.
VARTYPE       - (varnum, VARTYPE) tuple.

ext_str is an optional keyword argument. For string types it has varied meaning depending on the type selected. For other types it is ignored.

!Note

With Python 2, Unicode objects are not accepted where a string object is expected. However, this can be worked around by converting the unicode type to str type. Example: unicodestr.encode('utf-8').

Examples:

>>> d=wgdb.attach_database()
...
>>> tmp=wgdb.create_record(d,4)
>>> tmp
<WhiteDB record at b6996e00>
>>> print (wgdb.get_field(d,tmp,0),)
(None,)
>>> wgdb.set_field(d,tmp,0,0)
>>> wgdb.set_field(d,tmp,1,256)
>>> wgdb.set_field(d,tmp,2,78.3345)
>>> wgdb.set_field(d,tmp,3,"hello")
>>> print (wgdb.get_field(d,tmp,0),)
(0,)
>>> print (wgdb.get_field(d,tmp,1),)
(256,)
>>> print (wgdb.get_field(d,tmp,2),)
(78.334500000000006,)
>>> print (wgdb.get_field(d,tmp,3),)
('hello',)
>>> wgdb.set_field(d,tmp,3,None)
>>> print (wgdb.get_field(d,tmp,3),)
(None,)

Example with a field pointing to another record:

>>> tmp=wgdb.create_record(d,4)
>>> n=wgdb.create_record(d,4)
>>> wgdb.set_field(d,tmp,3,n)
>>> wgdb.set_field(d,n,0,1)
>>> uu=wgdb.get_field(d,tmp,3)
>>> uu
<WhiteDB record at b69b3e18>
>>> wgdb.get_field(d,uu,0)
1

Example with using specific encoding:

>>> d=wgdb.attach_database()
>>> tmp=wgdb.create_record(d,1)
>>> wgdb.set_field(d,tmp,0,"Hello")
>>> wgdb.get_field(d,tmp,0)
'Hello'
>>> wgdb.set_field(d,tmp,0,"Hello", wgdb.STRTYPE)
>>> wgdb.get_field(d,tmp,0)
'Hello'
>>> wgdb.set_field(d,tmp,0,"Hello", wgdb.CHARTYPE)
>>> wgdb.get_field(d,tmp,0)
'H'
>>> wgdb.set_field(d,tmp,0,"H", wgdb.FIXPOINTTYPE)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: Requested encoding is not supported.

3.5. Transaction handling

Logical level of transaction handling is provided by the wgdb module. These functions should guarantee safe concurrent usage, however the method of providing that concurrency is up to the database engine (in simplest case, the method is a database level lock).

FUNCTIONS
   end_read(db, lock_id)
       Finish reading transaction.
end_write(db, lock_id)
    Finish writing transaction.
start_read(db)
    Start reading transaction.
start_write(db)
    Start writing transaction.

Parameter lock_id is returned by start_write() and start_read() functions. The same lock id should be passed to end_write() and end_read() functions, respectively. Depending on the locking mode used, the id may or may not be meaningful, but in any case this should be handled by the database itself.

If timeouts are enabled, start_read() and start_write() will raise the wgdb.error exception upon failure to acquire the lock.

Examples:

>>> d=wgdb.attach_database()
...
>>> l=wgdb.start_write(d)
>>> wgdb.create_record(d, 5)
<WhiteDB record at b6981e00>
>>> wgdb.end_write(d,l)
>>> l=wgdb.start_read(d)
>>> wgdb.get_first_record(d)
<WhiteDB record at b6981e00>
>>> wgdb.end_read(d,l)

3.6. Date and time fields.

WhiteDB uses a compact encoding for date and time values, which is translated to and from Python datetime representation on the wgdb module level. See Python datetime module documentation for more information on how to construct and use date and time objects.

Note that tzinfo field of the time object and general timezone awareness supported by the datetime module is ignored on wgdb module level. In practical applications, it’s recommended to treat all time fields as UTC or local time.

Examples:

>>> import wgdb
>>> import datetime
>>> d=wgdb.attach_database()
>>> tmp=wgdb.create_record(d,1)
>>> a=datetime.date(1990,1,2)
>>> wgdb.set_field(d,tmp,0,a)
>>> x=wgdb.get_field(d,tmp,0)
>>> x
datetime.date(1990, 1, 2)
>>> x.day
2
>>> x.month
1
>>> x.year
1990
>>> b=datetime.time(12,5)
>>> wgdb.set_field(d,tmp,0,b)
>>> x=wgdb.get_field(d,tmp,0)
>>> x
datetime.time(12, 5)
>>> x.hour
12
>>> x.minute
5
>>> x.second
0
>>> x.microsecond
0

3.7. Queries

wgdb module provides a direct wrapper for wg_make_query() and wg_fetch() functions. The query building function uses a similar convention for handling wgdb data types as the whitedb.py module (see Section 4.4, “Specifying field encoding and extended information.”) - data values in query parameters may be given as immediate Python values or as tuples that add the field type and extra string information.

FUNCTIONS
   fetch(db, query)
       Fetch next record from a query.
free_query(db, query)
    Unallocates the memory (local and shared) used by the query.
make_query(db, matchrec, arglist)
    Create a query object.

query is the wgdb.Query object returned by the make_query() method. matchrec is either a sequence of values or a reference to an actual database record. In either case, rows that have exactly matching fields will be returned. The query object has a read-only attribute res_count that contains the number of matching rows. If the number of rows is not known, query.res_count will be None.

arglist is a list of 3-tuples (column, condition, value). Conditions (defined in wgdb module) may be:

COND_EQUAL
COND_NOT_EQUAL
COND_LESSTHAN
COND_GREATER
COND_LTEQUAL
COND_GTEQUAL

Both matchrec and arglist are optional keyword arguments. If neither is provided, the query will return all the rows in the database.

Example:

>>> d=wgdb.attach_database()
>>> tmp=wgdb.create_record(d,2)
>>> tmp
<WhiteDB record at b65932c8>
>>> wgdb.set_field(d,tmp,0,2)
>>> wgdb.set_field(d,tmp,1,"hello")
>>> tmp=wgdb.create_record(d,2)
>>> tmp
<WhiteDB record at b65932e0>
>>> wgdb.set_field(d,tmp,0,3)
>>> wgdb.set_field(d,tmp,1,4)
>>> # column 0 equals 2
... q=wgdb.make_query(d, arglist=[(0,wgdb.COND_EQUAL,2)])
>>> wgdb.fetch(d, q)
<WhiteDB record at b65932c8>
>>> # column 1 does not equal "hello", column 0 is less than 100
... q=wgdb.make_query(d, arglist=[(1,wgdb.COND_NOT_EQUAL,"hello"),
...    (0,wgdb.COND_LESSTHAN,100)])
>>> wgdb.fetch(d, q)
<WhiteDB record at b65932e0>
>>> # use match record
... q=wgdb.make_query(d, [3, 4])
>>> wgdb.fetch(d, q)
<WhiteDB record at b65932e0>
>>> # all rows.
... q=wgdb.make_query(d)
>>> q.res_count # number of rows matching
2
>>> wgdb.fetch(d, q)
<WhiteDB record at b65932c8>
>>> wgdb.fetch(d, q)
<WhiteDB record at b65932e0>
>>> wgdb.fetch(d, q)  # runs out of rows
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
wgdb.error: Failed to fetch a record.
>>>

4. whitedb.py module (high level API)

4.1. Overview

High level access to database is provided by whitedb.py module. This module requires the low level wgdb.so (wgdb.pyd on Windows) module.

CLASSES
   Connection
   Cursor
   Record
   wgdb.error(exceptions.StandardError)
       DatabaseError
           DataError
           InternalError
           ProgrammingError
class Connection
 |  The Connection class acts as a container for
 |  wgdb.Database and provides all connection-related
 |  and record accessing functions.
 |
 |  Methods defined here:
 |
 |  __init__(self, shmname=None, shmsize=0)
 |
 |  atomic_create_record(self, fields)
 |      Create a record and set field contents atomically.
 |
 |  atomic_update_record(self, rec, fields)
 |      Set the contents of the entire record atomically.
 |
 |  close(self)
 |      Close the connection.
 |
 |  commit(self)
 |      Commit the transaction (no-op)
 |
 |  create_record(self, size)
 |      Create new record with given size.
 |
 |  cursor(self)
 |      Return a DBI-style database cursor
 |
 |  delete_record(self, rec)
 |      Delete record.
 |
 |  end_read(self)
 |      Finish reading transaction
 |
 |  end_write(self)
 |      Finish writing transaction
 |
 |  fetch(self, query)
 |      Get next record from query result set.
 |
 |  first_record(self)
 |      Get first record from database.
 |
 |  free_query(self, cur)
 |      Free query belonging to a cursor.
 |
 |  get_field(self, rec, fieldnr)
 |      Return data field contents
 |
 |  insert(self, fields)
 |      Insert a record into database
 |
 |  make_query(self, matchrec=None, *arg, **kwarg)
 |      Create a query object.
 |
 |  next_record(self, rec)
 |      Get next record from database.
 |
 |  rollback(self)
 |      Roll back the transaction (no-op)
 |
 |  set_field(self, rec, fieldnr, data, *arg, **kwarg)
 |      Set data field contents
 |
 |  set_locking(self, mode)
 |      Set locking mode (1=on, 0=off)
 |
 |  start_read(self)
 |      Start reading transaction
 |
 |  start_write(self)
 |      Start writing transaction
class Cursor
 |  Cursor object. Supports wgdb-style queries based on match
 |  records or argument lists. Does not currently support SQL.
 |
 |  Methods defined here:
 |
 |  __init__(self, conn)
 |
 |  close(self)
 |      Close the cursor
 |
 |  execute(self, sql='', matchrec=None, arglist=None)
 |      Execute a database query
 |
 |  fetchall(self)
 |      Fetch all (remaining) records from the result set
 |
 |  fetchone(self)
 |      Fetch the next record from the result set
 |
 |  get__query(self)
 |      Return low level query object
 |
 |  insert(self, fields)
 |      Insert a record into database --DEPRECATED--
 |
 |  set__query(self, query)
 |      Overwrite low level query object
class DataError(DatabaseError)
 |  Exception class to indicate invalid data passed to the db adapter
class DatabaseError(wgdb.error)
 |  Base class for database errors
class InternalError(DatabaseError)
 |  Exception class to indicate invalid internal state of the module
class ProgrammingError(DatabaseError)
 |  Exception class to indicate invalid database usage
class Record
 |  Record data representation. Allows field-level and record-level
 |  manipulation of data. Supports iterator and (partial) sequence protocol.
 |
 |  Methods defined here:
 |
 |  __getitem__(self, index)
 |      # sequence protocol
 |
 |  __init__(self, conn, rec)
 |
 |  __iter__(self)
 |      # iterator protocol
 |
 |  __setitem__(self, index, data, *arg, **kwarg)
 |
 |  delete(self)
 |      Delete the record from database
 |
 |  get__rec(self)
 |      Return low level record object
 |
 |  get_field(self, fieldnr)
 |      Return data field contents
 |
 |  get_size(self)
 |      Return record size
 |
 |  set__rec(self, rec)
 |      Overwrite low level record object
 |
 |  set_field(self, fieldnr, data, *arg, **kwarg)
 |      Set data field contents with optional encoding
 |
 |  update(self, fields)
 |      Set the contents of the entire record
FUNCTIONS
   connect(shmname=None, shmsize=0, local=0)
       Attaches to (or creates) a database. Returns a database object

Examples:

Connecting to database with default parameters (see examples for attach_database() for possible arguments and their usage).

>>> import whitedb
>>> d=whitedb.connect()

Cursor methods. Calling execute() without any parameters creates a query that returns all the rows in the database. At first the record set will be emtpy, then we insert one using the insert() method provided by the connection object. It will subsequently be returned by the query.

>>> c=d.cursor()
>>> c.execute()
>>> c.fetchall()
[]
>>> d.insert(("This", "is", "my", 1.0, "record"))
<whitedb.Record instance at 0x842ec0c>
>>> c.execute()
>>> rows=c.fetchall()
>>> rows
[<whitedb.Record instance at 0x842eb0c>]

The Record class has some aspects of a sequence and also works as an iterator. To simply access the entire contents of the record, it can be converted to a normal sequence, such as with the tuple() function. Fields may be accessed by their index as well:

>>> r=rows[0]
>>> r[1]
'is'
>>> r[2]
'my'
>>> tuple(r)
('This', 'is', 'my', 1.0, 'record')
>>> for column in r: print (column)
...
This
is
my
1.0
record

Record methods. We create a new record, then attempt to modify a single field and the full record. The last attempt will fail because record size is fixed.

>>> new=d.insert(('My', 2, 'record'))
>>> new
<whitedb.Record instance at 0x842ebcc>
>>> c.execute()
>>> rows=c.fetchall()
>>> rows
[<whitedb.Record instance at 0x842ec0c>, <whitedb.Record instance at 0x842eb8c>]
>>> new.get_field(1)
2
>>> new.set_field(1, 2.0)
>>> tuple(new)
('My', 2.0, 'record')
>>> new.update(('this','will','not','fit'))
wg data handling error: wrong field number given to  wg_set_field
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "whitedb.py", line 433, in update
    self._conn.atomic_update_record(self, fields)
  File "whitedb.py", line 242, in atomic_update_record
    wgdb.set_field(*fargs)
wgdb.error: Failed to set field value.
>>> tuple(new)
('this', 'will', 'not')

Records can be deleted like so (when using the method provided by the Record object, the Python level object itself will remain, but the database record will no longer be accessible):

>>> new.delete()
>>> new
<whitedb.Record instance at 0x842ebcc>
>>> tuple(new)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "whitedb.py", line 442, in __iter__
    yield self.get_field(fieldnr)
  File "whitedb.py", line 416, in get_field
    return self._conn.get_field(self, fieldnr)
  File "whitedb.py", line 264, in get_field
    data = wgdb.get_field(self._db, rec.get__rec(), fieldnr)
TypeError: argument 2 must be wgdb.Record, not None

Connections can be closed, after which the cursors and records created using that connection will no longer be usable. NOTE: if Connection.close() method is used, it is recommended to close all cursors first.

>>> c.close()
>>> d.close()
>>> tuple(new)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "whitedb.py", line 442, in __iter__
    yield self.get_field(fieldnr)
  File "whitedb.py", line 416, in get_field
    return self._conn.get_field(self, fieldnr)
  File "whitedb.py", line 262, in get_field
    self.start_read()
  File "whitedb.py", line 108, in start_read
    self._lock_id = wgdb.start_read(self._db)
TypeError: argument 1 must be wgdb.Database, not None

4.2. Linked records

WhiteDB record fields may contain references to other records. In high level API, these records are represented as instances of whitedb.Record class. Note that it is not useful to create such instances directly. Instances of Record class are always returned by WhiteDB operations (creating new records or retrieving existing ones).

Example of linking to other records:

>>> import whitedb
>>> d=whitedb.connect()
>>> rec=d.insert((1,2,3,4,5))
>>> c=d.cursor()
>>> c.execute()
>>> tuple(c.fetchone())
(1, 2, 3, 4, 5)
>>> d.insert(('1st linked record', rec))
<whitedb.Record instance at 0x8ebac2c>
>>> d.insert(('2nd linked record', rec))
<whitedb.Record instance at 0x8ebac4c>
>>> c.execute()
>>> l=c.fetchall()
>>> list(map(tuple,l))
[(1, 2, 3, 4, 5), ('1st linked record', <whitedb.Record instance at 0x8ebad0c>), ('2nd linked record', <whitedb.Record instance at 0x8ebad4c>)]

Changing the contents of the original record will be visible through the records that refer to it:

>>> linked=l[-2:]
>>> linked
[<whitedb.Record instance at 0x8ebac0c>, <whitedb.Record instance at 0x8ebac8c>]
>>> list(map(lambda x: tuple(x[1]), linked))
[(1, 2, 3, 4, 5), (1, 2, 3, 4, 5)]
>>> rec.set_field(3, 99)
>>> list(map(lambda x: tuple(x[1]), linked))
[(1, 2, 3, 99, 5), (1, 2, 3, 99, 5)]

4.3. Transaction support

Transactions are handled internally by the whitedb module. By default the concurrency support is turned on and each database read or write is treated as a separate transaction. The user can turn this behaviour on and off (when there is a single database user, there will be a small performance gain with locking turned off).

Turning locking (or transactional) mode off:

>>> d=whitedb.connect()
>>> d.set_locking(0)

Turning it back on:

>>> d.set_locking(1)

4.4. Specifying field encoding and extended information.

The user can explicitly state which encoding should be used when writing data to the database. Examples of encodings where this is useful are 1-character strings and small fixed-point numbers. When encoded as such they consume less storage space in database and may speed up access as well.

Allowed types are listed under the Section 3.4, “Writing and reading field contents.”.

Example:

>>> import whitedb
>>> d=whitedb.connect()
>>> r=d.insert((None,))
>>> r.set_field(0,"Hello")
>>> tuple(r)
('Hello',)
>>> r.set_field(0,"Hello",whitedb.wgdb.STRTYPE)
>>> tuple(r)
('Hello',)
>>> r.set_field(0,"Hello", encoding=whitedb.wgdb.CHARTYPE)
>>> tuple(r)
('H',)
>>> r.set_field(0,"Hello",whitedb.wgdb.INTTYPE)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "whitedb.py", line 422, in set_field
    return self._conn.set_field(self, fieldnr, data, *arg, **kwarg)
  File "whitedb.py", line 283, in set_field
    rec.get__rec(), fieldnr, data, *arg, **kwarg)
TypeError: Requested encoding is not supported.

Some string types allow extra information, stored together with the value. This can be done by adding the ext_str keyword parameter. The specific types and meaning of the extra information:

STRTYPE - language
URITYPE - URI prefix
XMLLITERAL - XML literal type

Example:

>>> r=d.create_record(3)
>>> r
<whitedb.Record instance at 0x9570c0c>
>>> r.set_field(0, "#example", whitedb.wgdb.URITYPE, "http://example.com/myns")
>>> r.set_field(1, "True", ext_str="xsd:boolean", encoding=whitedb.wgdb.XMLLITERALTYPE)
>>> r.set_field(2, "#object_id", encoding=whitedb.wgdb.URITYPE)
>>> tuple(r)
('http://example.com/myns#example', 'True', '#object_id')

Finally, Connection.insert() method and Record.update() method allow the user to supply the additional field encoding and extra string parameters together with the data value.

Field values passed to these methods may be given as tuples (data, encoding) or (data, encoding, ext_str). These additional parameters will be passed on to the database in a similar way to the positional parameters in the above examples with the set_field() method. If ext_str is given, encoding must also be present. Passing 0 for the encoding lets the wgdb module select the default encoding.

Example:

>>> r=d.insert((1,2.0,"3"))
>>> tuple(r)
(1, 2.0, '3')
>>> r.update((None,None,("hello",whitedb.wgdb.CHARTYPE)))
>>> tuple(r)
(None, None, 'h')
>>> r.update((None,None,("hello",0,"en")))
>>> tuple(r)
(None, None, 'hello')
>>> r=d.insert((("#example",whitedb.wgdb.URITYPE,"http://mydomain.org/"),
... ("False",whitedb.wgdb.XMLLITERALTYPE,"xsd:boolean")))
>>> tuple(r)
('http://mydomain.org/#example', 'False')
>>> import math
>>> r.update((math.pi,(math.pi,whitedb.wgdb.FIXPOINTTYPE)))
>>> tuple(r)
(3.1415926535897931, 3.1415999999999999)

4.5. Using dates and times.

Date and time support is implemented using the datetime module included with the standard Python distribution. Storing a datetime.date object in the database creates a WhiteDB date type field, similarly a datetime.time object is stored as a time field. When reading the database, low-level wgdb module converts the times and dates to datetime.date/time instances again.

Timezones are not supported through the wgdb API, so timezone-awareness should be implemented on the application level, if needed.

Date and time fields combined can be used to construct datetime data.

Example:

>>> import whitedb
>>> import datetime
>>> d=whitedb.connect()
>>> a=datetime.date(2010,3,31)
>>> b=datetime.time(12,59,microsecond=330000)
>>> rec=d.insert((a,b))
>>> tuple(rec)
(datetime.date(2010, 3, 31), datetime.time(12, 59, 0, 330000))
>>> rec[0].month
3
>>> rec[1].hour
12

Example of using combined date and time fields as a datetime object (continuing previous example):

>>> x=datetime.datetime.combine(rec[0], rec[1])
>>> x
datetime.datetime(2010, 3, 31, 12, 59, 0, 330000)
>>> x.strftime("%d.%m.%Y")
'31.03.2010'
>>> x.ctime()
'Wed Mar 31 12:59:00 2010'

4.6. Using queries.

The execute() method of Cursor class implements non-DBI, WhiteDB-specific extensions. These can be used to query data that matches specific conditions. SQL support is currently not implemented in libwgdb and is non-functional in the whitedb Python module.

Optional keyword parameters to execute():

  • sql - ignored
  • matchrec - may be either a sequence of values or a whitedb.Record instance that points to an actual record in the database. In the first case, records with fields matching the values in the sequence will be returned. In the second case, equivalent records (including the match record itself) will be returned.
  • arglist - sequence of 3-tuples (column, condition, value)

Values are either immediate Python values or tuples with extended type information (see Section 4.4, “Specifying field encoding and extended information.”). For the possible conditions, see the Section 3.7, “Queries”.

arglist and matchrec parameters may be present simultaneously. Also, arglist parameter may contain multiple conditions for one column. If neither parameter is present, the result set will include all the rows in the database unconditionally.

After calling execute(), the attribute rowcount will indicate the number of rows matching the query (unless that information is not available from the wgdb layer).

Examples:

>>> import whitedb
>>> from wgdb import COND_EQUAL, COND_LESSTHAN, COND_NOT_EQUAL
>>> d=whitedb.connect()
>>> d.insert((2,3,4))
<whitedb.Record instance at 0x85a6b8c>
>>> d.insert(("Hello", 110))
<whitedb.Record instance at 0x85a6bcc>

One condition (column 0 should not equal 2):

>>> c=d.cursor()
>>> c.execute(arglist=[(0, COND_NOT_EQUAL, 2)])
>>> tuple(c.fetchone())
('Hello', 110)

Multiple conditions (column 1 should be < 100, column 0 should equal 2):

>>> c.execute(arglist=[(1, COND_LESSTHAN, 100), (0, COND_EQUAL, 2)])
>>> r=c.fetchone()
>>> tuple(r)
(2, 3, 4)

Try match record:

>>> d.insert((2,3,4,5))
<whitedb.Record instance at 0x85a6cac>
>>> c.execute(matchrec=r)
>>> c.rowcount
2
>>> list(map(tuple, c.fetchall()))
[(2, 3, 4), (2, 3, 4, 5)]

Empty query (all database rows match):

>>> c.execute()
>>> list(map(tuple, c.fetchall()))
[(2, 3, 4), ('Hello', 110), (2, 3, 4, 5)]

libwgdb query engine treats all match record fields that are of WG_VARTYPE, as wildcards. This can be used in Python-side match records as well (VARTYPE field is constructed using the extended type syntax convention):

>>> x=(0, whitedb.wgdb.VARTYPE)
>>> c.execute(matchrec=[2,x,4])
>>> list(map(tuple, c.fetchall()))
[(2, 3, 4), (2, 3, 4, 5)]

Database record fields can also be of WG_VARTYPE. Note that the query using such match record also returns the match record itself. The variables are represented as (varnum, VARTYPE) tuples in Python:

>>> var_rec=d.insert((x,x,4))
>>> var_rec
<whitedb.Record instance at 0x9b7ebec>
>>> c.execute(matchrec=var_rec)
>>> list(map(tuple, c.fetchall()))
[(2, 3, 4), (2, 3, 4, 5), ((0, 14), (0, 14), 4)]