5.1.3 Contact Object

A Contact object represents a live view into the state of a single contact in the database. You can access the fields either with a contact's numeric field ID as contact[fieldid], or using the find method. Attempting to modify a contact while it has been locked for editing in another application will raise the exception ContactBusy.

class Contact
Contact objects have the following attributes:


The unique ID of this Contact. Read-only.


The title of this Contact. Read-only.


The date/time when this Contact object was last modified. Read-only.


Returns 1 if this contact is a contact group. Returns 0 if normal contact entry. Read-only.

Contact objects have the following methods:

begin( )

Locks the contact for editing. This prevents other applications from modifying the contact for as long as the lock is held. This method will raise the exception ContactBusy if the contact has already been locked.

commit( )

Releases the lock and commits the changes made into the database.

rollback( )

Releases the lock and discards all changes that were made. The contact remains in the state it was before begin.

as_vcard( )

Returns the contact as a string in vCard format.

add_field( type [, value [, label=field_label][, location=location_spec]])

Adds a new field into this Contact. This method raises ContactBusy if the contact has been locked by some other application. type can be one of the supported field types as a string.

The following field types can be added:

  • city
  • company_name
  • country
  • date
  • dtmf_string
  • email_address
  • extended_address
  • fax_number
  • first_name
  • job_title
  • last_name
  • mobile_number
  • note
  • pager_number
  • phone_number
  • po_box
  • postal_address
  • postal_code
  • state
  • street_address
  • url
  • video_number
  • picture
  • second_name
  • voip
  • sip_id
  • personal_ringtone
  • share_view
  • prefix
  • suffix
  • push_to_talk
  • locationid_indication

The following field types are recognized but cannot be created at present:

  • first_name_reading
  • last_name_reading
  • speed_dial
  • thumbnail_image
  • voice_tag
  • wvid

All supported field types are passed as strings or Unicode strings, except for 'date' which is a float that represents Unix time. For more information on Unix time, see Section , Date and Time.

field_label is the name of the field shown to the user. If you do not pass a label, the default label for the field type is used.

location_spec, if given, must be 'home' or 'work'. Note that not all combinations of type and location are valid. The settings of the current contacts database in use determine which ones are valid.

find( [type=field_type][, location=field_location])

Finds the fields of this contact that match the given search specifications. If no parameters are given, all fields are returned.

__delitem__( fieldindex)

Deletes the given field from this contact. Note that since this will change the indices of all fields that appear after this field in the contact, and since the ContactField objects refer to the fields by index, old ContactField objects that refer to fields after the deleted field will refer to different fields after this operation.

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