WhiteDB python bindings
========================


About this document
-------------------

The second part, "Compilation and Installation" describes the compilation,
installation and general usage of WhiteDB Python bindings.

The third part, "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.

The last part, "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).

Compilation and Installation
----------------------------

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.

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.

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.

wgdb.so (wgdb.pyd) module
-------------------------

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()


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')
 ... 


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.


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.


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.


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)


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


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
"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.
 >>> 


whitedb.py module (high level API)
-----------------------------------

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
`wgdb.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


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)]


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)


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 "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)


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'


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 "Specifying field encoding and extended information"). For
the possible conditions, see the section "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)]