codekingpro/portable-devtools

1from __future__ import annotations
2
3import http
4import logging
5from typing import TYPE_CHECKING, Any, NewType, Sequence
6
7
8__all__ = [
9    "Data",
10    "LoggerLike",
11    "StatusLike",
12    "Origin",
13    "Subprotocol",
14    "ExtensionName",
15    "ExtensionParameter",
16]
17
18
19# Public types used in the signature of public APIs
20
21Data = str | bytes
22"""Types supported in a WebSocket message:
23:class:`str` for a Text_ frame, :class:`bytes` for a Binary_ frame.
24
25.. _Text: https://datatracker.ietf.org/doc/html/rfc6455#section-5.6
26.. _Binary : https://datatracker.ietf.org/doc/html/rfc6455#section-5.6
27
28"""
29
30BytesLike = bytes | bytearray | memoryview
31"""Types accepted where :class:`bytes` is expected."""
32
33DataLike = str | bytes | bytearray | memoryview
34"""Types accepted where :class:`Data` is expected."""
35
36if TYPE_CHECKING:
37    LoggerLike = logging.Logger | logging.LoggerAdapter[Any]
38    """Types accepted where a :class:`~logging.Logger` is expected."""
39else:  # remove this branch when dropping support for Python < 3.11
40    LoggerLike = logging.Logger | logging.LoggerAdapter
41    """Types accepted where a :class:`~logging.Logger` is expected."""
42
43
44StatusLike = http.HTTPStatus | int
45"""
46Types accepted where an :class:`~http.HTTPStatus` is expected."""
47
48
49Origin = NewType("Origin", str)
50"""Value of a ``Origin`` header."""
51
52
53Subprotocol = NewType("Subprotocol", str)
54"""Subprotocol in a ``Sec-WebSocket-Protocol`` header."""
55
56
57ExtensionName = NewType("ExtensionName", str)
58"""Name of a WebSocket extension."""
59
60ExtensionParameter = tuple[str, str | None]
61"""Parameter of a WebSocket extension."""
62
63
64# Private types
65
66ExtensionHeader = tuple[ExtensionName, Sequence[ExtensionParameter]]
67"""Extension in a ``Sec-WebSocket-Extensions`` header."""
68
69
70ConnectionOption = NewType("ConnectionOption", str)
71"""Connection option in a ``Connection`` header."""
72
73
74UpgradeProtocol = NewType("UpgradeProtocol", str)
75"""Upgrade protocol in an ``Upgrade`` header."""
76