khard.carddav_object module

Classes and logic to handle vCards in khard.

This module explicitly supports the vCard specifications version 3.0 and 4.0 which can be found here: - version 3.0: https://tools.ietf.org/html/rfc2426 - version 4.0: https://tools.ietf.org/html/rfc6350

class khard.carddav_object.CarddavObject(vcard, address_book, filename, supported_private_objects=None, vcard_version=None, localize_dates=False)

Bases: khard.carddav_object.YAMLEditable

classmethod clone_with_yaml_update(contact, yaml, localize_dates=False)

Use this if you want to clone an existing contact and replace its data with new user input in one step.

delete_vcard_file()
classmethod from_file(address_book, filename, query, supported_private_objects=None, localize_dates=False)

Load a CarddavObject object from a .vcf file if the plain file matches the query.

Parameters:
  • address_book (address_book.AddressBook) – the address book where this contact is stored
  • filename (str) – the file name of the .vcf file
  • query (re.Pattern|str|NoneType) – the regex to search in the source file or None to load the file unconditionally
  • supported_private_objects (list(str)|NoneType) – the list of private property names that will be loaded from the actual vcard and represented in this pobject
  • vcard_version (str|NoneType) – the version of the RFC to use
  • localize_dates (bool) – should the formatted output of anniversary and birthday be localized or should the isoformat be used instead
Returns:

the loaded CarddavObject or None if the file didn’t match

Return type:

CarddavObject or NoneType

classmethod from_yaml(address_book, yaml, supported_private_objects=None, version=None, localize_dates=False)

Use this if you want to create a new contact from user input.

classmethod new(address_book, supported_private_objects=None, version=None, localize_dates=False)

Create a new CarddavObject from scratch

print_vcard(show_address_book=True, show_uid=True)
write_to_file(overwrite=False)
class khard.carddav_object.VCardWrapper(vcard, version=None)

Bases: object

Wrapper class around a vobject.vCard object.

This class can wrap a single vCard and presents its data in a manner suitable for khard. Additionally some details of the vCard specifications in RFC 2426 (version 3.0) and RFC 6350 (version 4.0) that are not enforced by the vobject library are enforced here.

add_email(type, address)
address_types_v3 = ('dom', 'intl', 'home', 'parcel', 'postal', 'work')
address_types_v4 = ('home', 'work')
anniversary
Returns:contacts anniversary or None if not available
Return type:datetime.datetime or str
birthday

Return the birthday as a datetime object or a string depending on weather it is of type text or not. If no birthday is present in the vcard None is returned.

Returns:contacts birthday or None if not available
Return type:datetime.datetime or str or NoneType
categories
Return type:list(str) or list(list(str))
email_types_v3 = ('home', 'internet', 'work', 'x400')
email_types_v4 = ('home', 'internet', 'work')
emails
Returns:dict of type and email address list
Return type:dict(str, list(str))
formatted_name
get_first_name_last_name()
Return type:str
get_formatted_post_addresses()
get_last_name_first_name()
Return type:str
nicknames
Return type:list(str or dict(str))
notes
Return type:list(str or dict(str))
organisations
Returns:list of organisations, sorted alphabetically
Return type:list(list(str) or dict(list(str)))
phone_numbers
Returns:dict of type and phone number list
Return type:dict(str, list(str))
phone_types_v3 = ('bbs', 'car', 'cell', 'fax', 'home', 'isdn', 'msg', 'modem', 'pager', 'pcs', 'video', 'voice', 'work')
phone_types_v4 = ('text', 'voice', 'fax', 'cell', 'video', 'pager', 'textphone', 'home', 'work')
post_addresses
Returns:dict of type and post address list
Return type:dict(str, list(dict(str,list|str)))
roles
Return type:list(str or dict(str))
titles
Return type:list(str or dict(str))
uid
version
webpages
Return type:list(str or dict(str))
class khard.carddav_object.YAMLEditable(vcard, supported_private_objects=None, version=None, localize_dates=False)

Bases: khard.carddav_object.VCardWrapper

Conversion of vcards to YAML and updateing the vcard from YAML

get_formatted_anniversary()
get_formatted_birthday()
get_template()
update(input)

Update this vcard with some yaml input

Parameters:input (str) – a yaml string to parse and then use to update self
Returns:None
khard.carddav_object.convert_to_vcard(name, value, allowed_object_type)

converts user input into vcard compatible data structures

Parameters:
  • name (str) – object name, only required for error messages
  • value (str or list(str)) – user input
  • allowed_object_type (enum of type ObjectType) – set the accepted return type for vcard attribute
Returns:

cleaned user input, ready for vcard or a ValueError

Return type:

str or list(str)

khard.carddav_object.multi_property_key(item)

key function to pass to sorted(), allowing sorting of dicts with lists and strings. Dicts will be sorted by their label, after other types.

Parameters:item (a dict with a single entry or any sortable type) – member of the list being sorted
Returns:a list with two members. The first is int(isinstance(item, dict). The second is either the key from the dict or the unchanged item if it is not a dict.

:rtype list(int, type(item)) or list(int, str)