Mercurial > repos > shellac > guppy_basecaller

comparison env/lib/python3.7/site-packages/docutils/frontend.py @ 5:9b1c78e6ba9c draft default tip

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
"planemo upload commit 6c0a8142489327ece472c84e558c47da711a9142"
author shellac
date Mon, 01 Jun 2020 08:59:25 -0400
parents 79f47841a781
children
comparison
equal deleted inserted replaced
4:79f47841a781 5:9b1c78e6ba9c
1 # $Id: frontend.py 8439 2019-12-13 17:02:41Z milde $
2 # Author: David Goodger <goodger@python.org>
3 # Copyright: This module has been placed in the public domain.
4
5 """
6 Command-line and common processing for Docutils front-end tools.
7
8 Exports the following classes:
9
10 * `OptionParser`: Standard Docutils command-line processing.
11 * `Option`: Customized version of `optparse.Option`; validation support.
12 * `Values`: Runtime settings; objects are simple structs
13 (``object.attribute``). Supports cumulative list settings (attributes).
14 * `ConfigParser`: Standard Docutils config file processing.
15
16 Also exports the following functions:
17
18 * Option callbacks: `store_multiple`, `read_config_file`.
19 * Setting validators: `validate_encoding`,
20 `validate_encoding_error_handler`,
21 `validate_encoding_and_error_handler`,
22 `validate_boolean`, `validate_ternary`, `validate_threshold`,
23 `validate_colon_separated_string_list`,
24 `validate_comma_separated_string_list`,
25 `validate_dependency_file`.
26 * `make_paths_absolute`.
27 * SettingSpec manipulation: `filter_settings_spec`.
28 """
29
30 __docformat__ = 'reStructuredText'
31
32 import os
33 import os.path
34 import sys
35 import warnings
36 import codecs
37 import optparse
38 from optparse import SUPPRESS_HELP
39 if sys.version_info >= (3, 0):
40 from configparser import RawConfigParser
41 from os import getcwd
42 else:
43 from ConfigParser import RawConfigParser
44 from os import getcwdu as getcwd
45
46 import docutils
47 import docutils.utils
48 import docutils.nodes
49 from docutils.utils.error_reporting import (locale_encoding, SafeString,
50 ErrorOutput, ErrorString)
51
52 if sys.version_info >= (3, 0):
53 unicode = str # noqa
54
55
56 def store_multiple(option, opt, value, parser, *args, **kwargs):
57 """
58 Store multiple values in `parser.values`. (Option callback.)
59
60 Store `None` for each attribute named in `args`, and store the value for
61 each key (attribute name) in `kwargs`.
62 """
63 for attribute in args:
64 setattr(parser.values, attribute, None)
65 for key, value in kwargs.items():
66 setattr(parser.values, key, value)
67
68 def read_config_file(option, opt, value, parser):
69 """
70 Read a configuration file during option processing. (Option callback.)
71 """
72 try:
73 new_settings = parser.get_config_file_settings(value)
74 except ValueError as error:
75 parser.error(error)
76 parser.values.update(new_settings, parser)
77
78 def validate_encoding(setting, value, option_parser,
79 config_parser=None, config_section=None):
80 try:
81 codecs.lookup(value)
82 except LookupError:
83 raise LookupError('setting "%s": unknown encoding: "%s"'
84 % (setting, value))
85 return value
86
87 def validate_encoding_error_handler(setting, value, option_parser,
88 config_parser=None, config_section=None):
89 try:
90 codecs.lookup_error(value)
91 except LookupError:
92 raise LookupError(
93 'unknown encoding error handler: "%s" (choices: '
94 '"strict", "ignore", "replace", "backslashreplace", '
95 '"xmlcharrefreplace", and possibly others; see documentation for '
96 'the Python ``codecs`` module)' % value)
97 return value
98
99 def validate_encoding_and_error_handler(
100 setting, value, option_parser, config_parser=None, config_section=None):
101 """
102 Side-effect: if an error handler is included in the value, it is inserted
103 into the appropriate place as if it was a separate setting/option.
104 """
105 if ':' in value:
106 encoding, handler = value.split(':')
107 validate_encoding_error_handler(
108 setting + '_error_handler', handler, option_parser,
109 config_parser, config_section)
110 if config_parser:
111 config_parser.set(config_section, setting + '_error_handler',
112 handler)
113 else:
114 setattr(option_parser.values, setting + '_error_handler', handler)
115 else:
116 encoding = value
117 validate_encoding(setting, encoding, option_parser,
118 config_parser, config_section)
119 return encoding
120
121 def validate_boolean(setting, value, option_parser,
122 config_parser=None, config_section=None):
123 """Check/normalize boolean settings:
124 True: '1', 'on', 'yes', 'true'
125 False: '0', 'off', 'no','false', ''
126 """
127 if isinstance(value, bool):
128 return value
129 try:
130 return option_parser.booleans[value.strip().lower()]
131 except KeyError:
132 raise LookupError('unknown boolean value: "%s"' % value)
133
134 def validate_ternary(setting, value, option_parser,
135 config_parser=None, config_section=None):
136 """Check/normalize three-value settings:
137 True: '1', 'on', 'yes', 'true'
138 False: '0', 'off', 'no','false', ''
139 any other value: returned as-is.
140 """
141 if isinstance(value, bool) or value is None:
142 return value
143 try:
144 return option_parser.booleans[value.strip().lower()]
145 except KeyError:
146 return value
147
148 def validate_nonnegative_int(setting, value, option_parser,
149 config_parser=None, config_section=None):
150 value = int(value)
151 if value < 0:
152 raise ValueError('negative value; must be positive or zero')
153 return value
154
155 def validate_threshold(setting, value, option_parser,
156 config_parser=None, config_section=None):
157 try:
158 return int(value)
159 except ValueError:
160 try:
161 return option_parser.thresholds[value.lower()]
162 except (KeyError, AttributeError):
163 raise LookupError('unknown threshold: %r.' % value)
164
165 def validate_colon_separated_string_list(
166 setting, value, option_parser, config_parser=None, config_section=None):
167 if not isinstance(value, list):
168 value = value.split(':')
169 else:
170 last = value.pop()
171 value.extend(last.split(':'))
172 return value
173
174 def validate_comma_separated_list(setting, value, option_parser,
175 config_parser=None, config_section=None):
176 """Check/normalize list arguments (split at "," and strip whitespace).
177 """
178 # `value` is already a ``list`` when given as command line option
179 # and "action" is "append" and ``unicode`` or ``str`` else.
180 if not isinstance(value, list):
181 value = [value]
182 # this function is called for every option added to `value`
183 # -> split the last item and append the result:
184 last = value.pop()
185 items = [i.strip(u' \t\n') for i in last.split(u',') if i.strip(u' \t\n')]
186 value.extend(items)
187 return value
188
189 def validate_url_trailing_slash(
190 setting, value, option_parser, config_parser=None, config_section=None):
191 if not value:
192 return './'
193 elif value.endswith('/'):
194 return value
195 else:
196 return value + '/'
197
198 def validate_dependency_file(setting, value, option_parser,
199 config_parser=None, config_section=None):
200 try:
201 return docutils.utils.DependencyList(value)
202 except IOError:
203 return docutils.utils.DependencyList(None)
204
205 def validate_strip_class(setting, value, option_parser,
206 config_parser=None, config_section=None):
207 # value is a comma separated string list:
208 value = validate_comma_separated_list(setting, value, option_parser,
209 config_parser, config_section)
210 # validate list elements:
211 for cls in value:
212 normalized = docutils.nodes.make_id(cls)
213 if cls != normalized:
214 raise ValueError('Invalid class value %r (perhaps %r?)'
215 % (cls, normalized))
216 return value
217
218 def validate_smartquotes_locales(setting, value, option_parser,
219 config_parser=None, config_section=None):
220 """Check/normalize a comma separated list of smart quote definitions.
221
222 Return a list of (language-tag, quotes) string tuples."""
223
224 # value is a comma separated string list:
225 value = validate_comma_separated_list(setting, value, option_parser,
226 config_parser, config_section)
227 # validate list elements
228 lc_quotes = []
229 for item in value:
230 try:
231 lang, quotes = item.split(':', 1)
232 except AttributeError:
233 # this function is called for every option added to `value`
234 # -> ignore if already a tuple:
235 lc_quotes.append(item)
236 continue
237 except ValueError:
238 raise ValueError(u'Invalid value "%s".'
239 ' Format is "<language>:<quotes>".'
240 % item.encode('ascii', 'backslashreplace'))
241 # parse colon separated string list:
242 quotes = quotes.strip()
243 multichar_quotes = quotes.split(':')
244 if len(multichar_quotes) == 4:
245 quotes = multichar_quotes
246 elif len(quotes) != 4:
247 raise ValueError('Invalid value "%s". Please specify 4 quotes\n'
248 ' (primary open/close; secondary open/close).'
249 % item.encode('ascii', 'backslashreplace'))
250 lc_quotes.append((lang, quotes))
251 return lc_quotes
252
253 def make_paths_absolute(pathdict, keys, base_path=None):
254 """
255 Interpret filesystem path settings relative to the `base_path` given.
256
257 Paths are values in `pathdict` whose keys are in `keys`. Get `keys` from
258 `OptionParser.relative_path_settings`.
259 """
260 if base_path is None:
261 base_path = getcwd() # type(base_path) == unicode
262 # to allow combining non-ASCII cwd with unicode values in `pathdict`
263 for key in keys:
264 if key in pathdict:
265 value = pathdict[key]
266 if isinstance(value, list):
267 value = [make_one_path_absolute(base_path, path)
268 for path in value]
269 elif value:
270 value = make_one_path_absolute(base_path, value)
271 pathdict[key] = value
272
273 def make_one_path_absolute(base_path, path):
274 return os.path.abspath(os.path.join(base_path, path))
275
276 def filter_settings_spec(settings_spec, *exclude, **replace):
277 """Return a copy of `settings_spec` excluding/replacing some settings.
278
279 `settings_spec` is a tuple of configuration settings with a structure
280 described for docutils.SettingsSpec.settings_spec.
281
282 Optional positional arguments are names of to-be-excluded settings.
283 Keyword arguments are option specification replacements.
284 (See the html4strict writer for an example.)
285 """
286 settings = list(settings_spec)
287 # every third item is a sequence of option tuples
288 for i in range(2, len(settings), 3):
289 newopts = []
290 for opt_spec in settings[i]:
291 # opt_spec is ("<help>", [<option strings>], {<keyword args>})
292 opt_name = [opt_string[2:].replace('-', '_')
293 for opt_string in opt_spec[1]
294 if opt_string.startswith('--')
295 ][0]
296 if opt_name in exclude:
297 continue
298 if opt_name in replace.keys():
299 newopts.append(replace[opt_name])
300 else:
301 newopts.append(opt_spec)
302 settings[i] = tuple(newopts)
303 return tuple(settings)
304
305
306 class Values(optparse.Values):
307
308 """
309 Updates list attributes by extension rather than by replacement.
310 Works in conjunction with the `OptionParser.lists` instance attribute.
311 """
312
313 def __init__(self, *args, **kwargs):
314 optparse.Values.__init__(self, *args, **kwargs)
315 if (not hasattr(self, 'record_dependencies')
316 or self.record_dependencies is None):
317 # Set up dependency list, in case it is needed.
318 self.record_dependencies = docutils.utils.DependencyList()
319
320 def update(self, other_dict, option_parser):
321 if isinstance(other_dict, Values):
322 other_dict = other_dict.__dict__
323 other_dict = other_dict.copy()
324 for setting in option_parser.lists.keys():
325 if (hasattr(self, setting) and setting in other_dict):
326 value = getattr(self, setting)
327 if value:
328 value += other_dict[setting]
329 del other_dict[setting]
330 self._update_loose(other_dict)
331
332 def copy(self):
333 """Return a shallow copy of `self`."""
334 return self.__class__(defaults=self.__dict__)
335
336
337 class Option(optparse.Option):
338
339 ATTRS = optparse.Option.ATTRS + ['validator', 'overrides']
340
341 def process(self, opt, value, values, parser):
342 """
343 Call the validator function on applicable settings and
344 evaluate the 'overrides' option.
345 Extends `optparse.Option.process`.
346 """
347 result = optparse.Option.process(self, opt, value, values, parser)
348 setting = self.dest
349 if setting:
350 if self.validator:
351 value = getattr(values, setting)
352 try:
353 new_value = self.validator(setting, value, parser)
354 except Exception as error:
355 raise optparse.OptionValueError(
356 'Error in option "%s":\n %s'
357 % (opt, ErrorString(error)))
358 setattr(values, setting, new_value)
359 if self.overrides:
360 setattr(values, self.overrides, None)
361 return result
362
363
364 class OptionParser(optparse.OptionParser, docutils.SettingsSpec):
365
366 """
367 Parser for command-line and library use. The `settings_spec`
368 specification here and in other Docutils components are merged to build
369 the set of command-line options and runtime settings for this process.
370
371 Common settings (defined below) and component-specific settings must not
372 conflict. Short options are reserved for common settings, and components
373 are restrict to using long options.
374 """
375
376 standard_config_files = [
377 '/etc/docutils.conf', # system-wide
378 './docutils.conf', # project-specific
379 '~/.docutils'] # user-specific
380 """Docutils configuration files, using ConfigParser syntax. Filenames
381 will be tilde-expanded later. Later files override earlier ones."""
382
383 threshold_choices = 'info 1 warning 2 error 3 severe 4 none 5'.split()
384 """Possible inputs for for --report and --halt threshold values."""
385
386 thresholds = {'info': 1, 'warning': 2, 'error': 3, 'severe': 4, 'none': 5}
387 """Lookup table for --report and --halt threshold values."""
388
389 booleans={'1': True, 'on': True, 'yes': True, 'true': True,
390 '0': False, 'off': False, 'no': False, 'false': False, '': False}
391 """Lookup table for boolean configuration file settings."""
392
393 default_error_encoding = getattr(sys.stderr, 'encoding',
394 None) or locale_encoding or 'ascii'
395
396 default_error_encoding_error_handler = 'backslashreplace'
397
398 settings_spec = (
399 'General Docutils Options',
400 None,
401 (('Specify the document title as metadata.',
402 ['--title'], {}),
403 ('Include a "Generated by Docutils" credit and link.',
404 ['--generator', '-g'], {'action': 'store_true',
405 'validator': validate_boolean}),
406 ('Do not include a generator credit.',
407 ['--no-generator'], {'action': 'store_false', 'dest': 'generator'}),
408 ('Include the date at the end of the document (UTC).',
409 ['--date', '-d'], {'action': 'store_const', 'const': '%Y-%m-%d',
410 'dest': 'datestamp'}),
411 ('Include the time & date (UTC).',
412 ['--time', '-t'], {'action': 'store_const',
413 'const': '%Y-%m-%d %H:%M UTC',
414 'dest': 'datestamp'}),
415 ('Do not include a datestamp of any kind.',
416 ['--no-datestamp'], {'action': 'store_const', 'const': None,
417 'dest': 'datestamp'}),
418 ('Include a "View document source" link.',
419 ['--source-link', '-s'], {'action': 'store_true',
420 'validator': validate_boolean}),
421 ('Use <URL> for a source link; implies --source-link.',
422 ['--source-url'], {'metavar': '<URL>'}),
423 ('Do not include a "View document source" link.',
424 ['--no-source-link'],
425 {'action': 'callback', 'callback': store_multiple,
426 'callback_args': ('source_link', 'source_url')}),
427 ('Link from section headers to TOC entries. (default)',
428 ['--toc-entry-backlinks'],
429 {'dest': 'toc_backlinks', 'action': 'store_const', 'const': 'entry',
430 'default': 'entry'}),
431 ('Link from section headers to the top of the TOC.',
432 ['--toc-top-backlinks'],
433 {'dest': 'toc_backlinks', 'action': 'store_const', 'const': 'top'}),
434 ('Disable backlinks to the table of contents.',
435 ['--no-toc-backlinks'],
436 {'dest': 'toc_backlinks', 'action': 'store_false'}),
437 ('Link from footnotes/citations to references. (default)',
438 ['--footnote-backlinks'],
439 {'action': 'store_true', 'default': 1,
440 'validator': validate_boolean}),
441 ('Disable backlinks from footnotes and citations.',
442 ['--no-footnote-backlinks'],
443 {'dest': 'footnote_backlinks', 'action': 'store_false'}),
444 ('Enable section numbering by Docutils. (default)',
445 ['--section-numbering'],
446 {'action': 'store_true', 'dest': 'sectnum_xform',
447 'default': 1, 'validator': validate_boolean}),
448 ('Disable section numbering by Docutils.',
449 ['--no-section-numbering'],
450 {'action': 'store_false', 'dest': 'sectnum_xform'}),
451 ('Remove comment elements from the document tree.',
452 ['--strip-comments'],
453 {'action': 'store_true', 'validator': validate_boolean}),
454 ('Leave comment elements in the document tree. (default)',
455 ['--leave-comments'],
456 {'action': 'store_false', 'dest': 'strip_comments'}),
457 ('Remove all elements with classes="<class>" from the document tree. '
458 'Warning: potentially dangerous; use with caution. '
459 '(Multiple-use option.)',
460 ['--strip-elements-with-class'],
461 {'action': 'append', 'dest': 'strip_elements_with_classes',
462 'metavar': '<class>', 'validator': validate_strip_class}),
463 ('Remove all classes="<class>" attributes from elements in the '
464 'document tree. Warning: potentially dangerous; use with caution. '
465 '(Multiple-use option.)',
466 ['--strip-class'],
467 {'action': 'append', 'dest': 'strip_classes',
468 'metavar': '<class>', 'validator': validate_strip_class}),
469 ('Report system messages at or higher than <level>: "info" or "1", '
470 '"warning"/"2" (default), "error"/"3", "severe"/"4", "none"/"5"',
471 ['--report', '-r'], {'choices': threshold_choices, 'default': 2,
472 'dest': 'report_level', 'metavar': '<level>',
473 'validator': validate_threshold}),
474 ('Report all system messages. (Same as "--report=1".)',
475 ['--verbose', '-v'], {'action': 'store_const', 'const': 1,
476 'dest': 'report_level'}),
477 ('Report no system messages. (Same as "--report=5".)',
478 ['--quiet', '-q'], {'action': 'store_const', 'const': 5,
479 'dest': 'report_level'}),
480 ('Halt execution at system messages at or above <level>. '
481 'Levels as in --report. Default: 4 (severe).',
482 ['--halt'], {'choices': threshold_choices, 'dest': 'halt_level',
483 'default': 4, 'metavar': '<level>',
484 'validator': validate_threshold}),
485 ('Halt at the slightest problem. Same as "--halt=info".',
486 ['--strict'], {'action': 'store_const', 'const': 1,
487 'dest': 'halt_level'}),
488 ('Enable a non-zero exit status for non-halting system messages at '
489 'or above <level>. Default: 5 (disabled).',
490 ['--exit-status'], {'choices': threshold_choices,
491 'dest': 'exit_status_level',
492 'default': 5, 'metavar': '<level>',
493 'validator': validate_threshold}),
494 ('Enable debug-level system messages and diagnostics.',
495 ['--debug'], {'action': 'store_true', 'validator': validate_boolean}),
496 ('Disable debug output. (default)',
497 ['--no-debug'], {'action': 'store_false', 'dest': 'debug'}),
498 ('Send the output of system messages to <file>.',
499 ['--warnings'], {'dest': 'warning_stream', 'metavar': '<file>'}),
500 ('Enable Python tracebacks when Docutils is halted.',
501 ['--traceback'], {'action': 'store_true', 'default': None,
502 'validator': validate_boolean}),
503 ('Disable Python tracebacks. (default)',
504 ['--no-traceback'], {'dest': 'traceback', 'action': 'store_false'}),
505 ('Specify the encoding and optionally the '
506 'error handler of input text. Default: <locale-dependent>:strict.',
507 ['--input-encoding', '-i'],
508 {'metavar': '<name[:handler]>',
509 'validator': validate_encoding_and_error_handler}),
510 ('Specify the error handler for undecodable characters. '
511 'Choices: "strict" (default), "ignore", and "replace".',
512 ['--input-encoding-error-handler'],
513 {'default': 'strict', 'validator': validate_encoding_error_handler}),
514 ('Specify the text encoding and optionally the error handler for '
515 'output. Default: UTF-8:strict.',
516 ['--output-encoding', '-o'],
517 {'metavar': '<name[:handler]>', 'default': 'utf-8',
518 'validator': validate_encoding_and_error_handler}),
519 ('Specify error handler for unencodable output characters; '
520 '"strict" (default), "ignore", "replace", '
521 '"xmlcharrefreplace", "backslashreplace".',
522 ['--output-encoding-error-handler'],
523 {'default': 'strict', 'validator': validate_encoding_error_handler}),
524 ('Specify text encoding and error handler for error output. '
525 'Default: %s:%s.'
526 % (default_error_encoding, default_error_encoding_error_handler),
527 ['--error-encoding', '-e'],
528 {'metavar': '<name[:handler]>', 'default': default_error_encoding,
529 'validator': validate_encoding_and_error_handler}),
530 ('Specify the error handler for unencodable characters in '
531 'error output. Default: %s.'
532 % default_error_encoding_error_handler,
533 ['--error-encoding-error-handler'],
534 {'default': default_error_encoding_error_handler,
535 'validator': validate_encoding_error_handler}),
536 ('Specify the language (as BCP 47 language tag). Default: en.',
537 ['--language', '-l'], {'dest': 'language_code', 'default': 'en',
538 'metavar': '<name>'}),
539 ('Write output file dependencies to <file>.',
540 ['--record-dependencies'],
541 {'metavar': '<file>', 'validator': validate_dependency_file,
542 'default': None}), # default set in Values class
543 ('Read configuration settings from <file>, if it exists.',
544 ['--config'], {'metavar': '<file>', 'type': 'string',
545 'action': 'callback', 'callback': read_config_file}),
546 ("Show this program's version number and exit.",
547 ['--version', '-V'], {'action': 'version'}),
548 ('Show this help message and exit.',
549 ['--help', '-h'], {'action': 'help'}),
550 # Typically not useful for non-programmatical use:
551 (SUPPRESS_HELP, ['--id-prefix'], {'default': ''}),
552 (SUPPRESS_HELP, ['--auto-id-prefix'], {'default': 'id'}),
553 # Hidden options, for development use only:
554 (SUPPRESS_HELP, ['--dump-settings'], {'action': 'store_true'}),
555 (SUPPRESS_HELP, ['--dump-internals'], {'action': 'store_true'}),
556 (SUPPRESS_HELP, ['--dump-transforms'], {'action': 'store_true'}),
557 (SUPPRESS_HELP, ['--dump-pseudo-xml'], {'action': 'store_true'}),
558 (SUPPRESS_HELP, ['--expose-internal-attribute'],
559 {'action': 'append', 'dest': 'expose_internals',
560 'validator': validate_colon_separated_string_list}),
561 (SUPPRESS_HELP, ['--strict-visitor'], {'action': 'store_true'}),
562 ))
563 """Runtime settings and command-line options common to all Docutils front
564 ends. Setting specs specific to individual Docutils components are also
565 used (see `populate_from_components()`)."""
566
567 settings_defaults = {'_disable_config': None,
568 '_source': None,
569 '_destination': None,
570 '_config_files': None}
571 """Defaults for settings that don't have command-line option equivalents."""
572
573 relative_path_settings = ('warning_stream',)
574
575 config_section = 'general'
576
577 version_template = ('%%prog (Docutils %s%s, Python %s, on %s)'
578 % (docutils.__version__,
579 docutils.__version_details__ and
580 ' [%s]'%docutils.__version_details__ or '',
581 sys.version.split()[0], sys.platform))
582 """Default version message."""
583
584 def __init__(self, components=(), defaults=None, read_config_files=None,
585 *args, **kwargs):
586 """
587 `components` is a list of Docutils components each containing a
588 ``.settings_spec`` attribute. `defaults` is a mapping of setting
589 default overrides.
590 """
591
592 self.lists = {}
593 """Set of list-type settings."""
594
595 self.config_files = []
596 """List of paths of applied configuration files."""
597
598 optparse.OptionParser.__init__(
599 self, option_class=Option, add_help_option=None,
600 formatter=optparse.TitledHelpFormatter(width=78),
601 *args, **kwargs)
602 if not self.version:
603 self.version = self.version_template
604 # Make an instance copy (it will be modified):
605 self.relative_path_settings = list(self.relative_path_settings)
606 self.components = (self,) + tuple(components)
607 self.populate_from_components(self.components)
608 self.set_defaults_from_dict(defaults or {})
609 if read_config_files and not self.defaults['_disable_config']:
610 try:
611 config_settings = self.get_standard_config_settings()
612 except ValueError as error:
613 self.error(SafeString(error))
614 self.set_defaults_from_dict(config_settings.__dict__)
615
616 def populate_from_components(self, components):
617 """
618 For each component, first populate from the `SettingsSpec.settings_spec`
619 structure, then from the `SettingsSpec.settings_defaults` dictionary.
620 After all components have been processed, check for and populate from
621 each component's `SettingsSpec.settings_default_overrides` dictionary.
622 """
623 for component in components:
624 if component is None:
625 continue
626 settings_spec = component.settings_spec
627 self.relative_path_settings.extend(
628 component.relative_path_settings)
629 for i in range(0, len(settings_spec), 3):
630 title, description, option_spec = settings_spec[i:i+3]
631 if title:
632 group = optparse.OptionGroup(self, title, description)
633 self.add_option_group(group)
634 else:
635 group = self # single options
636 for (help_text, option_strings, kwargs) in option_spec:
637 option = group.add_option(help=help_text, *option_strings,
638 **kwargs)
639 if kwargs.get('action') == 'append':
640 self.lists[option.dest] = 1
641 if component.settings_defaults:
642 self.defaults.update(component.settings_defaults)
643 for component in components:
644 if component and component.settings_default_overrides:
645 self.defaults.update(component.settings_default_overrides)
646
647 def get_standard_config_files(self):
648 """Return list of config files, from environment or standard."""
649 try:
650 config_files = os.environ['DOCUTILSCONFIG'].split(os.pathsep)
651 except KeyError:
652 config_files = self.standard_config_files
653
654 # If 'HOME' is not set, expandvars() requires the 'pwd' module which is
655 # not available under certain environments, for example, within
656 # mod_python. The publisher ends up in here, and we need to publish
657 # from within mod_python. Therefore we need to avoid expanding when we
658 # are in those environments.
659 expand = os.path.expanduser
660 if 'HOME' not in os.environ:
661 try:
662 import pwd
663 except ImportError:
664 expand = lambda x: x
665 return [expand(f) for f in config_files if f.strip()]
666
667 def get_standard_config_settings(self):
668 settings = Values()
669 for filename in self.get_standard_config_files():
670 settings.update(self.get_config_file_settings(filename), self)
671 return settings
672
673 def get_config_file_settings(self, config_file):
674 """Returns a dictionary containing appropriate config file settings."""
675 parser = ConfigParser()
676 parser.read(config_file, self)
677 self.config_files.extend(parser._files)
678 base_path = os.path.dirname(config_file)
679 applied = {}
680 settings = Values()
681 for component in self.components:
682 if not component:
683 continue
684 for section in (tuple(component.config_section_dependencies or ())
685 + (component.config_section,)):
686 if section in applied:
687 continue
688 applied[section] = 1
689 settings.update(parser.get_section(section), self)
690 make_paths_absolute(
691 settings.__dict__, self.relative_path_settings, base_path)
692 return settings.__dict__
693
694 def check_values(self, values, args):
695 """Store positional arguments as runtime settings."""
696 values._source, values._destination = self.check_args(args)
697 make_paths_absolute(values.__dict__, self.relative_path_settings)
698 values._config_files = self.config_files
699 return values
700
701 def check_args(self, args):
702 source = destination = None
703 if args:
704 source = args.pop(0)
705 if source == '-': # means stdin
706 source = None
707 if args:
708 destination = args.pop(0)
709 if destination == '-': # means stdout
710 destination = None
711 if args:
712 self.error('Maximum 2 arguments allowed.')
713 if source and source == destination:
714 self.error('Do not specify the same file for both source and '
715 'destination. It will clobber the source file.')
716 return source, destination
717
718 def set_defaults_from_dict(self, defaults):
719 self.defaults.update(defaults)
720
721 def get_default_values(self):
722 """Needed to get custom `Values` instances."""
723 defaults = Values(self.defaults)
724 defaults._config_files = self.config_files
725 return defaults
726
727 def get_option_by_dest(self, dest):
728 """
729 Get an option by its dest.
730
731 If you're supplying a dest which is shared by several options,
732 it is undefined which option of those is returned.
733
734 A KeyError is raised if there is no option with the supplied
735 dest.
736 """
737 for group in self.option_groups + [self]:
738 for option in group.option_list:
739 if option.dest == dest:
740 return option
741 raise KeyError('No option with dest == %r.' % dest)
742
743
744 class ConfigParser(RawConfigParser):
745
746 old_settings = {
747 'pep_stylesheet': ('pep_html writer', 'stylesheet'),
748 'pep_stylesheet_path': ('pep_html writer', 'stylesheet_path'),
749 'pep_template': ('pep_html writer', 'template')}
750 """{old setting: (new section, new setting)} mapping, used by
751 `handle_old_config`, to convert settings from the old [options] section."""
752
753 old_warning = """
754 The "[option]" section is deprecated. Support for old-format configuration
755 files may be removed in a future Docutils release. Please revise your
756 configuration files. See <http://docutils.sf.net/docs/user/config.html>,
757 section "Old-Format Configuration Files".
758 """
759
760 not_utf8_error = """\
761 Unable to read configuration file "%s": content not encoded as UTF-8.
762 Skipping "%s" configuration file.
763 """
764
765 def __init__(self, *args, **kwargs):
766 RawConfigParser.__init__(self, *args, **kwargs)
767
768 self._files = []
769 """List of paths of configuration files read."""
770
771 self._stderr = ErrorOutput()
772 """Wrapper around sys.stderr catching en-/decoding errors"""
773
774 def read(self, filenames, option_parser):
775 if type(filenames) in (str, unicode):
776 filenames = [filenames]
777 for filename in filenames:
778 try:
779 # Config files must be UTF-8-encoded:
780 fp = codecs.open(filename, 'r', 'utf-8')
781 except IOError:
782 continue
783 try:
784 if sys.version_info < (3, 0):
785 RawConfigParser.readfp(self, fp, filename)
786 else:
787 RawConfigParser.read_file(self, fp, filename)
788 except UnicodeDecodeError:
789 self._stderr.write(self.not_utf8_error % (filename, filename))
790 fp.close()
791 continue
792 fp.close()
793 self._files.append(filename)
794 if self.has_section('options'):
795 self.handle_old_config(filename)
796 self.validate_settings(filename, option_parser)
797
798 def handle_old_config(self, filename):
799 warnings.warn_explicit(self.old_warning, ConfigDeprecationWarning,
800 filename, 0)
801 options = self.get_section('options')
802 if not self.has_section('general'):
803 self.add_section('general')
804 for key, value in options.items():
805 if key in self.old_settings:
806 section, setting = self.old_settings[key]
807 if not self.has_section(section):
808 self.add_section(section)
809 else:
810 section = 'general'
811 setting = key
812 if not self.has_option(section, setting):
813 self.set(section, setting, value)
814 self.remove_section('options')
815
816 def validate_settings(self, filename, option_parser):
817 """
818 Call the validator function and implement overrides on all applicable
819 settings.
820 """
821 for section in self.sections():
822 for setting in self.options(section):
823 try:
824 option = option_parser.get_option_by_dest(setting)
825 except KeyError:
826 continue
827 if option.validator:
828 value = self.get(section, setting)
829 try:
830 new_value = option.validator(
831 setting, value, option_parser,
832 config_parser=self, config_section=section)
833 except Exception as error:
834 raise ValueError(
835 'Error in config file "%s", section "[%s]":\n'
836 ' %s\n'
837 ' %s = %s'
838 % (filename, section, ErrorString(error),
839 setting, value))
840 self.set(section, setting, new_value)
841 if option.overrides:
842 self.set(section, option.overrides, None)
843
844 def optionxform(self, optionstr):
845 """
846 Transform '-' to '_' so the cmdline form of option names can be used.
847 """
848 return optionstr.lower().replace('-', '_')
849
850 def get_section(self, section):
851 """
852 Return a given section as a dictionary (empty if the section
853 doesn't exist).
854 """
855 section_dict = {}
856 if self.has_section(section):
857 for option in self.options(section):
858 section_dict[option] = self.get(section, option)
859 return section_dict
860
861
862 class ConfigDeprecationWarning(DeprecationWarning):
863 """Warning for deprecated configuration file features."""