3
|
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:
|