← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

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

  • Committer: Canonical.com Patch Queue Manager
  • Date: 2007-12-20 16:16:34 UTC
  • mfrom: (3123.5.18 hardlinks)
  • Revision ID: pqm@pqm.ubuntu.com-20071220161634-2kcjb650o21ydko4
Accelerate build_tree using similar workingtrees (abentley)

Show diffs side-by-side

added added

removed removed

Lines of Context:
bzrlib/util/configobj/docs/validate.txt
8
8
 
9
9
 
10
10
:Authors: `Michael Foord`_, `Nicola Larosa`_, `Mark Andrews`_
11
 
:Version: Validate 0.3.2
12
 
:Date: 2008/02/24
 
11
:Version: Validate 0.2.3
 
12
:Date: 2007/02/04
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
20
21
.. _This Document:
21
22
.. _Validate Homepage: http://www.voidspace.org.uk/python/validate.html
22
23
.. _BSD License: http://www.voidspace.org.uk/python/license.shtml
23
24
 
24
25
 
25
26
.. contents:: Validate Manual
26
 
.. sectnum::
27
 
 
28
27
 
29
28
Introduction
30
29
============
38
37
type.
39
38
 
40
39
Checks are also strings, and are easy to write. One generic system can be used
41
 
to validate information from different sources via a single consistent
 
40
to validate information from different sources, via a single consistent
42
41
mechanism.
43
42
 
44
43
Checks look like function calls, and map to function calls. They can include
64
63
 
65
64
.. _ConfigObj: http://www.voidspace.org.uk/python/configobj.html
66
65
 
67
 
 
68
66
Downloading
69
67
===========
70
68
 
71
 
The current version is **0.3.2**, dated 24th February 2008. 
 
69
The current version is **0.2.3**, dated 4th February 2007. 
72
70
 
73
71
You can get obtain validate in the following ways :
74
72
 
75
 
 
76
73
Files
77
74
-----
78
75
 
86
83
    
87
84
* The latest development version can be obtained from the `Subversion Repository`_.
88
85
 
89
 
 
90
86
Documentation
91
87
-------------
92
88
 
93
 
*configobj.zip* contains `this document`_.
 
89
*configobj.zip* contains `this document`_ and full `API Docs`_, generated 
 
90
automatically by EpyDoc_.
94
91
 
95
92
* You can view `this document`_ online as the `Validate Homepage`_.
96
93
 
 
94
* You can also browse the `API Docs`_ online.
97
95
 
98
96
Pythonutils
99
97
-----------
103
101
Python Projects`_.
104
102
 
105
103
.. _configobj.py: http://www.voidspace.org.uk/cgi-bin/voidspace/downman.py?file=configobj.py
106
 
.. _configobj.zip: http://www.voidspace.org.uk/cgi-bin/voidspace/downman.py?file=configobj-4.5.2.zip
 
104
.. _configobj.zip: http://www.voidspace.org.uk/cgi-bin/voidspace/downman.py?file=configobj-4.4.0.zip
107
105
.. _validate.py: http://www.voidspace.org.uk/cgi-bin/voidspace/downman.py?file=validate.py
108
 
.. _Subversion Repository: http://svn.pythonutils.python-hosting.com/trunk/pythonutils/
 
106
.. _API Docs: http://www.voidspace.org.uk/python/configobj-api/
 
107
.. _Subversion Repository: http://svn.rest2web.python-hosting.com/branches/configobj4/
109
108
.. _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. The list checks always 
163
 
         return a list.
164
 
         
165
 
:'tuple': matches any list. This check returns a tuple rather than a list.
 
162
         specify min and max sizes of the list.
166
163
 
167
164
:'int_list': Matches a list of integers. Takes the same arguments as list.
168
165
 
268
265
Dictionary keys/functions you pass in can override the built-in ones if you
269
266
want.
270
267
 
271
 
 
272
268
Adding functions
273
269
----------------
274
270
 
288
284
 
289
285
    {-coloring}
290
286
 
291
 
``vtor.functions`` is just a dictionary that maps names to functions, so we
 
287
``vtor.functions``is just a dictionary that maps names to functions, so we
292
288
could also have called ``vtor.functions.update(fdict)``.
293
289
 
294
 
 
295
290
Writing the check
296
291
-----------------
297
292
 
306
301
 
307
302
but the check part will be identical .
308
303
 
309
 
 
310
304
The check method
311
305
----------------
312
306
 
358
352
    check1 = 'integer(default=50)'
359
353
    check2 = 'option("val 1", "val 2", "val 3", default="val 1")'
360
354
 
361
 
    assert vtor.check(check1, '', missing=True) == 50
362
 
    assert vtor.check(check2, '', missing=True) == "val 1"
 
355
    assert vtor.check('', check1, missing=True) == 50
 
356
    assert vtor.check('', check2, missing=True) == "val 1"
363
357
 
364
358
    {-coloring}
365
359
 
374
368
optional, and may be omitted without harm.
375
369
 
376
370
 
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
 
 
383
371
List Values
384
372
~~~~~~~~~~~
385
373
 
393
381
 
394
382
    checkname(default=list('val1', 'val2', 'val3'))
395
383
 
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
 
 
410
384
Validator Exceptions
411
385
====================
412
386
 
465
439
* ``VdtValueTooShortError``
466
440
* ``VdtValueTooLongError``
467
441
 
468
 
 
469
442
Writing check functions
470
443
=======================
471
444
 
489
462
 
490
463
And that's it !
491
464
 
492
 
 
493
465
Example
494
466
-------
495
467
 
578
550
If you are using validate in another circumstance you may want to create your 
579
551
own subclasses of ``ValidateError``, that convey more specific information.
580
552
 
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
 
 
595
553
TODO
596
554
====
597
555
 
598
556
* A regex check function ?
599
 
* A timestamp check function ? (Using the ``parse`` function from ``DateUtil`` perhaps).
600
 
 
 
557
* A timestamp check function ? (Using the ``parse`` function from ``DateUtil``).
 
558
* Allow triple quotes ? (getting a bit heavy for a regex)
601
559
 
602
560
ISSUES
603
561
======
610
568
If we could pull tuples out of arguments, it would be easier
611
569
to specify arguments for 'mixed_lists'.
612
570
 
613
 
 
614
571
CHANGELOG
615
572
=========
616
573
 
617
 
2008/02/24 - Version 0.3.2
618
 
--------------------------
619
 
 
620
 
BUGFIX: Handling of None as default value fixed.
621
 
 
622
 
 
623
 
2008/02/05 - Version 0.3.1
624
 
--------------------------
625
 
 
626
 
BUGFIX: Unicode checks no longer broken.
627
 
 
628
 
 
629
 
2008/02/05 - Version 0.3.0
630
 
--------------------------
631
 
 
632
 
Improved performance with a parse cache.
633
 
 
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.
637
 
 
638
 
Added 'tuple' check and corresponding 'is_tuple' function (which always returns a tuple).
639
 
 
640
 
BUGFIX: A quoted 'None' as a default value is no longer treated as None,
641
 
but as the string 'None'.
642
 
 
643
 
BUGFIX: We weren't unquoting keyword arguments of length two, so an
644
 
empty string didn't work as a default.
645
 
 
646
 
BUGFIX: Strings no longer pass the 'is_list' check. Additionally, the
647
 
list checks always return lists.
648
 
 
649
 
A couple of documentation bug fixes.
650
 
 
651
 
Removed CHANGELOG from module.
652
 
 
653
 
 
654
574
2007/02/04      Version 0.2.3
655
575
-----------------------------
656
576
 
700
620
-----------------------------
701
621
 
702
622
Initial version developed by `Michael Foord`_
703
 
and Mark Andrews.
 
623
and `Mark Andrews`_
704
624
 
705
625
.. note::
706
626
 
708
628
    textmacros module and the PySrc CSS stuff. See
709
629
    http://www.voidspace.org.uk/python/firedrop2/textmacros.shtml
710
630
 
711
 
 
712
631
.. raw:: html
713
632
 
714
633
    <div align="center">
731
650
                alt="Python on Voidspace" border="0" />
732
651
            </a>
733
652
        </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>
734
666
    </div>
735
667