|
1 .. _validation-plugin-howto-example-plugin: |
|
2 |
|
3 Example ConfML validation plug-in |
|
4 ================================= |
|
5 |
|
6 The example plug-in implements a simple ConfML validator class, and so demostrates |
|
7 how ConfML validation can be extended by plug-ins. |
|
8 |
|
9 The extra validation in this case is as follows: we have a requirement that if |
|
10 a string-type ConfML setting's reference starts with ``FOO_``, its value |
|
11 should also contain the string ``foo``. For example, consider the following |
|
12 file: |
|
13 |
|
14 .. code-block :: xml |
|
15 :linenos: |
|
16 |
|
17 <?xml version="1.0" encoding="UTF-8"?> |
|
18 <configuration xmlns="http://www.s60.com/xml/confml/1" name="ExampleValidatorTest"> |
|
19 <feature ref="ExampleValidatorTest" name="Settings for example validator testing"> |
|
20 <setting ref="SomeSetting" name="Some setting" type="string"/> |
|
21 <setting ref="FOO_SomeSetting1" name="FOO - Some setting 1" type="string"/> |
|
22 <setting ref="FOO_SomeSetting2" name="FOO - Some setting 2" type="string"/> |
|
23 </feature> |
|
24 <data> |
|
25 <ExampleValidatorTest> |
|
26 <SomeSetting>foo bar</SomeSetting> |
|
27 <FOO_SomeSetting1>abc foo</FOO_SomeSetting1> |
|
28 <FOO_SomeSetting2>abc123</FOO_SomeSetting2> |
|
29 </ExampleValidatorTest> |
|
30 </data> |
|
31 </configuration> |
|
32 |
|
33 Here two settings are prefixed with ``FOO_``, but only one of them has ``foo`` |
|
34 in its value, thus our custom validator should report a warning for the value |
|
35 on line 12. |
|
36 |
|
37 Directory structure |
|
38 ------------------- |
|
39 |
|
40 - ``plugins/`` - Root directory for all ConE plug-in sources |
|
41 - ``example/`` - Example plug-in package directory |
|
42 - ``ConeExampleValidatorPlugin/`` - Source for the example validator plug-in |
|
43 - ``examplevalidatorplugin/`` - Module directory containing all plug-in code |
|
44 - ``tests/`` - Unit tests and test data for the plug-in |
|
45 - ``testdata/`` - Directory containing all test data needed by the test cases |
|
46 - ``__init__.py`` - Test module initialization file |
|
47 - ``runtests.py`` - Script for running all test cases |
|
48 - ``unittest_validation.py`` - File containing test cases |
|
49 - ``__init__.py`` - Plug-in module initialization file |
|
50 - ``validators.py`` - Plug-in source file |
|
51 - ``setup.py`` - Setup script for packaging the plug-in into an .egg file |
|
52 - ``setup.cfg`` - Configuration file for ``setup.py`` |
|
53 |
|
54 Plug-in code |
|
55 ------------ |
|
56 |
|
57 validators.py |
|
58 ............. |
|
59 |
|
60 This file defines the validator class. The validator simply goes through all |
|
61 ``ConfmlStringSetting`` instances in the configuration and checks their values. |
|
62 |
|
63 .. literalinclude:: /../source/plugins/example/ConeExampleValidatorPlugin/examplevalidatorplugin/validators.py |
|
64 :linenos: |
|
65 |
|
66 |
|
67 unittest_validation.py |
|
68 ...................... |
|
69 |
|
70 The tests for the plug-in simply contain one test case that tests the validator |
|
71 with the example ConfML file shown earlier, using the ``assert_problem_list_equals_expected()`` |
|
72 method provided by the ``testautomation`` module. |
|
73 |
|
74 .. literalinclude:: /../source/plugins/example/ConeExampleValidatorPlugin/examplevalidatorplugin/tests/unittest_validation.py |
|
75 :linenos: |
|
76 |
|
77 |
|
78 Plug-in packaging |
|
79 ----------------- |
|
80 |
|
81 The file ``setup.py`` handles the packaging of the plug-in into an egg file. |
|
82 |
|
83 The most important thing here is the plug-in's entry point info. The list |
|
84 of validator classes provided by the plug-in must be specified as an entry |
|
85 point. The entry point group in this case is ``cone.plugins.confmlvalidators``. |
|
86 |
|
87 .. literalinclude:: /../source/plugins/example/ConeExampleValidatorPlugin/setup.py |
|
88 :linenos: |