android-notify 1.60.0__py3-none-any.whl → 1.60.1__py3-none-any.whl

venv/Lib/site-packages/docutils/io.py

@@ -1,718 +0,0 @@
-# $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