~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to bzrlib/util/configobj/docs/validate.txt

  • Committer: Aaron Bentley
  • Date: 2008-03-03 16:52:41 UTC
  • mfrom: (3144.3.11 fix-conflict-handling)
  • mto: This revision was merged to the branch mainline in revision 3250.
  • Revision ID: aaron@aaronbentley.com-20080303165241-0k2c7ggs6kr9q6hf
Merge with fix-conflict-handling

Show diffs side-by-side

added added

removed removed

Lines of Context:
8
8
 
9
9
 
10
10
:Authors: `Michael Foord`_, `Nicola Larosa`_, `Mark Andrews`_
11
 
:Version: Validate 0.2.3
12
 
:Date: 2007/02/04
 
11
:Version: Validate 0.3.1
 
12
:Date: 2008/02/05
13
13
:Homepage: `Validate Homepage`_
14
14
:License: `BSD License`_
15
15
:Support: `Mailing List`_
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
21
20
.. _This Document:
22
21
.. _Validate Homepage: http://www.voidspace.org.uk/python/validate.html
23
22
.. _BSD License: http://www.voidspace.org.uk/python/license.shtml
24
23
 
25
24
 
26
25
.. contents:: Validate Manual
 
26
.. sectnum::
 
27
 
27
28
 
28
29
Introduction
29
30
============
37
38
type.
38
39
 
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
41
42
mechanism.
42
43
 
43
44
Checks look like function calls, and map to function calls. They can include
63
64
 
64
65
.. _ConfigObj: http://www.voidspace.org.uk/python/configobj.html
65
66
 
 
67
 
66
68
Downloading
67
69
===========
68
70
 
69
 
The current version is **0.2.3**, dated 4th February 2007. 
 
71
The current version is **0.3.1**, dated 5th February 2008. 
70
72
 
71
73
You can get obtain validate in the following ways :
72
74
 
 
75
 
73
76
Files
74
77
-----
75
78
 
83
86
    
84
87
* The latest development version can be obtained from the `Subversion Repository`_.
85
88
 
 
89
 
86
90
Documentation
87
91
-------------
88
92
 
89
 
*configobj.zip* contains `this document`_ and full `API Docs`_, generated 
90
 
automatically by EpyDoc_.
 
93
*configobj.zip* contains `this document`_.
91
94
 
92
95
* You can view `this document`_ online as the `Validate Homepage`_.
93
96
 
94
 
* You can also browse the `API Docs`_ online.
95
97
 
96
98
Pythonutils
97
99
-----------
101
103
Python Projects`_.
102
104
 
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.4.0.zip
 
106
.. _configobj.zip: http://www.voidspace.org.uk/cgi-bin/voidspace/downman.py?file=configobj-4.5.1.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
159
159
            dotted-quad string, i.e. '1.2.3.4'.
160
160
 
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 
 
163
         return a list.
 
164
         
 
165
:'tuple': matches any list. This check returns a tuple rather than a list.
163
166
 
164
167
:'int_list': Matches a list of integers. Takes the same arguments as list.
165
168
 
265
268
Dictionary keys/functions you pass in can override the built-in ones if you
266
269
want.
267
270
 
 
271
 
268
272
Adding functions
269
273
----------------
270
274
 
287
291
``vtor.functions``is just a dictionary that maps names to functions, so we
288
292
could also have called ``vtor.functions.update(fdict)``.
289
293
 
 
294
 
290
295
Writing the check
291
296
-----------------
292
297
 
301
306
 
302
307
but the check part will be identical .
303
308
 
 
309
 
304
310
The check method
305
311
----------------
306
312
 
352
358
    check1 = 'integer(default=50)'
353
359
    check2 = 'option("val 1", "val 2", "val 3", default="val 1")'
354
360
 
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"
357
363
 
358
364
    {-coloring}
359
365
 
368
374
optional, and may be omitted without harm.
369
375
 
370
376
 
 
377
.. note:: 
 
378
 
 
379
    As of version 0.3.0, if you specify ``default='None'`` (note the quote marks
 
380
    around ``None``) then it will be interpreted as the string ``'None'``.
 
381
 
 
382
 
371
383
List Values
372
384
~~~~~~~~~~~
373
385
 
381
393
 
382
394
    checkname(default=list('val1', 'val2', 'val3'))
383
395
 
 
396
 
 
397
get_default_value
 
398
-----------------
 
399
 
 
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``.
 
404
 
 
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).
 
407
 
 
408
 
 
409
 
384
410
Validator Exceptions
385
411
====================
386
412
 
439
465
* ``VdtValueTooShortError``
440
466
* ``VdtValueTooLongError``
441
467
 
 
468
 
442
469
Writing check functions
443
470
=======================
444
471
 
462
489
 
463
490
And that's it !
464
491
 
 
492
 
465
493
Example
466
494
-------
467
495
 
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.
552
580
 
 
581
 
 
582
Known Issues
 
583
============
 
584
 
 
585
The following parses and then blows up. The resulting error message
 
586
is confusing:
 
587
 
 
588
    ``checkname(default=list(1, 2, 3, 4)``
 
589
    
 
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.
 
593
    
 
594
 
553
595
TODO
554
596
====
555
597
 
557
599
* A timestamp check function ? (Using the ``parse`` function from ``DateUtil``).
558
600
* Allow triple quotes ? (getting a bit heavy for a regex)
559
601
 
 
602
 
560
603
ISSUES
561
604
======
562
605
 
568
611
If we could pull tuples out of arguments, it would be easier
569
612
to specify arguments for 'mixed_lists'.
570
613
 
 
614
 
571
615
CHANGELOG
572
616
=========
573
617
 
 
618
 
 
619
2008/02/05 - Version 0.3.1
 
620
--------------------------
 
621
 
 
622
BUGFIX: Unicode checks no longer broken.
 
623
 
 
624
 
 
625
2008/02/05 - Version 0.3.0
 
626
--------------------------
 
627
 
 
628
Improved performance with a parse cache.
 
629
 
 
630
New ``get_default_value`` method. Given a check it returns the default
 
631
value (converted to the correct type) or raises a ``KeyError`` if the
 
632
check doesn't specify a default.
 
633
 
 
634
Added 'tuple' check and corresponding 'is_tuple' function (which always returns a tuple).
 
635
 
 
636
BUGFIX: A quoted 'None' as a default value is no longer treated as None,
 
637
but as the string 'None'.
 
638
 
 
639
BUGFIX: We weren't unquoting keyword arguments of length two, so an
 
640
empty string didn't work as a default.
 
641
 
 
642
BUGFIX: Strings no longer pass the 'is_list' check. Additionally, the
 
643
list checks always return lists.
 
644
 
 
645
A couple of documentation bug fixes.
 
646
 
 
647
Removed CHANGELOG from module.
 
648
 
 
649
 
574
650
2007/02/04      Version 0.2.3
575
651
-----------------------------
576
652
 
620
696
-----------------------------
621
697
 
622
698
Initial version developed by `Michael Foord`_
623
 
and `Mark Andrews`_
 
699
and Mark Andrews.
624
700
 
625
701
.. note::
626
702
 
628
704
    textmacros module and the PySrc CSS stuff. See
629
705
    http://www.voidspace.org.uk/python/firedrop2/textmacros.shtml
630
706
 
 
707
 
631
708
.. raw:: html
632
709
 
633
710
    <div align="center">
650
727
                alt="Python on Voidspace" border="0" />
651
728
            </a>
652
729
        </p>
653
 
        <p>
654
 
            <a href="http://sourceforge.net/donate/index.php?group_id=123265">
655
 
                <img src="http://images.sourceforge.net/images/project-support.jpg" width="88" height="32" border="0" alt="Support This Project" /> 
656
 
            </a>
657
 
        </p>
658
 
        <p>
659
 
            <script src="http://www.google-analytics.com/urchin.js" type="text/javascript">
660
 
            </script>
661
 
            <script type="text/javascript">
662
 
            _uacct = "UA-203625-1";
663
 
            urchinTracker();
664
 
            </script>
665
 
        </p>
666
730
    </div>
667
731