Skip to content

Commit b881e3d

Browse files
LamentXU123picnixz
andauthored
gh-89083: add links to RFC 9562 sections in UUID docs (#135684)
We also sync the docs for UUIDv1 and UUIDv6 concerning the node address and clock sequence. --------- Co-authored-by: Bénédikt Tran <[email protected]>
1 parent eec7a8f commit b881e3d

File tree

1 file changed

+19
-10
lines changed

1 file changed

+19
-10
lines changed

Doc/library/uuid.rst

Lines changed: 19 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -193,43 +193,52 @@ The :mod:`uuid` module defines the following functions:
193193

194194
.. function:: uuid1(node=None, clock_seq=None)
195195

196-
Generate a UUID from a host ID, sequence number, and the current time. If *node*
197-
is not given, :func:`getnode` is used to obtain the hardware address. If
198-
*clock_seq* is given, it is used as the sequence number; otherwise a random
199-
14-bit sequence number is chosen.
196+
Generate a UUID from a host ID, sequence number, and the current time
197+
according to :rfc:`RFC 9562, §5.1 <9562#section-5.1>`.
198+
199+
When *node* is not specified, :func:`getnode` is used to obtain the hardware
200+
address as a 48-bit positive integer. When a sequence number *clock_seq* is
201+
not specified, a pseudo-random 14-bit positive integer is generated.
202+
203+
If *node* or *clock_seq* exceed their expected bit count,
204+
only their least significant bits are kept.
200205

201206

202207
.. function:: uuid3(namespace, name)
203208

204209
Generate a UUID based on the MD5 hash of a namespace identifier (which is a
205210
UUID) and a name (which is a :class:`bytes` object or a string
206-
that will be encoded using UTF-8).
211+
that will be encoded using UTF-8)
212+
according to :rfc:`RFC 9562, §5.3 <9562#section-5.3>`.
207213

208214

209215
.. function:: uuid4()
210216

211-
Generate a random UUID.
217+
Generate a random UUID in a cryptographically-secure method
218+
according to :rfc:`RFC 9562, §5.4 <9562#section-5.4>`.
212219

213220

214221
.. function:: uuid5(namespace, name)
215222

216223
Generate a UUID based on the SHA-1 hash of a namespace identifier (which is a
217224
UUID) and a name (which is a :class:`bytes` object or a string
218-
that will be encoded using UTF-8).
225+
that will be encoded using UTF-8)
226+
according to :rfc:`RFC 9562, §5.5 <9562#section-5.5>`.
219227

220228

221229
.. function:: uuid6(node=None, clock_seq=None)
222230

223231
Generate a UUID from a sequence number and the current time according to
224-
:rfc:`9562`.
232+
:rfc:`RFC 9562, §5.6 <9562#section-5.6>`.
233+
225234
This is an alternative to :func:`uuid1` to improve database locality.
226235

227236
When *node* is not specified, :func:`getnode` is used to obtain the hardware
228237
address as a 48-bit positive integer. When a sequence number *clock_seq* is
229238
not specified, a pseudo-random 14-bit positive integer is generated.
230239

231-
If *node* or *clock_seq* exceed their expected bit count, only their least
232-
significant bits are kept.
240+
If *node* or *clock_seq* exceed their expected bit count,
241+
only their least significant bits are kept.
233242

234243
.. versionadded:: 3.14
235244

0 commit comments

Comments
 (0)