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 When the object is a Cocoa object (including those implemented in 62 Python) this method calls the regular Cocoa API for setting a property. 63 64 When the object is an instance of :class:`collections.Mapping` 65 this function uses :func:`operator.setitem` to update the 66 dictionary. 67 68 The following methods are tried for regular Python objects: 69 70 * Accessor method ``setKey`` 71 72 * Accessor method ``set_key`` 73 74 * attribute ``key`` when that already exists (and is not a method) 75 76 * attribute ``_key`` when that already exists 77 78 * Attribute ``key`` 79 80 (In all of these "key" is replaced by the value of ``key``). 81 82 :param object: An arbitrary object 83 :param key: name of a key 84 :param value: The value to set 85 :type key: string 86 :result: the value of a key 87 :raise: :exc:`KeyError` when the key does not exist. 88 89 90.. function:: getKeyPath(object, keypath) 91 92 The ``keypath`` is a string containing a path of keys. The keys 93 are separated by colons, for example :data:`"owner.firstName"`. 94 95 The key path is used to traverse an object graph to an attribute. This 96 function also supports set and array operators. Those are keys of 97 the form ``@operator`` are are used as ``pathToArray.@operator.pathToProperty``, 98 for example ``system.disks.@max.capacity``. 99 100 The table below lists the supported array operators 101 102 =========================== ======================================================= 103 Operator 104 =========================== ======================================================= 105 ``avg`` Use the rest of the keypath to fetch the value 106 of each item in the container and returns the 107 average of those values. 108 --------------------------- ------------------------------------------------------- 109 ``count`` Returns the number of items in the container 110 --------------------------- ------------------------------------------------------- 111 ``distinctUnionOfArrays`` Use the rest of the keypath to fetch the value of 112 each item, which must be a sequence. Those sequences 113 are merged into an array with distict values. 114 --------------------------- ------------------------------------------------------- 115 ``distinctUnionOfObjects`` Use the rest of the keypath to fetch the value of 116 each item and return an array with all distinct 117 values. 118 --------------------------- ------------------------------------------------------- 119 ``max`` Use the rest of the keypath to fetch the value 120 of each item in the container and returns the 121 maximum of those values. 122 --------------------------- ------------------------------------------------------- 123 ``min`` Use the rest of the keypath to fetch the value 124 of each item in the container and returns the 125 minimum of those values. 126 --------------------------- ------------------------------------------------------- 127 ``sum`` Use the rest of the keypath to fetch the value 128 of each item in the container and returns the 129 sum of those values. 130 --------------------------- ------------------------------------------------------- 131 ``unionOfArrays`` Like ``distinctUnionOfArrays``, but without 132 removing duplicates. 133 --------------------------- ------------------------------------------------------- 134 ``unionOfObjects`` Like ``distinctUnionOfObjects``, but without 135 removing duplicates 136 =========================== ======================================================= 137 138 This function calls the regular Key-Value Coding method for Cocoa objects. 139 140 :param object: An arbitrary object 141 :param keypath: The keypath, colon seperated keys 142 :type keypath: string 143 144.. function setKeyPath(object, keypath, value) 145 146 The ``keypath`` is a string containing a path of keys. The keys 147 are separated by colons, for example :data:`"owner.firstName"`. 148 149 The key path is used to traverse an object graph to an attribute and 150 the value is then set simularly to how :func:`setKey` sets the value. 151 152 :param object: An arbitrary object 153 :param keypath: The keypath, colon seperated keys 154 :type keypath: string 155 :param value: The value to set 156 157 158Key-Value Coding wrapper 159------------------------ 160 161.. class:: kvc(value) 162 163 This wrappers ``value`` in an object that uses KeyValue Coding 164 to implement the attribute and item accessors. 165 166 .. method __getattr__(key) 167 168 Returns ``getKey(self, key)``. 169 170 .. method __setattr__(key, value) 171 172 Returns ``setKey(self, key, value)`` if the key 173 does not start with an underscore. 174 175 Sets an attribute of the wrapper 176 when the key does start with an undercore. 177 178 .. method __getitem_(self, keypath) 179 180 Returns ``getKeyPath(self, keypath)`` 181 182 .. method __setitem_(self, keypath, value) 183 184 Returns ``setKeyPath(self, keypath, value)`` 185