hip 0.2__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
hip/_headers.py ADDED
@@ -0,0 +1,251 @@
1
+ from __future__ import annotations
2
+
3
+ import re
4
+ import typing
5
+
6
+ __all__ = ["Headers"]
7
+
8
+
9
+ VALID_HEADER_CHARS = (
10
+ "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789!#$%&'*+-.^_`|~"
11
+ )
12
+
13
+
14
+ # TODO...
15
+ #
16
+ # * Comma folded values, eg. `Vary: ...`
17
+ # * Multiple Set-Cookie headers.
18
+ # * Non-ascii support.
19
+ # * Ordering, including `Host` header exception.
20
+
21
+
22
+ def headername(name: str) -> str:
23
+ if name.strip(VALID_HEADER_CHARS) or not name:
24
+ raise ValueError(f"Invalid HTTP header name {name!r}.")
25
+ return name
26
+
27
+
28
+ def headervalue(value: str) -> str:
29
+ value = value.strip(" ")
30
+ if not value or not value.isascii() or not value.isprintable():
31
+ raise ValueError(f"Invalid HTTP header value {value!r}.")
32
+ return value
33
+
34
+
35
+ class Headers(typing.Mapping[str, str]):
36
+ def __init__(
37
+ self,
38
+ headers: typing.Mapping[str, str]
39
+ | typing.Sequence[tuple[str, str]]
40
+ | None = None,
41
+ ) -> None:
42
+ # {'accept': ('Accept', '*/*')}
43
+ d: dict[str, str] = {}
44
+
45
+ if isinstance(headers, typing.Mapping):
46
+ # Headers({
47
+ # 'Content-Length': '1024',
48
+ # 'Content-Type': 'text/plain; charset=utf-8',
49
+ # )
50
+ d = {headername(k): headervalue(v) for k, v in headers.items()}
51
+ elif headers is not None:
52
+ # Headers([
53
+ # ('Location', 'https://www.example.com'),
54
+ # ('Set-Cookie', 'session_id=3498jj489jhb98jn'),
55
+ # ])
56
+ d = {headername(k): headervalue(v) for k, v in headers}
57
+
58
+ self._dict = d
59
+
60
+ def keys(self) -> typing.KeysView[str]:
61
+ """
62
+ Return all the header keys.
63
+
64
+ Usage:
65
+
66
+ h = hip.Headers({"Accept": "*/*", "User-Agent": "python/hip"})
67
+ assert list(h.keys()) == ["Accept", "User-Agent"]
68
+ """
69
+ return self._dict.keys()
70
+
71
+ def values(self) -> typing.ValuesView[str]:
72
+ """
73
+ Return all the header values.
74
+
75
+ Usage:
76
+
77
+ h = hip.Headers({"Accept": "*/*", "User-Agent": "python/hip"})
78
+ assert list(h.values()) == ["*/*", "python/hip"]
79
+ """
80
+ return self._dict.values()
81
+
82
+ def items(self) -> typing.ItemsView[str, str]:
83
+ """
84
+ Return all headers as (key, value) tuples.
85
+
86
+ Usage:
87
+
88
+ h = hip.Headers({"Accept": "*/*", "User-Agent": "python/hip"})
89
+ assert list(h.items()) == [("Accept", "*/*"), ("User-Agent", "python/hip")]
90
+ """
91
+ return self._dict.items()
92
+
93
+ def get(self, key: str, default: typing.Any = None) -> typing.Any:
94
+ """
95
+ Get a value from the query param for a given key. If the key occurs
96
+ more than once, then only the first value is returned.
97
+
98
+ Usage:
99
+
100
+ h = hip.Headers({"Accept": "*/*", "User-Agent": "python/hip"})
101
+ assert h.get("User-Agent") == "python/hip"
102
+ """
103
+ for k, v in self._dict.items():
104
+ if k.lower() == key.lower():
105
+ return v
106
+ return default
107
+
108
+ def copy_set(self, key: str, value: str) -> Headers:
109
+ """
110
+ Return a new Headers instance, setting the value of a key.
111
+
112
+ Usage:
113
+
114
+ h = hip.Headers({"Expires": "0"})
115
+ h = h.copy_set("Expires", "Wed, 21 Oct 2015 07:28:00 GMT")
116
+ assert h == hip.Headers({"Expires": "Wed, 21 Oct 2015 07:28:00 GMT"})
117
+ """
118
+ l = []
119
+ seen = False
120
+
121
+ # Either insert...
122
+ for k, v in self._dict.items():
123
+ if k.lower() == key.lower():
124
+ l.append((key, value))
125
+ seen = True
126
+ else:
127
+ l.append((k, v))
128
+
129
+ # Or append...
130
+ if not seen:
131
+ l.append((key, value))
132
+
133
+ return Headers(l)
134
+
135
+ def copy_remove(self, key: str) -> Headers:
136
+ """
137
+ Return a new Headers instance, removing the value of a key.
138
+
139
+ Usage:
140
+
141
+ h = hip.Headers({"Accept": "*/*"})
142
+ h = h.copy_remove("Accept")
143
+ assert h == hip.Headers({})
144
+ """
145
+ h = {k: v for k, v in self._dict.items() if k.lower() != key.lower()}
146
+ return Headers(h)
147
+
148
+ def copy_update(self, update: Headers | typing.Mapping[str, str] | None) -> Headers:
149
+ """
150
+ Return a new Headers instance, removing the value of a key.
151
+
152
+ Usage:
153
+
154
+ h = hip.Headers({"Accept": "*/*", "User-Agent": "python/hip"})
155
+ h = h.copy_update({"Accept-Encoding": "gzip"})
156
+ assert h == hip.Headers({"Accept": "*/*", "Accept-Encoding": "gzip", "User-Agent": "python/hip"})
157
+ """
158
+ if update is None:
159
+ return self
160
+
161
+ new = update if isinstance(update, Headers) else Headers(update)
162
+
163
+ # Remove updated items using a case-insensitive approach...
164
+ keys = {key.lower() for key in new}
165
+ h = {k: v for k, v in self._dict.items() if k.lower() not in keys}
166
+
167
+ # Perform the actual update...
168
+ h.update(dict(new))
169
+
170
+ return Headers(h)
171
+
172
+ def as_byte_pairs(self) -> list[tuple[bytes, bytes]]:
173
+ return [(k.encode("ascii"), v.encode("ascii")) for k, v in self.items()]
174
+
175
+ def __getitem__(self, key: str) -> str:
176
+ match = key.lower()
177
+ for k, v in self._dict.items():
178
+ if k.lower() == match:
179
+ return v
180
+ raise KeyError(key)
181
+
182
+ def __contains__(self, key: typing.Any) -> bool:
183
+ match = key.lower()
184
+ return any(k.lower() == match for k in self._dict)
185
+
186
+ def __iter__(self) -> typing.Iterator[str]:
187
+ return iter(self.keys())
188
+
189
+ def __len__(self) -> int:
190
+ return len(self._dict)
191
+
192
+ def __bool__(self) -> bool:
193
+ return bool(self._dict)
194
+
195
+ def __eq__(self, other: object) -> bool:
196
+ if not isinstance(other, (typing.Mapping, typing.Sequence)):
197
+ return False
198
+ self_lower = {k.lower(): v for k, v in self.items()}
199
+ other_lower = {k.lower(): v for k, v in Headers(other).items()}
200
+ return self_lower == other_lower
201
+
202
+ def __repr__(self) -> str:
203
+ return f"<Headers {dict(self)!r}>"
204
+
205
+
206
+ def parse_opts_header(header: str) -> tuple[str, dict[str, str]]:
207
+ # The Content-Type header is described in RFC 2616 'Content-Type'
208
+ # https://datatracker.ietf.org/doc/html/rfc2616#section-14.17
209
+
210
+ # The 'type/subtype; parameter' format is described in RFC 2616 'Media Types'
211
+ # https://datatracker.ietf.org/doc/html/rfc2616#section-3.7
212
+
213
+ # Parameter quoting is described in RFC 2616 'Transfer Codings'
214
+ # https://datatracker.ietf.org/doc/html/rfc2616#section-3.6
215
+
216
+ header = header.strip()
217
+ content_type = ""
218
+ params = {}
219
+
220
+ # Match the content type (up to the first semicolon or end)
221
+ match = re.match(r"^([^;]+)", header)
222
+ if match:
223
+ content_type = match.group(1).strip().lower()
224
+ rest = header[match.end() :]
225
+ else:
226
+ return "", {}
227
+
228
+ # Parse parameters, accounting for quoted strings
229
+ param_pattern = re.compile(
230
+ r"""
231
+ ;\s* # Semicolon + optional whitespace
232
+ (?P<key>[^=;\s]+) # Parameter key
233
+ = # Equal sign
234
+ (?P<value> # Parameter value:
235
+ "(?:[^"\\]|\\.)*" # Quoted string with escapes
236
+ | # OR
237
+ [^;]* # Unquoted string (until semicolon)
238
+ )
239
+ """,
240
+ re.VERBOSE,
241
+ )
242
+
243
+ for match in param_pattern.finditer(rest):
244
+ key = match.group("key").lower()
245
+ value = match.group("value").strip()
246
+ if value.startswith('"') and value.endswith('"'):
247
+ # Remove surrounding quotes and unescape
248
+ value = re.sub(r"\\(.)", r"\1", value[1:-1])
249
+ params[key] = value
250
+
251
+ return content_type, params
hip/_network.py ADDED
@@ -0,0 +1,252 @@
1
+ import concurrent.futures
2
+ import contextlib
3
+ import contextvars
4
+ import select
5
+ import socket
6
+ import ssl
7
+ import threading
8
+ import time
9
+ import types
10
+ import typing
11
+
12
+ import truststore
13
+
14
+ if typing.TYPE_CHECKING:
15
+ # Once we drop 3.10 support, we can use 'typing.Self'.
16
+ from typing_extensions import Self
17
+
18
+ from ._streams import Stream
19
+
20
+ __all__ = ["NetworkBackend", "NetworkStream", "timeout"]
21
+
22
+ _timeout_stack: contextvars.ContextVar[tuple[float, ...]] = contextvars.ContextVar(
23
+ "timeout_context", default=()
24
+ )
25
+
26
+
27
+ @contextlib.contextmanager
28
+ def timeout(duration: float) -> typing.Iterator[None]:
29
+ """
30
+ A context managed timeout API.
31
+
32
+ with timeout(1.0):
33
+ ...
34
+ """
35
+ now = time.monotonic()
36
+ until = now + duration
37
+ stack = (until, *_timeout_stack.get())
38
+ token = _timeout_stack.set(stack)
39
+ try:
40
+ yield
41
+ finally:
42
+ _timeout_stack.reset(token)
43
+
44
+
45
+ def get_current_timeout() -> float | None:
46
+ stack = _timeout_stack.get()
47
+ if not stack:
48
+ return None
49
+ soonest = min(stack)
50
+ now = time.monotonic()
51
+ remaining = soonest - now
52
+ if remaining <= 0.0:
53
+ raise TimeoutError()
54
+ return remaining
55
+
56
+
57
+ class NetworkStream(Stream):
58
+ def __init__(self, sock: socket.socket, address: tuple[str, int]) -> None:
59
+ self._socket = sock
60
+ self._address = address
61
+ self._is_tls = False
62
+ self._is_closed = False
63
+
64
+ @property
65
+ def host(self) -> str:
66
+ return self._address[0]
67
+
68
+ @property
69
+ def port(self) -> int:
70
+ return self._address[1]
71
+
72
+ def read(self, size: int = -1) -> bytes:
73
+ if size < 0:
74
+ size = 64 * 1024
75
+ timeout = get_current_timeout()
76
+ self._socket.settimeout(timeout)
77
+ content = self._socket.recv(size)
78
+ return content
79
+
80
+ def write(self, buffer: bytes) -> None:
81
+ while buffer:
82
+ timeout = get_current_timeout()
83
+ self._socket.settimeout(timeout)
84
+ n = self._socket.send(buffer)
85
+ buffer = buffer[n:]
86
+
87
+ def close(self) -> None:
88
+ if not self._is_closed:
89
+ self._is_closed = True
90
+ try:
91
+ self._socket.shutdown(socket.SHUT_RDWR)
92
+ except OSError:
93
+ pass
94
+ self._socket.close()
95
+
96
+ def __repr__(self):
97
+ description = ""
98
+ description += " TLS" if self._is_tls else ""
99
+ description += " CLOSED" if self._is_closed else ""
100
+ return f"<NetworkStream [{self.host}:{self.port}{description}]>"
101
+
102
+ def __enter__(self) -> "Self":
103
+ return self
104
+
105
+ def __exit__(
106
+ self,
107
+ exc_type: type[BaseException] | None = None,
108
+ exc_value: BaseException | None = None,
109
+ traceback: types.TracebackType | None = None,
110
+ ):
111
+ self.close()
112
+
113
+
114
+ class NetworkListener:
115
+ def __init__(self, sock: socket.socket, address: tuple[str, int]) -> None:
116
+ self._server_socket = sock
117
+ self._address = address
118
+ self._is_closed = False
119
+
120
+ @property
121
+ def host(self):
122
+ return self._address[0]
123
+
124
+ @property
125
+ def port(self):
126
+ return self._address[1]
127
+
128
+ def accept(self) -> NetworkStream | None:
129
+ """
130
+ Blocks until an incoming connection is accepted, and returns the NetworkStream.
131
+ Stops blocking and returns `None` once the listener is closed.
132
+ """
133
+ while not self._is_closed:
134
+ r, _, _ = select.select([self._server_socket], [], [], 3)
135
+ if r:
136
+ sock, address = self._server_socket.accept()
137
+ return NetworkStream(sock, address)
138
+ return None
139
+
140
+ def close(self):
141
+ self._is_closed = True
142
+ self._server_socket.close()
143
+
144
+ def __enter__(self) -> "Self":
145
+ return self
146
+
147
+ def __exit__(
148
+ self,
149
+ exc_type: type[BaseException] | None = None,
150
+ exc_value: BaseException | None = None,
151
+ traceback: types.TracebackType | None = None,
152
+ ):
153
+ self.close()
154
+
155
+
156
+ class NetworkServer:
157
+ def __init__(
158
+ self, listener: NetworkListener, handler: typing.Callable[[NetworkStream], None]
159
+ ) -> None:
160
+ self.listener = listener
161
+ self.handler = handler
162
+ self._max_workers = 10
163
+ self._executor = None
164
+ self._thread = None
165
+ self._streams: list[NetworkStream] = []
166
+
167
+ @property
168
+ def host(self):
169
+ return self.listener.host
170
+
171
+ @property
172
+ def port(self):
173
+ return self.listener.port
174
+
175
+ def __enter__(self):
176
+ self._executor = concurrent.futures.ThreadPoolExecutor(
177
+ max_workers=self._max_workers
178
+ )
179
+ self._executor.submit(self._serve)
180
+ return self
181
+
182
+ def __exit__(self, exc_type, exc_val, exc_tb):
183
+ for stream in self._streams:
184
+ stream.close()
185
+ self.listener.close()
186
+ self._executor.shutdown(wait=True)
187
+
188
+ def _serve(self):
189
+ while stream := self.listener.accept():
190
+ self._executor.submit(self._handler, stream)
191
+
192
+ def _handler(self, stream):
193
+ try:
194
+ self._streams.append(stream)
195
+ self.handler(stream)
196
+ finally:
197
+ stream.close()
198
+ self._streams.remove(stream)
199
+
200
+
201
+ class NetworkBackend:
202
+ def __init__(self, ssl_ctx: ssl.SSLContext | None = None):
203
+ self._ssl_ctx = self.create_default_context() if ssl_ctx is None else ssl_ctx
204
+
205
+ def create_default_context(self) -> ssl.SSLContext:
206
+ return truststore.SSLContext(ssl.PROTOCOL_TLS_CLIENT)
207
+
208
+ def connect(self, host: str, port: int) -> NetworkStream:
209
+ """
210
+ Connect to the given address, returning a NetworkStream instance.
211
+ """
212
+ address = (host, port)
213
+ timeout = get_current_timeout()
214
+ sock = socket.create_connection(address, timeout=timeout)
215
+ return NetworkStream(sock, address)
216
+
217
+ def connect_tls(self, host: str, port: int, hostname: str = "") -> NetworkStream:
218
+ """
219
+ Connect to the given address, returning a NetworkStream instance.
220
+ """
221
+ address = (host, port)
222
+ hostname = hostname or host
223
+ timeout = get_current_timeout()
224
+ sock = socket.create_connection(address, timeout=timeout)
225
+ sock = self._ssl_ctx.wrap_socket(sock, server_hostname=hostname)
226
+ return NetworkStream(sock, address)
227
+
228
+ def listen(self, host: str, port: int) -> NetworkListener:
229
+ """
230
+ List on the given address, returning a NetworkListener instance.
231
+ """
232
+ address = (host, port)
233
+ sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
234
+ sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
235
+ sock.bind(address)
236
+ sock.listen(5)
237
+ sock.setblocking(False)
238
+ return NetworkListener(sock, address)
239
+
240
+ def serve(
241
+ self, host: str, port: int, handler: typing.Callable[[NetworkStream], None]
242
+ ) -> NetworkServer:
243
+ listener = self.listen(host, port)
244
+ return NetworkServer(listener, handler)
245
+
246
+ def __repr__(self):
247
+ return "<NetworkBackend [threaded]>"
248
+
249
+
250
+ Semaphore = threading.Semaphore
251
+ Lock = threading.Lock
252
+ sleep = time.sleep