# `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.