gh-139122: Reimplement base UUID type, uuid4(), and uuid7() in C (#139123)

The C implementation considerably boosts the performance of the key UUID operations:

------------------------------------
Operation                    Speedup
------------------------------------
uuid4() generation            15.01x
uuid7() generation            29.64x
UUID from string               6.76x
UUID from bytes                5.16x
str(uuid) conversion           6.66x
------------------------------------

Summary of changes:

* The UUID type is reimplemented in C in its entirety.

* The pure-Python is kept around and is used of the C implementation
  isn't available for some reason.

* Both implementations are tested extensively; additional tests are
  added to ensure that the C implementation of the type follows the pure
  Python implementation fully.

* The Python implementation stores UUID values as int objects. The C
  implementation stores them as `uint8_t[16]` array.

* The C implementation has faster hash() implementation but also caches
  the computed hash value to speedup cases when UUIDs are used as
  set/dict keys.

* The C implementation has a freelist to make new UUID object
  instantiation as fast as possible.

* uuid4() and uuid7() are now implmented in C. The most performance
  boost (10x) comes from overfetching entropy to decrease the number of
  _PyOS_URandom() calls. On its own it's a safe optimization with the
  edge case that Unix fork needs to be explicitly handled. We do that by
  comparing the current PID to the PID of when the random buffer was
  populated.

* Portions of code are coming from my implementation of faster UUID
  in gel-python [1]. I did use AI during the development, but basically
  had to rewrite the code it generated to be more idiomatic and
  efficient.

* The benchmark can be found here [2].

* This PR makes Python UUID operations as fast as they are in NodeJS and
  Bun runtimes.

[1] https://github.com/MagicStack/py-pgproto/blob/b8109fb311a59f30f9947567a13508da9a776564/uuid.pyx

[2] https://gist.github.com/1st1/f03e816f34a61e4d46c78ff98baf4818

Author: 1st1

Doc/library/uuid.rst

@@ -69,6 +69,11 @@ which relays any information about the UUID's safety, using this enumeration:
    variant and version number set according to :rfc:`9562`, overriding bits in the
    given *hex*, *bytes*, *bytes_le*, *fields*, or *int*.
 
+   .. versionchanged:: next
+      Passing an object other than :class:`bytes` as *bytes* or *bytes_le*
+      now consistently raises :exc:`TypeError`. Previously, some invalid inputs
+      raised :exc:`AssertionError` or :exc:`ValueError`.
+
    Comparison of UUID objects are made by way of comparing their
    :attr:`UUID.int` attributes.  Comparison with a non-UUID object
    raises a :exc:`TypeError`.

Doc/whatsnew/3.16.rst

@@ -852,6 +852,18 @@ unicodedata
 * The Unicode database has been updated to Unicode 18.0.0.
 
 
+uuid
+----
+
+* :class:`uuid.UUID`, :func:`uuid.uuid4`, and :func:`uuid.uuid7` now have
+  C implementations, with a pure Python fallback.
+  In microbenchmarks, UUIDv4 and UUIDv7 generation are approximately 15 and
+  30 times faster, respectively, than the pure Python implementations.
+  UUID construction and string conversion are also faster; see
+  :ref:`whatsnew316-uuid-optimizations` for the benchmark results.
+  (Contributed by Yury Selivanov in :gh:`139123`.)
+
+
 xml
 ---
 
@@ -960,6 +972,28 @@ re
   :gh:`152056`.)
 
 
+.. _whatsnew316-uuid-optimizations:
+
+uuid
+----
+
+* C implementations accelerate UUID generation, construction, and string
+  conversion. Microbenchmarks comparing the C and pure Python implementations
+  measured the following speedups:
+
+  ================================  =======
+  Operation                         Speedup
+  ================================  =======
+  :func:`uuid.uuid4` generation       15.01x
+  :func:`uuid.uuid7` generation       29.64x
+  :class:`uuid.UUID` from a string     6.76x
+  :class:`uuid.UUID` from bytes        5.16x
+  :func:`str` conversion of a UUID     6.66x
+  ================================  =======
+
+  (Contributed by Yury Selivanov in :gh:`139123`.)
+
+
 Removed
 ========
 
@@ -1158,6 +1192,12 @@ that may require changes to your code.
   :exc:`TypeError`.
   (Contributed by Serhiy Storchaka in :gh:`152587`.)
 
+* :class:`uuid.UUID` now consistently raises :exc:`TypeError` when the
+  *bytes* or *bytes_le* argument is not a :class:`bytes` object.
+  Previously, some invalid inputs raised :exc:`AssertionError` or
+  :exc:`ValueError`.
+  (Contributed by Yury Selivanov in :gh:`139123`.)
+
 * :mod:`xml.dom.minidom` now raises :exc:`~xml.dom.InvalidCharacterErr`
   for a name which is not a valid XML name,
   :exc:`~xml.dom.WrongDocumentErr`

Include/internal/pycore_global_objects_fini_generated.h

@@ -349,6 +349,7 @@ struct _Py_global_strings {
         STRUCT_FOR_ID(byte_size)
         STRUCT_FOR_ID(byteorder)
         STRUCT_FOR_ID(bytes)
+        STRUCT_FOR_ID(bytes_le)
         STRUCT_FOR_ID(bytes_per_sep)
         STRUCT_FOR_ID(c_call)
         STRUCT_FOR_ID(c_exception)
@@ -543,6 +544,7 @@ struct _Py_global_strings {
         STRUCT_FOR_ID(hash_name)
         STRUCT_FOR_ID(header)
         STRUCT_FOR_ID(headers)
+        STRUCT_FOR_ID(hex)
         STRUCT_FOR_ID(hi)
         STRUCT_FOR_ID(hook)
         STRUCT_FOR_ID(host)
@@ -576,13 +578,15 @@ struct _Py_global_strings {
         STRUCT_FOR_ID(insert_comments)
         STRUCT_FOR_ID(insert_pis)
         STRUCT_FOR_ID(instructions)
+        STRUCT_FOR_ID(int)
         STRUCT_FOR_ID(intern)
         STRUCT_FOR_ID(intersection)
         STRUCT_FOR_ID(interval)
         STRUCT_FOR_ID(io)
         STRUCT_FOR_ID(is_compress)
         STRUCT_FOR_ID(is_raw)
         STRUCT_FOR_ID(is_running)
+        STRUCT_FOR_ID(is_safe)
         STRUCT_FOR_ID(is_struct)
         STRUCT_FOR_ID(isatty)
         STRUCT_FOR_ID(isinstance)
@@ -756,6 +760,7 @@ struct _Py_global_strings {
         STRUCT_FOR_ID(query)
         STRUCT_FOR_ID(queuetype)
         STRUCT_FOR_ID(quotetabs)
+        STRUCT_FOR_ID(random_func)
         STRUCT_FOR_ID(raw)
         STRUCT_FOR_ID(read)
         STRUCT_FOR_ID(read1)
@@ -870,6 +875,7 @@ struct _Py_global_strings {
         STRUCT_FOR_ID(threading)
         STRUCT_FOR_ID(throw)
         STRUCT_FOR_ID(time)
+        STRUCT_FOR_ID(time_func)
         STRUCT_FOR_ID(timeout)
         STRUCT_FOR_ID(timer)
         STRUCT_FOR_ID(times)

Include/internal/pycore_global_strings.h

@@ -96,8 +96,8 @@ extern const char* _Py_gitversion(void);
 // Export for '_asyncio' shared extension
 PyAPI_FUNC(int) _Py_IsInterpreterFinalizing(PyInterpreterState *interp);
 
-/* Random */
-extern int _PyOS_URandom(void *buffer, Py_ssize_t size);
+// Export for '_uuid' shared extension
+PyAPI_FUNC(int) _PyOS_URandom(void *buffer, Py_ssize_t size);
 
 // Export for '_random' shared extension
 PyAPI_FUNC(int) _PyOS_URandomNonblock(void *buffer, Py_ssize_t size);