.config/coc/extensions/node_modules/coc-pyright/node_modules/pyright/dist/typeshed-fallback/stdlib/codecs.pyi

   1 import sys
   2 import types
   3 from _typeshed import Self
   4 from abc import abstractmethod
   5 from typing import IO, Any, BinaryIO, Callable, Generator, Iterable, Iterator, Protocol, TextIO, Tuple, Type, TypeVar, overload
   6 from typing_extensions import Literal
   7
   8 # TODO: this only satisfies the most common interface, where
   9 # bytes is the raw form and str is the cooked form.
  10 # In the long run, both should become template parameters maybe?
  11 # There *are* bytes->bytes and str->str encodings in the standard library.
  12 # They are much more common in Python 2 than in Python 3.
  13
  14 class _Encoder(Protocol):
  15     def __call__(self, input: str, errors: str = ...) -> tuple[bytes, int]: ...  # signature of Codec().encode
  16
  17 class _Decoder(Protocol):
  18     def __call__(self, input: bytes, errors: str = ...) -> tuple[str, int]: ...  # signature of Codec().decode
  19
  20 class _StreamReader(Protocol):
  21     def __call__(self, stream: IO[bytes], errors: str = ...) -> StreamReader: ...
  22
  23 class _StreamWriter(Protocol):
  24     def __call__(self, stream: IO[bytes], errors: str = ...) -> StreamWriter: ...
  25
  26 class _IncrementalEncoder(Protocol):
  27     def __call__(self, errors: str = ...) -> IncrementalEncoder: ...
  28
  29 class _IncrementalDecoder(Protocol):
  30     def __call__(self, errors: str = ...) -> IncrementalDecoder: ...
  31
  32 # The type ignore on `encode` and `decode` is to avoid issues with overlapping overloads, for more details, see #300
  33 # mypy and pytype disagree about where the type ignore can and cannot go, so alias the long type
  34 _BytesToBytesEncodingT = Literal[
  35     "base64",
  36     "base_64",
  37     "base64_codec",
  38     "bz2",
  39     "bz2_codec",
  40     "hex",
  41     "hex_codec",
  42     "quopri",
  43     "quotedprintable",
  44     "quoted_printable",
  45     "quopri_codec",
  46     "uu",
  47     "uu_codec",
  48     "zip",
  49     "zlib",
  50     "zlib_codec",
  51 ]
  52
  53 @overload
  54 def encode(obj: bytes, encoding: _BytesToBytesEncodingT, errors: str = ...) -> bytes: ...
  55 @overload
  56 def encode(obj: str, encoding: Literal["rot13", "rot_13"] = ..., errors: str = ...) -> str: ...  # type: ignore
  57 @overload
  58 def encode(obj: str, encoding: str = ..., errors: str = ...) -> bytes: ...
  59 @overload
  60 def decode(obj: bytes, encoding: _BytesToBytesEncodingT, errors: str = ...) -> bytes: ...  # type: ignore
  61 @overload
  62 def decode(obj: str, encoding: Literal["rot13", "rot_13"] = ..., errors: str = ...) -> str: ...
  63 @overload
  64 def decode(obj: bytes, encoding: str = ..., errors: str = ...) -> str: ...
  65 def lookup(__encoding: str) -> CodecInfo: ...
  66 def utf_16_be_decode(__data: bytes, __errors: str | None = ..., __final: bool = ...) -> tuple[str, int]: ...  # undocumented
  67 def utf_16_be_encode(__str: str, __errors: str | None = ...) -> tuple[bytes, int]: ...  # undocumented
  68
  69 class CodecInfo(Tuple[_Encoder, _Decoder, _StreamReader, _StreamWriter]):
  70     @property
  71     def encode(self) -> _Encoder: ...
  72     @property
  73     def decode(self) -> _Decoder: ...
  74     @property
  75     def streamreader(self) -> _StreamReader: ...
  76     @property
  77     def streamwriter(self) -> _StreamWriter: ...
  78     @property
  79     def incrementalencoder(self) -> _IncrementalEncoder: ...
  80     @property
  81     def incrementaldecoder(self) -> _IncrementalDecoder: ...
  82     name: str
  83     def __new__(
  84         cls,
  85         encode: _Encoder,
  86         decode: _Decoder,
  87         streamreader: _StreamReader | None = ...,
  88         streamwriter: _StreamWriter | None = ...,
  89         incrementalencoder: _IncrementalEncoder | None = ...,
  90         incrementaldecoder: _IncrementalDecoder | None = ...,
  91         name: str | None = ...,
  92         *,
  93         _is_text_encoding: bool | None = ...,
  94     ) -> CodecInfo: ...
  95
  96 def getencoder(encoding: str) -> _Encoder: ...
  97 def getdecoder(encoding: str) -> _Decoder: ...
  98 def getincrementalencoder(encoding: str) -> _IncrementalEncoder: ...
  99 def getincrementaldecoder(encoding: str) -> _IncrementalDecoder: ...
 100 def getreader(encoding: str) -> _StreamReader: ...
 101 def getwriter(encoding: str) -> _StreamWriter: ...
 102 def register(__search_function: Callable[[str], CodecInfo | None]) -> None: ...
 103 def open(
 104     filename: str, mode: str = ..., encoding: str | None = ..., errors: str = ..., buffering: int = ...
 105 ) -> StreamReaderWriter: ...
 106 def EncodedFile(file: IO[bytes], data_encoding: str, file_encoding: str | None = ..., errors: str = ...) -> StreamRecoder: ...
 107 def iterencode(iterator: Iterable[str], encoding: str, errors: str = ...) -> Generator[bytes, None, None]: ...
 108 def iterdecode(iterator: Iterable[bytes], encoding: str, errors: str = ...) -> Generator[str, None, None]: ...
 109
 110 if sys.version_info >= (3, 10):
 111     def unregister(__search_function: Callable[[str], CodecInfo | None]) -> None: ...
 112
 113 BOM: bytes
 114 BOM_BE: bytes
 115 BOM_LE: bytes
 116 BOM_UTF8: bytes
 117 BOM_UTF16: bytes
 118 BOM_UTF16_BE: bytes
 119 BOM_UTF16_LE: bytes
 120 BOM_UTF32: bytes
 121 BOM_UTF32_BE: bytes
 122 BOM_UTF32_LE: bytes
 123
 124 # It is expected that different actions be taken depending on which of the
 125 # three subclasses of `UnicodeError` is actually ...ed. However, the Union
 126 # is still needed for at least one of the cases.
 127 def register_error(__errors: str, __handler: Callable[[UnicodeError], tuple[str | bytes, int]]) -> None: ...
 128 def lookup_error(__name: str) -> Callable[[UnicodeError], tuple[str | bytes, int]]: ...
 129 def strict_errors(exception: UnicodeError) -> tuple[str | bytes, int]: ...
 130 def replace_errors(exception: UnicodeError) -> tuple[str | bytes, int]: ...
 131 def ignore_errors(exception: UnicodeError) -> tuple[str | bytes, int]: ...
 132 def xmlcharrefreplace_errors(exception: UnicodeError) -> tuple[str | bytes, int]: ...
 133 def backslashreplace_errors(exception: UnicodeError) -> tuple[str | bytes, int]: ...
 134
 135 class Codec:
 136     # These are sort of @abstractmethod but sort of not.
 137     # The StreamReader and StreamWriter subclasses only implement one.
 138     def encode(self, input: str, errors: str = ...) -> tuple[bytes, int]: ...
 139     def decode(self, input: bytes, errors: str = ...) -> tuple[str, int]: ...
 140
 141 class IncrementalEncoder:
 142     errors: str
 143     def __init__(self, errors: str = ...) -> None: ...
 144     @abstractmethod
 145     def encode(self, input: str, final: bool = ...) -> bytes: ...
 146     def reset(self) -> None: ...
 147     # documentation says int but str is needed for the subclass.
 148     def getstate(self) -> int | str: ...
 149     def setstate(self, state: int | str) -> None: ...
 150
 151 class IncrementalDecoder:
 152     errors: str
 153     def __init__(self, errors: str = ...) -> None: ...
 154     @abstractmethod
 155     def decode(self, input: bytes, final: bool = ...) -> str: ...
 156     def reset(self) -> None: ...
 157     def getstate(self) -> tuple[bytes, int]: ...
 158     def setstate(self, state: tuple[bytes, int]) -> None: ...
 159
 160 # These are not documented but used in encodings/*.py implementations.
 161 class BufferedIncrementalEncoder(IncrementalEncoder):
 162     buffer: str
 163     def __init__(self, errors: str = ...) -> None: ...
 164     @abstractmethod
 165     def _buffer_encode(self, input: str, errors: str, final: bool) -> bytes: ...
 166     def encode(self, input: str, final: bool = ...) -> bytes: ...
 167
 168 class BufferedIncrementalDecoder(IncrementalDecoder):
 169     buffer: bytes
 170     def __init__(self, errors: str = ...) -> None: ...
 171     @abstractmethod
 172     def _buffer_decode(self, input: bytes, errors: str, final: bool) -> tuple[str, int]: ...
 173     def decode(self, input: bytes, final: bool = ...) -> str: ...
 174
 175 # TODO: it is not possible to specify the requirement that all other
 176 # attributes and methods are passed-through from the stream.
 177 class StreamWriter(Codec):
 178     errors: str
 179     def __init__(self, stream: IO[bytes], errors: str = ...) -> None: ...
 180     def write(self, object: str) -> None: ...
 181     def writelines(self, list: Iterable[str]) -> None: ...
 182     def reset(self) -> None: ...
 183     def __enter__(self: Self) -> Self: ...
 184     def __exit__(self, typ: Type[BaseException] | None, exc: BaseException | None, tb: types.TracebackType | None) -> None: ...
 185     def __getattr__(self, name: str, getattr: Callable[[str], Any] = ...) -> Any: ...
 186
 187 class StreamReader(Codec):
 188     errors: str
 189     def __init__(self, stream: IO[bytes], errors: str = ...) -> None: ...
 190     def read(self, size: int = ..., chars: int = ..., firstline: bool = ...) -> str: ...
 191     def readline(self, size: int | None = ..., keepends: bool = ...) -> str: ...
 192     def readlines(self, sizehint: int | None = ..., keepends: bool = ...) -> list[str]: ...
 193     def reset(self) -> None: ...
 194     def __enter__(self: Self) -> Self: ...
 195     def __exit__(self, typ: Type[BaseException] | None, exc: BaseException | None, tb: types.TracebackType | None) -> None: ...
 196     def __iter__(self) -> Iterator[str]: ...
 197     def __getattr__(self, name: str, getattr: Callable[[str], Any] = ...) -> Any: ...
 198
 199 _T = TypeVar("_T", bound=StreamReaderWriter)
 200
 201 # Doesn't actually inherit from TextIO, but wraps a BinaryIO to provide text reading and writing
 202 # and delegates attributes to the underlying binary stream with __getattr__.
 203 class StreamReaderWriter(TextIO):
 204     def __init__(self, stream: IO[bytes], Reader: _StreamReader, Writer: _StreamWriter, errors: str = ...) -> None: ...
 205     def read(self, size: int = ...) -> str: ...
 206     def readline(self, size: int | None = ...) -> str: ...
 207     def readlines(self, sizehint: int | None = ...) -> list[str]: ...
 208     def __next__(self) -> str: ...
 209     def __iter__(self: _T) -> _T: ...
 210     # This actually returns None, but that's incompatible with the supertype
 211     def write(self, data: str) -> int: ...
 212     def writelines(self, list: Iterable[str]) -> None: ...
 213     def reset(self) -> None: ...
 214     # Same as write()
 215     def seek(self, offset: int, whence: int = ...) -> int: ...
 216     def __enter__(self: Self) -> Self: ...
 217     def __exit__(self, typ: Type[BaseException] | None, exc: BaseException | None, tb: types.TracebackType | None) -> None: ...
 218     def __getattr__(self, name: str) -> Any: ...
 219     # These methods don't actually exist directly, but they are needed to satisfy the TextIO
 220     # interface. At runtime, they are delegated through __getattr__.
 221     def close(self) -> None: ...
 222     def fileno(self) -> int: ...
 223     def flush(self) -> None: ...
 224     def isatty(self) -> bool: ...
 225     def readable(self) -> bool: ...
 226     def truncate(self, size: int | None = ...) -> int: ...
 227     def seekable(self) -> bool: ...
 228     def tell(self) -> int: ...
 229     def writable(self) -> bool: ...
 230
 231 _SRT = TypeVar("_SRT", bound=StreamRecoder)
 232
 233 class StreamRecoder(BinaryIO):
 234     def __init__(
 235         self,
 236         stream: IO[bytes],
 237         encode: _Encoder,
 238         decode: _Decoder,
 239         Reader: _StreamReader,
 240         Writer: _StreamWriter,
 241         errors: str = ...,
 242     ) -> None: ...
 243     def read(self, size: int = ...) -> bytes: ...
 244     def readline(self, size: int | None = ...) -> bytes: ...
 245     def readlines(self, sizehint: int | None = ...) -> list[bytes]: ...
 246     def __next__(self) -> bytes: ...
 247     def __iter__(self: _SRT) -> _SRT: ...
 248     def write(self, data: bytes) -> int: ...
 249     def writelines(self, list: Iterable[bytes]) -> int: ...  # type: ignore  # it's supposed to return None
 250     def reset(self) -> None: ...
 251     def __getattr__(self, name: str) -> Any: ...
 252     def __enter__(self: Self) -> Self: ...
 253     def __exit__(self, type: Type[BaseException] | None, value: BaseException | None, tb: types.TracebackType | None) -> None: ...
 254     # These methods don't actually exist directly, but they are needed to satisfy the BinaryIO
 255     # interface. At runtime, they are delegated through __getattr__.
 256     def seek(self, offset: int, whence: int = ...) -> int: ...
 257     def close(self) -> None: ...
 258     def fileno(self) -> int: ...
 259     def flush(self) -> None: ...
 260     def isatty(self) -> bool: ...
 261     def readable(self) -> bool: ...
 262     def truncate(self, size: int | None = ...) -> int: ...
 263     def seekable(self) -> bool: ...
 264     def tell(self) -> int: ...
 265     def writable(self) -> bool: ...