1
===========================
2
Docutils Runtime Settings
3
===========================
6
:Contact: goodger@python.org
7
:Date: $Date: 2005-05-28 03:22:12 +0200 (Sat, 28 May 2005) $
8
:Revision: $Revision: 3398 $
9
:Copyright: This document has been placed in the public domain.
17
Docutils runtime settings are assembled from several sources:
18
component settings specifications, application settings
19
specifications, configuration files, and command-line options.
20
Docutils overlays default and explicitly specified values from these
21
sources such that settings behave the way we want and expect them to
24
To understand how Docutils deals with runtime settings, the attributes
25
and parameters involved must first be understood. Begin with the the
26
docstrings of the attributes of the ``docutils.SettingsSpec`` base
27
class (in the ``docutils/__init__.py`` module):
30
* ``settings_defaults``
31
* ``settings_default_overrides``
32
* ``relative_path_settings``
34
* ``config_section_dependencies``
36
Next, several _`convenience function parameters` are also significant
37
(described in the ``docutils.core.publish_programmatically`` function
40
* The ``settings`` parameter is a runtime settings
41
(``docutils.frontend.Values``) object which, if present, is assumed
42
to be complete (it must include all runtime settings). Also, if the
43
``settings`` parameter is present, no further runtime settings
44
processing is done. In other words, the other parameters, described
45
below, will have no effect.
47
* ``settings_spec``, a `docutils.SettingsSpec` subclass or object, is
48
treated like a fourth component (after the Parser, Reader, and
49
Writer). In other words, it's the settings specification for the
52
* ``settings_overrides`` is a dictionary which will override the
53
defaults of the components (from their settings specs).
55
* ``config_section`` specifies the name of an application-specific
56
configuration file section.
59
.. _command-line tools:
61
Runtime Settings Processing for Command-Line Tools
62
==================================================
64
Following along with the actual code is recommended. The
65
``docutils/__init__.py``, ``docutils/core.py``, and
66
``docutils.frontend.py`` modules are described.
68
1. A command-line front-end tool imports and calls
69
``docutils.core.publish_cmdline``. The relevant `convenience
70
function parameters`_ are described above.
72
2. ``docutils.core.publish_cmdline`` initializes a
73
``docutils.core.Publisher`` object, then calls its ``publish``
76
3. The ``docutils.core.Publisher`` object's ``publish`` method checks
77
its ``settings`` attribute to see if it's defined. If it is, no
78
further runtime settings processing is done.
80
If ``settings`` is not defined, ``self.process_command_line`` is
81
called with the following relevant arguments:
85
* ``settings_overrides`` (in the form of excess keyword
86
arguments, collected in the ``defaults`` parameter)
88
4. ``self.process_command_line`` calls ``self.setup_option_parser``,
89
passing ``settings_spec``, ``config_section``, and ``defaults``.
91
5. ``self.setup_option_parser`` checks its ``config_section``
92
parameter; if defined, it adds that config file section to
93
``settings_spec`` (or to a new, empty ``docutils.SettingsSpec``
94
object), replacing anything defined earlier. (See `Docutils
95
Configuration Files`_ for details.) Then it instantiates a new
96
``docutils.frontend.OptionParser`` object, passing the following
99
* ``components``: A tuple of ``docutils.SettingsSpec`` objects,
100
``(self.parser, self.reader, self.writer, settings_spec)``
101
* ``defaults`` (originally from ``settings_overrides``)
103
6. The ``docutils.frontend.OptionParser`` object's ``__init__`` method
104
calls ``self.populate_from_components`` with ``self.components``,
105
which consists of ``self`` prepended to the ``components`` tuple it
106
received. ``self`` (``docutils.frontend.OptionParser``) defines
107
general Docutils settings.
109
7. In ``self.populate_from_components``, for each component passed,
110
``component.settings_spec`` is processed and
111
``component.settings_defaults`` is applied. Then, for each
112
component, ``component.settings_default_overrides`` is applied.
113
This two-loop process ensures that
114
``component.settings_default_overrides`` can override the default
115
settings of any other component.
117
8. Back in ``docutils.frontend.OptionParser.__init__``, the
118
``defaults`` parameter (derived from the ``settings_overrides``
119
parameter of ``docutils.core.Publisher.publish``) is overlaid over
120
``self.defaults``. So ``settings_overrides`` has priority over all
121
``SettingsSpec`` data.
123
9. Next, ``docutils.frontend.OptionParser.__init__`` checks if
124
configuration files are enabled (its ``read_config_files``
125
parameter is true, and ``self.defaults['_disable_config']`` is
126
false). If they are enabled (and normally, they are),
127
``self.get_standard_config_settings`` is called. This reads the
128
`docutils configuration files`_, and returns a dictionary of
129
settings. This is then overlaid on ``self.defaults``. So
130
configuration file settings have priority over all software-defined
133
10. Back in the ``docutils.core.Publisher`` object,
134
``self.setup_option_parser`` returns the ``option_parser`` object
135
to its caller, ``self.process_command_line``.
137
11. ``self.process_command_line`` calls ``option_parser.parse_args``,
138
which parses all command line options and returns a
139
``docutils.frontend.Values`` object. This is assigned to the
140
``docutils.core.Publisher`` object's ``self.settings``. So
141
command-line options have priority over configuration file
144
When ``option_parser.parse_args`` is called, the source and
145
destination command-line arguments are also parsed, and assigned
146
to the ``_source`` and ``_destination`` attributes of what becomes
147
the ``docutils.core.Publisher`` object's ``self.settings``.
149
12. From ``docutils.core.Publisher.publish``, ``self.set_io`` is
150
called with no arguments. If either ``self.source`` or
151
``self.destination`` are not set, the corresponding
152
``self.set_source`` and ``self.set_destination`` are called,
153
effectively with no arguments.
155
13. ``self.set_source`` checks for a ``source_path`` parameter, and if
156
there is none (which is the case for command-line use), it is
157
taken from ``self.settings._source``. ``self.source`` is set by
158
instantiating a ``self.source_class`` object. For command-line
159
front-end tools, the default ``self.source_class`` is used,
160
``docutils.io.FileInput``.
162
14. ``self.set_destination`` does the same job for the destination
163
that ``self.set_source`` does for the source (the default
164
``self.destination_class`` is ``docutils.io.FileOutput``).
166
.. _Docutils Configuration Files: ../user/config.html
169
Runtime Settings Processing From Applications
170
=============================================
172
Applications process runtime settings in a different way than
173
`command-line tools`_ do. Instead of calling ``publish_cmdline``, the
174
application calls one of ``publish_file``, ``publish_string``, or
175
``publish_parts``. These in turn call ``publish_programmatically``,
176
which implements a generic programmatic interface. Although an
177
application may also call ``publish_programmatically`` directly, it is
178
not recommended (if it does seem to be necessary, please write to the
179
Docutils-develop_ mailing list).
181
``publish_programmatically`` accepts the same `convenience function
182
parameters`_ as ``publish_cmdline``. Where things differ is that
183
programmatic use does no command-line processing. Instead of calling
184
``docutils.Publisher.process_command_line`` (as ``publish_cmdline``
185
does, via ``docutils.Publisher.publish``),
186
``docutils.Publisher.process_programmatic_settings`` is called to set
187
up the runtime settings.
189
.. copy & modify the list from command-line tools?
192
.. _Docutils-develop: ../user/mailing-lists.html#docutils-develop
added
removed
docs/api/runtime-settings.txt
