amir0907 commited on
Commit
2edb2ec
·
verified ·
1 Parent(s): c9e08b6

Upload env/portalocker/types.py

Browse files
Files changed (1) hide show
  1. 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