719 lines
25 KiB
Python
719 lines
25 KiB
Python
# $Id: io.py 10146 2025-05-27 06:14:22Z milde $
|
||
# Author: David Goodger <goodger@python.org>
|
||
# Copyright: This module has been placed in the public domain.
|
||
|
||
"""
|
||
I/O classes provide a uniform API for low-level input and output. Subclasses
|
||
exist for a variety of input/output mechanisms.
|
||
"""
|
||
|
||
from __future__ import annotations
|
||
|
||
__docformat__ = 'reStructuredText'
|
||
|
||
import codecs
|
||
import locale
|
||
import os
|
||
import re
|
||
import sys
|
||
import warnings
|
||
|
||
from docutils import TransformSpec
|
||
|
||
TYPE_CHECKING = False
|
||
if TYPE_CHECKING:
|
||
from typing import Any, BinaryIO, ClassVar, Final, Literal, TextIO
|
||
|
||
from docutils import nodes
|
||
from docutils.nodes import StrPath
|
||
|
||
# Guess the locale's preferred encoding.
|
||
# If no valid guess can be made, _locale_encoding is set to `None`:
|
||
#
|
||
# TODO: check whether this is set correctly with every OS and Python version
|
||
# or whether front-end tools need to call `locale.setlocale()`
|
||
# before importing this module
|
||
try:
|
||
# Return locale encoding also in UTF-8 mode
|
||
with warnings.catch_warnings():
|
||
warnings.simplefilter("ignore")
|
||
_locale_encoding: str | None = (locale.getlocale()[1]
|
||
or locale.getdefaultlocale()[1]
|
||
).lower()
|
||
except: # NoQA: E722 (catchall)
|
||
# Any problem determining the locale: use None
|
||
_locale_encoding = None
|
||
try:
|
||
codecs.lookup(_locale_encoding)
|
||
except (LookupError, TypeError):
|
||
_locale_encoding = None
|
||
|
||
|
||
class InputError(OSError): pass
|
||
class OutputError(OSError): pass
|
||
|
||
|
||
def check_encoding(stream: TextIO, encoding: str) -> bool | None:
|
||
"""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.
|
||
"""
|
||
try:
|
||
return codecs.lookup(stream.encoding) == codecs.lookup(encoding)
|
||
except (LookupError, AttributeError, TypeError):
|
||
return None
|
||
|
||
|
||
def error_string(err: BaseException) -> str:
|
||
"""Return string representation of Exception `err`.
|
||
"""
|
||
return f'{err.__class__.__name__}: {err}'
|
||
|
||
|
||
class Input(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" to
|
||
the "Transformer". (Since Docutils 0.19, input objects are no longer
|
||
required to be `TransformSpec` instances.)
|
||
"""
|
||
|
||
component_type: Final = 'input'
|
||
|
||
default_source_path: ClassVar[str | None] = None
|
||
|
||
def __init__(
|
||
self,
|
||
source: str | TextIO | nodes.document | None = None,
|
||
source_path: StrPath | None = None,
|
||
encoding: str | Literal['unicode'] | None = 'utf-8',
|
||
error_handler: str | None = 'strict',
|
||
) -> None:
|
||
self.encoding = encoding
|
||
"""Text encoding for the input source."""
|
||
|
||
self.error_handler = error_handler
|
||
"""Text decoding error handler."""
|
||
|
||
self.source = source
|
||
"""The source of input data."""
|
||
|
||
self.source_path = source_path
|
||
"""A text reference to the source."""
|
||
|
||
if not source_path:
|
||
self.source_path = self.default_source_path
|
||
|
||
self.successful_encoding = None
|
||
"""The encoding that successfully decoded the source data."""
|
||
|
||
def __repr__(self) -> str:
|
||
return '%s: source=%r, source_path=%r' % (self.__class__, self.source,
|
||
self.source_path)
|
||
|
||
def read(self) -> str:
|
||
"""Return input as `str`. Define in subclasses."""
|
||
raise NotImplementedError
|
||
|
||
def decode(self, data: str | bytes) -> str:
|
||
"""
|
||
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 and the locale's preferred encoding.
|
||
The client application should call ``locale.setlocale()`` at the
|
||
beginning of processing::
|
||
|
||
locale.setlocale(locale.LC_ALL, '')
|
||
|
||
Raise UnicodeError if unsuccessful.
|
||
|
||
Provisional: encoding detection will be removed in Docutils 1.0.
|
||
"""
|
||
if self.encoding and self.encoding.lower() == 'unicode':
|
||
assert isinstance(data, str), ('input encoding is "unicode" '
|
||
'but `data` is no `str` instance')
|
||
if isinstance(data, str):
|
||
# nothing to decode
|
||
return data
|
||
if self.encoding:
|
||
# We believe the user/application when the encoding is
|
||
# explicitly given.
|
||
encoding_candidates = [self.encoding]
|
||
else:
|
||
with warnings.catch_warnings():
|
||
warnings.filterwarnings('ignore', category=DeprecationWarning)
|
||
data_encoding = self.determine_encoding_from_data(data)
|
||
if data_encoding:
|
||
# `data` declares its encoding with "magic comment" or BOM,
|
||
encoding_candidates = [data_encoding]
|
||
else:
|
||
# Apply heuristics if the encoding is not specified.
|
||
# Start with UTF-8, because that only matches
|
||
# data that *IS* UTF-8:
|
||
encoding_candidates = ['utf-8']
|
||
# If UTF-8 fails, fall back to the locale's preferred encoding:
|
||
if sys.version_info[:2] >= (3, 11):
|
||
fallback = locale.getencoding()
|
||
else:
|
||
fallback = locale.getpreferredencoding(do_setlocale=False)
|
||
if fallback and fallback.lower() != 'utf-8':
|
||
encoding_candidates.append(fallback)
|
||
if not self.encoding and encoding_candidates[0] != 'utf-8':
|
||
warnings.warn('Input encoding auto-detection will be removed and '
|
||
'the encoding values None and "" become invalid '
|
||
'in Docutils 1.0.', DeprecationWarning, stacklevel=2)
|
||
for enc in encoding_candidates:
|
||
try:
|
||
decoded = str(data, enc, self.error_handler)
|
||
self.successful_encoding = enc
|
||
return decoded
|
||
except (UnicodeError, LookupError) as err:
|
||
# keep exception instance for use outside of the "for" loop.
|
||
error = err
|
||
raise UnicodeError(
|
||
'Unable to decode input data. Tried the following encodings: '
|
||
f'{", ".join(repr(enc) for enc in encoding_candidates)}.\n'
|
||
f'({error_string(error)})')
|
||
|
||
coding_slug: ClassVar[re.Pattern[bytes]] = re.compile(
|
||
br'coding[:=]\s*([-\w.]+)'
|
||
)
|
||
"""Encoding declaration pattern."""
|
||
|
||
byte_order_marks: ClassVar[tuple[tuple[bytes, str], ...]] = (
|
||
(codecs.BOM_UTF32_BE, 'utf-32'),
|
||
(codecs.BOM_UTF32_LE, 'utf-32'),
|
||
(codecs.BOM_UTF8, 'utf-8-sig'),
|
||
(codecs.BOM_UTF16_BE, 'utf-16'),
|
||
(codecs.BOM_UTF16_LE, 'utf-16'),
|
||
)
|
||
"""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.
|
||
|
||
Internal. Will be removed in Docutils 1.0.
|
||
"""
|
||
|
||
def determine_encoding_from_data(self, data: bytes) -> str | None:
|
||
"""
|
||
Try to determine the encoding of `data` by looking *in* `data`.
|
||
Check for a byte order mark (BOM) or an encoding declaration.
|
||
|
||
Deprecated. Will be removed in Docutils 1.0.
|
||
"""
|
||
warnings.warn('docutils.io.Input.determine_encoding_from_data() '
|
||
'will be removed in Docutils 1.0.',
|
||
DeprecationWarning, stacklevel=2)
|
||
# check for a byte order mark:
|
||
for start_bytes, encoding in self.byte_order_marks:
|
||
if data.startswith(start_bytes):
|
||
return encoding
|
||
# check for an encoding declaration pattern in first 2 lines of file:
|
||
for line in data.splitlines()[:2]:
|
||
match = self.coding_slug.search(line)
|
||
if match:
|
||
return match.group(1).decode('ascii')
|
||
return None
|
||
|
||
def isatty(self) -> bool:
|
||
"""Return True, if the input source is connected to a TTY device."""
|
||
try:
|
||
return self.source.isatty()
|
||
except AttributeError:
|
||
return False
|
||
|
||
|
||
class Output(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" to
|
||
the "Transformer". (Since Docutils 0.19, output objects are no longer
|
||
required to be `TransformSpec` instances.)
|
||
"""
|
||
|
||
component_type: Final = 'output'
|
||
|
||
default_destination_path: ClassVar[str | None] = None
|
||
|
||
def __init__(
|
||
self,
|
||
destination: TextIO | str | bytes | None = None,
|
||
destination_path: StrPath | None = None,
|
||
encoding: str | None = None,
|
||
error_handler: str | None = 'strict',
|
||
) -> None:
|
||
self.encoding: str | None = encoding
|
||
"""Text encoding for the output destination."""
|
||
|
||
self.error_handler: str = error_handler or 'strict'
|
||
"""Text encoding error handler."""
|
||
|
||
self.destination: TextIO | str | bytes | None = destination
|
||
"""The destination for output data."""
|
||
|
||
self.destination_path: StrPath | None = destination_path
|
||
"""A text reference to the destination."""
|
||
|
||
if not destination_path:
|
||
self.destination_path = self.default_destination_path
|
||
|
||
def __repr__(self) -> str:
|
||
return ('%s: destination=%r, destination_path=%r'
|
||
% (self.__class__, self.destination, self.destination_path))
|
||
|
||
def write(self, data: str | bytes) -> str | bytes | None:
|
||
"""Write `data`. Define in subclasses."""
|
||
raise NotImplementedError
|
||
|
||
def encode(self, data: str | bytes) -> str | bytes:
|
||
"""
|
||
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.
|
||
"""
|
||
if self.encoding and self.encoding.lower() == 'unicode':
|
||
assert isinstance(data, str), ('output encoding is "unicode" '
|
||
'but `data` is no `str` instance')
|
||
return data
|
||
if not isinstance(data, str):
|
||
# Non-unicode (e.g. bytes) output.
|
||
return data
|
||
else:
|
||
return data.encode(self.encoding, self.error_handler)
|
||
|
||
|
||
class ErrorOutput:
|
||
"""
|
||
Wrapper class for file-like error streams with
|
||
failsafe de- and encoding of `str`, `bytes`, and `Exception` instances.
|
||
"""
|
||
|
||
def __init__(
|
||
self,
|
||
destination: TextIO | BinaryIO | str | Literal[False] | None = None,
|
||
encoding: str | None = None,
|
||
encoding_errors: str = 'backslashreplace',
|
||
decoding_errors: str = 'replace',
|
||
) -> None:
|
||
"""
|
||
: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.
|
||
"""
|
||
if destination is None:
|
||
destination = sys.stderr
|
||
elif not destination:
|
||
destination = False
|
||
# if `destination` is a file name, open it
|
||
elif isinstance(destination, str):
|
||
destination = open(destination, 'w')
|
||
|
||
self.destination: TextIO | BinaryIO | Literal[False] = destination
|
||
"""Where warning output is sent."""
|
||
|
||
self.encoding: str = (
|
||
encoding
|
||
or getattr(destination, 'encoding', None)
|
||
or _locale_encoding
|
||
or 'ascii'
|
||
)
|
||
"""The output character encoding."""
|
||
|
||
self.encoding_errors: str = encoding_errors
|
||
"""Encoding error handler."""
|
||
|
||
self.decoding_errors: str = decoding_errors
|
||
"""Decoding error handler."""
|
||
|
||
def write(self, data: str | bytes | Exception) -> None:
|
||
"""
|
||
Write `data` to self.destination. Ignore, if self.destination is False.
|
||
|
||
`data` can be a `bytes`, `str`, or `Exception` instance.
|
||
"""
|
||
if not self.destination:
|
||
return
|
||
if isinstance(data, Exception):
|
||
data = str(data)
|
||
# The destination is either opened in text or binary mode.
|
||
# If data has the wrong type, try to convert it.
|
||
try:
|
||
self.destination.write(data)
|
||
except UnicodeEncodeError:
|
||
# Encoding data from string to bytes failed with the
|
||
# destination's encoding and error handler.
|
||
# Try again with our own encoding and error handler.
|
||
binary = data.encode(self.encoding, self.encoding_errors)
|
||
self.destination.write(binary)
|
||
except TypeError:
|
||
if isinstance(data, str): # destination may expect bytes
|
||
binary = data.encode(self.encoding, self.encoding_errors)
|
||
self.destination.write(binary)
|
||
elif self.destination in (sys.stderr, sys.stdout):
|
||
# write bytes to raw stream
|
||
self.destination.buffer.write(data)
|
||
else:
|
||
# destination in text mode, write str
|
||
string = data.decode(self.encoding, self.decoding_errors)
|
||
self.destination.write(string)
|
||
|
||
def close(self) -> None:
|
||
"""
|
||
Close the error-output stream.
|
||
|
||
Ignored if the destination is` sys.stderr` or `sys.stdout` or has no
|
||
close() method.
|
||
"""
|
||
if self.destination in (sys.stdout, sys.stderr):
|
||
return
|
||
try:
|
||
self.destination.close()
|
||
except AttributeError:
|
||
pass
|
||
|
||
def isatty(self) -> bool:
|
||
"""Return True, if the destination is connected to a TTY device."""
|
||
try:
|
||
return self.destination.isatty()
|
||
except AttributeError:
|
||
return False
|
||
|
||
|
||
class FileInput(Input):
|
||
|
||
"""
|
||
Input for single, simple file-like objects.
|
||
"""
|
||
def __init__(
|
||
self,
|
||
source: TextIO | None = None,
|
||
source_path: StrPath | None = None,
|
||
encoding: str | Literal['unicode'] | None = 'utf-8',
|
||
error_handler: str | None = 'strict',
|
||
autoclose: bool = True,
|
||
mode: Literal['r', 'rb', 'br'] = 'r'
|
||
) -> None:
|
||
"""
|
||
: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 for reading.
|
||
- `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').
|
||
"""
|
||
super().__init__(source, source_path, encoding, error_handler)
|
||
self.autoclose = autoclose
|
||
self._stderr = ErrorOutput()
|
||
|
||
if source is None:
|
||
if source_path:
|
||
try:
|
||
self.source = open(source_path, mode,
|
||
encoding=self.encoding,
|
||
errors=self.error_handler)
|
||
except OSError as error:
|
||
raise InputError(error.errno, error.strerror, source_path)
|
||
else:
|
||
self.source = sys.stdin
|
||
elif check_encoding(self.source, self.encoding) is False:
|
||
# TODO: re-open, warn or raise error?
|
||
raise UnicodeError('Encoding clash: encoding given is "%s" '
|
||
'but source is opened with encoding "%s".' %
|
||
(self.encoding, self.source.encoding))
|
||
if not source_path:
|
||
try:
|
||
self.source_path = self.source.name
|
||
except AttributeError:
|
||
pass
|
||
|
||
def read(self) -> str:
|
||
"""
|
||
Read and decode a single file, return as `str`.
|
||
"""
|
||
try:
|
||
if not self.encoding and hasattr(self.source, 'buffer'):
|
||
# read as binary data
|
||
data = self.source.buffer.read()
|
||
# decode with heuristics
|
||
data = self.decode(data)
|
||
# normalize newlines
|
||
data = '\n'.join(data.splitlines()+[''])
|
||
else:
|
||
data = self.source.read()
|
||
finally:
|
||
if self.autoclose:
|
||
self.close()
|
||
return data
|
||
|
||
def readlines(self) -> list[str]:
|
||
"""
|
||
Return lines of a single file as list of strings.
|
||
"""
|
||
return self.read().splitlines(True)
|
||
|
||
def close(self) -> None:
|
||
if self.source is not sys.stdin:
|
||
self.source.close()
|
||
|
||
|
||
class FileOutput(Output):
|
||
|
||
"""Output for single, simple file-like objects."""
|
||
|
||
default_destination_path: Final = '<file>'
|
||
|
||
mode: Literal['w', 'a', 'x', 'wb', 'ab', 'xb', 'bw', 'ba', 'bx'] = 'w'
|
||
"""The mode argument for `open()`."""
|
||
# 'wb' for binary (e.g. OpenOffice) files (see also `BinaryFileOutput`).
|
||
# (Do not use binary mode ('wb') for text files, as this prevents the
|
||
# conversion of newlines to the system specific default.)
|
||
|
||
def __init__(self,
|
||
destination: TextIO | None = None,
|
||
destination_path: StrPath | None = None,
|
||
encoding: str | None = None,
|
||
error_handler: str | None = 'strict',
|
||
autoclose: bool = True,
|
||
handle_io_errors: None = None,
|
||
mode=None,
|
||
) -> 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.
|
||
"""
|
||
super().__init__(
|
||
destination, destination_path, encoding, error_handler)
|
||
self.opened = True
|
||
self.autoclose = autoclose
|
||
if handle_io_errors is not None:
|
||
warnings.warn('io.FileOutput: init argument "handle_io_errors" '
|
||
'is ignored and will be removed in '
|
||
'Docutils 2.0.', DeprecationWarning, stacklevel=2)
|
||
if mode is not None:
|
||
self.mode = mode
|
||
self._stderr = ErrorOutput()
|
||
if destination is None:
|
||
if destination_path:
|
||
self.opened = False
|
||
else:
|
||
self.destination = sys.stdout
|
||
elif ( # destination is file-type object -> check mode:
|
||
mode and hasattr(self.destination, 'mode')
|
||
and mode != self.destination.mode):
|
||
print('Warning: Destination mode "%s" differs from specified '
|
||
'mode "%s"' % (self.destination.mode, mode),
|
||
file=self._stderr)
|
||
if not destination_path:
|
||
try:
|
||
self.destination_path = self.destination.name
|
||
except AttributeError:
|
||
pass
|
||
|
||
def open(self) -> None:
|
||
# Specify encoding
|
||
if 'b' not in self.mode:
|
||
kwargs = {'encoding': self.encoding,
|
||
'errors': self.error_handler}
|
||
else:
|
||
kwargs = {}
|
||
try:
|
||
self.destination = open(self.destination_path, self.mode, **kwargs)
|
||
except OSError as error:
|
||
raise OutputError(error.errno, error.strerror,
|
||
self.destination_path)
|
||
self.opened = True
|
||
|
||
def write(self, data: str | bytes) -> str | bytes:
|
||
"""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.
|
||
"""
|
||
if not self.opened:
|
||
self.open()
|
||
if (isinstance(data, str)
|
||
and check_encoding(self.destination, self.encoding) is False):
|
||
if os.linesep != '\n':
|
||
data = data.replace('\n', os.linesep) # fix endings
|
||
data = self.encode(data)
|
||
|
||
try:
|
||
self.destination.write(data)
|
||
except TypeError as err:
|
||
if isinstance(data, bytes):
|
||
try:
|
||
self.destination.buffer.write(data)
|
||
except AttributeError:
|
||
if check_encoding(self.destination,
|
||
self.encoding) is False:
|
||
raise ValueError(
|
||
f'Encoding of {self.destination_path} '
|
||
f'({self.destination.encoding}) differs \n'
|
||
f' from specified encoding ({self.encoding})')
|
||
else:
|
||
raise err
|
||
except (UnicodeError, LookupError) as err:
|
||
raise UnicodeError(
|
||
'Unable to encode output data. output-encoding is: '
|
||
f'{self.encoding}.\n({error_string(err)})')
|
||
finally:
|
||
if self.autoclose:
|
||
self.close()
|
||
return data
|
||
|
||
def close(self) -> None:
|
||
if self.destination not in (sys.stdout, sys.stderr):
|
||
self.destination.close()
|
||
self.opened = False
|
||
|
||
|
||
class BinaryFileOutput(FileOutput):
|
||
"""
|
||
A version of docutils.io.FileOutput which writes to a binary file.
|
||
|
||
Deprecated. Use `FileOutput` (works with `bytes` since Docutils 0.20).
|
||
Will be removed in Docutils 0.24.
|
||
"""
|
||
# Used by core.publish_cmdline_to_binary() which is also deprecated.
|
||
mode = 'wb'
|
||
|
||
def __init__(self, *args: Any, **kwargs: Any) -> None:
|
||
warnings.warn('"BinaryFileOutput" is obsoleted by "FileOutput"'
|
||
' and will be removed in Docutils 0.24.',
|
||
DeprecationWarning, stacklevel=2)
|
||
super().__init__(*args, **kwargs)
|
||
|
||
|
||
class StringInput(Input):
|
||
"""Input from a `str` or `bytes` instance."""
|
||
|
||
source: str | bytes
|
||
|
||
default_source_path: Final = '<string>'
|
||
|
||
def read(self) -> str:
|
||
"""Return the source as `str` instance.
|
||
|
||
Decode, if required (see `Input.decode`).
|
||
"""
|
||
return self.decode(self.source)
|
||
|
||
|
||
class StringOutput(Output):
|
||
"""Output to a `bytes` or `str` instance.
|
||
|
||
Provisional.
|
||
"""
|
||
|
||
destination: str | bytes
|
||
|
||
default_destination_path: Final = '<string>'
|
||
|
||
def write(self, data: str | bytes) -> str | bytes:
|
||
"""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).
|
||
"""
|
||
self.destination = self.encode(data)
|
||
return self.destination
|
||
|
||
|
||
class NullInput(Input):
|
||
|
||
"""Degenerate input: read nothing."""
|
||
|
||
source: None
|
||
|
||
default_source_path: Final = 'null input'
|
||
|
||
def read(self) -> str:
|
||
"""Return an empty string."""
|
||
return ''
|
||
|
||
|
||
class NullOutput(Output):
|
||
|
||
"""Degenerate output: write nothing."""
|
||
|
||
destination: None
|
||
|
||
default_destination_path: Final = 'null output'
|
||
|
||
def write(self, data: str | bytes) -> None:
|
||
"""Do nothing, return None."""
|
||
|
||
|
||
class DocTreeInput(Input):
|
||
|
||
"""
|
||
Adapter for document tree input.
|
||
|
||
The document tree must be passed in the ``source`` parameter.
|
||
"""
|
||
|
||
source: nodes.document
|
||
|
||
default_source_path: Final = 'doctree input'
|
||
|
||
def read(self) -> nodes.document:
|
||
"""Return the document tree."""
|
||
return self.source
|