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