Upload env/portalocker/types.py
Browse files- env/portalocker/types.py +177 -0
env/portalocker/types.py
ADDED
|
@@ -0,0 +1,177 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
# noqa: A005
|
| 2 |
+
"""Shared type aliases and protocols used across portalocker's public API.
|
| 3 |
+
|
| 4 |
+
These are pure typing constructs with no runtime behaviour of their own;
|
| 5 |
+
they exist so the locking functions in `portalocker.portalocker` and
|
| 6 |
+
`portalocker.utils` can share consistent, precise signatures.
|
| 7 |
+
"""
|
| 8 |
+
|
| 9 |
+
from __future__ import annotations
|
| 10 |
+
|
| 11 |
+
import io
|
| 12 |
+
import pathlib
|
| 13 |
+
import typing
|
| 14 |
+
|
| 15 |
+
# spellchecker: off
|
| 16 |
+
# fmt: off
|
| 17 |
+
#: Every text mode string accepted by the built-in `open()`, spelled out
|
| 18 |
+
#: explicitly so type checkers reject a typo'd mode string instead of
|
| 19 |
+
#: letting it fail at runtime. Kept separate from `BinaryMode` so
|
| 20 |
+
#: `portalocker.Lock` can infer ``IO[str]`` filehandles from the mode.
|
| 21 |
+
#: The legacy universal-newline (`U`) modes are deliberately absent:
|
| 22 |
+
#: Python 3.11 removed them, and 3.10 only accepted them with a warning.
|
| 23 |
+
TextMode = typing.Literal[
|
| 24 |
+
# Read text
|
| 25 |
+
'r', 'rt', 'tr',
|
| 26 |
+
# Write text
|
| 27 |
+
'w', 'wt', 'tw',
|
| 28 |
+
# Append text
|
| 29 |
+
'a', 'at', 'ta',
|
| 30 |
+
# Exclusive creation text
|
| 31 |
+
'x', 'xt', 'tx',
|
| 32 |
+
# Read and write text
|
| 33 |
+
'r+', '+r', 'rt+', 'r+t', '+rt', 'tr+', 't+r', '+tr',
|
| 34 |
+
# Write and read text
|
| 35 |
+
'w+', '+w', 'wt+', 'w+t', '+wt', 'tw+', 't+w', '+tw',
|
| 36 |
+
# Append and read text
|
| 37 |
+
'a+', '+a', 'at+', 'a+t', '+at', 'ta+', 't+a', '+ta',
|
| 38 |
+
# Exclusive creation and read text
|
| 39 |
+
'x+', '+x', 'xt+', 'x+t', '+xt', 'tx+', 't+x', '+tx',
|
| 40 |
+
]
|
| 41 |
+
#: Every binary mode string accepted by the built-in `open()`, the
|
| 42 |
+
#: counterpart of `TextMode` that makes `portalocker.Lock` infer
|
| 43 |
+
#: ``IO[bytes]`` filehandles.
|
| 44 |
+
BinaryMode = typing.Literal[
|
| 45 |
+
# Read binary
|
| 46 |
+
'rb', 'br',
|
| 47 |
+
# Write binary
|
| 48 |
+
'wb', 'bw',
|
| 49 |
+
# Append binary
|
| 50 |
+
'ab', 'ba',
|
| 51 |
+
# Exclusive creation binary
|
| 52 |
+
'xb', 'bx',
|
| 53 |
+
# Read and write binary
|
| 54 |
+
'rb+', 'r+b', '+rb', 'br+', 'b+r', '+br',
|
| 55 |
+
# Write and read binary
|
| 56 |
+
'wb+', 'w+b', '+wb', 'bw+', 'b+w', '+bw',
|
| 57 |
+
# Append and read binary
|
| 58 |
+
'ab+', 'a+b', '+ab', 'ba+', 'b+a', '+ba',
|
| 59 |
+
# Exclusive creation and read binary
|
| 60 |
+
'xb+', 'x+b', '+xb', 'bx+', 'b+x', '+bx',
|
| 61 |
+
]
|
| 62 |
+
#: Every mode string accepted by the built-in `open()`, text and binary
|
| 63 |
+
#: combined. Spelled out flat instead of as ``TextMode | BinaryMode`` so
|
| 64 |
+
#: ``typing.get_args(Mode)`` keeps returning the mode strings themselves,
|
| 65 |
+
#: which the common runtime validation idiom
|
| 66 |
+
#: ``mode in typing.get_args(Mode)`` depends on; on a union of Literals
|
| 67 |
+
#: `typing.get_args` returns the two Literal aliases instead of their
|
| 68 |
+
#: members. The test suite pins this literal to be exactly the union of
|
| 69 |
+
#: `TextMode` and `BinaryMode`, statically and at runtime.
|
| 70 |
+
Mode = typing.Literal[
|
| 71 |
+
# Text modes
|
| 72 |
+
# Read text
|
| 73 |
+
'r', 'rt', 'tr',
|
| 74 |
+
# Write text
|
| 75 |
+
'w', 'wt', 'tw',
|
| 76 |
+
# Append text
|
| 77 |
+
'a', 'at', 'ta',
|
| 78 |
+
# Exclusive creation text
|
| 79 |
+
'x', 'xt', 'tx',
|
| 80 |
+
# Read and write text
|
| 81 |
+
'r+', '+r', 'rt+', 'r+t', '+rt', 'tr+', 't+r', '+tr',
|
| 82 |
+
# Write and read text
|
| 83 |
+
'w+', '+w', 'wt+', 'w+t', '+wt', 'tw+', 't+w', '+tw',
|
| 84 |
+
# Append and read text
|
| 85 |
+
'a+', '+a', 'at+', 'a+t', '+at', 'ta+', 't+a', '+ta',
|
| 86 |
+
# Exclusive creation and read text
|
| 87 |
+
'x+', '+x', 'xt+', 'x+t', '+xt', 'tx+', 't+x', '+tx',
|
| 88 |
+
|
| 89 |
+
# Binary modes
|
| 90 |
+
# Read binary
|
| 91 |
+
'rb', 'br',
|
| 92 |
+
# Write binary
|
| 93 |
+
'wb', 'bw',
|
| 94 |
+
# Append binary
|
| 95 |
+
'ab', 'ba',
|
| 96 |
+
# Exclusive creation binary
|
| 97 |
+
'xb', 'bx',
|
| 98 |
+
# Read and write binary
|
| 99 |
+
'rb+', 'r+b', '+rb', 'br+', 'b+r', '+br',
|
| 100 |
+
# Write and read binary
|
| 101 |
+
'wb+', 'w+b', '+wb', 'bw+', 'b+w', '+bw',
|
| 102 |
+
# Append and read binary
|
| 103 |
+
'ab+', 'a+b', '+ab', 'ba+', 'b+a', '+ba',
|
| 104 |
+
# Exclusive creation and read binary
|
| 105 |
+
'xb+', 'x+b', '+xb', 'bx+', 'b+x', '+bx',
|
| 106 |
+
]
|
| 107 |
+
# spellchecker: on
|
| 108 |
+
#: A filename argument: either a plain string path or a `pathlib.Path`.
|
| 109 |
+
#: Accepting both lets callers pass whichever they already have on hand
|
| 110 |
+
#: without converting first.
|
| 111 |
+
Filename = str | pathlib.Path
|
| 112 |
+
#: A file-like object already opened for reading or writing, in either text
|
| 113 |
+
#: or binary mode.
|
| 114 |
+
IO = typing.IO[str] | typing.IO[bytes]
|
| 115 |
+
|
| 116 |
+
|
| 117 |
+
class FileOpenKwargs(typing.TypedDict):
|
| 118 |
+
"""Keyword arguments accepted by the built-in `open()`.
|
| 119 |
+
|
| 120 |
+
Mirrors `open()`'s signature (minus `file` and `mode`) so helpers that
|
| 121 |
+
accept a filename can forward arbitrary open-related keyword arguments
|
| 122 |
+
straight through to the underlying `open()` call.
|
| 123 |
+
"""
|
| 124 |
+
|
| 125 |
+
# Note: Napoleon reads a leading ``something: rest`` on the first line
|
| 126 |
+
# of an attribute docstring as a type declaration, so first lines here
|
| 127 |
+
# deliberately avoid colons.
|
| 128 |
+
buffering: int | None
|
| 129 |
+
"""Buffering policy. `0` disables buffering (binary mode only), `1`
|
| 130 |
+
selects line buffering (text mode), and any larger integer fixes the
|
| 131 |
+
buffer size in bytes.
|
| 132 |
+
"""
|
| 133 |
+
|
| 134 |
+
encoding: str | None
|
| 135 |
+
"""Text encoding to use; ignored in binary mode."""
|
| 136 |
+
|
| 137 |
+
errors: str | None
|
| 138 |
+
"""How encoding/decoding errors are handled, e.g. `'strict'` or
|
| 139 |
+
`'ignore'`.
|
| 140 |
+
"""
|
| 141 |
+
|
| 142 |
+
newline: str | None
|
| 143 |
+
r"""Controls how universal newlines mode works, e.g. `''`, `'\\n'`,
|
| 144 |
+
`'\\r'`, or `'\\r\\n'`.
|
| 145 |
+
"""
|
| 146 |
+
|
| 147 |
+
closefd: bool | None
|
| 148 |
+
"""Whether the underlying file descriptor is closed when the file
|
| 149 |
+
object is closed. Must be `True` (the default) when a filename rather
|
| 150 |
+
than a file descriptor was passed to `open()`.
|
| 151 |
+
"""
|
| 152 |
+
|
| 153 |
+
opener: typing.Callable[[str, int], int] | None
|
| 154 |
+
"""A custom opener, called as `opener(file, flags)` to obtain the
|
| 155 |
+
underlying file descriptor, used instead of the default `os.open`.
|
| 156 |
+
"""
|
| 157 |
+
|
| 158 |
+
|
| 159 |
+
class HasFileno(typing.Protocol):
|
| 160 |
+
"""Structural protocol for objects exposing a `fileno()` method.
|
| 161 |
+
|
| 162 |
+
Exists so functions that ultimately call `fcntl.flock` can be typed
|
| 163 |
+
against anything with a file descriptor - open files, sockets, and so
|
| 164 |
+
on - without requiring those objects to share a common base class.
|
| 165 |
+
"""
|
| 166 |
+
|
| 167 |
+
def fileno(self) -> int:
|
| 168 |
+
"""Return the underlying file descriptor, as used by `fcntl.flock`."""
|
| 169 |
+
...
|
| 170 |
+
|
| 171 |
+
|
| 172 |
+
#: The type accepted by the module-level `lock()`/`unlock()` functions: an
|
| 173 |
+
#: already-open file object, anything exposing a `fileno()` method, or a
|
| 174 |
+
#: bare file descriptor (`int`). The `int` case exists because
|
| 175 |
+
#: `fcntl.flock`/`msvcrt.locking()` operate on raw file descriptors, which
|
| 176 |
+
#: callers may already have without an open file object wrapping them.
|
| 177 |
+
FileArgument = typing.IO[typing.Any] | io.TextIOWrapper | int | HasFileno
|