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 "", line 1, in 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 >>> b=wgdb.create_record(d,3) >>> b >>> rec=wgdb.get_first_record(d) >>> wgdb.get_record_len(d,rec) 5 >>> rec >>> rec=wgdb.get_next_record(d,rec) >>> wgdb.get_record_len(d,rec) 3 >>> rec >>> rec=wgdb.get_next_record(d,rec) Traceback (most recent call last): File "", line 1, in 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 >>> 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 >>> 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 "", line 1, in 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) >>> wgdb.end_write(d,l) >>> l=wgdb.start_read(d) >>> wgdb.get_first_record(d) >>> 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 >>> wgdb.set_field(d,tmp,0,2) >>> wgdb.set_field(d,tmp,1,"hello") >>> tmp=wgdb.create_record(d,2) >>> tmp >>> 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) >>> # 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) >>> # use match record ... q=wgdb.make_query(d, [3, 4]) >>> wgdb.fetch(d, q) >>> # all rows. ... q=wgdb.make_query(d) >>> q.res_count # number of rows matching 2 >>> wgdb.fetch(d, q) >>> wgdb.fetch(d, q) >>> wgdb.fetch(d, q) # runs out of rows Traceback (most recent call last): File "", line 1, in 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")) >>> c.execute() >>> rows=c.fetchall() >>> rows [] 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 >>> c.execute() >>> rows=c.fetchall() >>> rows [, ] >>> 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 "", line 1, in 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 >>> tuple(new) Traceback (most recent call last): File "", line 1, in 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 "", line 1, in 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)) >>> d.insert(('2nd linked record', rec)) >>> c.execute() >>> l=c.fetchall() >>> list(map(tuple,l)) [(1, 2, 3, 4, 5), ('1st linked record', ), ('2nd linked record', )] Changing the contents of the original record will be visible through the records that refer to it: >>> linked=l[-2:] >>> linked [, ] >>> 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 "", line 1, in 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 >>> 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)) >>> d.insert(("Hello", 110)) 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)) >>> 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 >>> c.execute(matchrec=var_rec) >>> list(map(tuple, c.fetchall())) [(2, 3, 4), (2, 3, 4, 5), ((0, 14), (0, 14), 4)]