docutils.SettingsSpec

class documentation

class SettingsSpec(object): (source)

Known subclasses: docutils.Component, docutils.frontend.OptionParser

View In Hierarchy

Runtime setting specification base class.

SettingsSpec subclass objects used by docutils.frontend.OptionParser.

Class Variable config​_section The name of the config file section specific to this component (lowercase, no brackets). Override in subclasses.
Class Variable config​_section​_dependencies No summary
Class Variable relative​_path​_settings Settings containing filesystem paths. Override in subclasses. Settings listed here are to be interpreted relative to the current working directory.
Class Variable settings​_default​_overrides A dictionary of auxiliary defaults, to override defaults for settings defined in other components. Override in subclasses.
Class Variable settings​_defaults A dictionary of defaults for settings not in settings_spec (internal settings, intended to be inaccessible by command-line and config file). Override in subclasses.
Class Variable settings​_spec Runtime settings specification. Override in subclasses.
config_section = (source)
overridden in docutils.frontend.OptionParser, docutils.parsers.Parser, docutils.readers.Reader, docutils.writers.Writer
The name of the config file section specific to this component (lowercase, no brackets). Override in subclasses.
config_section_dependencies = (source)
overridden in docutils.parsers.null.Parser, docutils.parsers.rst.Parser, docutils.readers.doctree.Reader, docutils.readers.standalone.Reader, docutils.writers._html_base.Writer, docutils.writers.docutils_xml.Writer, docutils.writers.latex2e.Writer, docutils.writers.null.Writer, docutils.writers.odf_odt.Writer, docutils.writers.pseudoxml.Writer
A list of names of config file sections that are to be applied before config_section, in order (from general to specific). In other words, the settings in config_section are to be overlaid on top of the settings from these sections. The "general" section is assumed implicitly. Override in subclasses.
relative_path_settings: tuple = (source)
overridden in docutils.frontend.OptionParser, docutils.writers.odf_odt.Writer, docutils.writers.pep_html.Writer
Settings containing filesystem paths. Override in subclasses. Settings listed here are to be interpreted relative to the current working directory.
settings_default_overrides = (source)
overridden in docutils.readers.pep.Reader, docutils.writers.pep_html.Writer, docutils.writers.s5_html.Writer
A dictionary of auxiliary defaults, to override defaults for settings defined in other components. Override in subclasses.
settings_defaults = (source)
overridden in docutils.frontend.OptionParser, docutils.writers._html_base.Writer, docutils.writers.docutils_xml.Writer, docutils.writers.latex2e.Writer, docutils.writers.odf_odt.Writer
A dictionary of defaults for settings not in settings_spec (internal settings, intended to be inaccessible by command-line and config file). Override in subclasses.
settings_spec: tuple = (source)
overridden in docutils.frontend.OptionParser, docutils.parsers.Parser, docutils.readers.standalone.Reader, docutils.writers.docutils_xml.Writer, docutils.writers.html4css1.Writer, docutils.writers.html5_polyglot.Writer, docutils.writers.latex2e.Writer, docutils.writers.odf_odt.Writer, docutils.writers.pseudoxml.Writer

Runtime settings specification. Override in subclasses.

Defines runtime settings and associated command-line options, as used by docutils.frontend.OptionParser. This is a tuple of:

  • Option group title (string or None which implies no group, just a list of single options).

  • Description (string or None).

  • A sequence of option tuples. Each consists of:

    • Help text (string)

    • List of option strings (e.g. ['-Q', '--quux']).

    • Dictionary of keyword arguments sent to the OptionParser/OptionGroup add_option method.

      Runtime setting names are derived implicitly from long option names ('--a-setting' becomes settings.a_setting) or explicitly from the 'dest' keyword argument.

      Most settings will also have a 'validator' keyword & function. The validator function validates setting values (from configuration files and command-line option arguments) and converts them to appropriate types. For example, the docutils.frontend.validate_boolean function, required by all boolean settings, converts true values ('1', 'on', 'yes', and 'true') to 1 and false values ('0', 'off', 'no', 'false', and '') to 0. Validators need only be set once per setting. See the docutils.frontend.validate_* functions.

      See the optparse docs for more details.

  • More triples of group title, description, options, as many times as needed. Thus, settings_spec tuples can be simply concatenated.