docutils.io module

I/O classes provide a uniform API for low-level input and output. Subclasses exist for a variety of input/output mechanisms.

exception InputError

Bases: OSError

exception OutputError

Bases: OSError

check_encoding(stream, encoding)

Test, whether the encoding of stream matches encoding.

Returns

None:

if encoding or stream.encoding are not a valid encoding argument (e.g. None) or `stream.encoding is missing.

True:

if the encoding argument resolves to the same value as encoding,

False:

if the encodings differ.

error_string(err)

Return string representation of Exception err.

class Input(source=None, source_path=None, encoding=None, error_handler='strict')

Bases: TransformSpec

Abstract base class for input wrappers.

Docutils input objects must provide a read() method that returns the source, typically as str instance.

Inheriting TransformSpec allows input objects to add “transforms” and “unknown_reference_resolvers” to the “Transformer”. (Optional for custom input objects since Docutils 0.19.)

component_type = 'input'

default_source_path = None

encoding

Text encoding for the input source.

error_handler

Text decoding error handler.

source

The source of input data.

source_path

A text reference to the source.

successful_encoding

The encoding that successfully decoded the source data.

read()

Return input as str. Define in subclasses.

decode(data)

Decode data if required.

Return Unicode str instances unchanged (nothing to decode).

If self.encoding is None, determine encoding from data or try UTF-8, locale encoding, and (as last ressort) ‘latin-1’. The client application should call locale.setlocale at the beginning of processing:

locale.setlocale(locale.LC_ALL, '')

Raise UnicodeError if unsuccessful.

Provisional:

• Raise UnicodeError (instead of falling back to the locale encoding) if decoding the source with the default encoding (UTF-8) fails and Python is started in UTF-8 mode.

  Raise UnicodeError (instead of falling back to “latin1”) if both, default and locale encoding, fail.

• Only remove BOM (U+FEFF ZWNBSP at start of data), no other ZWNBSPs.

coding_slug = re.compile(b'coding[:=]\\s*([-\\w.]+)')

Encoding declaration pattern.

byte_order_marks = ((b'\xef\xbb\xbf', 'utf-8'), (b'\xfe\xff', 'utf-16-be'), (b'\xff\xfe', 'utf-16-le'))

Sequence of (start_bytes, encoding) tuples for encoding detection. The first bytes of input data are checked against the start_bytes strings. A match indicates the given encoding.

determine_encoding_from_data(data)

Try to determine the encoding of data by looking in data. Check for a byte order mark (BOM) or an encoding declaration.

isatty()

Return True, if the input source is connected to a TTY device.

class Output(destination=None, destination_path=None, encoding=None, error_handler='strict')

Bases: TransformSpec

Abstract base class for output wrappers.

Docutils output objects must provide a write() method that expects and handles one argument (the output).

Inheriting TransformSpec allows output objects to add “transforms” and “unknown_reference_resolvers” to the “Transformer”. (Optional for custom output objects since Docutils 0.19.)

component_type = 'output'

default_destination_path = None

encoding

Text encoding for the output destination.

error_handler

Text encoding error handler.

destination

The destination for output data.

destination_path

A text reference to the destination.

write(data)

Write data. Define in subclasses.

encode(data)

Encode and return data.

If data is a bytes instance, it is returned unchanged. Otherwise it is encoded with self.encoding.

Provisional: If self.encoding is set to the pseudo encoding name “unicode”, data must be a str instance and is returned unchanged.

class ErrorOutput(destination=None, encoding=None, encoding_errors='backslashreplace', decoding_errors='replace')

Bases: object

Wrapper class for file-like error streams with failsafe de- and encoding of str, bytes, unicode and Exception instances.

__init__(destination=None, encoding=None, encoding_errors='backslashreplace', decoding_errors='replace')

Parameters:

• destination: a file-like object,

  a string (path to a file), None (write to sys.stderr, default), or evaluating to False (write() requests are ignored).

• encoding: destination text encoding. Guessed if None.

• encoding_errors: how to treat encoding errors.

destination

Where warning output is sent.

encoding

The output character encoding.

encoding_errors

Encoding error handler.

decoding_errors

Decoding error handler.

write(data)

Write data to self.destination. Ignore, if self.destination is False.

data can be a bytes, str, or Exception instance.

close()

Close the error-output stream.

Ignored if the destination is` sys.stderr` or sys.stdout or has no close() method.

isatty()

Return True, if the destination is connected to a TTY device.

class FileInput(source=None, source_path=None, encoding=None, error_handler='strict', autoclose=True, mode='r')

Bases: Input

Input for single, simple file-like objects.

__init__(source=None, source_path=None, encoding=None, error_handler='strict', autoclose=True, mode='r')

Parameters:

• source: either a file-like object (which is read directly), or None (which implies sys.stdin if no source_path given).

• source_path: a path to a file, which is opened and then read.

• encoding: the expected text encoding of the input file.

• error_handler: the encoding error handler to use.

• autoclose: close automatically after read (except when sys.stdin is the source).

• mode: how the file is to be opened (see standard function open). The default is read only (‘r’).

read()

Read and decode a single file and return the data (Unicode string).

readlines()

Return lines of a single file as list of Unicode strings.

close()

class FileOutput(destination=None, destination_path=None, encoding=None, error_handler='strict', autoclose=True, handle_io_errors=None, mode=None)

Bases: Output

Output for single, simple file-like objects.

default_destination_path = '<file>'

__init__(destination=None, destination_path=None, encoding=None, error_handler='strict', autoclose=True, handle_io_errors=None, mode=None)

Parameters:

• destination: either a file-like object (which is written directly) or None (which implies sys.stdout if no destination_path given).

• destination_path: a path to a file, which is opened and then written.

• encoding: the text encoding of the output file.

• error_handler: the encoding error handler to use.

• autoclose: close automatically after write (except when sys.stdout or sys.stderr is the destination).

• handle_io_errors: ignored, deprecated, will be removed.

• mode: how the file is to be opened (see standard function open). The default is ‘w’, providing universal newline support for text files.

mode = 'w'

The mode argument for open().

open()

write(data)

Write data to a single file, also return it.

data can be a str or bytes instance. If writing bytes fails, an attempt is made to write to the low-level interface self.destination.buffer.

If data is a str instance and self.encoding and self.destination.encoding are set to different values, data is encoded to a bytes instance using self.encoding.

Provisional: future versions may raise an error if self.encoding and self.destination.encoding are set to different values.

close()

class BinaryFileOutput(destination=None, destination_path=None, encoding=None, error_handler='strict', autoclose=True, handle_io_errors=None, mode=None)

Bases: FileOutput

A version of docutils.io.FileOutput which writes to a binary file.

mode = 'wb'

The mode argument for open().

class StringInput(source=None, source_path=None, encoding=None, error_handler='strict')

Bases: Input

Input from a str or bytes instance.

default_source_path = '<string>'

read()

Return the source as str instance.

Decode, if required (see Input.decode).

class StringOutput(destination=None, destination_path=None, encoding=None, error_handler='strict')

Bases: Output

Output to a bytes or str instance.

Provisional.

default_destination_path = '<string>'

write(data)

Store data in self.destination, and return it.

If self.encoding is set to the pseudo encoding name “unicode”, data must be a str instance and is stored/returned unchanged (cf. Output.encode).

Otherwise, data can be a bytes or str instance and is stored/returned as a bytes instance (str data is encoded with self.encode()).

Attention: the `output_encoding`_ setting may affect the content of the output (e.g. an encoding declaration in HTML or XML or the representation of characters as LaTeX macro vs. literal character).

class NullInput(source=None, source_path=None, encoding=None, error_handler='strict')

Bases: Input

Degenerate input: read nothing.

default_source_path = 'null input'

read()

Return an empty string.

class NullOutput(destination=None, destination_path=None, encoding=None, error_handler='strict')

Bases: Output

Degenerate output: write nothing.

default_destination_path = 'null output'

write(data)

Do nothing, return None.

class DocTreeInput(source=None, source_path=None, encoding=None, error_handler='strict')

Bases: Input

Adapter for document tree input.

The document tree must be passed in the source parameter.

default_source_path = 'doctree input'

read()

Return the document tree.