PyObjCTools.KeyValueCoding – Key-Value Coding API

Support for Key-Value Coding in Python. This provides a simple functional interface to Cocoa’s Key-Value coding that also works for regular Python objects.

Key-Value Coding is Cocoa functionality that is simular to the getattr() and setattr() functions in Python. The APIs in this module are modelled on those functions and work on Cocoa objects as well as basic Python objects.

Key-Value Coding works with keys, basically attribute names, as well as key-paths. A key-path is a string that contains a sequence of dot-separated keys and is used to chain a number of keys together.

Accessor functions

PyObjCTools.KeyValueCoding.getKey(object, key)

Return the value of the attribute referenced by key. The key is used to build the name of an accessor method or attribute name.

The following methods are tried for regular Python objects:

• Accessor method getKey

• Accessor method get_key

• Accessor method or attribute key

• Accessor method or attribute isKey

• Attribute _key

(In all of these “key” is replaced by the value of key).

This function calls the regular Key-Value Coding methods for Cocoa objects, including those implemented in Python.

Parameters:

• object – An arbitrary object

• key (string) – name of a key

Result:

the value of a key

Raise:

KeyError when the key does not exist.

PyObjCTools.KeyValueCoding.setKey(object, key, value)

Set the value of the attribute referenced by key to key. The key is used to build the name of an accessor method or attribute name.

When the object is a Cocoa object (including those implemented in Python) this method calls the regular Cocoa API for setting a property.

When the object is an instance of collections.Mapping this function uses operator.setitem() to update the dictionary.

The following methods are tried for regular Python objects:

• Accessor method setKey

• Accessor method set_key

• attribute key when that already exists (and is not a method)

• attribute _key when that already exists

• Attribute key

(In all of these “key” is replaced by the value of key).

Parameters:

• object – An arbitrary object

• key (string) – name of a key

• value – The value to set

Result:

the value of a key

Raise:

KeyError when the key does not exist.

PyObjCTools.KeyValueCoding.getKeyPath(object, keypath)

The keypath is a string containing a path of keys. The keys are separated by colons, for example "owner.firstName".

The key path is used to traverse an object graph to an attribute. This function also supports set and array operators. Those are keys of the form @operator are are used as pathToArray.@operator.pathToProperty, for example system.disks.@max.capacity.

The table below lists the supported array operators

Operator
avg	Use the rest of the keypath to fetch the value of each item in the container and returns the average of those values.
count	Returns the number of items in the container
distinctUnionOfArrays	Use the rest of the keypath to fetch the value of each item, which must be a sequence. Those sequences are merged into an array with distinct values.
distinctUnionOfObjects	Use the rest of the keypath to fetch the value of each item and return an array with all distinct values.
max	Use the rest of the keypath to fetch the value of each item in the container and returns the maximum of those values.
min	Use the rest of the keypath to fetch the value of each item in the container and returns the minimum of those values.
sum	Use the rest of the keypath to fetch the value of each item in the container and returns the sum of those values.
unionOfArrays	Like distinctUnionOfArrays, but without removing duplicates.
unionOfObjects	Like distinctUnionOfObjects, but without removing duplicates

This function calls the regular Key-Value Coding method for Cocoa objects.

Parameters:

• object – An arbitrary object

• keypath (string) – The keypath, colon separated keys

Key-Value Coding wrapper

class PyObjCTools.KeyValueCoding.kvc(value)

This wrappers value in an object that uses KeyValue Coding to implement the attribute and item accessors.