Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.10/site-packages/docutils/frontend.py: 24%

Shortcuts on this page

r m x   toggle line displays

j k   next/prev highlighted chunk

0   (zero) top of page

1   (one) first highlighted chunk

445 statements  

1# $Id$ 

2# Author: David Goodger <goodger@python.org> 

3# Copyright: This module has been placed in the public domain. 

4 

5""" 

6Command-line and common processing for Docutils front-end tools. 

7 

8This module is provisional. 

9Major changes will happen with the switch from the deprecated 

10"optparse" module to "arparse". 

11 

12Applications should use the high-level API provided by `docutils.core`. 

13See https://docutils.sourceforge.io/docs/api/runtime-settings.html. 

14 

15Exports the following classes: 

16 

17* `OptionParser`: Standard Docutils command-line processing. 

18 Deprecated. Will be replaced by an ArgumentParser. 

19* `Option`: Customized version of `optparse.Option`; validation support. 

20 Deprecated. Will be removed. 

21* `Values`: Runtime settings; objects are simple structs 

22 (``object.attribute``). Supports cumulative list settings (attributes). 

23 Deprecated. Will be removed. 

24* `ConfigParser`: Standard Docutils config file processing. 

25 Provisional. Details will change. 

26 

27Also exports the following functions: 

28 

29Interface function: 

30 `get_default_settings()`. New in 0.19. 

31 

32Option callbacks: 

33 `store_multiple()`, `read_config_file()`. Deprecated. 

34 

35Setting validators: 

36 `validate_encoding()`, `validate_encoding_error_handler()`, 

37 `validate_encoding_and_error_handler()`, 

38 `validate_boolean()`, `validate_ternary()`, 

39 `validate_nonnegative_int()`, `validate_threshold()`, 

40 `validate_colon_separated_string_list()`, 

41 `validate_comma_separated_list()`, 

42 `validate_url_trailing_slash()`, 

43 `validate_dependency_file()`, 

44 `validate_strip_class()` 

45 `validate_smartquotes_locales()`. 

46 

47 Provisional. 

48 

49Misc: 

50 `make_paths_absolute()`, `filter_settings_spec()`. Provisional. 

51""" 

52 

53from __future__ import annotations 

54 

55__docformat__ = 'reStructuredText' 

56 

57 

58import codecs 

59import configparser 

60import optparse 

61import os 

62import os.path 

63import sys 

64import warnings 

65from optparse import SUPPRESS_HELP 

66from pathlib import Path 

67from typing import TYPE_CHECKING 

68 

69import docutils 

70from docutils import io, utils 

71 

72if TYPE_CHECKING: 

73 from collections.abc import Iterable, Mapping, Sequence 

74 from typing import Any, ClassVar, Literal, Protocol 

75 

76 from docutils import SettingsSpec, _OptionTuple, _SettingsSpecTuple 

77 from docutils.io import StrPath 

78 

79 class _OptionValidator(Protocol): 

80 def __call__( 

81 self, 

82 setting: str, 

83 value: str | None, 

84 option_parser: OptionParser, 

85 /, 

86 config_parser: ConfigParser | None = None, 

87 config_section: str | None = None, 

88 ) -> Any: 

89 ... 

90 

91 

92def store_multiple(option: optparse.Option, 

93 opt: str, 

94 value: Any, 

95 parser: OptionParser, 

96 *args: str, 

97 **kwargs: Any, 

98 ) -> None: 

99 """ 

100 Store multiple values in `parser.values`. (Option callback.) 

101 

102 Store `None` for each attribute named in `args`, and store the value for 

103 each key (attribute name) in `kwargs`. 

104 """ 

105 for attribute in args: 

106 setattr(parser.values, attribute, None) 

107 for key, value in kwargs.items(): 

108 setattr(parser.values, key, value) 

109 

110 

111def read_config_file(option: optparse.Option, 

112 opt: str, 

113 value: Any, 

114 parser: OptionParser, 

115 ) -> None: 

116 """ 

117 Read a configuration file during option processing. (Option callback.) 

118 """ 

119 try: 

120 new_settings = parser.get_config_file_settings(value) 

121 except ValueError as err: 

122 parser.error(err) 

123 parser.values.update(new_settings, parser) 

124 

125 

126def validate_encoding(setting: str, 

127 value: str | None = None, 

128 option_parser: OptionParser | None = None, 

129 config_parser: ConfigParser | None = None, 

130 config_section: str | None = None, 

131 ) -> str | None: 

132 # All arguments except `value` are ignored 

133 # (kept for compatibility with "optparse" module). 

134 # If there is only one positional argument, it is interpreted as `value`. 

135 if value is None: 

136 value = setting 

137 if value == '': 

138 warnings.warn('Input encoding detection will be removed ' 

139 'in Docutils 1.0.', DeprecationWarning, stacklevel=2) 

140 return None 

141 try: 

142 codecs.lookup(value) 

143 except LookupError: 

144 prefix = f'setting "{setting}":' if setting else '' 

145 raise LookupError(f'{prefix} unknown encoding: "{value}"') 

146 return value 

147 

148 

149def validate_encoding_error_handler( 

150 setting: str, 

151 value: str | None = None, 

152 option_parser: OptionParser | None = None, 

153 config_parser: ConfigParser | None = None, 

154 config_section: str | None = None, 

155 ) -> str: 

156 # All arguments except `value` are ignored 

157 # (kept for compatibility with "optparse" module). 

158 # If there is only one positional argument, it is interpreted as `value`. 

159 if value is None: 

160 value = setting 

161 try: 

162 codecs.lookup_error(value) 

163 except LookupError: 

164 raise LookupError( 

165 'unknown encoding error handler: "%s" (choices: ' 

166 '"strict", "ignore", "replace", "backslashreplace", ' 

167 '"xmlcharrefreplace", and possibly others; see documentation for ' 

168 'the Python ``codecs`` module)' % value) 

169 return value 

170 

171 

172def validate_encoding_and_error_handler( 

173 setting: str, 

174 value: str | None = None, 

175 option_parser: OptionParser | None = None, 

176 config_parser: ConfigParser | None = None, 

177 config_section: str | None = None, 

178 ) -> str: 

179 """Check/normalize encoding settings 

180 

181 Side-effect: if an error handler is included in the value, it is inserted 

182 into the appropriate place as if it were a separate setting/option. 

183 

184 All arguments except `value` are ignored 

185 (kept for compatibility with "optparse" module). 

186 If there is only one positional argument, it is interpreted as `value`. 

187 """ 

188 if ':' in value: 

189 encoding, handler = value.split(':') 

190 validate_encoding_error_handler(handler) 

191 if config_parser: 

192 config_parser.set(config_section, setting + '_error_handler', 

193 handler) 

194 else: 

195 setattr(option_parser.values, setting + '_error_handler', handler) 

196 else: 

197 encoding = value 

198 return validate_encoding(encoding) 

199 

200 

201def validate_boolean(setting: str | bool, 

202 value: str | None = None, 

203 option_parser: OptionParser | None = None, 

204 config_parser: ConfigParser | None = None, 

205 config_section: str | None = None, 

206 ) -> bool: 

207 """Check/normalize boolean settings: 

208 

209 :True: '1', 'on', 'yes', 'true' 

210 :False: '0', 'off', 'no','false', '' 

211 

212 All arguments except `value` are ignored 

213 (kept for compatibility with "optparse" module). 

214 If there is only one positional argument, it is interpreted as `value`. 

215 """ 

216 if value is None: 

217 value = setting 

218 if isinstance(value, bool): 

219 return value 

220 try: 

221 return OptionParser.booleans[value.strip().lower()] 

222 except KeyError: 

223 raise LookupError('unknown boolean value: "%s"' % value) 

224 

225 

226def validate_ternary(setting: str | bool, 

227 value: str | None = None, 

228 option_parser: OptionParser | None = None, 

229 config_parser: ConfigParser | None = None, 

230 config_section: str | None = None, 

231 ) -> str | bool | None: 

232 """Check/normalize three-value settings: 

233 

234 :True: '1', 'on', 'yes', 'true' 

235 :False: '0', 'off', 'no','false', '' 

236 :any other value: returned as-is. 

237 

238 All arguments except `value` are ignored 

239 (kept for compatibility with "optparse" module). 

240 If there is only one positional argument, it is interpreted as `value`. 

241 """ 

242 if value is None: 

243 value = setting 

244 if isinstance(value, bool) or value is None: 

245 return value 

246 try: 

247 return OptionParser.booleans[value.strip().lower()] 

248 except KeyError: 

249 return value 

250 

251 

252def validate_nonnegative_int(setting: str | int, 

253 value: str | None = None, 

254 option_parser: OptionParser | None = None, 

255 config_parser: ConfigParser | None = None, 

256 config_section: str | None = None, 

257 ) -> int: 

258 # All arguments except `value` are ignored 

259 # (kept for compatibility with "optparse" module). 

260 # If there is only one positional argument, it is interpreted as `value`. 

261 if value is None: 

262 value = setting 

263 value = int(value) 

264 if value < 0: 

265 raise ValueError('negative value; must be positive or zero') 

266 return value 

267 

268 

269def validate_threshold(setting: str | int, 

270 value: str | None = None, 

271 option_parser: OptionParser | None = None, 

272 config_parser: ConfigParser | None = None, 

273 config_section: str | None = None, 

274 ) -> int: 

275 # All arguments except `value` are ignored 

276 # (kept for compatibility with "optparse" module). 

277 # If there is only one positional argument, it is interpreted as `value`. 

278 if value is None: 

279 value = setting 

280 try: 

281 return int(value) 

282 except ValueError: 

283 try: 

284 return OptionParser.thresholds[value.lower()] 

285 except (KeyError, AttributeError): 

286 raise LookupError('unknown threshold: %r.' % value) 

287 

288 

289def validate_colon_separated_string_list( 

290 setting: str | list[str], 

291 value: str | None = None, 

292 option_parser: OptionParser | None = None, 

293 config_parser: ConfigParser | None = None, 

294 config_section: str | None = None, 

295 ) -> list[str]: 

296 # All arguments except `value` are ignored 

297 # (kept for compatibility with "optparse" module). 

298 # If there is only one positional argument, it is interpreted as `value`. 

299 if value is None: 

300 value = setting 

301 if not isinstance(value, list): 

302 value = value.split(':') 

303 else: 

304 last = value.pop() 

305 value.extend(last.split(':')) 

306 return value 

307 

308 

309def validate_comma_separated_list( 

310 setting: str | list[str], 

311 value: str | None = None, 

312 option_parser: OptionParser | None = None, 

313 config_parser: ConfigParser | None = None, 

314 config_section: str | None = None, 

315 ) -> list[str]: 

316 """Check/normalize list arguments (split at "," and strip whitespace). 

317 

318 All arguments except `value` are ignored 

319 (kept for compatibility with "optparse" module). 

320 If there is only one positional argument, it is interpreted as `value`. 

321 """ 

322 if value is None: 

323 value = setting 

324 # `value` may be ``bytes``, ``str``, or a ``list`` (when given as 

325 # command line option and "action" is "append"). 

326 if not isinstance(value, list): 

327 value = [value] 

328 # this function is called for every option added to `value` 

329 # -> split the last item and append the result: 

330 last = value.pop() 

331 items = [i.strip(' \t\n') for i in last.split(',') if i.strip(' \t\n')] 

332 value.extend(items) 

333 return value 

334 

335 

336def validate_math_output(setting: str, 

337 value: str | None = None, 

338 option_parser: OptionParser | None = None, 

339 config_parser: ConfigParser | None = None, 

340 config_section: str | None = None, 

341 ) -> tuple[()] | tuple[str, str]: 

342 """Check "math-output" setting, return list with "format" and "options". 

343 

344 See also https://docutils.sourceforge.io/docs/user/config.html#math-output 

345 

346 Argument list for compatibility with "optparse" module. 

347 All arguments except `value` are ignored. 

348 If there is only one positional argument, it is interpreted as `value`. 

349 """ 

350 if value is None: 

351 value = setting 

352 

353 formats = ('html', 'latex', 'mathml', 'mathjax') 

354 tex2mathml_converters = ('', 'latexml', 'ttm', 'blahtexml', 'pandoc') 

355 

356 if not value: 

357 return () 

358 values = value.split(maxsplit=1) 

359 format = values[0].lower() 

360 try: 

361 options = values[1] 

362 except IndexError: 

363 options = '' 

364 if format not in formats: 

365 raise LookupError(f'Unknown math output format: "{value}",\n' 

366 f' choose from {formats}.') 

367 if format == 'mathml': 

368 converter = options.lower() 

369 if converter not in tex2mathml_converters: 

370 raise LookupError(f'MathML converter "{options}" not supported,\n' 

371 f' choose from {tex2mathml_converters}.') 

372 options = converter 

373 return format, options 

374 

375 

376def validate_url_trailing_slash(setting: str | None, 

377 value: str | None = None, 

378 option_parser: OptionParser | None = None, 

379 config_parser: ConfigParser | None = None, 

380 config_section: str | None = None, 

381 ) -> str: 

382 # All arguments except `value` are ignored 

383 # (kept for compatibility with "optparse" module). 

384 # If there is only one positional argument, it is interpreted as `value`. 

385 if value is None: 

386 value = setting 

387 if not value: 

388 return './' 

389 elif value.endswith('/'): 

390 return value 

391 else: 

392 return value + '/' 

393 

394 

395def validate_dependency_file(setting: str | None, 

396 value: str | None = None, 

397 option_parser: OptionParser | None = None, 

398 config_parser: ConfigParser | None = None, 

399 config_section: str | None = None, 

400 ) -> utils.DependencyList: 

401 # All arguments except `value` are ignored 

402 # (kept for compatibility with "optparse" module). 

403 # If there is only one positional argument, it is interpreted as `value`. 

404 if value is None: 

405 value = setting 

406 try: 

407 return utils.DependencyList(value) 

408 except OSError: 

409 # TODO: warn/info? 

410 return utils.DependencyList(None) 

411 

412 

413def validate_strip_class(setting: str, 

414 value: str | None = None, 

415 option_parser: OptionParser | None = None, 

416 config_parser: ConfigParser | None = None, 

417 config_section: str | None = None, 

418 ) -> list[str]: 

419 # All arguments except `value` are ignored 

420 # (kept for compatibility with "optparse" module). 

421 # If there is only one positional argument, it is interpreted as `value`. 

422 if value is None: 

423 value = setting 

424 # value is a comma separated string list: 

425 value = validate_comma_separated_list(value) 

426 # validate list elements: 

427 for cls in value: 

428 normalized = docutils.nodes.make_id(cls) 

429 if cls != normalized: 

430 raise ValueError('Invalid class value %r (perhaps %r?)' 

431 % (cls, normalized)) 

432 return value 

433 

434 

435def validate_smartquotes_locales( 

436 setting: str | list[str | tuple[str, str]], 

437 value: str | None = None, 

438 option_parser: OptionParser | None = None, 

439 config_parser: ConfigParser | None = None, 

440 config_section: str | None = None, 

441 ) -> list[tuple[str, Sequence[str]]]: 

442 """Check/normalize a comma separated list of smart quote definitions. 

443 

444 Return a list of (language-tag, quotes) string tuples. 

445 

446 All arguments except `value` are ignored 

447 (kept for compatibility with "optparse" module). 

448 If there is only one positional argument, it is interpreted as `value`. 

449 """ 

450 if value is None: 

451 value = setting 

452 # value is a comma separated string list: 

453 value = validate_comma_separated_list(value) 

454 # validate list elements 

455 lc_quotes = [] 

456 for item in value: 

457 try: 

458 lang, quotes = item.split(':', 1) 

459 except AttributeError: 

460 # this function is called for every option added to `value` 

461 # -> ignore if already a tuple: 

462 lc_quotes.append(item) 

463 continue 

464 except ValueError: 

465 raise ValueError('Invalid value "%s".' 

466 ' Format is "<language>:<quotes>".' 

467 % item.encode('ascii', 'backslashreplace')) 

468 # parse colon separated string list: 

469 quotes = quotes.strip() 

470 multichar_quotes = quotes.split(':') 

471 if len(multichar_quotes) == 4: 

472 quotes = multichar_quotes 

473 elif len(quotes) != 4: 

474 raise ValueError('Invalid value "%s". Please specify 4 quotes\n' 

475 ' (primary open/close; secondary open/close).' 

476 % item.encode('ascii', 'backslashreplace')) 

477 lc_quotes.append((lang, quotes)) 

478 return lc_quotes 

479 

480 

481def make_paths_absolute(pathdict: dict[str, list[StrPath] | StrPath], 

482 keys: tuple[str], 

483 base_path: StrPath | None = None, 

484 ) -> None: 

485 """ 

486 Interpret filesystem path settings relative to the `base_path` given. 

487 

488 Paths are values in `pathdict` whose keys are in `keys`. Get `keys` from 

489 `OptionParser.relative_path_settings`. 

490 """ 

491 if base_path is None: 

492 base_path = Path.cwd() 

493 else: 

494 base_path = Path(base_path) 

495 if sys.platform == 'win32' and sys.version_info[:2] <= (3, 9): 

496 base_path = base_path.absolute() 

497 for key in keys: 

498 if key in pathdict: 

499 value = pathdict[key] 

500 if isinstance(value, (list, tuple)): 

501 value = [str((base_path/path).resolve()) for path in value] 

502 elif value: 

503 value = str((base_path/value).resolve()) 

504 pathdict[key] = value 

505 

506 

507def make_one_path_absolute(base_path: StrPath, path: StrPath) -> str: 

508 # deprecated, will be removed 

509 warnings.warn('frontend.make_one_path_absolute() will be removed ' 

510 'in Docutils 0.23.', DeprecationWarning, stacklevel=2) 

511 return os.path.abspath(os.path.join(base_path, path)) 

512 

513 

514def filter_settings_spec(settings_spec: _SettingsSpecTuple, 

515 *exclude: str, 

516 **replace: _OptionTuple, 

517 ) -> _SettingsSpecTuple: 

518 """Return a copy of `settings_spec` excluding/replacing some settings. 

519 

520 `settings_spec` is a tuple of configuration settings 

521 (cf. `docutils.SettingsSpec.settings_spec`). 

522 

523 Optional positional arguments are names of to-be-excluded settings. 

524 Keyword arguments are option specification replacements. 

525 (See the html4strict writer for an example.) 

526 """ 

527 settings = list(settings_spec) 

528 # every third item is a sequence of option tuples 

529 for i in range(2, len(settings), 3): 

530 newopts: list[_OptionTuple] = [] 

531 for opt_spec in settings[i]: 

532 # opt_spec is ("<help>", [<option strings>], {<keyword args>}) 

533 opt_name = [opt_string[2:].replace('-', '_') 

534 for opt_string in opt_spec[1] 

535 if opt_string.startswith('--')][0] 

536 if opt_name in exclude: 

537 continue 

538 if opt_name in replace.keys(): 

539 newopts.append(replace[opt_name]) 

540 else: 

541 newopts.append(opt_spec) 

542 settings[i] = tuple(newopts) 

543 return tuple(settings) 

544 

545 

546class Values(optparse.Values): 

547 """Storage for option values. 

548 

549 Updates list attributes by extension rather than by replacement. 

550 Works in conjunction with the `OptionParser.lists` instance attribute. 

551 

552 Deprecated. Will be removed. 

553 """ 

554 

555 def __init__(self, defaults: dict[str, Any] | None = None) -> None: 

556 warnings.warn('frontend.Values class will be removed ' 

557 'in Docutils 0.21 or later.', 

558 DeprecationWarning, stacklevel=2) 

559 super().__init__(defaults=defaults) 

560 if getattr(self, 'record_dependencies', None) is None: 

561 # Set up dummy dependency list. 

562 self.record_dependencies = utils.DependencyList() 

563 

564 def update(self, 

565 other_dict: Values | Mapping[str, Any], 

566 option_parser: OptionParser, 

567 ) -> None: 

568 if isinstance(other_dict, Values): 

569 other_dict = other_dict.__dict__ 

570 other_dict = dict(other_dict) # also works with ConfigParser sections 

571 for setting in option_parser.lists.keys(): 

572 if hasattr(self, setting) and setting in other_dict: 

573 value = getattr(self, setting) 

574 if value: 

575 value += other_dict[setting] 

576 del other_dict[setting] 

577 self._update_loose(other_dict) 

578 

579 def copy(self) -> Values: 

580 """Return a shallow copy of `self`.""" 

581 with warnings.catch_warnings(): 

582 warnings.filterwarnings('ignore', category=DeprecationWarning) 

583 return self.__class__(defaults=self.__dict__) 

584 

585 def setdefault(self, name: str, default: Any) -> Any: 

586 """Return ``self.name`` or ``default``. 

587 

588 If ``self.name`` is unset, set ``self.name = default``. 

589 """ 

590 if getattr(self, name, None) is None: 

591 setattr(self, name, default) 

592 return getattr(self, name) 

593 

594 

595class Option(optparse.Option): 

596 """Add validation and override support to `optparse.Option`. 

597 

598 Deprecated. Will be removed. 

599 """ 

600 

601 ATTRS = optparse.Option.ATTRS + ['validator', 'overrides'] 

602 

603 validator: _OptionValidator 

604 overrides: str | None 

605 

606 def __init__(self, *args: str | None, **kwargs: Any) -> None: 

607 warnings.warn('The frontend.Option class will be removed ' 

608 'in Docutils 0.21 or later.', 

609 DeprecationWarning, stacklevel=2) 

610 super().__init__(*args, **kwargs) 

611 

612 def process(self, 

613 opt: str, 

614 value: Any, 

615 values: Values, 

616 parser: OptionParser, 

617 ) -> int: 

618 """ 

619 Call the validator function on applicable settings and 

620 evaluate the 'overrides' option. 

621 Extends `optparse.Option.process`. 

622 """ 

623 result = super().process(opt, value, values, parser) 

624 setting = self.dest 

625 if setting: 

626 if self.validator: 

627 value = getattr(values, setting) 

628 try: 

629 new_value = self.validator(setting, value, parser) 

630 except Exception as err: 

631 raise optparse.OptionValueError( 

632 'Error in option "%s":\n %s' 

633 % (opt, io.error_string(err))) 

634 setattr(values, setting, new_value) 

635 if self.overrides: 

636 setattr(values, self.overrides, None) 

637 return result 

638 

639 

640class OptionParser(optparse.OptionParser, docutils.SettingsSpec): 

641 """ 

642 Settings parser for command-line and library use. 

643 

644 The `settings_spec` specification here and in other Docutils components 

645 are merged to build the set of command-line options and runtime settings 

646 for this process. 

647 

648 Common settings (defined below) and component-specific settings must not 

649 conflict. Short options are reserved for common settings, and components 

650 are restricted to using long options. 

651 

652 Deprecated. 

653 Will be replaced by a subclass of `argparse.ArgumentParser`. 

654 """ 

655 

656 standard_config_files: ClassVar[list[str]] = [ 

657 '/etc/docutils.conf', # system-wide 

658 './docutils.conf', # project-specific 

659 '~/.docutils'] # user-specific 

660 """Docutils configuration files, using ConfigParser syntax. 

661 

662 Filenames will be tilde-expanded later. Later files override earlier ones. 

663 """ 

664 

665 threshold_choices: ClassVar[tuple[str]] = ( 

666 'info', '1', 'warning', '2', 'error', '3', 'severe', '4', 'none', '5') 

667 """Possible inputs for for --report and --halt threshold values.""" 

668 

669 thresholds: ClassVar[dict[str, int]] = { 

670 'info': 1, 'warning': 2, 'error': 3, 'severe': 4, 'none': 5} 

671 """Lookup table for --report and --halt threshold values.""" 

672 

673 booleans: ClassVar[dict[str, bool]] = { 

674 '1': True, 'on': True, 'yes': True, 'true': True, 

675 '0': False, 'off': False, 'no': False, 'false': False, '': False} 

676 """Lookup table for boolean configuration file settings.""" 

677 

678 default_error_encoding: ClassVar[str] = ( 

679 getattr(sys.stderr, 'encoding', None) 

680 or io._locale_encoding 

681 or 'ascii') 

682 

683 default_error_encoding_error_handler: ClassVar[str] = 'backslashreplace' 

684 

685 settings_spec = ( 

686 'General Docutils Options', 

687 None, 

688 (('Output destination name. Obsoletes the <destination> ' 

689 'positional argument. Default: None (stdout).', 

690 ['--output'], {'metavar': '<destination>'}), 

691 ('Specify the document title as metadata.', 

692 ['--title'], {'metavar': '<title>'}), 

693 ('Include a "Generated by Docutils" credit and link.', 

694 ['--generator', '-g'], {'action': 'store_true', 

695 'validator': validate_boolean}), 

696 ('Do not include a generator credit.', 

697 ['--no-generator'], {'action': 'store_false', 'dest': 'generator'}), 

698 ('Include the date at the end of the document (UTC).', 

699 ['--date', '-d'], {'action': 'store_const', 'const': '%Y-%m-%d', 

700 'dest': 'datestamp'}), 

701 ('Include the time & date (UTC).', 

702 ['--time', '-t'], {'action': 'store_const', 

703 'const': '%Y-%m-%d %H:%M UTC', 

704 'dest': 'datestamp'}), 

705 ('Do not include a datestamp of any kind.', 

706 ['--no-datestamp'], {'action': 'store_const', 'const': None, 

707 'dest': 'datestamp'}), 

708 ('Base directory for absolute paths when reading ' 

709 'from the local filesystem. Default "/".', 

710 ['--root-prefix'], 

711 {'default': '/', 'metavar': '<path>'}), 

712 ('Include a "View document source" link.', 

713 ['--source-link', '-s'], {'action': 'store_true', 

714 'validator': validate_boolean}), 

715 ('Use <URL> for a source link; implies --source-link.', 

716 ['--source-url'], {'metavar': '<URL>'}), 

717 ('Do not include a "View document source" link.', 

718 ['--no-source-link'], 

719 {'action': 'callback', 'callback': store_multiple, 

720 'callback_args': ('source_link', 'source_url')}), 

721 ('Link from section headers to TOC entries. (default)', 

722 ['--toc-entry-backlinks'], 

723 {'dest': 'toc_backlinks', 'action': 'store_const', 'const': 'entry', 

724 'default': 'entry'}), 

725 ('Link from section headers to the top of the TOC.', 

726 ['--toc-top-backlinks'], 

727 {'dest': 'toc_backlinks', 'action': 'store_const', 'const': 'top'}), 

728 ('Disable backlinks to the table of contents.', 

729 ['--no-toc-backlinks'], 

730 {'dest': 'toc_backlinks', 'action': 'store_false'}), 

731 ('Link from footnotes/citations to references. (default)', 

732 ['--footnote-backlinks'], 

733 {'action': 'store_true', 'default': True, 

734 'validator': validate_boolean}), 

735 ('Disable backlinks from footnotes and citations.', 

736 ['--no-footnote-backlinks'], 

737 {'dest': 'footnote_backlinks', 'action': 'store_false'}), 

738 ('Enable section numbering by Docutils. (default)', 

739 ['--section-numbering'], 

740 {'action': 'store_true', 'dest': 'sectnum_xform', 

741 'default': True, 'validator': validate_boolean}), 

742 ('Disable section numbering by Docutils.', 

743 ['--no-section-numbering'], 

744 {'action': 'store_false', 'dest': 'sectnum_xform'}), 

745 ('Remove comment elements from the document tree.', 

746 ['--strip-comments'], 

747 {'action': 'store_true', 'validator': validate_boolean}), 

748 ('Leave comment elements in the document tree. (default)', 

749 ['--leave-comments'], 

750 {'action': 'store_false', 'dest': 'strip_comments'}), 

751 ('Remove all elements with classes="<class>" from the document tree. ' 

752 'Warning: potentially dangerous; use with caution. ' 

753 '(Multiple-use option.)', 

754 ['--strip-elements-with-class'], 

755 {'action': 'append', 'dest': 'strip_elements_with_classes', 

756 'metavar': '<class>', 'validator': validate_strip_class}), 

757 ('Remove all classes="<class>" attributes from elements in the ' 

758 'document tree. Warning: potentially dangerous; use with caution. ' 

759 '(Multiple-use option.)', 

760 ['--strip-class'], 

761 {'action': 'append', 'dest': 'strip_classes', 

762 'metavar': '<class>', 'validator': validate_strip_class}), 

763 ('Report system messages at or higher than <level>: "info" or "1", ' 

764 '"warning"/"2" (default), "error"/"3", "severe"/"4", "none"/"5"', 

765 ['--report', '-r'], {'choices': threshold_choices, 'default': 2, 

766 'dest': 'report_level', 'metavar': '<level>', 

767 'validator': validate_threshold}), 

768 ('Report all system messages. (Same as "--report=1".)', 

769 ['--verbose', '-v'], {'action': 'store_const', 'const': 1, 

770 'dest': 'report_level'}), 

771 ('Report no system messages. (Same as "--report=5".)', 

772 ['--quiet', '-q'], {'action': 'store_const', 'const': 5, 

773 'dest': 'report_level'}), 

774 ('Halt execution at system messages at or above <level>. ' 

775 'Levels as in --report. Default: 4 (severe).', 

776 ['--halt'], {'choices': threshold_choices, 'dest': 'halt_level', 

777 'default': 4, 'metavar': '<level>', 

778 'validator': validate_threshold}), 

779 ('Halt at the slightest problem. Same as "--halt=info".', 

780 ['--strict'], {'action': 'store_const', 'const': 1, 

781 'dest': 'halt_level'}), 

782 ('Enable a non-zero exit status for non-halting system messages at ' 

783 'or above <level>. Default: 5 (disabled).', 

784 ['--exit-status'], {'choices': threshold_choices, 

785 'dest': 'exit_status_level', 

786 'default': 5, 'metavar': '<level>', 

787 'validator': validate_threshold}), 

788 ('Enable debug-level system messages and diagnostics.', 

789 ['--debug'], {'action': 'store_true', 

790 'validator': validate_boolean}), 

791 ('Disable debug output. (default)', 

792 ['--no-debug'], {'action': 'store_false', 'dest': 'debug'}), 

793 ('Send the output of system messages to <file>.', 

794 ['--warnings'], {'dest': 'warning_stream', 'metavar': '<file>'}), 

795 ('Enable Python tracebacks when Docutils is halted.', 

796 ['--traceback'], {'action': 'store_true', 'default': None, 

797 'validator': validate_boolean}), 

798 ('Disable Python tracebacks. (default)', 

799 ['--no-traceback'], {'dest': 'traceback', 'action': 'store_false'}), 

800 ('Specify the encoding and optionally the ' 

801 'error handler of input text. Default: utf-8.', 

802 ['--input-encoding'], 

803 {'metavar': '<name[:handler]>', 'default': 'utf-8', 

804 'validator': validate_encoding_and_error_handler}), 

805 ('Specify the error handler for undecodable characters. ' 

806 'Choices: "strict" (default), "ignore", and "replace".', 

807 ['--input-encoding-error-handler'], 

808 {'default': 'strict', 'validator': validate_encoding_error_handler}), 

809 ('Specify the text encoding and optionally the error handler for ' 

810 'output. Default: utf-8.', 

811 ['--output-encoding'], 

812 {'metavar': '<name[:handler]>', 'default': 'utf-8', 

813 'validator': validate_encoding_and_error_handler}), 

814 ('Specify error handler for unencodable output characters; ' 

815 '"strict" (default), "ignore", "replace", ' 

816 '"xmlcharrefreplace", "backslashreplace".', 

817 ['--output-encoding-error-handler'], 

818 {'default': 'strict', 'validator': validate_encoding_error_handler}), 

819 ('Specify text encoding and optionally error handler ' 

820 'for error output. Default: %s:%s.' 

821 % (default_error_encoding, default_error_encoding_error_handler), 

822 ['--error-encoding', '-e'], 

823 {'metavar': '<name[:handler]>', 'default': default_error_encoding, 

824 'validator': validate_encoding_and_error_handler}), 

825 ('Specify the error handler for unencodable characters in ' 

826 'error output. Default: %s.' 

827 % default_error_encoding_error_handler, 

828 ['--error-encoding-error-handler'], 

829 {'default': default_error_encoding_error_handler, 

830 'validator': validate_encoding_error_handler}), 

831 ('Specify the language (as BCP 47 language tag). Default: en.', 

832 ['--language', '-l'], {'dest': 'language_code', 'default': 'en', 

833 'metavar': '<name>'}), 

834 ('Write output file dependencies to <file>.', 

835 ['--record-dependencies'], 

836 {'metavar': '<file>', 'validator': validate_dependency_file, 

837 'default': None}), # default set in Values class 

838 ('Read configuration settings from <file>, if it exists.', 

839 ['--config'], {'metavar': '<file>', 'type': 'string', 

840 'action': 'callback', 'callback': read_config_file}), 

841 ("Show this program's version number and exit.", 

842 ['--version', '-V'], {'action': 'version'}), 

843 ('Show this help message and exit.', 

844 ['--help', '-h'], {'action': 'help'}), 

845 # Typically not useful for non-programmatical use: 

846 (SUPPRESS_HELP, ['--id-prefix'], {'default': ''}), 

847 (SUPPRESS_HELP, ['--auto-id-prefix'], {'default': '%'}), 

848 # Hidden options, for development use only: 

849 (SUPPRESS_HELP, ['--dump-settings'], {'action': 'store_true'}), 

850 (SUPPRESS_HELP, ['--dump-internals'], {'action': 'store_true'}), 

851 (SUPPRESS_HELP, ['--dump-transforms'], {'action': 'store_true'}), 

852 (SUPPRESS_HELP, ['--dump-pseudo-xml'], {'action': 'store_true'}), 

853 (SUPPRESS_HELP, ['--expose-internal-attribute'], 

854 {'action': 'append', 'dest': 'expose_internals', 

855 'validator': validate_colon_separated_string_list}), 

856 (SUPPRESS_HELP, ['--strict-visitor'], {'action': 'store_true'}), 

857 )) 

858 """Runtime settings and command-line options common to all Docutils front 

859 ends. Setting specs specific to individual Docutils components are also 

860 used (see `populate_from_components()`).""" 

861 

862 settings_defaults = {'_disable_config': None, 

863 '_source': None, 

864 '_destination': None, 

865 '_config_files': None} 

866 """Defaults for settings without command-line option equivalents. 

867 

868 See https://docutils.sourceforge.io/docs/user/config.html#internal-settings 

869 """ 

870 

871 relative_path_settings: tuple[str, ...] = () # will be modified 

872 

873 config_section = 'general' 

874 

875 version_template: ClassVar[str] = '%%prog (Docutils %s%s, Python %s, on %s)' % ( # NoQA: E501 

876 docutils.__version__, 

877 (details := docutils.__version_details__) and f' [{details}]' or '', 

878 sys.version.split()[0], 

879 sys.platform) 

880 """Default version message.""" 

881 

882 def __init__(self, 

883 components: Iterable[SettingsSpec] = (), 

884 defaults: Mapping[str, Any] | None = None, 

885 read_config_files: bool | None = False, 

886 *args, 

887 **kwargs, 

888 ) -> None: 

889 """Set up OptionParser instance. 

890 

891 `components` is a list of Docutils components each containing a 

892 ``.settings_spec`` attribute. 

893 `defaults` is a mapping of setting default overrides. 

894 """ 

895 

896 self.lists: dict[str, Literal[True]] = {} 

897 """Set of list-type settings.""" 

898 

899 self.config_files: list[str] = [] 

900 """List of paths of applied configuration files.""" 

901 

902 self.relative_path_settings = ('warning_stream',) # will be modified 

903 

904 warnings.warn('The frontend.OptionParser class will be replaced ' 

905 'by a subclass of argparse.ArgumentParser ' 

906 'in Docutils 0.21 or later.', 

907 DeprecationWarning, stacklevel=2) 

908 super().__init__(option_class=Option, add_help_option=False, 

909 formatter=optparse.TitledHelpFormatter(width=78), 

910 *args, **kwargs) 

911 if not self.version: 

912 self.version = self.version_template 

913 self.components: tuple[SettingsSpec, ...] = (self, *components) 

914 self.populate_from_components(self.components) 

915 self.defaults.update(defaults or {}) 

916 if read_config_files and not self.defaults['_disable_config']: 

917 try: 

918 config_settings = self.get_standard_config_settings() 

919 except ValueError as err: 

920 self.error(str(err)) 

921 self.defaults.update(config_settings.__dict__) 

922 

923 def populate_from_components(self, components: Iterable[SettingsSpec], 

924 ) -> None: 

925 """Collect settings specification from components. 

926 

927 For each component, populate from the `SettingsSpec.settings_spec` 

928 structure, then from the `SettingsSpec.settings_defaults` dictionary. 

929 After all components have been processed, check for and populate from 

930 each component's `SettingsSpec.settings_default_overrides` dictionary. 

931 """ 

932 for component in components: 

933 if component is None: 

934 continue 

935 settings_spec = component.settings_spec 

936 self.relative_path_settings += component.relative_path_settings 

937 for i in range(0, len(settings_spec), 3): 

938 title, description, option_spec = settings_spec[i:i+3] 

939 if title: 

940 group = optparse.OptionGroup(self, title, description) 

941 self.add_option_group(group) 

942 else: 

943 group = self # single options 

944 for (help_text, option_strings, kwargs) in option_spec: 

945 option = group.add_option(help=help_text, *option_strings, 

946 **kwargs) 

947 if kwargs.get('action') == 'append': 

948 self.lists[option.dest] = True 

949 if component.settings_defaults: 

950 self.defaults.update(component.settings_defaults) 

951 for component in components: 

952 if component and component.settings_default_overrides: 

953 self.defaults.update(component.settings_default_overrides) 

954 

955 @classmethod 

956 def get_standard_config_files(cls) -> Sequence[StrPath]: 

957 """Return list of config files, from environment or standard.""" 

958 if 'DOCUTILSCONFIG' in os.environ: 

959 config_files = os.environ['DOCUTILSCONFIG'].split(os.pathsep) 

960 else: 

961 config_files = cls.standard_config_files 

962 return [os.path.expanduser(f) for f in config_files if f.strip()] 

963 

964 def get_standard_config_settings(self) -> Values: 

965 with warnings.catch_warnings(): 

966 warnings.filterwarnings('ignore', category=DeprecationWarning) 

967 settings = Values() 

968 for filename in self.get_standard_config_files(): 

969 settings.update(self.get_config_file_settings(filename), self) 

970 return settings 

971 

972 def get_config_file_settings(self, config_file: str) -> dict[str, Any]: 

973 """Returns a dictionary containing appropriate config file settings.""" 

974 config_parser = ConfigParser() 

975 # parse config file, add filename if found and successfully read. 

976 applied = set() 

977 with warnings.catch_warnings(): 

978 warnings.filterwarnings('ignore', category=DeprecationWarning) 

979 self.config_files += config_parser.read(config_file, self) 

980 settings = Values() 

981 for component in self.components: 

982 if not component: 

983 continue 

984 for section in (tuple(component.config_section_dependencies or ()) 

985 + (component.config_section,)): 

986 if section in applied: 

987 continue 

988 applied.add(section) 

989 if config_parser.has_section(section): 

990 settings.update(config_parser[section], self) 

991 make_paths_absolute(settings.__dict__, 

992 self.relative_path_settings, 

993 os.path.dirname(config_file)) 

994 return settings.__dict__ 

995 

996 def check_values(self, values: Values, args: list[str]) -> Values: 

997 """Store positional arguments as runtime settings.""" 

998 values._source, values._destination = self.check_args(args) 

999 make_paths_absolute(values.__dict__, self.relative_path_settings) 

1000 values._config_files = self.config_files 

1001 return values 

1002 

1003 def check_args(self, args: list[str]) -> tuple[str|None, str|None]: 

1004 # provisional: argument handling will change, see RELEASE_NOTES 

1005 source = destination = None 

1006 if args: 

1007 source = args.pop(0) 

1008 if source == '-': # means stdin 

1009 source = None 

1010 if args: 

1011 destination = args.pop(0) 

1012 if destination == '-': # means stdout 

1013 destination = None 

1014 if args: 

1015 self.error('Maximum 2 arguments allowed.') 

1016 if source and source == destination: 

1017 self.error('Do not specify the same file for both source and ' 

1018 'destination. It will clobber the source file.') 

1019 return source, destination 

1020 

1021 def get_default_values(self) -> Values: 

1022 """Needed to get custom `Values` instances.""" 

1023 with warnings.catch_warnings(): 

1024 warnings.filterwarnings('ignore', category=DeprecationWarning) 

1025 defaults = Values(self.defaults) 

1026 defaults._config_files = self.config_files 

1027 return defaults 

1028 

1029 def get_option_by_dest(self, dest: str) -> Option: 

1030 """ 

1031 Get an option by its dest. 

1032 

1033 If you're supplying a dest which is shared by several options, 

1034 it is undefined which option of those is returned. 

1035 

1036 A KeyError is raised if there is no option with the supplied 

1037 dest. 

1038 """ 

1039 for group in self.option_groups + [self]: 

1040 for option in group.option_list: 

1041 if option.dest == dest: 

1042 return option 

1043 raise KeyError('No option with dest == %r.' % dest) 

1044 

1045 

1046class ConfigParser(configparser.RawConfigParser): 

1047 """Parser for Docutils configuration files. 

1048 

1049 See https://docutils.sourceforge.io/docs/user/config.html. 

1050 

1051 Option key normalization includes conversion of '-' to '_'. 

1052 

1053 Config file encoding is "utf-8". Encoding errors are reported 

1054 and the affected file(s) skipped. 

1055 

1056 This class is provisional and will change in future versions. 

1057 """ 

1058 

1059 old_settings: ClassVar[dict[str, tuple[str, str]]] = { 

1060 'pep_stylesheet': ('pep_html writer', 'stylesheet'), 

1061 'pep_stylesheet_path': ('pep_html writer', 'stylesheet_path'), 

1062 'pep_template': ('pep_html writer', 'template')} 

1063 """{old setting: (new section, new setting)} mapping, used by 

1064 `handle_old_config`, to convert settings from the old [options] section. 

1065 """ 

1066 

1067 old_warning: ClassVar[str] = ( 

1068 'The "[option]" section is deprecated.\n' 

1069 'Support for old-format configuration files will be removed in ' 

1070 'Docutils 2.0. Please revise your configuration files. ' 

1071 'See <https://docutils.sourceforge.io/docs/user/config.html>, ' 

1072 'section "Old-Format Configuration Files".') 

1073 

1074 not_utf8_error: ClassVar[str] = """\ 

1075Unable to read configuration file "%s": content not encoded as UTF-8. 

1076Skipping "%s" configuration file. 

1077""" 

1078 

1079 def read(self, 

1080 filenames: str | Sequence[str], 

1081 option_parser: OptionParser | None = None, 

1082 ) -> list[str]: 

1083 # Currently, if a `docutils.frontend.OptionParser` instance is 

1084 # supplied, setting values are validated. 

1085 if option_parser is not None: 

1086 warnings.warn('frontend.ConfigParser.read(): parameter ' 

1087 '"option_parser" will be removed ' 

1088 'in Docutils 0.21 or later.', 

1089 DeprecationWarning, stacklevel=2) 

1090 read_ok = [] 

1091 if isinstance(filenames, str): 

1092 filenames = [filenames] 

1093 for filename in filenames: 

1094 # Config files are UTF-8-encoded: 

1095 try: 

1096 read_ok += super().read(filename, encoding='utf-8') 

1097 except UnicodeDecodeError: 

1098 sys.stderr.write(self.not_utf8_error % (filename, filename)) 

1099 continue 

1100 if 'options' in self: 

1101 self.handle_old_config(filename) 

1102 if option_parser is not None: 

1103 self.validate_settings(filename, option_parser) 

1104 return read_ok 

1105 

1106 def handle_old_config(self, filename: str) -> None: 

1107 warnings.warn_explicit(self.old_warning, ConfigDeprecationWarning, 

1108 filename, 0) 

1109 options = self.get_section('options') 

1110 if not self.has_section('general'): 

1111 self.add_section('general') 

1112 for key, value in options.items(): 

1113 if key in self.old_settings: 

1114 section, setting = self.old_settings[key] 

1115 if not self.has_section(section): 

1116 self.add_section(section) 

1117 else: 

1118 section = 'general' 

1119 setting = key 

1120 if not self.has_option(section, setting): 

1121 self.set(section, setting, value) 

1122 self.remove_section('options') 

1123 

1124 def validate_settings(self, filename: str, option_parser: OptionParser, 

1125 ) -> None: 

1126 """ 

1127 Call the validator function and implement overrides on all applicable 

1128 settings. 

1129 """ 

1130 for section in self.sections(): 

1131 for setting in self.options(section): 

1132 try: 

1133 option = option_parser.get_option_by_dest(setting) 

1134 except KeyError: 

1135 continue 

1136 if option.validator: 

1137 value = self.get(section, setting) 

1138 try: 

1139 new_value = option.validator( 

1140 setting, value, option_parser, 

1141 config_parser=self, config_section=section) 

1142 except Exception as err: 

1143 raise ValueError(f'Error in config file "{filename}", ' 

1144 f'section "[{section}]":\n' 

1145 f' {io.error_string(err)}\n' 

1146 f' {setting} = {value}') 

1147 self.set(section, setting, new_value) 

1148 if option.overrides: 

1149 self.set(section, option.overrides, None) 

1150 

1151 def optionxform(self, optionstr: str) -> str: 

1152 """ 

1153 Lowercase and transform '-' to '_'. 

1154 

1155 So the cmdline form of option names can be used in config files. 

1156 """ 

1157 return optionstr.lower().replace('-', '_') 

1158 

1159 def get_section(self, section: str) -> dict[str, str]: 

1160 """ 

1161 Return a given section as a dictionary. 

1162 

1163 Return empty dictionary if the section doesn't exist. 

1164 

1165 Deprecated. Use the configparser "Mapping Protocol Access" and 

1166 catch KeyError. 

1167 """ 

1168 warnings.warn('frontend.OptionParser.get_section() ' 

1169 'will be removed in Docutils 0.21 or later.', 

1170 DeprecationWarning, stacklevel=2) 

1171 try: 

1172 return dict(self[section]) 

1173 except KeyError: 

1174 return {} 

1175 

1176 

1177class ConfigDeprecationWarning(FutureWarning): 

1178 """Warning for deprecated configuration file features.""" 

1179 

1180 

1181def get_default_settings(*components: SettingsSpec) -> Values: 

1182 """Return default runtime settings for `components`. 

1183 

1184 Return a `frontend.Values` instance with defaults for generic Docutils 

1185 settings and settings from the `components` (`SettingsSpec` instances). 

1186 

1187 This corresponds to steps 1 and 2 in the `runtime settings priority`__. 

1188 

1189 __ https://docutils.sourceforge.io/docs/api/runtime-settings.html 

1190 #settings-priority 

1191 """ 

1192 with warnings.catch_warnings(): 

1193 warnings.filterwarnings('ignore', category=DeprecationWarning) 

1194 return OptionParser(components).get_default_values()