Commit 73dd4869 authored by Jim Fulton's avatar Jim Fulton Committed by GitHub

Added missing section on conditional sections (#360)

Added missing section on conditional sections

Fortunately, I was able to move and update the not-bad doctest here,
because it was more doc than test.
parent dda4367a
...@@ -131,6 +131,91 @@ extends-cache buildout option <extends-cache-buildout-option>`. ...@@ -131,6 +131,91 @@ extends-cache buildout option <extends-cache-buildout-option>`.
When a relative path is used in an extends option, it's interpreted When a relative path is used in an extends option, it's interpreted
relative to the path of the extending configuration. relative to the path of the extending configuration.
Conditional configuration sections
==================================
Sometimes, you need different configuration in different environments
(different operating systems, or different versions of Python). To
make this easier, you can define environment-specific options by
providing conditional sections:
.. code-block:: ini
[ctl]
suffix =
[ctl:windows]
suffix = .bat
.. -> conf
>>> import zc.buildout.configparser
>>> import six
>>> zc.buildout.configparser.parse(
... six.StringIO(conf), 'test', lambda : dict(windows=True))
{'ctl': {'suffix': '.bat'}}
>>> zc.buildout.configparser.parse(
... six.StringIO(conf), 'test', lambda : dict(windows=False))
{'ctl': {'suffix': ''}}
In this tiny example, we've defined a ``ctl:suffix`` option that's
``.bat`` on Windows and an empty string elsewhere.
A conditional section has a colon and then a Python expression after
the name. If the Python expression result is true, the section
options from the section are included. If the value is false, the
section is ignored.
Some things to note:
- If there is no exception, then options from the section are
included.
- Sections and options can be repeated. If an option is repeated, the
last value is used. In the example above, on Windows, the second
``suffix`` option overrides the first. If the order of the sections
was reversed, the conditional section would have no effect.
In addition to the normal built-ins, the expression has access to
global variables that make common cases short and descriptive as shown
below
============= ====================================================
Name Value
============= ====================================================
sys ``sys`` module
os ``os`` module
platform ``platform`` module
re ``re`` module
python2 True if running Python 2
python3 True if running Python 3
python26 True if running Python 2.6
python27 True if running Python 2.7
python32 True if running Python 3.2
python33 True if running Python 3.3
python34 True if running Python 3.4
python35 True if running Python 3.5
python36 True if running Python 3.6
sys_version ``sys.version.lower()``
pypy True if running PyPy
jython True if running Jython
iron True if running Iron Python
cpython True if not running PyPy, Jython, or Iron Python
sys_platform ``str(sys.platform).lower()``
linux True if running on linux
windows True if running on Windows
cygwin True if running on cygwin
solaris True if running on solaris
macosx True if running on Mac OS X
posix True if running on a POSIX-compatible system
bits32 True if running on a 32-bit system.
bits64 True if running on a 64-bit system.
little_endian True if running on a little-endian system
big_endian True if running on a little-endian system
============= ====================================================
Expressions must not contain either the ``#`` or the ``;`` character.
.. _user-default-configuration: .. _user-default-configuration:
User-default configuration User-default configuration
......
...@@ -1237,133 +1237,6 @@ Cleanup. ...@@ -1237,133 +1237,6 @@ Cleanup.
>>> os.remove(os.path.join(sample_buildout, 'base.cfg')) >>> os.remove(os.path.join(sample_buildout, 'base.cfg'))
>>> rmdir(sample_buildout, 'demo') >>> rmdir(sample_buildout, 'demo')
Conditional sections
--------------------
Sometimes, you need different configuration in different environments
(different operating systems, or different versions of Python). To
make this easier, you can define environment-specific options by
providing conditional sections::
[ctl]
suffix =
[ctl:windows]
suffix = .bat
.. -> conf
>>> import zc.buildout.configparser
>>> zc.buildout.configparser.parse(
... StringIO.StringIO(conf), 'test', lambda : dict(windows=True))
{'ctl': {'suffix': '.bat'}}
>>> zc.buildout.configparser.parse(
... StringIO.StringIO(conf), 'test', lambda : dict(windows=False))
{'ctl': {'suffix': ''}}
In this tiny example, we've defined a ``ctl:suffix`` option that's
``.bat`` on Windows and an empty string elsewhere.
A conditional section has a colon and then a Python expression after
the name. If the Python expression result is true, the section
options from the section are included. If the value is false, the
section is ignored.
Some things to note:
- If there is no exception, then options from the section are
included.
- Sections and options can be repeated. If an option is repeated, the
last value is used. In the example above, on Windows, the second
``suffix`` option overrides the first. If the order of the sections
was reversed, the conditional section would have no effect.
In addition to the normal built-ins, the expression has access to
global variables that make common cases short and descriptive as shown
below
sys
the ``sys`` module
os
the ``os`` module
platform
the ``platform`` module
re
The ``re`` module
python2
We're running Python 2
python3
We're running Python 3
python26
We're running Python 2.6
python27
We're running Python 2.7
python32
We're running Python 3.2
python33
We're running Python 3.3
sys_version
``sys.version.lower()``
pypy
We're running PyPy
jython
We're running Jython
iron
We're running Iron Python
cpython
We're not running PyPy, Jython, or Iron Python
sys_platform
``str(sys.platform).lower()``
linux
We're running on linux
windows
We're running on Windows
cygwin
We're running on cygwin
solaris
We're running on solaris
macosx
We're running on Mac OS X
posix
We're running on a POSIX-compatible system
bits32
We're running on a 32-bit system.
bits64
We're running on a 64-bit system.
little_endian
We're running on a little-endian system
big_endian
We're running on a little-endian system
Expressions must not contain either the ``#`` or the ``;`` character.
Adding and removing options Adding and removing options
--------------------------- ---------------------------
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment