codekingpro/portable-devtools

1import builtins
2import sys
3from typing import Final
4from uuid import SafeUUID
5
6from typing_extensions import LiteralString, TypeAlias
7
8# Because UUID has properties called int and bytes we need to rename these temporarily.
9_FieldsType: TypeAlias = tuple[int, int, int, int, int, int]
10
11__version__: str
12
13class UUID:
14    """Instances of the UUID class represent UUIDs as specified in RFC 4122.
15    UUID objects are immutable, hashable, and usable as dictionary keys.
16    Converting a UUID to a string with str() yields something in the form
17    '12345678-1234-1234-1234-123456789abc'.  The UUID constructor accepts
18    five possible forms: a similar string of hexadecimal digits, or a tuple
19    of six integer fields (with 32-bit, 16-bit, 16-bit, 8-bit, 8-bit, and
20    48-bit values respectively) as an argument named 'fields', or a string
21    of 16 bytes (with all the integer fields in big-endian order) as an
22    argument named 'bytes', or a string of 16 bytes (with the first three
23    fields in little-endian order) as an argument named 'bytes_le', or a
24    single 128-bit integer as an argument named 'int'.
25
26    UUIDs have these read-only attributes:
27
28        bytes       the UUID as a 16-byte string (containing the six
29                    integer fields in big-endian byte order)
30
31        bytes_le    the UUID as a 16-byte string (with time_low, time_mid,
32                    and time_hi_version in little-endian byte order)
33
34        fields      a tuple of the six integer fields of the UUID,
35                    which are also available as six individual attributes
36                    and two derived attributes:
37
38            time_low                the first 32 bits of the UUID
39            time_mid                the next 16 bits of the UUID
40            time_hi_version         the next 16 bits of the UUID
41            clock_seq_hi_variant    the next 8 bits of the UUID
42            clock_seq_low           the next 8 bits of the UUID
43            node                    the last 48 bits of the UUID
44
45            time                    the 60-bit timestamp
46            clock_seq               the 14-bit sequence number
47
48        hex         the UUID as a 32-character hexadecimal string
49
50        int         the UUID as a 128-bit integer
51
52        urn         the UUID as a URN as specified in RFC 4122
53
54        variant     the UUID variant (one of the constants RESERVED_NCS,
55                    RFC_4122, RESERVED_MICROSOFT, or RESERVED_FUTURE)
56
57        version     the UUID version number
58
59        is_safe     An enum indicating whether the UUID has been generated in
60                    a way that is safe for multiprocessing applications, via
61                    uuid_generate_time_safe(3).
62
63        timestamp   The timestamp of the UUID in milliseconds since epoch.
64                    Only works for UUID versions 1, 6 and 7,
65                    otherwise raises ValueError.
66    """
67
68    is_safe: Final[SafeUUID]
69    int: Final[builtins.int]
70
71    def __init__(
72        self,
73        hex: str | None = None,
74        bytes: builtins.bytes | None = None,
75        bytes_le: builtins.bytes | None = None,
76        fields: _FieldsType | None = None,
77        int: builtins.int | None = None,
78        version: builtins.int | None = None,
79        *,
80        is_safe: SafeUUID = ...,
81    ) -> None: ...
82    @property
83    def bytes(self) -> builtins.bytes: ...
84    @property
85    def bytes_le(self) -> builtins.bytes: ...
86    @property
87    def clock_seq(self) -> builtins.int: ...
88    @property
89    def clock_seq_hi_variant(self) -> builtins.int: ...
90    @property
91    def clock_seq_low(self) -> builtins.int: ...
92    @property
93    def fields(self) -> _FieldsType: ...
94    @property
95    def hex(self) -> str: ...
96    @property
97    def node(self) -> builtins.int: ...
98    @property
99    def time(self) -> builtins.int: ...
100    @property
101    def time_hi_version(self) -> builtins.int: ...
102    @property
103    def time_low(self) -> builtins.int: ...
104    @property
105    def time_mid(self) -> builtins.int: ...
106    @property
107    def timestamp(self) -> builtins.int:
108        """Get UUID timestamp milliseconds since epoch.
109        Only works for UUID versions 1, 6 and 7, otherwise raises ValueError."""
110        ...
111
112    @property
113    def urn(self) -> str: ...
114    @property
115    def variant(self) -> str: ...
116    @property
117    def version(self) -> builtins.int | None: ...
118    def __int__(self) -> builtins.int: ...
119    def __hash__(self) -> builtins.int: ...
120    def __eq__(self, other: object) -> bool: ...
121    def __lt__(self, other: UUID) -> bool: ...
122    def __le__(self, other: UUID) -> bool: ...
123    def __gt__(self, other: UUID) -> bool: ...
124    def __ge__(self, other: UUID) -> bool: ...
125
126def getnode() -> int: ...
127def reseed_rng() -> None:
128    """
129    Reseeds the underlying rng.
130    This is useful in cases where you fork, as without reseeding the
131    generated uuids may be identical. This can be called manually in the child process,
132    or automatically run after fork with:
133
134    os.register_at_fork(after_in_child=uuid_utils.reseed_rng)
135    """
136    ...
137
138def uuid1(node: int | None = None, clock_seq: int | None = None) -> UUID:
139    """Generate a UUID from a host ID, sequence number, and the current time.
140    If 'node' is not given, getnode() is used to obtain the hardware
141    address.  If 'clock_seq' is given, it is used as the sequence number;
142    otherwise a random 14-bit sequence number is chosen."""
143    ...
144
145if sys.version_info >= (3, 12):
146    def uuid3(namespace: UUID, name: str | bytes) -> UUID:
147        """Generate a UUID from the MD5 hash of a namespace UUID and a name."""
148        ...
149else:
150    def uuid3(namespace: UUID, name: str) -> UUID:
151        """Generate a UUID from the MD5 hash of a namespace UUID and a name."""
152        ...
153
154def uuid4() -> UUID:
155    """Generate a random UUID."""
156    ...
157
158if sys.version_info >= (3, 12):
159    def uuid5(namespace: UUID, name: str | bytes) -> UUID:
160        """Generate a UUID from the SHA-1 hash of a namespace UUID and a name."""
161        ...
162else:
163    def uuid5(namespace: UUID, name: str) -> UUID:
164        """Generate a UUID from the SHA-1 hash of a namespace UUID and a name."""
165        ...
166
167def uuid6(
168    node: int | None = None, timestamp: int | None = None, nanos: int | None = None
169) -> UUID:
170    """Generate a version 6 UUID using the given timestamp and a host ID.
171    This is similar to version 1 UUIDs,
172    except that it is lexicographically sortable by timestamp.
173    """
174    ...
175
176def uuid7(timestamp: int | None = None, nanos: int | None = None) -> UUID:
177    """Generate a version 7 UUID using a time value and random bytes."""
178    ...
179
180def uuid8(bytes: bytes) -> UUID:
181    """Generate a custom UUID comprised almost entirely of user-supplied bytes."""
182    ...
183
184NAMESPACE_DNS: Final[UUID]
185NAMESPACE_URL: Final[UUID]
186NAMESPACE_OID: Final[UUID]
187NAMESPACE_X500: Final[UUID]
188RESERVED_NCS: Final[LiteralString]
189RFC_4122: Final[LiteralString]
190RESERVED_MICROSOFT: Final[LiteralString]
191RESERVED_FUTURE: Final[LiteralString]
192NIL: Final[UUID]
193MAX: Final[UUID]
194
195__all__ = [
196    "MAX",
197    "NAMESPACE_DNS",
198    "NAMESPACE_OID",
199    "NAMESPACE_URL",
200    "NAMESPACE_X500",
201    "NIL",
202    "RESERVED_FUTURE",
203    "RESERVED_MICROSOFT",
204    "RESERVED_NCS",
205    "RFC_4122",
206    "UUID",
207    "SafeUUID",
208    "__version__",
209    "getnode",
210    "reseed_rng",
211    "uuid1",
212    "uuid3",
213    "uuid4",
214    "uuid5",
215    "uuid6",
216    "uuid7",
217    "uuid8",
218]
219