1:mod:`PyObjCTools.KeyValueCoding` -- Key-Value Coding API 2========================================================= 3 4.. module:: PyObjCTools.KeyValueCoding 5 :platform: MacOS X 6 :synopsis: Key-Value Coding API 7 8.. moduleauthor:: Ronald Oussoren <ronaldoussoren@mac.com> 9 10Support for Key-Value Coding in Python. This provides a simple functional 11interface to Cocoa's Key-Value coding that also works for regular Python 12objects. 13 14Key-Value Coding is Cocoa functionality that is simular to 15the :func:`getattr` and :func:`setattr` functions in Python. The APIs 16in this module are modelled on those functions and work on 17Cocoa objects as well as basic Python objects. 18 19Key-Value Coding works with keys, basically attribute names, as well as 20key-paths. A key-path is a string that contains a sequence of dot-separated 21keys and is used to chain a number of keys together. 22 23Accessor functions 24------------------ 25 26.. function:: getKey(object, key) 27 28 Return the value of the attribute referenced by ``key``. The key 29 is used to build the name of an accessor method or attribute name. 30 31 The following methods are tried for regular Python objects: 32 33 * Accessor method ``getKey`` 34 35 * Accessor method ``get_key`` 36 37 * Accessor method or attribute ``key`` 38 39 * Accessor meethod or attribute ``isKey`` 40 41 * Attribute ``_key`` 42 43 (In all of these "key" is replaced by the value of ``key``). 44 45 This function calls the regular Key-Value Coding methods for Cocoa objects, 46 including those implemented in Python. 47 48 :param object: An arbitrary object 49 :param key: name of a key 50 :type key: string 51 :result: the value of a key 52 :raise: :exc:`KeyError` when the key does not exist. 53 54 55.. function:: setKey(object, key, value) 56 57 Set the value of the attribute referenced by ``key`` to 58 ``key``. The key is used to build the name of an accessor 59 method or attribute name. 60 61 The following methods are tried for regular Python objects: 62 63 * Accessor method ``setKey`` 64 65 * Accessor method ``set_key`` 66 67 * attribute ``_key`` 68 69 * Attribute ``key`` 70 71 (In all of these "key" is replaced by the value of ``key``). 72 73 This function calls the regular Key-Value Coding methods for Cocoa objects, 74 including those implemented in Python. 75 76 :param object: An arbitrary object 77 :param key: name of a key 78 :param value: The value to set 79 :type key: string 80 :result: the value of a key 81 :raise: :exc:`KeyError` when the key does not exist. 82 83 84.. function:: getKeyPath(object, keypath) 85 86 The ``keypath`` is a string containing a path of keys. The keys 87 are separated by colons, for example :data:`"owner.firstName"`. 88 89 The key path is used to traverse an object graph to an attribute. This 90 function also supports set and array operators. Those are keys of 91 the form ``@operator`` are are used as ``pathToArray.@operator.pathToProperty``, 92 for example ``system.disks.@max.capacity``. 93 94 The table below lists the supported array operators 95 96 =========================== ======================================================= 97 Operator 98 =========================== ======================================================= 99 ``avg`` Use the rest of the keypath to fetch the value 100 of each item in the container and returns the 101 average of those values. 102 --------------------------- ------------------------------------------------------- 103 ``count`` Returns the number of items in the container 104 --------------------------- ------------------------------------------------------- 105 ``distinctUnionOfArrays`` Use the rest of the keypath to fetch the value of 106 each item, which must be a sequence. Those sequences 107 are merged into an array with distict values. 108 --------------------------- ------------------------------------------------------- 109 ``distinctUnionOfObjects`` Use the rest of the keypath to fetch the value of 110 each item and return an array with all distinct 111 values. 112 --------------------------- ------------------------------------------------------- 113 ``max`` Use the rest of the keypath to fetch the value 114 of each item in the container and returns the 115 maximum of those values. 116 --------------------------- ------------------------------------------------------- 117 ``min`` Use the rest of the keypath to fetch the value 118 of each item in the container and returns the 119 minimum of those values. 120 --------------------------- ------------------------------------------------------- 121 ``sum`` Use the rest of the keypath to fetch the value 122 of each item in the container and returns the 123 sum of those values. 124 --------------------------- ------------------------------------------------------- 125 ``unionOfArrays`` Like ``distinctUnionOfArrays``, but without 126 removing duplicates. 127 --------------------------- ------------------------------------------------------- 128 ``unionOfObjects`` Like ``distinctUnionOfObjects``, but without 129 removing duplicates 130 =========================== ======================================================= 131 132 This function calls the regular Key-Value Coding method for Cocoa objects. 133 134 :param object: An arbitrary object 135 :param keypath: The keypath, colon seperated keys 136 :type keypath: string 137 138.. function setKeyPath(object, keypath, value) 139 140 The ``keypath`` is a string containing a path of keys. The keys 141 are separated by colons, for example :data:`"owner.firstName"`. 142 143 The key path is used to traverse an object graph to an attribute and 144 the value is then set simularly to how :func:`setKey` sets the value. 145 146 :param object: An arbitrary object 147 :param keypath: The keypath, colon seperated keys 148 :type keypath: string 149 :param value: The value to set 150 151 152Key-Value Coding wrapper 153------------------------ 154 155.. class:: kvc(value) 156 157 This wrappers ``value`` in an object that uses KeyValue Coding 158 to implement the attribute and item accessors. 159 160 .. method __getattr__(key) 161 162 Returns ``getKey(self, key)``. 163 164 .. method __setattr__(key, value) 165 166 Returns ``setKey(self, key, value)``. 167 168 .. method __getitem_(self, keypath) 169 170 Returns ``getKeyPath(self, keypath)`` 171 172 .. method __setitem_(self, keypath, value) 173 174 Returns ``setKeyPath(self, keypath, value)`` 175