Mercurial > hg > configuration

annotate README.txt @ 72:c39ca7020da7

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
formatting
author Jeff Hammel <jhammel@mozilla.com>
date Wed, 28 Mar 2012 11:21:22 -0700
parents 451aeb35ec04
children 79f2d70ed5e5
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
0
Jeff Hammel <jhammel@mozilla.com>
parents:
diff changeset
1 configuration
72
c39ca7020da7 formatting
Jeff Hammel <jhammel@mozilla.com>
parents: 70
diff changeset
2 =============
0
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
72
c39ca7020da7 formatting
Jeff Hammel <jhammel@mozilla.com>
parents: 70
diff changeset
11
16
b7e7f450ad1a why do we care about configuration files?
Jeff Hammel <jhammel@mozilla.com>
parents: 0
diff changeset
12 API
b7e7f450ad1a why do we care about configuration files?
Jeff Hammel <jhammel@mozilla.com>
parents: 0
diff changeset
13 ---
b7e7f450ad1a why do we care about configuration files?
Jeff Hammel <jhammel@mozilla.com>
parents: 0
diff changeset
14
68
1025d283a570 start in on the README
Jeff Hammel <jhammel@mozilla.com>
parents: 16
diff changeset
15 The ``configuration.Configuration`` class implements an abstract base
1025d283a570 start in on the README
Jeff Hammel <jhammel@mozilla.com>
parents: 16
diff changeset
16 class that extends ``optparse.OptionParser``. The form of the
1025d283a570 start in on the README
Jeff Hammel <jhammel@mozilla.com>
parents: 16
diff changeset
17 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
18 subclass. ``options`` is a dictionary of the form::
1025d283a570 start in on the README
Jeff Hammel <jhammel@mozilla.com>
parents: 16
diff changeset
19
1025d283a570 start in on the README
Jeff Hammel <jhammel@mozilla.com>
parents: 16
diff changeset
20 {'name': {<value>}}
1025d283a570 start in on the README
Jeff Hammel <jhammel@mozilla.com>
parents: 16
diff changeset
21
1025d283a570 start in on the README
Jeff Hammel <jhammel@mozilla.com>
parents: 16
diff changeset
22 ``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
23 ``dict`` that gives the form of the option.
1025d283a570 start in on the README
Jeff Hammel <jhammel@mozilla.com>
parents: 16
diff changeset
24
70
451aeb35ec04 outline what options are available for ``value``
Jeff Hammel <jhammel@mozilla.com>
parents: 68
diff changeset
25 ``Configuration`` transforms these options into ``OptionParser`` options.
451aeb35ec04 outline what options are available for ``value``
Jeff Hammel <jhammel@mozilla.com>
parents: 68
diff changeset
26
451aeb35ec04 outline what options are available for ``value``
Jeff Hammel <jhammel@mozilla.com>
parents: 68
diff changeset
27 Options for ``value`` include:
451aeb35ec04 outline what options are available for ``value``
Jeff Hammel <jhammel@mozilla.com>
parents: 68
diff changeset
28
451aeb35ec04 outline what options are available for ``value``
Jeff Hammel <jhammel@mozilla.com>
parents: 68
diff changeset
29 * 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
30 * default: default value for the option
451aeb35ec04 outline what options are available for ``value``
Jeff Hammel <jhammel@mozilla.com>
parents: 68
diff changeset
31 * 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
32 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
33 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
34 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
35 * 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
36 * 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
37 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
38 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
39
451aeb35ec04 outline what options are available for ``value``
Jeff Hammel <jhammel@mozilla.com>
parents: 68
diff changeset
40 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
41 useful items in the ``value`` dict for ``options``.
68
1025d283a570 start in on the README
Jeff Hammel <jhammel@mozilla.com>
parents: 16
diff changeset
42
1025d283a570 start in on the README
Jeff Hammel <jhammel@mozilla.com>
parents: 16
diff changeset
43 For an example, see
1025d283a570 start in on the README
Jeff Hammel <jhammel@mozilla.com>
parents: 16
diff changeset
44 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
45
b7e7f450ad1a why do we care about configuration files?
Jeff Hammel <jhammel@mozilla.com>
parents: 0
diff changeset
46
b7e7f450ad1a why do we care about configuration files?
Jeff Hammel <jhammel@mozilla.com>
parents: 0
diff changeset
47 Configuration Files
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
b7e7f450ad1a why do we care about configuration files?
Jeff Hammel <jhammel@mozilla.com>
parents: 0
diff changeset
50 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
51 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
52 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
53 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
54 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
55 command line.
0
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 <jhammel@mozilla.com>
parents:
diff changeset
59 Jeff Hammel
Jeff Hammel <jhammel@mozilla.com>
parents:
diff changeset
60
Jeff Hammel <jhammel@mozilla.com>
parents:
diff changeset
61 http://k0s.org/mozilla/hg/configuration
Jeff Hammel <jhammel@mozilla.com>
parents:
diff changeset
62