Mercurial > hg > configuration

annotate README.txt @ 70:451aeb35ec04

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
outline what options are available for ``value``
author Jeff Hammel <jhammel@mozilla.com>
date Wed, 28 Mar 2012 11:18:13 -0700
parents 1025d283a570
children c39ca7020da7
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
0
Jeff Hammel <jhammel@mozilla.com>
parents:
diff changeset
1 configuration
Jeff Hammel <jhammel@mozilla.com>
parents:
diff changeset
2 ===========
Jeff Hammel <jhammel@mozilla.com>
parents:
diff changeset
3
16
b7e7f450ad1a why do we care about configuration files?
Jeff Hammel <jhammel@mozilla.com>
parents: 0
diff changeset
4 multi-level unified configuration for python consumption
b7e7f450ad1a why do we care about configuration files?
Jeff Hammel <jhammel@mozilla.com>
parents: 0
diff changeset
5
68
1025d283a570 start in on the README
Jeff Hammel <jhammel@mozilla.com>
parents: 16
diff changeset
6 - you have a (python) program that wants to read configuration from
1025d283a570 start in on the README
Jeff Hammel <jhammel@mozilla.com>
parents: 16
diff changeset
7 configuration files (I currently support JSON and YAML) and also
1025d283a570 start in on the README
Jeff Hammel <jhammel@mozilla.com>
parents: 16
diff changeset
8 from the command line
1025d283a570 start in on the README
Jeff Hammel <jhammel@mozilla.com>
parents: 16
diff changeset
9 - you want to be able to serialize and deserialize configuration
1025d283a570 start in on the README
Jeff Hammel <jhammel@mozilla.com>
parents: 16
diff changeset
10
16
b7e7f450ad1a why do we care about configuration files?
Jeff Hammel <jhammel@mozilla.com>
parents: 0
diff changeset
11 API
b7e7f450ad1a why do we care about configuration files?
Jeff Hammel <jhammel@mozilla.com>
parents: 0
diff changeset
12 ---
b7e7f450ad1a why do we care about configuration files?
Jeff Hammel <jhammel@mozilla.com>
parents: 0
diff changeset
13
68
1025d283a570 start in on the README
Jeff Hammel <jhammel@mozilla.com>
parents: 16
diff changeset
14 The ``configuration.Configuration`` class implements an abstract base
1025d283a570 start in on the README
Jeff Hammel <jhammel@mozilla.com>
parents: 16
diff changeset
15 class that extends ``optparse.OptionParser``. The form of the
1025d283a570 start in on the README
Jeff Hammel <jhammel@mozilla.com>
parents: 16
diff changeset
16 configuration is dictated by setting the ``options`` attribute on your
1025d283a570 start in on the README
Jeff Hammel <jhammel@mozilla.com>
parents: 16
diff changeset
17 subclass. ``options`` is a dictionary of the form::
1025d283a570 start in on the README
Jeff Hammel <jhammel@mozilla.com>
parents: 16
diff changeset
18
1025d283a570 start in on the README
Jeff Hammel <jhammel@mozilla.com>
parents: 16
diff changeset
19 {'name': {<value>}}
1025d283a570 start in on the README
Jeff Hammel <jhammel@mozilla.com>
parents: 16
diff changeset
20
1025d283a570 start in on the README
Jeff Hammel <jhammel@mozilla.com>
parents: 16
diff changeset
21 ``name`` is the name of the configuration option, and ``value`` is a
1025d283a570 start in on the README
Jeff Hammel <jhammel@mozilla.com>
parents: 16
diff changeset
22 ``dict`` that gives the form of the option.
1025d283a570 start in on the README
Jeff Hammel <jhammel@mozilla.com>
parents: 16
diff changeset
23
70
451aeb35ec04 outline what options are available for ``value``
Jeff Hammel <jhammel@mozilla.com>
parents: 68
diff changeset
24 ``Configuration`` transforms these options into ``OptionParser`` options.
451aeb35ec04 outline what options are available for ``value``
Jeff Hammel <jhammel@mozilla.com>
parents: 68
diff changeset
25
451aeb35ec04 outline what options are available for ``value``
Jeff Hammel <jhammel@mozilla.com>
parents: 68
diff changeset
26 Options for ``value`` include:
451aeb35ec04 outline what options are available for ``value``
Jeff Hammel <jhammel@mozilla.com>
parents: 68
diff changeset
27
451aeb35ec04 outline what options are available for ``value``
Jeff Hammel <jhammel@mozilla.com>
parents: 68
diff changeset
28 * help : what the option is about (translated to command line help)
451aeb35ec04 outline what options are available for ``value``
Jeff Hammel <jhammel@mozilla.com>
parents: 68
diff changeset
29 * default: default value for the option
451aeb35ec04 outline what options are available for ``value``
Jeff Hammel <jhammel@mozilla.com>
parents: 68
diff changeset
30 * required: if a true value, this option must be present in the
451aeb35ec04 outline what options are available for ``value``
Jeff Hammel <jhammel@mozilla.com>
parents: 68
diff changeset
31 configuration. If ``required`` is a string, it will be displayed if
451aeb35ec04 outline what options are available for ``value``
Jeff Hammel <jhammel@mozilla.com>
parents: 68
diff changeset
32 the option is not present. If the default is defined, you won't
451aeb35ec04 outline what options are available for ``value``
Jeff Hammel <jhammel@mozilla.com>
parents: 68
diff changeset
33 need required as the default value will be used
451aeb35ec04 outline what options are available for ``value``
Jeff Hammel <jhammel@mozilla.com>
parents: 68
diff changeset
34 * type: type of the option. Used to control the parsing of the option
451aeb35ec04 outline what options are available for ``value``
Jeff Hammel <jhammel@mozilla.com>
parents: 68
diff changeset
35 * flags: a list that, if present, will be used for the command line
451aeb35ec04 outline what options are available for ``value``
Jeff Hammel <jhammel@mozilla.com>
parents: 68
diff changeset
36 flags. Othwise, the option name prepended by ``--`` will be used.
451aeb35ec04 outline what options are available for ``value``
Jeff Hammel <jhammel@mozilla.com>
parents: 68
diff changeset
37 To disable as a command line option, use an empty list ``[]``
451aeb35ec04 outline what options are available for ``value``
Jeff Hammel <jhammel@mozilla.com>
parents: 68
diff changeset
38
451aeb35ec04 outline what options are available for ``value``
Jeff Hammel <jhammel@mozilla.com>
parents: 68
diff changeset
39 In addition, you may extend ``Configuration`` and have additional
451aeb35ec04 outline what options are available for ``value``
Jeff Hammel <jhammel@mozilla.com>
parents: 68
diff changeset
40 useful items in the ``value`` dict for ``options``.
68
1025d283a570 start in on the README
Jeff Hammel <jhammel@mozilla.com>
parents: 16
diff changeset
41
1025d283a570 start in on the README
Jeff Hammel <jhammel@mozilla.com>
parents: 16
diff changeset
42 For an example, see
1025d283a570 start in on the README
Jeff Hammel <jhammel@mozilla.com>
parents: 16
diff changeset
43 http://k0s.org/mozilla/hg/configuration/file/c831eb58fb52/tests/example.py#l7
16
b7e7f450ad1a why do we care about configuration files?
Jeff Hammel <jhammel@mozilla.com>
parents: 0
diff changeset
44
b7e7f450ad1a why do we care about configuration files?
Jeff Hammel <jhammel@mozilla.com>
parents: 0
diff changeset
45
b7e7f450ad1a why do we care about configuration files?
Jeff Hammel <jhammel@mozilla.com>
parents: 0
diff changeset
46 Configuration Files
b7e7f450ad1a why do we care about configuration files?
Jeff Hammel <jhammel@mozilla.com>
parents: 0
diff changeset
47 -------------------
b7e7f450ad1a why do we care about configuration files?
Jeff Hammel <jhammel@mozilla.com>
parents: 0
diff changeset
48
b7e7f450ad1a why do we care about configuration files?
Jeff Hammel <jhammel@mozilla.com>
parents: 0
diff changeset
49 Config files are useful for (IMHO) A. complicated setup;
b7e7f450ad1a why do we care about configuration files?
Jeff Hammel <jhammel@mozilla.com>
parents: 0
diff changeset
50 B. reproducibility; C. being able to share run time configurations
b7e7f450ad1a why do we care about configuration files?
Jeff Hammel <jhammel@mozilla.com>
parents: 0
diff changeset
51 The latter is only useful if the configuration contains nothing
b7e7f450ad1a why do we care about configuration files?
Jeff Hammel <jhammel@mozilla.com>
parents: 0
diff changeset
52 machine-specific (e.g. the path to an executable might vary from
b7e7f450ad1a why do we care about configuration files?
Jeff Hammel <jhammel@mozilla.com>
parents: 0
diff changeset
53 machine to machine) or if the configuration is overridable from the
b7e7f450ad1a why do we care about configuration files?
Jeff Hammel <jhammel@mozilla.com>
parents: 0
diff changeset
54 command line.
0
Jeff Hammel <jhammel@mozilla.com>
parents:
diff changeset
55
Jeff Hammel <jhammel@mozilla.com>
parents:
diff changeset
56 ----
Jeff Hammel <jhammel@mozilla.com>
parents:
diff changeset
57
Jeff Hammel <jhammel@mozilla.com>
parents:
diff changeset
58 Jeff Hammel
Jeff Hammel <jhammel@mozilla.com>
parents:
diff changeset
59
Jeff Hammel <jhammel@mozilla.com>
parents:
diff changeset
60 http://k0s.org/mozilla/hg/configuration
Jeff Hammel <jhammel@mozilla.com>
parents:
diff changeset
61