docutils.frontend

module documentation
(source)

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.

Class ConfigDeprecationWarning Warning for deprecated configuration file features.
Class ConfigParser Parser for Docutils configuration files.
Class Option Add validation and override support to `optparse.Option`.
Class OptionParser Settings parser for command-line and library use.
Class Values Storage for option values.
Function filter_settings_spec Return a copy of `settings_spec` excluding/replacing some settings.
Function get_default_settings Return default runtime settings for `components`.
Function make_one_path_absolute Undocumented
Function make_paths_absolute Interpret filesystem path settings relative to the `base_path` given.
Function read_config_file Read a configuration file during option processing. (Option callback.)
Function store_multiple Store multiple values in `parser.values`. (Option callback.)
Function validate_boolean Check/normalize boolean settings: True: '1', 'on', 'yes', 'true' False: '0', 'off', 'no','false', ''
Function validate_colon_separated_string_list Undocumented
Function validate_comma_separated_list Check/normalize list arguments (split at "," and strip whitespace).
Function validate_dependency_file Undocumented
Function validate_encoding Undocumented
Function validate_encoding_and_error_handler 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.
Function validate_encoding_error_handler Undocumented
Function validate_nonnegative_int Undocumented
Function validate_smartquotes_locales Check/normalize a comma separated list of smart quote definitions.
Function validate_strip_class Undocumented
Function validate_ternary Check/normalize three-value settings: True: '1', 'on', 'yes', 'true' False: '0', 'off', 'no','false', '' any other value: returned as-is.
Function validate_threshold Undocumented
Function validate_url_trailing_slash Undocumented
def filter_settings_spec(settings_spec, *exclude, **replace): (source)

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.)

def get_default_settings(*components): (source)

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`__. __ https://docutils.sourceforge.io/docs/api/runtime-settings.html #settings-priority

def make_one_path_absolute(base_path, path): (source)

Undocumented

def make_paths_absolute(pathdict, keys, base_path=None): (source)

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`.

def read_config_file(option, opt, value, parser): (source)

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

def store_multiple(option, opt, value, parser, *args, **kwargs): (source)

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`.

def validate_boolean(setting, value, option_parser, config_parser=None, config_section=None): (source)

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

def validate_colon_separated_string_list(setting, value, option_parser, config_parser=None, config_section=None): (source)

Undocumented

def validate_comma_separated_list(setting, value, option_parser, config_parser=None, config_section=None): (source)

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

def validate_dependency_file(setting, value, option_parser, config_parser=None, config_section=None): (source)

Undocumented

def validate_encoding(setting, value, option_parser, config_parser=None, config_section=None): (source)

Undocumented

def validate_encoding_and_error_handler(setting, value, option_parser, config_parser=None, config_section=None): (source)

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.

def validate_encoding_error_handler(setting, value, option_parser, config_parser=None, config_section=None): (source)

Undocumented

def validate_nonnegative_int(setting, value, option_parser, config_parser=None, config_section=None): (source)

Undocumented

def validate_smartquotes_locales(setting, value, option_parser, config_parser=None, config_section=None): (source)

Check/normalize a comma separated list of smart quote definitions. Return a list of (language-tag, quotes) string tuples.

def validate_strip_class(setting, value, option_parser, config_parser=None, config_section=None): (source)

Undocumented

def validate_ternary(setting, value, option_parser, config_parser=None, config_section=None): (source)

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

def validate_threshold(setting, value, option_parser, config_parser=None, config_section=None): (source)

Undocumented

def validate_url_trailing_slash(setting, value, option_parser, config_parser=None, config_section=None): (source)

Undocumented