`khard.carddav_object`¶

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

Module Contents¶

Classes¶

`VCardWrapper`	Wrapper class around a vobject.vCard object.
`YAMLEditable`	Conversion of vcards to YAML and updating the vcard from YAML
`CarddavObject`	Conversion of vcards to YAML and updating the vcard from YAML

Functions¶

multi_property_key(…)

Key function to pass to sorted(), allowing sorting of dicts with lists

Attributes¶

`logger`
`T`

khard.carddav_object.logger¶

khard.carddav_object.T¶

khard.carddav_object.multi_property_key(item: str) → Tuple[Literal[0], str]¶

khard.carddav_object.multi_property_key(item: Dict[T, Any]) → Tuple[Literal[1], T]

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 pair, the first item is int(isinstance(item, dict). The second is either the key from the dict or the unchanged item if it is not a dict.

class khard.carddav_object.VCardWrapper(vcard: vobject.vCard, version: str | None = None)¶

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.

property version: str¶

property uid: str¶

property birthday: khard.helpers.typing.Date | None¶

Return the birthday as a datetime object or a string depending on whether 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

property anniversary: khard.helpers.typing.Date | None¶

Returns:: contacts anniversary or None if not available

property kind: str¶

property formatted_name: str¶

property first_name: str¶

property last_name: str¶

property organisations: List[List[str] | Dict[str, List[str]]]¶

Returns:: list of organisations, sorted alphabetically

property titles: List[str | Dict[str, str]]¶

property roles: List[str | Dict[str, str]]¶

property nicknames: List[str | Dict[str, str]]¶

property notes: List[str | Dict[str, str]]¶

property webpages: List[str | Dict[str, str]]¶

property categories: List[str] | List[List[str]]¶

property phone_numbers: Dict[str, List[str]]¶

Returns:: dict of type and phone number list

property emails: Dict[str, List[str]]¶

Returns:: dict of type and email address list

property post_addresses: Dict[str, List[khard.helpers.typing.PostAddress]]¶

Returns:: dict of type and post address list

_default_kind = 'individual'¶

_default_version = '3.0'¶

_supported_versions = ('3.0', '4.0')¶

phone_types_v3 = ('bbs', 'car', 'cell', 'fax', 'home', 'isdn', 'msg', 'modem', 'pager', 'pcs', 'video', 'voice', 'work')¶

email_types_v3 = ('home', 'internet', 'work', 'x400')¶

address_types_v3 = ('dom', 'intl', 'home', 'parcel', 'postal', 'work')¶

phone_types_v4 = ('text', 'voice', 'fax', 'cell', 'video', 'pager', 'textphone', 'home', 'work')¶

email_types_v4 = ('home', 'internet', 'work')¶

address_types_v4 = ('home', 'work')¶

__str__() → str¶: Return str(self).

_get_string_field(field: str) → str¶

Get a string field from the underlying vCard.

Parameters:: field – the field value to get
Returns:: the field value or the empty string

_get_multi_property(name: str) → List¶

Get a vCard property that can exist more than once.

It does not matter what the individual vcard properties store as their value. This function returns them untouched inside an aggregating list.

If the property is part of a group containing exactly two items, with exactly one ABLABEL. the property will be prefixed with that ABLABEL.

Parameters:: name – the name of the property (should be UPPER case)
Returns:: the values from all occurrences of the named property

_delete_vcard_object(name: str) → None¶

Delete all fields with the given name from the underlying vCard.

If a field that will be deleted is in a group with an X-ABLABEL field, that X-ABLABEL field will also be deleted. These fields are commonly added by the Apple address book to attach custom labels to some fields.

Parameters:: name – the name of the fields to delete

static _parse_type_value(types: Sequence[str], supported_types: Sequence[str]) → Tuple[List[str], List[str], int]¶

Parse type value of phone numbers, email and post addresses.

Parameters:

types – list of type values
supported_types – all allowed standard types

Returns:

tuple of standard and custom types and pref integer

_get_types_for_vcard_object(object: vobject.base.ContentLine, default_type: str) → List[str]¶

get list of types for phone number, email or post address

Parameters:

object – vcard class object
default_type – use if the object contains no type

Returns:

list of type labels

_update_revision() → None¶

Generate a new REV field for the vCard, replace any existing

All vCards should only always have one revision, this is a requirement for version 4 but also makes sense for all other versions.

Return type:: NoneType

_get_ablabel(item: vobject.base.ContentLine) → str¶

Get an ABLABEL for a specified item in the vCard. Will return the ABLABEL only if the item is part of a group with exactly two items, exactly one of which is an ABLABEL.

Parameters:: item – the item to be labelled
Returns:: the ABLABEL in the circumstances above or an empty string

_get_new_group(group_type: str = '') → str¶

Get an unused group name for adding new groups. Uses the form item123 or itemgroup_type123 if a grouptype is specified.

Parameters:: group_type – (Optional) a string to add between “item” and the number
Returns:: the name of the first unused group of the specified form

_add_labelled_object(obj_type: str, user_input, name_groups: bool = False, allowed_object_type: khard.helpers.typing.ObjectType = ObjectType.str) → None¶

Add an object to the VCARD. If user_input is a dict, the object will: be added to a group with an ABLABEL created from the key of the dict.

Parameters:

obj_type – type of object to add to the VCARD.
user_input (str or list(str) or dict(str) or dict(list(str))) – Contents of the object to add. If a dict
name_groups – (Optional) If True, use the obj_type in the group name for labelled objects.
allowed_object_type – (Optional) set the accepted return type for vcard attribute

_prepare_birthday_value(date: khard.helpers.typing.Date) → Tuple[str | None, bool]¶

Prepare a value to be stored in a BDAY or ANNIVERSARY attribute.

Parameters:: date – the date like value to be stored
Returns:: the object to set as the .value for the attribute and whether it should be stored as plain text
Return type:: tuple(str,bool)

_get_names_part(part: str) → List[str]¶

Get some part of the “N” entry in the vCard as a list

Parameters:: part – the name to get e.g. “prefix” or “given”
Returns:: a list of entries for this name part

_get_name_prefixes() → List[str]¶

_get_first_names() → List[str]¶

_get_additional_names() → List[str]¶

_get_last_names() → List[str]¶

_get_name_suffixes() → List[str]¶

get_first_name_last_name() → str¶: Compute the full name of the contact by joining first, additional and last names together

get_last_name_first_name() → str¶: Compute the full name of the contact by joining the last names and then after a comma the first and additional names together

_add_name(prefix: khard.helpers.typing.StrList, first_name: khard.helpers.typing.StrList, additional_name: khard.helpers.typing.StrList, last_name: khard.helpers.typing.StrList, suffix: khard.helpers.typing.StrList) → None¶

Add an N entry to the vCard. No old entries are affected.

Parameters:

prefix –
first_name –
additional_name –
last_name –
suffix –

_add_organisation(organisation: khard.helpers.typing.StrList) → None¶

Add one ORG entry to the underlying vcard

Parameters:: organisation – the value to add

_add_title(title) → None¶

_add_role(role) → None¶

_add_nickname(nickname) → None¶

_add_note(note) → None¶

_add_webpage(webpage) → None¶

_add_category(categories: List[str]) → None¶

Add categories to the vCard

Parameters:: categories –

_add_phone_number(type: str, number: str) → None¶

add_email(type: str, address: str) → None¶

get_formatted_post_addresses() → Dict[str, List[str]]¶

_add_post_address(type, box, extended, street, code, city, region, country)¶

class khard.carddav_object.YAMLEditable(vcard: vobject.vCard, supported_private_objects: List[str] | None = None, version: str | None = None, localize_dates: bool = False)¶

Bases: VCardWrapper

Conversion of vcards to YAML and updating the vcard from YAML

_get_private_objects() → Dict[str, List[str]]¶

_add_private_object(key: str, value) → None¶

get_formatted_anniversary() → str¶

get_formatted_birthday() → str¶

static _format_date_object(date: khard.helpers.typing.Date | None, localize: bool) → str¶

static _filter_invalid_tags(contents: str) → str¶

static _parse_yaml(input: str) → Dict¶

Parse a YAML document into a dictionary and validate the data to some degree.

Parameters:: input (str) – the YAML document to parse
Returns:: the parsed data structure
Return type:: dict

static _set_string_list(setter: Callable[[str | List], None], key: str, data: Dict) → None¶

Pre-process a string or list and set each value with the given setter

Parameters:

setter – the setter method to add a value to a card
key –
data –

_set_date(target: str, key: str, data: Dict) → None¶

update(input: str) → None¶

Update this vcard with some yaml input

Parameters:: input – a yaml string to parse and then use to update self

to_yaml() → str¶

Convert this contact to a YAML string

The conversion follows the implicit schema that is given by the internal YAML template of khard.

Returns:: a YAML representation of this contact

class khard.carddav_object.CarddavObject(vcard: vobject.vCard, address_book: CarddavObject.__init__.address_book, filename: str, supported_private_objects: List[str] | None = None, vcard_version: str | None = None, localize_dates: bool = False)¶

Bases: YAMLEditable

Conversion of vcards to YAML and updating the vcard from YAML

classmethod new(address_book: CarddavObject.new.address_book, supported_private_objects: List[str] | None = None, version: str | None = None, localize_dates: bool = False) → CarddavObject¶: Create a new CarddavObject from scratch

classmethod from_file(address_book: CarddavObject.from_file.address_book, filename: str, query: khard.query.Query = AnyQuery(), supported_private_objects: List[str] | None = None, localize_dates: bool = False) → CarddavObject | None¶

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

Parameters:

address_book – the address book where this contact is stored
filename – the file name of the .vcf file
query – the query to search in the source file or None to load the file unconditionally
supported_private_objects – the list of private property names that will be loaded from the actual vcard and represented in this object
localize_dates – should the formatted output of anniversary and birthday be localized or should the iso format be used instead

Returns:

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

classmethod from_yaml(address_book: CarddavObject.from_yaml.address_book, yaml: str, supported_private_objects: List[str] | None = None, version: str | None = None, localize_dates: bool = False) → CarddavObject¶: Use this if you want to create a new contact from user input.

classmethod clone_with_yaml_update(contact: CarddavObject, yaml: str, localize_dates: bool = False) → CarddavObject¶: Use this if you want to clone an existing contact and replace its data with new user input in one step.

__eq__(other: object) → bool¶: Return self==value.

__ne__(other: object) → bool¶: Return self!=value.

pretty(verbose: bool = True) → str¶

write_to_file(overwrite: bool = False) → None¶

delete_vcard_file() → None¶

classmethod get_properties() → List[str]¶: Return the property names that are defined on this class.

khard.carddav_object¶

Module Contents¶

Classes¶

Functions¶

Attributes¶

`khard.carddav_object`¶