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