3
|
1 |
.. _cone-api-howto:
|
|
2 |
|
0
|
3 |
How to use cone APIs
|
|
4 |
====================
|
|
5 |
|
|
6 |
The ConE public usage is described here with few common use cases as HowTo guides.
|
|
7 |
|
3
|
8 |
* See `Cone API epydoc <../epydoc/index.html>`_ for reference guide of api functions.
|
|
9 |
|
0
|
10 |
How to open a Configuration project
|
|
11 |
-----------------------------------
|
|
12 |
|
3
|
13 |
* See reference of `Project class <../epydoc/cone.public.api.Project-class.html>`_
|
|
14 |
|
0
|
15 |
To open a project with ConE the api offers a Storage and Project classes. The Storage is the storage
|
|
16 |
agostic implemenetation for cpf/zip, filestorage and soon also a webstorage. To access anything in ConE
|
|
17 |
you must a project open.
|
|
18 |
|
3
|
19 |
|
0
|
20 |
.. code-block:: python
|
|
21 |
|
|
22 |
from cone.public import api,exceptions
|
|
23 |
"""
|
|
24 |
The Storage access can be given as a extra parameter. It can have values r=read|w=write|a=append.
|
|
25 |
The default Storage access is read, which will fail if the storage does not exist.
|
|
26 |
|
|
27 |
The Storage.open method will try which of the storage implementations can open that particular path.
|
|
28 |
So for example the path can be
|
|
29 |
'foo/bar' => Opened with FileStorage
|
|
30 |
'test.cpf' => Opened with ZipStorage
|
|
31 |
'test.zip' => Opened with ZipStorage
|
|
32 |
"""
|
|
33 |
|
|
34 |
""" Open a storage to current path and give it to the project. """
|
|
35 |
prj = api.Project(api.Storage.open('.'))
|
|
36 |
""" Create a new storage to a cpf file and give it to the project. """
|
|
37 |
prj = api.Project(api.Storage.open('test.cpf', 'w'))
|
|
38 |
|
|
39 |
|
|
40 |
How to access and manipulate Configurations
|
|
41 |
-------------------------------------------
|
|
42 |
|
3
|
43 |
* See reference of `Configuration class <../epydoc/cone.public.api.Configuration-class.html>`_
|
|
44 |
|
0
|
45 |
A Configuration normally is presented inside the Configuration project as a .confml file. So when you
|
|
46 |
are accessing configurations your are actually accessing confml files. The project offers funtionality to
|
|
47 |
get,add, remove configurations, which acts on root configurations inside the given project.
|
|
48 |
|
|
49 |
How to List configuration's
|
|
50 |
^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
51 |
|
|
52 |
.. code-block:: python
|
|
53 |
|
|
54 |
from cone.public import api,exceptions
|
|
55 |
""" Create a storage to current path and give it to the project """
|
|
56 |
prj = api.Project(api.Storage.open('.'))
|
|
57 |
""" list and print all root configurations """
|
|
58 |
configlist = prj.list_configurations()
|
|
59 |
for config in configlist:
|
|
60 |
print config
|
|
61 |
|
|
62 |
How to Open configuration
|
|
63 |
^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
64 |
|
|
65 |
|
|
66 |
.. code-block:: python
|
|
67 |
|
|
68 |
from cone.public import api,exceptions
|
|
69 |
""" Create a storage to current path and give it to the project """
|
|
70 |
prj = api.Project(api.Storage.open('.'))
|
|
71 |
""" open a with name """
|
|
72 |
"""
|
|
73 |
get_configuration raises a NotFound exception if the given configuration resource
|
|
74 |
is not found from Storage
|
|
75 |
"""
|
|
76 |
try:
|
|
77 |
myconfig = prj.get_configuration('myconfig.confml')
|
|
78 |
except exceptions.NotFound:
|
|
79 |
print "myconfml is not found from project!"
|
|
80 |
|
|
81 |
How to remove Configuration
|
|
82 |
^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
83 |
|
|
84 |
To remove a Configuration call ``remove_configuration`` method of Configuration.
|
|
85 |
|
|
86 |
.. code-block:: python
|
|
87 |
|
|
88 |
myconfig = prj.get_configuration('myconfig.confml')
|
|
89 |
myconfig.remove_configuration('my_remove.confml')
|
|
90 |
""" finally save and close project """
|
|
91 |
prj.save()
|
|
92 |
prj.close()
|
|
93 |
|
|
94 |
How to include a one Configuration to an other Configuration
|
|
95 |
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
96 |
|
|
97 |
To include a one Configuration to an other call ``include_configuration()`` method of Configuration and pass the filename of Configuration as a parameter.
|
|
98 |
|
|
99 |
.. code-block:: python
|
|
100 |
|
|
101 |
myconfig = prj.get_configuration('myconfig.confml')
|
|
102 |
myconfig.include_configuration('../data.confml')
|
|
103 |
|
3
|
104 |
|
|
105 |
How to set / write metadata to a Configuration root file
|
|
106 |
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
107 |
|
|
108 |
The metadata element is currently confml model specific, so you need to import the confml.model to enable metadata writing.
|
|
109 |
The ConfmlMeta element is desinged so that it can contain several ConfmlMetaProperty elements, each of which can be in
|
|
110 |
different xml namespaces.
|
|
111 |
|
|
112 |
.. code-block:: python
|
|
113 |
|
|
114 |
from cone.public import api
|
|
115 |
from cone.confml import model
|
|
116 |
|
|
117 |
store = api.Storage.open(".","w")
|
|
118 |
prj = api.Project(store)
|
|
119 |
config = prj.create_configuration("test_meta.confml")
|
|
120 |
|
|
121 |
prop1 = model.ConfmlMetaProperty("test", 'testing string')
|
|
122 |
prop2 = model.ConfmlMetaProperty("testName", 'testing string2', \
|
|
123 |
"http://www.nokia.com/xml/cpf-id/1", \
|
|
124 |
attrs={"name":"name1", "value": "value1"})
|
|
125 |
prop3 = model.ConfmlMetaProperty("configuration-property", None, \
|
|
126 |
"http://www.nokia.com/xml/cpf-id/1", \
|
|
127 |
attrs={"name":"sw_version", "value": "1.0.0"})
|
|
128 |
metaelem = model.ConfmlMeta([prop1, prop2, prop3])
|
|
129 |
|
|
130 |
config.meta = metaelem
|
|
131 |
config.save()
|
|
132 |
prj.close()
|
|
133 |
|
|
134 |
The output file *test_meta.confml* should look like this..
|
|
135 |
|
|
136 |
.. code-block:: xml
|
|
137 |
|
|
138 |
<configuration name="test_meta_confml" xmlns="http://www.s60.com/xml/confml/2" ...>
|
|
139 |
<meta xmlns:cv="http://www.nokia.com/xml/cpf-id/1">
|
|
140 |
<test>testing string</test>
|
|
141 |
<cv:testName name="name1" value="value1">testing string2</cv:testName>
|
|
142 |
<cv:configuration-property name="sw_version" value="1.0.0" />
|
|
143 |
</meta>
|
|
144 |
</configuration>
|
|
145 |
|
0
|
146 |
Feature Access and manipulation
|
|
147 |
-------------------------------
|
3
|
148 |
* See reference of `Feature class <../epydoc/cone.public.api.Feature-class.html>`_
|
0
|
149 |
|
|
150 |
How to add a Feature to Configuration
|
|
151 |
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
152 |
|
|
153 |
To add a Feature to Configuration ``add_feature()`` method can be used.
|
|
154 |
|
|
155 |
.. code-block:: python
|
|
156 |
|
|
157 |
conf = api.Configuration("myconf.confml")
|
|
158 |
conf.add_feature(api.Feature("feature1"))
|
|
159 |
|
|
160 |
How to add a child Feature to Feature
|
|
161 |
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
162 |
|
|
163 |
Childs can be added under Feature by ``add_feature()`` method and passing the parent Feature as a second paremeter:
|
|
164 |
|
|
165 |
.. code-block:: python
|
|
166 |
|
|
167 |
conf = api.Configuration("myconf.confml")
|
|
168 |
conf.add_feature(api.Feature("feature1"))
|
|
169 |
conf.add_feature(api.Feature("feature11"),'feature1')
|
|
170 |
|
|
171 |
How to remove Feature from Configuration
|
|
172 |
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
173 |
|
|
174 |
Features can be removed from Configuration by a following way:
|
|
175 |
|
|
176 |
.. code-block:: python
|
|
177 |
|
|
178 |
conf1 = api.Configuration("myconf.confml")
|
|
179 |
conf1.add_feature('feature1.feature12') # Add feature to Configuration
|
|
180 |
conf1.remove_feature('feature1.feature12') # and then remove it
|
|
181 |
""" finally save and close project """
|
|
182 |
prj.save()
|
|
183 |
prj.close()
|
|
184 |
|
|
185 |
|
3
|
186 |
Feature acces via Views
|
|
187 |
-----------------------
|
|
188 |
* See reference of `View class <../epydoc/cone.public.api.View-class.html>`_
|
|
189 |
* See reference of `Group class <../epydoc/cone.public.api.Group-class.html>`_
|
|
190 |
* See reference of `FeatureLink class <../epydoc/cone.public.api.FeatureLink-class.html>`_
|
|
191 |
|
0
|
192 |
How to get a Feature from Configuration
|
|
193 |
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
194 |
|
|
195 |
Features can be accessed through View:
|
|
196 |
|
|
197 |
.. code-block:: python
|
|
198 |
|
|
199 |
from cone.public import api
|
|
200 |
""" Create a storage to current path and give it to the project """
|
|
201 |
prj = api.Project(api.Storage.open('.'))
|
|
202 |
""" open the first configuration from the list """
|
|
203 |
firstconfig = prj.get_configuration(configlist[0])
|
|
204 |
""" get default view of first configuration """
|
|
205 |
default_view = firstconfig.get_default_view()
|
|
206 |
""" fetch example_feature1 from default view """
|
|
207 |
feature = default_view.get_feature('example_feature1')
|
|
208 |
|
|
209 |
Feature can be accessed also by a property:
|
|
210 |
|
|
211 |
.. code-block:: python
|
|
212 |
|
|
213 |
from cone.public import api
|
|
214 |
""" Create a storage to current path and give it to the project """
|
|
215 |
prj = api.Project(api.Storage.open('.'))
|
|
216 |
""" open the first configuration from the list """
|
|
217 |
firstconfig = prj.get_configuration(configlist[0])
|
|
218 |
""" get default view of first configuration """
|
|
219 |
default_view = firstconfig.get_default_view()
|
|
220 |
""" fetch example_feature1 from default view """
|
|
221 |
feature = default_view.example_feature1
|
|
222 |
|
|
223 |
How to list all Features inside a certain View
|
|
224 |
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
225 |
|
|
226 |
All Features can listed by calling ``list_all_features()`` method of View. Default view returns always
|
|
227 |
the view from the Root configuration point of view.
|
|
228 |
|
|
229 |
.. code-block:: python
|
|
230 |
|
|
231 |
from cone.public import api
|
|
232 |
""" Create a storage to current path and give it to the project """
|
|
233 |
prj = api.Project(api.Storage.open('.'))
|
|
234 |
""" open the first configuration from the list """
|
|
235 |
firstconfig = prj.get_configuration(configlist[0])
|
|
236 |
""" get default view of first configuration """
|
|
237 |
default_view = firstconfig.get_default_view()
|
|
238 |
""" get all features in list from default view """
|
|
239 |
features = default_view.list_all_features()
|
|
240 |
|
|
241 |
All features can be listed also using some custom View:
|
|
242 |
|
|
243 |
.. code-block:: python
|
|
244 |
|
|
245 |
from cone.public import api
|
|
246 |
""" Create a storage to current path and give it to the project """
|
|
247 |
prj = api.Project(api.Storage.open('.'))
|
|
248 |
""" open the first configuration from the list """
|
|
249 |
firstconfig = prj.get_configuration(configlist[0])
|
|
250 |
""" get my_view view to first configuration """
|
|
251 |
view = firstconfig.get_view("my_view")
|
|
252 |
""" fetch example_feature1 from my_view view """
|
|
253 |
features = view.list_all_features()
|
|
254 |
|
|
255 |
How to list Features inside a certain View
|
|
256 |
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
257 |
|
|
258 |
To list immediate Features found under the certain View can be done by calling ``list_features()`` method.
|
|
259 |
|
|
260 |
.. code-block:: python
|
|
261 |
|
|
262 |
myconfig = api.Configuration("root.confml")
|
|
263 |
view = myconfig.get_view("my_view")
|
|
264 |
features = view.list_features()
|
|
265 |
|
|
266 |
How to list all Features inside a certain Configuration
|
|
267 |
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
268 |
|
|
269 |
To list all Features found under a certain Configuration can be done by calling ``list_all_features()`` method of Configuration.
|
|
270 |
|
|
271 |
.. code-block:: python
|
|
272 |
|
|
273 |
from cone.public import api
|
|
274 |
""" Create a storage to current path and give it to the project """
|
|
275 |
prj = api.Project(api.Storage.open('.'))
|
|
276 |
""" open the first configuration from the list """
|
|
277 |
firstconfig = prj.get_configuration(configlist[0])
|
|
278 |
""" get all features in list from configuration """
|
|
279 |
features = firstconfig.list_all_features()
|
|
280 |
|
|
281 |
How to read a value for a specific Feature
|
|
282 |
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
283 |
|
|
284 |
The a value of specific Feature can be read by calling ``get_value()`` method or using value property.
|
|
285 |
|
|
286 |
.. code-block:: python
|
|
287 |
|
|
288 |
value1 = my_feature1.get_value()
|
|
289 |
value2 = my_feature2.value
|
|
290 |
|
|
291 |
How to read a possible options of selection Feature
|
|
292 |
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
293 |
|
|
294 |
To list possible options of selection Feature can be done by calling ``get_valueset()`` method of Feature.
|
|
295 |
|
|
296 |
.. code-block:: python
|
|
297 |
|
|
298 |
feature = api.Feature('my_selection_feature',type='selection')
|
|
299 |
feature.add_option('one', '1')
|
|
300 |
feature.add_option('two', '2')
|
|
301 |
value_set = feature.get_valueset()
|
|
302 |
feature.get_option('1').get_name() #returns 'one'
|
|
303 |
|
|
304 |
How to read a type of specific Feature
|
|
305 |
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
306 |
|
|
307 |
To read a specific type on Feature ``get_type()`` method or type property can be used.
|
|
308 |
|
|
309 |
.. code-block:: python
|
|
310 |
|
|
311 |
feature = dview.get_feature('my_feature')
|
|
312 |
feature.get_type() # returns type of the Feature
|
|
313 |
feature.type # returns type of the Feature
|
|
314 |
|
|
315 |
How to set a value for a specific Feature
|
|
316 |
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
317 |
|
|
318 |
To set value for a specific Feature can be done by calling ``set_value()`` method or ``value`` property.
|
|
319 |
|
|
320 |
.. code-block:: python
|
|
321 |
|
|
322 |
feature1 = dview.get_feature('my_feature1')
|
|
323 |
feature2 = dview.get_feature('my_feature2')
|
|
324 |
feature1.set_value(123)
|
|
325 |
feature2.value = "my_value"
|
|
326 |
""" finally save and close project """
|
|
327 |
prj.save()
|
|
328 |
prj.close()
|
|
329 |
|
3
|
330 |
|
|
331 |
How to Create a View
|
|
332 |
^^^^^^^^^^^^^^^^^^^^
|
|
333 |
|
|
334 |
.. code-block:: python
|
|
335 |
|
|
336 |
from cone.public import api
|
|
337 |
from cone.confml import model
|
|
338 |
|
|
339 |
store = api.Storage.open(".","w")
|
|
340 |
prj = api.Project(store)
|
|
341 |
""" First create the configuration with two features """
|
|
342 |
if prj.is_configuration("test_override.confml"):
|
|
343 |
config = prj.get_configuration("test_override.confml")
|
|
344 |
else:
|
|
345 |
config = prj.create_configuration("test_override.confml")
|
|
346 |
fea1 = config.create_feature("foo", name="foo name")
|
|
347 |
fea2 = fea1.create_feature("bar", name="bar name")
|
|
348 |
|
|
349 |
""" Create the view and group to it """
|
|
350 |
view = config.create_view('testview')
|
|
351 |
group = view.create_group('group1')
|
|
352 |
|
|
353 |
"""
|
|
354 |
Create a featurelink.
|
|
355 |
Note! the featurelink now overrides the name attribute of the original feature.
|
|
356 |
"""
|
|
357 |
link = group.create_featurelink('foo', name="foo name overridden")
|
|
358 |
""" override the description attribute of the view link """
|
|
359 |
link.desc = "override desc"
|
|
360 |
config.save()
|
|
361 |
|
|
362 |
How to Get a view and test attribute overrides
|
|
363 |
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
364 |
In this example we assume that the previous example was stored to a file *test_override.confml*.
|
|
365 |
|
|
366 |
.. code-block:: python
|
|
367 |
|
|
368 |
from cone.public import api
|
|
369 |
from cone.confml import model
|
|
370 |
|
|
371 |
store = api.Storage.open(".","w")
|
|
372 |
prj = api.Project(store)
|
|
373 |
config = prj.get_configuration("test_override.confml")
|
|
374 |
""" get the view and a feature from it """
|
|
375 |
view = config.get_view('testview')
|
|
376 |
fea = view.get_feature('group1.foo')
|
|
377 |
""" assert that the feature attributes have been overridden in the view """
|
|
378 |
assert(fea.has_attribute('name'))
|
|
379 |
assert(fea.has_attribute('desc'))
|
|
380 |
assert(fea.has_attribute('minLength') == False)
|
|
381 |
assert(fea._obj.name == 'foo name')
|
|
382 |
prj.close()
|
|
383 |
|
|
384 |
|
0
|
385 |
Data access and manipulation
|
|
386 |
----------------------------
|
|
387 |
The data access inside a configuration is possible, but basically this can be avoided by manipulating the values
|
|
388 |
of features, which actually modify the data elements inside the configuration.
|
|
389 |
However if direct data element access is needed, here's how you can do it.
|
|
390 |
|
|
391 |
How to add Data to Configuration
|
|
392 |
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
393 |
|
|
394 |
To add Data to Configuration can be done by calling ``add_data()`` method of Configuration:
|
|
395 |
|
|
396 |
.. code-block:: python
|
|
397 |
|
|
398 |
conf = api.Configuration("data.confml")
|
|
399 |
conf.add_data(api.Data(ref='feature1', value=123))
|
|
400 |
conf.add_data(api.Data(fqn='feature1.feature12', value="test"))
|
|
401 |
""" finally save and close project """
|
|
402 |
prj.save()
|
|
403 |
prj.close()
|
|
404 |
|
|
405 |
|
|
406 |
|