docutils.frontend Namespace Reference

Classes
class	ConfigDeprecationWarning
class	ConfigParser
class	Option
class	OptionParser
class	Values

Functions
	store_multiple (option, opt, value, parser, *args, **kwargs)
	read_config_file (option, opt, value, parser)
	validate_encoding (setting, value=None, option_parser=None, config_parser=None, config_section=None)
	validate_encoding_error_handler (setting, value=None, option_parser=None, config_parser=None, config_section=None)
	validate_encoding_and_error_handler (setting, value, option_parser, config_parser=None, config_section=None)
	validate_boolean (setting, value=None, option_parser=None, config_parser=None, config_section=None)
	validate_ternary (setting, value=None, option_parser=None, config_parser=None, config_section=None)
	validate_nonnegative_int (setting, value=None, option_parser=None, config_parser=None, config_section=None)
	validate_threshold (setting, value=None, option_parser=None, config_parser=None, config_section=None)
	validate_colon_separated_string_list (setting, value=None, option_parser=None, config_parser=None, config_section=None)
	validate_comma_separated_list (setting, value=None, option_parser=None, config_parser=None, config_section=None)
	validate_math_output (setting, value=None, option_parser=None, config_parser=None, config_section=None)
	validate_url_trailing_slash (setting, value=None, option_parser=None, config_parser=None, config_section=None)
	validate_dependency_file (setting, value=None, option_parser=None, config_parser=None, config_section=None)
	validate_strip_class (setting, value=None, option_parser=None, config_parser=None, config_section=None)
	validate_smartquotes_locales (setting, value=None, option_parser=None, config_parser=None, config_section=None)
	make_paths_absolute (pathdict, keys, base_path=None)
	make_one_path_absolute (base_path, path)
	filter_settings_spec (settings_spec, *exclude, **replace)
	get_default_settings (*components)

Detailed Description

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.

Function Documentation

filter_settings_spec()

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

get_default_settings()

docutils.frontend.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`__.

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

make_paths_absolute()

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

read_config_file()

docutils.frontend.read_config_file	(		option,
			opt,
			value,
			parser
	)

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

store_multiple()

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

validate_boolean()

docutils.frontend.validate_boolean	(		setting,
			value = None,
			option_parser = None,
			config_parser = None,
			config_section = None
	)

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

All arguments except `value` are ignored
(kept for compatibility with "optparse" module).
If there is only one positional argument, it is interpreted as `value`.

validate_comma_separated_list()

docutils.frontend.validate_comma_separated_list	(		setting,
			value = None,
			option_parser = None,
			config_parser = None,
			config_section = None
	)

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

All arguments except `value` are ignored
(kept for compatibility with "optparse" module).
If there is only one positional argument, it is interpreted as `value`.

validate_encoding_and_error_handler()

docutils.frontend.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 were a separate setting/option.

validate_math_output()

docutils.frontend.validate_math_output	(		setting,
			value = None,
			option_parser = None,
			config_parser = None,
			config_section = None
	)

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

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

Argument list for compatibility with "optparse" module.
All arguments except `value` are ignored.
If there is only one positional argument, it is interpreted as `value`.

validate_smartquotes_locales()

docutils.frontend.validate_smartquotes_locales	(		setting,
			value = None,
			option_parser = None,
			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.

All arguments except `value` are ignored
(kept for compatibility with "optparse" module).
If there is only one positional argument, it is interpreted as `value`.

validate_ternary()

docutils.frontend.validate_ternary	(		setting,
			value = None,
			option_parser = None,
			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.

All arguments except `value` are ignored
(kept for compatibility with "optparse" module).
If there is only one positional argument, it is interpreted as `value`.