17
17
.. _Mailing List: http://lists.sourceforge.net/lists/listinfo/configobj-develop
18
18
.. _Michael Foord: fuzzyman@voidspace.org.uk
19
19
.. _Nicola Larosa: nico@teknico.net
20
.. _Mark Andrews: mark@la-la.com
22
21
.. _Validate Homepage: http://www.voidspace.org.uk/python/validate.html
23
22
.. _BSD License: http://www.voidspace.org.uk/python/license.shtml
26
25
.. contents:: Validate Manual
39
40
Checks are also strings, and are easy to write. One generic system can be used
40
to validate information from different sources, via a single consistent
41
to validate information from different sources via a single consistent
43
44
Checks look like function calls, and map to function calls. They can include
64
65
.. _ConfigObj: http://www.voidspace.org.uk/python/configobj.html
69
The current version is **0.2.1**, dated 16th December 2005.
71
The current version is **0.3.2**, dated 24th February 2008.
71
73
You can get obtain validate in the following ways :
84
87
* The latest development version can be obtained from the `Subversion Repository`_.
89
*configobj.zip* contains `this document`_ and full `API Docs`_, generated
90
automatically by EpyDoc_.
93
*configobj.zip* contains `this document`_.
92
95
* You can view `this document`_ online as the `Validate Homepage`_.
94
* You can also browse the `API Docs`_ online.
101
103
Python Projects`_.
103
105
.. _configobj.py: http://www.voidspace.org.uk/cgi-bin/voidspace/downman.py?file=configobj.py
104
.. _configobj.zip: http://www.voidspace.org.uk/cgi-bin/voidspace/downman.py?file=configobj-4.1.0.zip
106
.. _configobj.zip: http://www.voidspace.org.uk/cgi-bin/voidspace/downman.py?file=configobj-4.5.2.zip
105
107
.. _validate.py: http://www.voidspace.org.uk/cgi-bin/voidspace/downman.py?file=validate.py
106
.. _API Docs: http://www.voidspace.org.uk/python/configobj-api/
107
.. _Subversion Repository: http://svn.rest2web.python-hosting.com/branches/configobj4/
108
.. _Subversion Repository: http://svn.pythonutils.python-hosting.com/trunk/pythonutils/
108
109
.. _Sourceforge: http://sourceforge.net/projects/configobj
109
.. _EpyDoc: http://epydoc.sourceforge.net
110
110
.. _pythonutils: http://www.voidspace.org.uk/python/pythonutils.html
111
111
.. _Voidspace Python Projects: http://www.voidspace.org.uk/python
112
112
.. _validate: http://www.voidspace.org.uk/python/validate.html
141
141
:'float': matches float values
142
142
Has the same parameters as the integer check.
144
:'bool': matches boolean values: ``True`` or ``False``.
145
Acceptable string values for True are : ::
144
:'boolean': matches boolean values: ``True`` or ``False``.
145
Acceptable string values for True are : ::
159
159
dotted-quad string, i.e. '1.2.3.4'.
161
161
:'list': matches any list. Takes optional keyword args 'min', and 'max' to
162
specify min and max sizes of the list.
162
specify min and max sizes of the list. The list checks always
165
:'tuple': matches any list. This check returns a tuple rather than a list.
164
167
:'int_list': Matches a list of integers. Takes the same arguments as list.
179
182
Each position can be one of : ::
181
int, str, bool, float, ip_addr
184
int, str, boolean, float, ip_addr
183
186
So to specify a list with two strings followed by two integers,
184
187
you write the check as : ::
205
208
vtor = Validator()
206
209
newval1 = vtor.check('integer', value1)
207
newval2 = vtor.check('bool', value2)
210
newval2 = vtor.check('boolean', value2)
287
``vtor.functions``is just a dictionary that maps names to functions, so we
291
``vtor.functions`` is just a dictionary that maps names to functions, so we
288
292
could also have called ``vtor.functions.update(fdict)``.
290
295
Writing the check
291
296
-----------------
352
358
check1 = 'integer(default=50)'
353
359
check2 = 'option("val 1", "val 2", "val 3", default="val 1")'
355
assert vtor.check('', check1, missing=True) == 50
356
assert vtor.check('', check2, missing=True) == "val 1"
361
assert vtor.check(check1, '', missing=True) == 50
362
assert vtor.check(check2, '', missing=True) == "val 1"
382
394
checkname(default=list('val1', 'val2', 'val3'))
400
``Validator`` instances have a ``get_default_value`` method. It takes a ``check`` string
401
(the same string you would pass to the ``check`` method) and returns the default value,
402
converted to the right type. If the check doesn't define a default value then this method
403
raises a ``KeyError``.
405
If the ``check`` has been seen before then it will have been parsed and cached already,
406
so this method is not expensive to call (however the conversion is done each time).
384
410
Validator Exceptions
385
411
====================
550
578
If you are using validate in another circumstance you may want to create your
551
579
own subclasses of ``ValidateError``, that convey more specific information.
585
The following parses and then blows up. The resulting error message
588
``checkname(default=list(1, 2, 3, 4)``
590
This is because it parses as: ``checkname(default="list(1", 2, 3, 4)``.
591
That isn't actually unreasonable, but the error message won't help you
592
work out what has happened.
556
598
* A regex check function ?
557
* A timestamp check function ? (Using the ``parse`` function from ``DateUtil``).
558
* Allow triple quotes ? (getting a bit heavy for a regex)
599
* A timestamp check function ? (Using the ``parse`` function from ``DateUtil`` perhaps).
568
610
If we could pull tuples out of arguments, it would be easier
569
611
to specify arguments for 'mixed_lists'.
617
2008/02/24 - Version 0.3.2
618
--------------------------
620
BUGFIX: Handling of None as default value fixed.
623
2008/02/05 - Version 0.3.1
624
--------------------------
626
BUGFIX: Unicode checks no longer broken.
629
2008/02/05 - Version 0.3.0
630
--------------------------
632
Improved performance with a parse cache.
634
New ``get_default_value`` method. Given a check it returns the default
635
value (converted to the correct type) or raises a ``KeyError`` if the
636
check doesn't specify a default.
638
Added 'tuple' check and corresponding 'is_tuple' function (which always returns a tuple).
640
BUGFIX: A quoted 'None' as a default value is no longer treated as None,
641
but as the string 'None'.
643
BUGFIX: We weren't unquoting keyword arguments of length two, so an
644
empty string didn't work as a default.
646
BUGFIX: Strings no longer pass the 'is_list' check. Additionally, the
647
list checks always return lists.
649
A couple of documentation bug fixes.
651
Removed CHANGELOG from module.
654
2007/02/04 Version 0.2.3
655
-----------------------------
660
2006/12/17 Version 0.2.3-alpha1
661
------------------------------------
665
Fixed validate doc to talk of ``boolean`` instead of ``bool``; changed the
666
``is_bool`` function to ``is_boolean`` (Sourceforge bug #1531525).
669
2006/04/29 Version 0.2.2
670
-----------------------------
672
Addressed bug where a string would pass the ``is_list`` test. (Thanks to
574
676
2005/12/16 Version 0.2.1
575
677
-----------------------------
604
708
textmacros module and the PySrc CSS stuff. See
605
709
http://www.voidspace.org.uk/python/firedrop2/textmacros.shtml
609
714
<div align="center">
610
<a href="http://www.python.org">
611
<img src="images/powered_by_python.jpg" width="602" height="186" border="0" />
613
<a href="http://www.opensource.org">
614
<img src="images/osi-certified-120x100.gif" width="120" height="100" border="0" />
615
<br /><strong>Certified Open Source</strong>
618
<script type="text/javascript" language="JavaScript">var site="s16atlantibots"</script>
619
<script type="text/javascript" language="JavaScript1.2" src="http://s16.sitemeter.com/js/counter.js?site=s16atlantibots"></script>
621
<a href="http://s16.sitemeter.com/stats.asp?site=s16atlantibots">
622
<img src="http://s16.sitemeter.com/meter.asp?site=s16atlantibots" alt="Site Meter" border=0 />
716
<a href="http://www.python.org">
717
<img src="images/new_python.gif" width="100" height="103" border="0"
718
alt="Powered by Python" />
720
<a href="http://sourceforge.net">
721
<img src="http://sourceforge.net/sflogo.php?group_id=123265&type=1" width="88" height="31" border="0" alt="SourceForge.net Logo" />
723
<a href="http://www.opensource.org">
724
<img src="images/osi-certified-120x100.gif" width="120" height="100" border="0"
725
alt="Certified Open Source"/>
729
<a href="http://www.voidspace.org.uk/python/index.shtml">
730
<img src="images/pythonbanner.gif" width="468" height="60"
731
alt="Python on Voidspace" border="0" />
added
removed
bzrlib/util/configobj/docs/validate.txt
