docutils.frontend module

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

This module is provisional. Major changes will happen with the switch from the deprecated “optparse” module to “arparse”.

Applications should use the high-level API provided by docutils.core. See https://docutils.sourceforge.io/docs/api/runtime-settings.html.

Exports the following classes:

• OptionParser: Standard Docutils command-line processing. Deprecated. Will be replaced by an ArgumentParser.

• Option: Customized version of optparse.Option; validation support. Deprecated. Will be removed.

• Values: Runtime settings; objects are simple structs (object.attribute). Supports cumulative list settings (attributes). Deprecated. Will be removed.

• ConfigParser: Standard Docutils config file processing. Provisional. Details will change.

Also exports the following functions:

Interface function:

get_default_settings(). New in 0.19.

Option callbacks:

store_multiple(), read_config_file(). Deprecated.

Setting validators:

validate_encoding(), validate_encoding_error_handler(), validate_encoding_and_error_handler(), validate_boolean(), validate_ternary(), validate_nonnegative_int(), validate_threshold(), validate_colon_separated_string_list(), validate_comma_separated_list(), validate_url_trailing_slash(), validate_dependency_file(), validate_strip_class() validate_smartquotes_locales().

Provisional.

Misc:

make_paths_absolute(), filter_settings_spec(). Provisional.

store_multiple(option, opt, value, parser, *args, **kwargs)

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

Store None for each attribute named in args, and store the value for each key (attribute name) in kwargs.

read_config_file(option, opt, value, parser)

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

validate_encoding(setting, value, option_parser, config_parser=None, config_section=None)

validate_encoding_error_handler(setting, value, option_parser, config_parser=None, config_section=None)

validate_encoding_and_error_handler(setting, value, option_parser, config_parser=None, config_section=None)

Side-effect: if an error handler is included in the value, it is inserted into the appropriate place as if it was a separate setting/option.

validate_boolean(setting, value, option_parser, config_parser=None, config_section=None)

Check/normalize boolean settings: True: ‘1’, ‘on’, ‘yes’, ‘true’ False: ‘0’, ‘off’, ‘no’,’false’, ‘’

validate_ternary(setting, value, option_parser, config_parser=None, config_section=None)

Check/normalize three-value settings: True: ‘1’, ‘on’, ‘yes’, ‘true’ False: ‘0’, ‘off’, ‘no’,’false’, ‘’ any other value: returned as-is.

validate_nonnegative_int(setting, value, option_parser, config_parser=None, config_section=None)

validate_threshold(setting, value, option_parser, config_parser=None, config_section=None)

validate_colon_separated_string_list(setting, value, option_parser, config_parser=None, config_section=None)

validate_comma_separated_list(setting, value, option_parser, config_parser=None, config_section=None)

Check/normalize list arguments (split at “,” and strip whitespace).

validate_url_trailing_slash(setting, value, option_parser, config_parser=None, config_section=None)

validate_dependency_file(setting, value, option_parser, config_parser=None, config_section=None)

validate_strip_class(setting, value, option_parser, config_parser=None, config_section=None)

validate_smartquotes_locales(setting, value, option_parser, config_parser=None, config_section=None)

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

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

make_paths_absolute(pathdict, keys, base_path=None)

Interpret filesystem path settings relative to the base_path given.

Paths are values in pathdict whose keys are in keys. Get keys from OptionParser.relative_path_settings.

make_one_path_absolute(base_path, path)

filter_settings_spec(settings_spec, *exclude, **replace)

Return a copy of settings_spec excluding/replacing some settings.

settings_spec is a tuple of configuration settings (cf. docutils.SettingsSpec.settings_spec).

Optional positional arguments are names of to-be-excluded settings. Keyword arguments are option specification replacements. (See the html4strict writer for an example.)

class Values(*args, **kwargs)

Bases: Values

Storage for option values.

Updates list attributes by extension rather than by replacement. Works in conjunction with the OptionParser.lists instance attribute.

Deprecated. Will be removed.

update(other_dict, option_parser)

copy()

Return a shallow copy of self.

setdefault(name, default)

Return self.name or default.

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

class Option(*args, **kwargs)

Bases: Option

Add validation and override support to optparse.Option.

Deprecated. Will be removed.

ATTRS = ['action', 'type', 'dest', 'default', 'nargs', 'const', 'choices', 'callback', 'callback_args', 'callback_kwargs', 'help', 'metavar', 'validator', 'overrides']

process(opt, value, values, parser)

Call the validator function on applicable settings and evaluate the ‘overrides’ option. Extends optparse.Option.process.

class OptionParser(components=(), defaults=None, read_config_files=False, *args, **kwargs)

Bases: OptionParser, SettingsSpec

Settings parser for command-line and library use.

The settings_spec specification here and in other Docutils components are merged to build the set of command-line options and runtime settings for this process.

Common settings (defined below) and component-specific settings must not conflict. Short options are reserved for common settings, and components are restricted to using long options.

Deprecated. Will be replaced by a subclass of argparse.ArgumentParser.

standard_config_files = ['/etc/docutils.conf', './docutils.conf', '~/.docutils']

Docutils configuration files, using ConfigParser syntax.

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

threshold_choices = ['info', '1', 'warning', '2', 'error', '3', 'severe', '4', 'none', '5']

Possible inputs for for –report and –halt threshold values.

thresholds = {'error': 3, 'info': 1, 'none': 5, 'severe': 4, 'warning': 2}

Lookup table for –report and –halt threshold values.

booleans = {'': False, '0': False, '1': True, 'false': False, 'no': False, 'off': False, 'on': True, 'true': True, 'yes': True}

Lookup table for boolean configuration file settings.

default_error_encoding = 'utf-8'

default_error_encoding_error_handler = 'backslashreplace'

settings_spec = ('General Docutils Options', None, (('Output destination name. Obsoletes the <destination> positional argument. Default: None (stdout).', ['--output'], {'metavar': '<destination>'}), ('Specify the document title as metadata.', ['--title'], {'metavar': '<title>'}), ('Include a "Generated by Docutils" credit and link.', ['--generator', '-g'], {'action': 'store_true', 'validator': <function validate_boolean>}), ('Do not include a generator credit.', ['--no-generator'], {'action': 'store_false', 'dest': 'generator'}), ('Include the date at the end of the document (UTC).', ['--date', '-d'], {'action': 'store_const', 'const': '%Y-%m-%d', 'dest': 'datestamp'}), ('Include the time & date (UTC).', ['--time', '-t'], {'action': 'store_const', 'const': '%Y-%m-%d %H:%M UTC', 'dest': 'datestamp'}), ('Do not include a datestamp of any kind.', ['--no-datestamp'], {'action': 'store_const', 'const': None, 'dest': 'datestamp'}), ('Include a "View document source" link.', ['--source-link', '-s'], {'action': 'store_true', 'validator': <function validate_boolean>}), ('Use <URL> for a source link; implies --source-link.', ['--source-url'], {'metavar': '<URL>'}), ('Do not include a "View document source" link.', ['--no-source-link'], {'action': 'callback', 'callback': <function store_multiple>, 'callback_args': ('source_link', 'source_url')}), ('Link from section headers to TOC entries.  (default)', ['--toc-entry-backlinks'], {'action': 'store_const', 'const': 'entry', 'default': 'entry', 'dest': 'toc_backlinks'}), ('Link from section headers to the top of the TOC.', ['--toc-top-backlinks'], {'action': 'store_const', 'const': 'top', 'dest': 'toc_backlinks'}), ('Disable backlinks to the table of contents.', ['--no-toc-backlinks'], {'action': 'store_false', 'dest': 'toc_backlinks'}), ('Link from footnotes/citations to references. (default)', ['--footnote-backlinks'], {'action': 'store_true', 'default': 1, 'validator': <function validate_boolean>}), ('Disable backlinks from footnotes and citations.', ['--no-footnote-backlinks'], {'action': 'store_false', 'dest': 'footnote_backlinks'}), ('Enable section numbering by Docutils.  (default)', ['--section-numbering'], {'action': 'store_true', 'default': 1, 'dest': 'sectnum_xform', 'validator': <function validate_boolean>}), ('Disable section numbering by Docutils.', ['--no-section-numbering'], {'action': 'store_false', 'dest': 'sectnum_xform'}), ('Remove comment elements from the document tree.', ['--strip-comments'], {'action': 'store_true', 'validator': <function validate_boolean>}), ('Leave comment elements in the document tree. (default)', ['--leave-comments'], {'action': 'store_false', 'dest': 'strip_comments'}), ('Remove all elements with classes="<class>" from the document tree. Warning: potentially dangerous; use with caution. (Multiple-use option.)', ['--strip-elements-with-class'], {'action': 'append', 'dest': 'strip_elements_with_classes', 'metavar': '<class>', 'validator': <function validate_strip_class>}), ('Remove all classes="<class>" attributes from elements in the document tree. Warning: potentially dangerous; use with caution. (Multiple-use option.)', ['--strip-class'], {'action': 'append', 'dest': 'strip_classes', 'metavar': '<class>', 'validator': <function validate_strip_class>}), ('Report system messages at or higher than <level>: "info" or "1", "warning"/"2" (default), "error"/"3", "severe"/"4", "none"/"5"', ['--report', '-r'], {'choices': ['info', '1', 'warning', '2', 'error', '3', 'severe', '4', 'none', '5'], 'default': 2, 'dest': 'report_level', 'metavar': '<level>', 'validator': <function validate_threshold>}), ('Report all system messages.  (Same as "--report=1".)', ['--verbose', '-v'], {'action': 'store_const', 'const': 1, 'dest': 'report_level'}), ('Report no system messages.  (Same as "--report=5".)', ['--quiet', '-q'], {'action': 'store_const', 'const': 5, 'dest': 'report_level'}), ('Halt execution at system messages at or above <level>.  Levels as in --report.  Default: 4 (severe).', ['--halt'], {'choices': ['info', '1', 'warning', '2', 'error', '3', 'severe', '4', 'none', '5'], 'default': 4, 'dest': 'halt_level', 'metavar': '<level>', 'validator': <function validate_threshold>}), ('Halt at the slightest problem.  Same as "--halt=info".', ['--strict'], {'action': 'store_const', 'const': 1, 'dest': 'halt_level'}), ('Enable a non-zero exit status for non-halting system messages at or above <level>.  Default: 5 (disabled).', ['--exit-status'], {'choices': ['info', '1', 'warning', '2', 'error', '3', 'severe', '4', 'none', '5'], 'default': 5, 'dest': 'exit_status_level', 'metavar': '<level>', 'validator': <function validate_threshold>}), ('Enable debug-level system messages and diagnostics.', ['--debug'], {'action': 'store_true', 'validator': <function validate_boolean>}), ('Disable debug output.  (default)', ['--no-debug'], {'action': 'store_false', 'dest': 'debug'}), ('Send the output of system messages to <file>.', ['--warnings'], {'dest': 'warning_stream', 'metavar': '<file>'}), ('Enable Python tracebacks when Docutils is halted.', ['--traceback'], {'action': 'store_true', 'default': None, 'validator': <function validate_boolean>}), ('Disable Python tracebacks.  (default)', ['--no-traceback'], {'action': 'store_false', 'dest': 'traceback'}), ('Specify the encoding and optionally the error handler of input text.  Default: <auto-detect>:strict.', ['--input-encoding', '-i'], {'metavar': '<name[:handler]>', 'validator': <function validate_encoding_and_error_handler>}), ('Specify the error handler for undecodable characters.  Choices: "strict" (default), "ignore", and "replace".', ['--input-encoding-error-handler'], {'default': 'strict', 'validator': <function validate_encoding_error_handler>}), ('Specify the text encoding and optionally the error handler for output.  Default: utf-8:strict.', ['--output-encoding', '-o'], {'default': 'utf-8', 'metavar': '<name[:handler]>', 'validator': <function validate_encoding_and_error_handler>}), ('Specify error handler for unencodable output characters; "strict" (default), "ignore", "replace", "xmlcharrefreplace", "backslashreplace".', ['--output-encoding-error-handler'], {'default': 'strict', 'validator': <function validate_encoding_error_handler>}), ('Specify text encoding and optionally error handler for error output.  Default: utf-8:backslashreplace.', ['--error-encoding', '-e'], {'default': 'utf-8', 'metavar': '<name[:handler]>', 'validator': <function validate_encoding_and_error_handler>}), ('Specify the error handler for unencodable characters in error output.  Default: backslashreplace.', ['--error-encoding-error-handler'], {'default': 'backslashreplace', 'validator': <function validate_encoding_error_handler>}), ('Specify the language (as BCP 47 language tag).  Default: en.', ['--language', '-l'], {'default': 'en', 'dest': 'language_code', 'metavar': '<name>'}), ('Write output file dependencies to <file>.', ['--record-dependencies'], {'default': None, 'metavar': '<file>', 'validator': <function validate_dependency_file>}), ('Read configuration settings from <file>, if it exists.', ['--config'], {'action': 'callback', 'callback': <function read_config_file>, 'metavar': '<file>', 'type': 'string'}), ("Show this program's version number and exit.", ['--version', '-V'], {'action': 'version'}), ('Show this help message and exit.', ['--help', '-h'], {'action': 'help'}), ('SUPPRESSHELP', ['--id-prefix'], {'default': ''}), ('SUPPRESSHELP', ['--auto-id-prefix'], {'default': '%'}), ('SUPPRESSHELP', ['--dump-settings'], {'action': 'store_true'}), ('SUPPRESSHELP', ['--dump-internals'], {'action': 'store_true'}), ('SUPPRESSHELP', ['--dump-transforms'], {'action': 'store_true'}), ('SUPPRESSHELP', ['--dump-pseudo-xml'], {'action': 'store_true'}), ('SUPPRESSHELP', ['--expose-internal-attribute'], {'action': 'append', 'dest': 'expose_internals', 'validator': <function validate_colon_separated_string_list>}), ('SUPPRESSHELP', ['--strict-visitor'], {'action': 'store_true'})))

Runtime settings and command-line options common to all Docutils front ends. Setting specs specific to individual Docutils components are also used (see populate_from_components()).

settings_defaults = {'_config_files': None, '_destination': None, '_disable_config': None, '_source': None}

Defaults for settings without command-line option equivalents.

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

config_section = 'general'

The name of the config file section specific to this component (lowercase, no brackets). Override in subclasses.

version_template = '%prog (Docutils 0.20.1, Python 3.12.0, on linux)'

Default version message.

__init__(components=(), defaults=None, read_config_files=False, *args, **kwargs)

Set up OptionParser instance.

components is a list of Docutils components each containing a .settings_spec attribute. defaults is a mapping of setting default overrides.

lists

Set of list-type settings.

config_files

List of paths of applied configuration files.

populate_from_components(components)

Collect settings specification from components.

For each component, populate from the SettingsSpec.settings_spec structure, then from the SettingsSpec.settings_defaults dictionary. After all components have been processed, check for and populate from each component’s SettingsSpec.settings_default_overrides dictionary.

classmethod get_standard_config_files()

Return list of config files, from environment or standard.

get_standard_config_settings()

get_config_file_settings(config_file)

Returns a dictionary containing appropriate config file settings.

check_values(values, args)

Store positional arguments as runtime settings.

check_args(args)

set_defaults_from_dict(defaults)

get_default_values()

Needed to get custom Values instances.

get_option_by_dest(dest)

Get an option by its dest.

If you’re supplying a dest which is shared by several options, it is undefined which option of those is returned.

A KeyError is raised if there is no option with the supplied dest.

class ConfigParser(defaults=None, dict_type=<class 'dict'>, allow_no_value=False, *, delimiters=('=', ':'), comment_prefixes=('#', ';'), inline_comment_prefixes=None, strict=True, empty_lines_in_values=True, default_section='DEFAULT', interpolation=<object object>, converters=<object object>)

Bases: RawConfigParser

Parser for Docutils configuration files.

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

Option key normalization includes conversion of ‘-’ to ‘_’.

Config file encoding is “utf-8”. Encoding errors are reported and the affected file(s) skipped.

This class is provisional and will change in future versions.

_abc_impl = <_abc._abc_data object>

old_settings = {'pep_stylesheet': ('pep_html writer', 'stylesheet'), 'pep_stylesheet_path': ('pep_html writer', 'stylesheet_path'), 'pep_template': ('pep_html writer', 'template')}

(new section, new setting)} mapping, used by handle_old_config, to convert settings from the old [options] section.

Type:

{old setting

old_warning = 'The "[option]" section is deprecated.\nSupport for old-format configuration files will be removed in Docutils 0.21 or later.  Please revise your configuration files.  See <https://docutils.sourceforge.io/docs/user/config.html>, section "Old-Format Configuration Files".'

not_utf8_error = 'Unable to read configuration file "%s": content not encoded as UTF-8.\nSkipping "%s" configuration file.\n'

read(filenames, option_parser=None)

Read and parse a filename or an iterable of filenames.

Files that cannot be opened are silently ignored; this is designed so that you can specify an iterable of potential configuration file locations (e.g. current directory, user’s home directory, systemwide directory), and all existing configuration files in the iterable will be read. A single filename may also be given.

Return list of successfully read files.

handle_old_config(filename)

validate_settings(filename, option_parser)

Call the validator function and implement overrides on all applicable settings.

optionxform(optionstr)

Lowercase and transform ‘-’ to ‘_’.

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

get_section(section)

Return a given section as a dictionary.

Return empty dictionary if the section doesn’t exist.

Deprecated. Use the configparser “Mapping Protocol Access” and catch KeyError.

exception ConfigDeprecationWarning

Bases: FutureWarning

Warning for deprecated configuration file features.

get_default_settings(*components)

Return default runtime settings for components.

Return a frontend.Values instance with defaults for generic Docutils settings and settings from the components (SettingsSpec instances).

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