5.1.2 ContactDb Object

There is one default contact database, but it is possible to create several databases with the open function.

class ContactDb

ContactDb objects have the following methods:

add_contact( )

Adds a new contact into the database. Returns a Contact object that represents the new contact. The returned object is already locked for modification. Note that a newly created contact will contain some empty default fields. If you do not want to use the default fields for anything, you can ignore them.

find( searchterm)

Finds the contacts that contain the given Unicode string as a substring and returns them as a list.

import_vcards( vcards)

Imports the vCard(s) in the given string into the database.

export_vcards( ids)

Converts the contacts corresponding to the ID's in the given tuple ids to vCards and returns them as a string.

keys( )

Returns a list of unique IDs of all Contact objects in the database.

compact_required( )

Verifies whether compacting is recommended. Returns an integer value indicating either a true or false state. Returns True if more than 32K of space is unused and if this comprises more than 50 percent of the database file, or if more than 256K is wasted in the database file.

compact( )

Compacts the database to its minimum size.

__delitem__( id)

Deletes the given contact from the database.

field_types( )

Returns a list of dictionary objects that contains information on all supported field types. The list contains dictionary objects, which each describe one field type. The most important keys in the dictionary are 'type' and 'location' which together indentify the field type. 'type' can have string values such as 'email_address'. 'location' can have the string values 'none', 'home', or 'work'. Another important key is 'storagetype', which defines the storage type of the field. 'storagetype' can have the string values 'text', 'datetime', 'item_id', or 'binary'. Note that the Contacts extension does not support adding, reading, or modifying fields of any other type than 'text' or 'datetime'. The other content returned by field_types is considered to be advanced knowledge and is not documented here.

groups

Returns contact groups of the database. Read-only.

See About this document... for information on suggesting changes.