4.4.1.1.2. core

Calling the publish_* convenience functions (or instantiating a Publisher object) with component names will result in default behavior. For custom behavior (setting component options), create custom component objects first, and pass them to publish_*/Publisher. See The Docutils Publisher.

class docutils.core.Publisher(reader=None, parser=None, writer=None, source=None, source_class=<class 'docutils.io.FileInput'>, destination=None, destination_class=<class 'docutils.io.FileOutput'>, settings=None)

Bases: object

A facade encapsulating the high-level logic of a Docutils system.

Initial setup. If any of reader, parser, or writer are not specified, the corresponding set_... method should be called with a component name (set_reader sets the parser as well).

apply_transforms()

debugging_dumps()

destination = None

The destination for docutils output, a docutils.io.Output instance.

destination_class = None

The class for dynamically created destination objects.

document = None

The document tree (docutils.nodes objects).

get_settings(usage=None, description=None, settings_spec=None, config_section=None, **defaults)

Set and return default settings (overrides in defaults dict).

Set components first (self.set_reader & self.set_writer). Explicitly setting self.settings disables command line option processing from self.publish().

parser = None

A docutils.parsers.Parser instance.

process_command_line(argv=None, usage=None, description=None, settings_spec=None, config_section=None, **defaults)

Pass an empty list to argv to avoid reading sys.argv (the default).

Set components first (self.set_reader & self.set_writer).

process_programmatic_settings(settings_spec, settings_overrides, config_section)

publish(argv=None, usage=None, description=None, settings_spec=None, settings_overrides=None, config_section=None, enable_exit_status=False)

Process command line options and arguments (if self.settings not already set), run self.reader and then self.writer. Return self.writer’s output.

reader = None

A docutils.readers.Reader instance.

report_Exception(error)

report_SystemMessage(error)

report_UnicodeError(error)

set_components(reader_name, parser_name, writer_name)

set_destination(destination=None, destination_path=None)

set_io(source_path=None, destination_path=None)

set_reader(reader_name, parser, parser_name)

Set self.reader by name.

set_source(source=None, source_path=None)

set_writer(writer_name)

Set self.writer by name.

settings = None

An object containing Docutils settings as instance attributes. Set by self.process_command_line() or self.get_settings().

setup_option_parser(usage=None, description=None, settings_spec=None, config_section=None, **defaults)

source = None

The source of input data, a docutils.io.Input instance.

source_class = None

The class for dynamically created source objects.

writer = None

A docutils.writers.Writer instance.

docutils.core.publish_cmdline(reader=None, reader_name='standalone', parser=None, parser_name='restructuredtext', writer=None, writer_name='pseudoxml', settings=None, settings_spec=None, settings_overrides=None, config_section=None, enable_exit_status=True, argv=None, usage='%prog [options] [<source> [<destination>]]', description='Reads from <source> (default is stdin) and writes to <destination> (default is stdout). See <http://docutils.sf.net/docs/user/config.html> for the full reference.')

Set up & run a Publisher for command-line-based file I/O (input and output file paths taken automatically from the command line). Return the encoded string output also.

Parameters: see publish_programmatically for the remainder.

• argv: Command-line argument list to use instead of sys.argv[1:].
• usage: Usage string, output if there’s a problem parsing the command line.
• description: Program description, output for the “–help” option (along with command-line option descriptions).

docutils.core.publish_cmdline_to_binary(reader=None, reader_name='standalone', parser=None, parser_name='restructuredtext', writer=None, writer_name='pseudoxml', settings=None, settings_spec=None, settings_overrides=None, config_section=None, enable_exit_status=True, argv=None, usage='%prog [options] [<source> [<destination>]]', description='Reads from <source> (default is stdin) and writes to <destination> (default is stdout). See <http://docutils.sf.net/docs/user/config.html> for the full reference.', destination=None, destination_class=<class 'docutils.io.BinaryFileOutput'>)

Set up & run a Publisher for command-line-based file I/O (input and output file paths taken automatically from the command line). Return the encoded string output also.

This is just like publish_cmdline, except that it uses io.BinaryFileOutput instead of io.FileOutput.

Parameters: see publish_programmatically for the remainder.

• argv: Command-line argument list to use instead of sys.argv[1:].
• usage: Usage string, output if there’s a problem parsing the command line.
• description: Program description, output for the “–help” option (along with command-line option descriptions).

docutils.core.publish_doctree(source, source_path=None, source_class=<class 'docutils.io.StringInput'>, reader=None, reader_name='standalone', parser=None, parser_name='restructuredtext', settings=None, settings_spec=None, settings_overrides=None, config_section=None, enable_exit_status=False)

Set up & run a Publisher for programmatic use with string I/O. Return the document tree.

For encoded string input, be sure to set the ‘input_encoding’ setting to the desired encoding. Set it to ‘unicode’ for unencoded Unicode string input. Here’s one way:

publish_doctree(..., settings_overrides={'input_encoding': 'unicode'})

Parameters: see publish_programmatically.

docutils.core.publish_file(source=None, source_path=None, destination=None, destination_path=None, reader=None, reader_name='standalone', parser=None, parser_name='restructuredtext', writer=None, writer_name='pseudoxml', settings=None, settings_spec=None, settings_overrides=None, config_section=None, enable_exit_status=False)

Set up & run a Publisher for programmatic use with file-like I/O. Return the encoded string output also.

Parameters: see publish_programmatically.

docutils.core.publish_from_doctree(document, destination_path=None, writer=None, writer_name='pseudoxml', settings=None, settings_spec=None, settings_overrides=None, config_section=None, enable_exit_status=False)

Set up & run a Publisher to render from an existing document tree data structure, for programmatic use with string I/O. Return the encoded string output.

Note that document.settings is overridden; if you want to use the settings of the original document, pass settings=document.settings.

Also, new document.transformer and document.reporter objects are generated.

For encoded string output, be sure to set the ‘output_encoding’ setting to the desired encoding. Set it to ‘unicode’ for unencoded Unicode string output. Here’s one way:

publish_from_doctree(
    ..., settings_overrides={'output_encoding': 'unicode'})

Parameters: document is a docutils.nodes.document object, an existing document tree.

Other parameters: see publish_programmatically.

docutils.core.publish_parts(source, source_path=None, source_class=<class 'docutils.io.StringInput'>, destination_path=None, reader=None, reader_name='standalone', parser=None, parser_name='restructuredtext', writer=None, writer_name='pseudoxml', settings=None, settings_spec=None, settings_overrides=None, config_section=None, enable_exit_status=False)

Set up & run a Publisher, and return a dictionary of document parts. Dictionary keys are the names of parts, and values are Unicode strings; encoding is up to the client. For programmatic use with string I/O.

For encoded string input, be sure to set the ‘input_encoding’ setting to the desired encoding. Set it to ‘unicode’ for unencoded Unicode string input. Here’s how:

publish_parts(..., settings_overrides={'input_encoding': 'unicode'})

Parameters: see publish_programmatically.

docutils.core.publish_programmatically(source_class, source, source_path, destination_class, destination, destination_path, reader, reader_name, parser, parser_name, writer, writer_name, settings, settings_spec, settings_overrides, config_section, enable_exit_status)

Set up & run a Publisher for custom programmatic use. Return the encoded string output and the Publisher object.

Applications should not need to call this function directly. If it does seem to be necessary to call this function directly, please write to the Docutils-develop mailing list <http://docutils.sf.net/docs/user/mailing-lists.html#docutils-develop>.

Parameters:

• source_class required: The class for dynamically created source objects. Typically io.FileInput or io.StringInput.
• source: Type depends on source_class:
  • If source_class is io.FileInput: Either a file-like object (must have ‘read’ and ‘close’ methods), or None (source_path is opened). If neither source nor source_path are supplied, sys.stdin is used.
  • If source_class is io.StringInput required: The input string, either an encoded 8-bit string (set the ‘input_encoding’ setting to the correct encoding) or a Unicode string (set the ‘input_encoding’ setting to ‘unicode’).
• source_path: Type depends on source_class:
  • io.FileInput: Path to the input file, opened if no source supplied.
  • io.StringInput: Optional. Path to the file or object that produced source. Only used for diagnostic output.
• destination_class required: The class for dynamically created destination objects. Typically io.FileOutput or io.StringOutput.
• destination: Type depends on destination_class:
  • io.FileOutput: Either a file-like object (must have ‘write’ and ‘close’ methods), or None (destination_path is opened). If neither destination nor destination_path are supplied, sys.stdout is used.
  • io.StringOutput: Not used; pass None.
• destination_path: Type depends on destination_class:
  • io.FileOutput: Path to the output file. Opened if no destination supplied.
  • io.StringOutput: Path to the file or object which will receive the output; optional. Used for determining relative paths (stylesheets, source links, etc.).
• reader: A docutils.readers.Reader object.
• reader_name: Name or alias of the Reader class to be instantiated if no reader supplied.
• parser: A docutils.parsers.Parser object.
• parser_name: Name or alias of the Parser class to be instantiated if no parser supplied.
• writer: A docutils.writers.Writer object.
• writer_name: Name or alias of the Writer class to be instantiated if no writer supplied.
• settings: A runtime settings (docutils.frontend.Values) object, for dotted-attribute access to runtime settings. It’s the end result of the SettingsSpec, config file, and option processing. If settings is passed, it’s assumed to be complete and no further setting/config/option processing is done.
• settings_spec: A docutils.SettingsSpec subclass or object. Provides extra application-specific settings definitions independently of components. In other words, the application becomes a component, and its settings data is processed along with that of the other components. Used only if no settings specified.
• settings_overrides: A dictionary containing application-specific settings defaults that override the defaults of other components. Used only if no settings specified.
• config_section: A string, the name of the configuration file section for this application. Overrides the config_section attribute defined by settings_spec. Used only if no settings specified.
• enable_exit_status: Boolean; enable exit status at end of processing?

docutils.core.publish_string(source, source_path=None, destination_path=None, reader=None, reader_name='standalone', parser=None, parser_name='restructuredtext', writer=None, writer_name='pseudoxml', settings=None, settings_spec=None, settings_overrides=None, config_section=None, enable_exit_status=False)

Set up & run a Publisher for programmatic use with string I/O. Return the encoded string or Unicode string output.

For encoded string output, be sure to set the ‘output_encoding’ setting to the desired encoding. Set it to ‘unicode’ for unencoded Unicode string output. Here’s one way:

publish_string(..., settings_overrides={'output_encoding': 'unicode'})

Similarly for Unicode string input (source):

publish_string(..., settings_overrides={'input_encoding': 'unicode'})

Parameters: see publish_programmatically.