picoid 0.0.1__tar.gz

picoid-0.0.1/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, picops
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

picoid-0.0.1/MANIFEST.in

@@ -0,0 +1,4 @@
+include requirements.txt
+include LICENSE
+recursive-include src *.py *.pyx *.pxd *.pyi *.pxi 
+recursive-include src *.c *.cpp *.h *.hpp

picoid-0.0.1/PKG-INFO

@@ -0,0 +1,20 @@
+Metadata-Version: 2.4
+Name: picoid
+Version: 0.0.1
+Summary: Low Level UUID Implementation for Python
+Author-email: ckirua <aquipongoalgo.dsz@gmail.com>
+License-Expression: BSD-3-Clause
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: setuptools>=80.9.0
+Requires-Dist: Cython
+Requires-Dist: picobuild==0.0.5b1
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Requires-Dist: sphinx>=7.0.0; extra == "dev"
+Requires-Dist: sphinx-rtd-theme>=2.0.0; extra == "dev"
+Dynamic: license-file
+
+# picoid
+Low Level UUID Implementation for Python

picoid-0.0.1/README.md

@@ -0,0 +1,2 @@
+# picoid
+Low Level UUID Implementation for Python

picoid-0.0.1/pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = [
+    "setuptools",
+    "wheel",
+    "Cython",
+    "picobuild==0.0.5b1"
+]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "picoid"
+description = "Low Level UUID Implementation for Python"
+readme = "README.md"
+license = "BSD-3-Clause"
+license-files = ["LICENSE"]
+authors = [{ name = "ckirua", email = "aquipongoalgo.dsz@gmail.com" }]
+requires-python = ">=3.13"
+dynamic = ["version"]
+dependencies = [
+    "setuptools>=80.9.0",
+    "Cython",
+    "picobuild==0.0.5b1",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0.0", "sphinx>=7.0.0", "sphinx-rtd-theme>=2.0.0"]
+
+[tool.setuptools]
+include-package-data = true
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.dynamic]
+version = { attr = "picoid.__about__.__version__" }
+
+[tool.cibuildwheel]
+enable = ["cpython-freethreading"]
+build = "cp313-* cp314-* cp313t-* cp314t-*"
+build-frontend = "build[uv]"

picoid-0.0.1/requirements.txt

@@ -0,0 +1,3 @@
+picobuild==0.0.5b1
+pytest
+Cython>=3.0.0

picoid-0.0.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

picoid-0.0.1/setup.py

@@ -0,0 +1,25 @@
+from picobuild import Extension, cythonize, get_cython_build_dir, setup
+
+extensions = cythonize(
+    Extension(
+        "picoid.*",
+        ["src/picoid/*.pyx", "src/picoid/uuid.c"],
+        extra_compile_args=[
+            "-O2",
+            "-march=native",
+            "-Wno-unused-function",
+            "-Wno-unused-variable",
+        ],
+        language="c",
+    ),
+    compiler_directives={"language_level": 3},
+    build_dir=get_cython_build_dir(),
+)
+
+
+if __name__ == "__main__":
+    setup(
+        name="picoid",
+        version="0.0.1",
+        ext_modules=extensions,
+    )

picoid-0.0.1/src/picoid/__about__.py

@@ -0,0 +1,3 @@
+"""Package version for picoid."""
+
+__version__ = "0.0.1"

picoid-0.0.1/src/picoid/__init__.pxd

@@ -0,0 +1,2 @@
+# Cython-only: for other .pyx/.pxd to cimport picoid
+from .picoid cimport UUID, randstr_16, uuid4

picoid-0.0.1/src/picoid/__init__.py

@@ -0,0 +1,12 @@
+"""
+Low-level UUID implementation for Python.
+
+Exposes UUID (compatible with stdlib uuid.UUID), uuid4(), and randstr_16().
+"""
+
+from typing import Tuple
+
+from .__about__ import __version__
+from .picoid import UUID, randstr_16, uuid4
+
+__all__: Tuple[str, ...] = ("UUID", "__version__", "randstr_16", "uuid4")

picoid-0.0.1/src/picoid/hex.h

@@ -0,0 +1,47 @@
+/* Copyright (C) 2016-present the asyncpg authors and contributors
+ * <see AUTHORS file>
+ *
+ * This module is part of asyncpg and is released under
+ * the Apache 2.0 License: http://www.apache.org/licenses/LICENSE-2.0
+ */
+
+#pragma once
+
+#define HEX_PRELUDE const char *__hexm = "0123456789abcdef";
+
+#define HEX_1_BYTE(buf, dest)                                                  \
+  {                                                                            \
+    char byte = (buf)[0];                                                      \
+    (dest)[0] = __hexm[(byte >> 4) & 0x0F];                                    \
+    (dest)[1] = __hexm[byte & 0x0F];                                            \
+  }
+
+#define HEX_2_BYTES(buf, dest)                                                 \
+  {HEX_1_BYTE(buf, dest) HEX_1_BYTE(buf + 1, dest + 2)}
+
+#define HEX_4_BYTES(buf, dest)                                                 \
+  {HEX_2_BYTES(buf, dest) HEX_2_BYTES(buf + 2, dest + 4)}
+
+#define HEX_8_BYTES(buf, dest)                                                 \
+  {HEX_4_BYTES(buf, dest) HEX_4_BYTES(buf + 4, dest + 8)}
+
+static inline void uuid_to_str(const char *source, char *dest) {
+  HEX_PRELUDE
+
+  HEX_4_BYTES(source, dest)
+  dest[8] = '-';
+  HEX_2_BYTES(source + 4, dest + 9)
+  dest[13] = '-';
+  HEX_2_BYTES(source + 6, dest + 14)
+  dest[18] = '-';
+  HEX_2_BYTES(source + 8, dest + 19)
+  dest[23] = '-';
+  HEX_4_BYTES(source + 10, dest + 24)
+  HEX_2_BYTES(source + 14, dest + 32)
+}
+
+static inline void uuid_to_hex(const char *source, char *dest) {
+  HEX_PRELUDE
+  HEX_8_BYTES(source, dest)
+  HEX_8_BYTES(source + 8, dest + 16)
+}

picoid-0.0.1/src/picoid/picoid.pxd

@@ -0,0 +1,38 @@
+# cython: language_level=3
+
+cimport cpython
+cimport cython
+from libc.stdint cimport int8_t, uint8_t
+from libc.string cimport memcmp, memcpy
+
+
+cdef extern from "Python.h":
+    int PyUnicode_1BYTE_KIND
+    const char* PyUnicode_AsUTF8AndSize(object unicode, Py_ssize_t *size) except NULL
+    object PyUnicode_FromKindAndData(int kind, const void *buffer, Py_ssize_t size)
+    object PyBytes_FromStringAndSize(const char *s, Py_ssize_t len)
+
+cdef extern from "hex.h":
+    cdef void uuid_to_str(const char *source, char *dest)
+    cdef void uuid_to_hex(const char *source, char *dest)
+
+cdef extern from "uuid.h":
+    cdef void c_uuid4(unsigned char* dest) nogil
+
+
+cdef class __UUIDReplaceMe:
+    pass
+
+@cython.final
+@cython.no_gc_clear
+cdef class UUID(__UUIDReplaceMe):
+    cdef char[16] _data
+    cdef object _int
+    cdef object _hash
+
+
+cdef UUID uuid_from_buf(const char *buf)
+cdef void uuid_bytes_from_str(str u, char *out)
+
+cpdef bytes randstr_16()
+cpdef UUID uuid4()

picoid-0.0.1/src/picoid/picoid.pyi

@@ -0,0 +1,85 @@
+import uuid
+from typing import Any, Tuple, Union
+
+class UUID(uuid.UUID):
+    """
+    UUID type compatible with stdlib uuid.UUID, with fast C-backed storage.
+
+    Args:
+        - inp: A hyphenated UUID string (32 hex chars with optional hyphens)
+              or exactly 16 bytes.
+
+    Returns:
+        None (constructor).
+    """
+
+    def __init__(self, inp: Union[str, bytes]) -> None: ...
+    @property
+    def bytes(self) -> bytes: ...
+    @property
+    def int(self) -> int: ...
+    @property
+    def is_safe(self) -> uuid.SafeUUID: ...
+    def __str__(self) -> str: ...
+    @property
+    def hex(self) -> str: ...
+    def __repr__(self) -> str: ...
+    def __reduce__(self) -> Tuple[type, Tuple[bytes]]: ...
+    def __eq__(self, other: Any) -> bool: ...
+    def __ne__(self, other: Any) -> bool: ...
+    def __lt__(self, other: Any) -> bool: ...
+    def __gt__(self, other: Any) -> bool: ...
+    def __le__(self, other: Any) -> bool: ...
+    def __ge__(self, other: Any) -> bool: ...
+    def __hash__(self) -> int: ...
+    def __int__(self) -> int: ...
+    @property
+    def bytes_le(self) -> bytes: ...
+    @property
+    def fields(self) -> Tuple[int, int, int, int, int, int]: ...
+    @property
+    def time_low(self) -> int: ...
+    @property
+    def time_mid(self) -> int: ...
+    @property
+    def time_hi_version(self) -> int: ...
+    @property
+    def clock_seq_hi_variant(self) -> int: ...
+    @property
+    def clock_seq_low(self) -> int: ...
+    @property
+    def time(self) -> int: ...
+    @property
+    def clock_seq(self) -> int: ...
+    @property
+    def node(self) -> int: ...
+    @property
+    def urn(self) -> str: ...
+    @property
+    def variant(self) -> uuid.UUID: ...
+    @property
+    def version(self) -> int: ...
+
+def randstr_16() -> bytes:
+    """
+    Return 16 random bytes with UUID4 version/variant bits set.
+
+    Args:
+        (none)
+
+    Returns:
+        16 random bytes with UUID4 version/variant bits set (bytes).
+    """
+    ...
+
+def uuid4() -> UUID:
+    """
+    Generate a random UUID (version 4).
+
+    Args:
+        (none)
+
+    Returns:
+        A new random UUID4 instance (UUID).
+    """
+    ...

picoid-0.0.1/src/picoid/picoid.pyx

@@ -0,0 +1,377 @@
+# Copyright (C) 2016-present the asyncpg authors and contributors
+# <see AUTHORS file>
+#
+# This module is part of asyncpg and is released under
+# the Apache 2.0 License: http://www.apache.org/licenses/LICENSE-2.0
+
+"""
+Cython implementation of UUID, uuid4, and randstr_16.
+
+Provides a fast UUID type compatible with stdlib uuid.UUID and helpers
+for generating random UUIDs or 16-byte values.
+"""
+
+import uuid
+
+cimport cpython
+cimport cython
+from libc.stdint cimport int8_t, uint8_t
+from libc.string cimport memcmp, memcpy
+
+
+cdef extern from "Python.h":
+    const char* PyUnicode_AsUTF8AndSize(
+        object unicode, Py_ssize_t *size) except NULL
+    object PyUnicode_FromKindAndData(
+        int kind, const void *buffer, Py_ssize_t size)
+    object PyBytes_FromStringAndSize(const char *s, Py_ssize_t len)
+        
+cdef extern from "hex.h":
+    cdef void uuid_to_str(const char *source, char *dest)
+    cdef void uuid_to_hex(const char *source, char *dest)
+
+cdef extern from "uuid.h":
+    void c_uuid4(unsigned char* dest) nogil
+
+
+cdef char[256] _hextable
+_hextable[:] = [
+    -1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,
+    -1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,
+    -1,-1, 0,1,2,3,4,5,6,7,8,9,-1,-1,-1,-1,-1,-1,-1,10,11,12,13,14,15,-1,
+    -1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,
+    -1,-1,10,11,12,13,14,15,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,
+    -1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,
+    -1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,
+    -1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,
+    -1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,
+    -1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,
+    -1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1
+]
+
+
+cdef std_UUID = uuid.UUID
+
+
+cdef void uuid_bytes_from_str(str u, char *out):
+    cdef:
+        const char *orig_buf
+        Py_ssize_t size
+        unsigned char ch
+        uint8_t acc, part, acc_set
+        int i, j
+
+    orig_buf = PyUnicode_AsUTF8AndSize(u, &size)
+    if size > 36 or size < 32:
+        raise ValueError(
+            f'invalid UUID {u!r}: '
+            f'length must be between 32..36 characters, got {size}')
+
+    acc_set = 0
+    j = 0
+    for i in range(size):
+        ch = <unsigned char>orig_buf[i]
+        if ch == <unsigned char>b'-':
+            continue
+
+        part = <uint8_t><int8_t>_hextable[ch]
+        if part == <uint8_t>-1:
+            if ch >= 0x20 and ch <= 0x7e:
+                raise ValueError(
+                    f'invalid UUID {u!r}: unexpected character {chr(ch)!r}')
+            else:
+                raise ValueError('invalid UUID {u!r}: unexpected character')
+
+        if acc_set:
+            acc |= part
+            out[j] = <char>acc
+            acc_set = 0
+            j += 1
+        else:
+            acc = <uint8_t>(part << 4)
+            acc_set = 1
+
+        if j > 16 or (j == 16 and acc_set):
+            raise ValueError(
+                f'invalid UUID {u!r}: decodes to more than 16 bytes')
+
+    if j != 16:
+        raise ValueError(
+            f'invalid UUID {u!r}: decodes to less than 16 bytes')
+
+
+cdef class __UUIDReplaceMe:
+    pass
+
+
+cdef UUID uuid_from_buf(const char *buf):
+    cdef:
+        UUID u = UUID.__new__(UUID)
+    memcpy(u._data, buf, 16)
+    return u
+
+@cython.final
+@cython.no_gc_clear
+cdef class UUID(__UUIDReplaceMe):
+    """
+    UUID type compatible with stdlib uuid.UUID, with fast C-backed storage.
+
+    Args:
+        - inp: A hyphenated UUID string (32 hex chars with optional hyphens)
+              or exactly 16 bytes.
+
+    Returns:
+        None (constructor).
+    """
+
+    def __cinit__(self):
+        self._int = None
+        self._hash = None
+
+    def __init__(self, inp):
+        cdef:
+            char *buf
+            Py_ssize_t size
+
+        if cpython.PyBytes_Check(inp):
+            cpython.PyBytes_AsStringAndSize(inp, &buf, &size)
+            if size != 16:
+                raise ValueError(f'16 bytes were expected, got {size}')
+            memcpy(self._data, buf, 16)
+
+        elif cpython.PyUnicode_Check(inp):
+            uuid_bytes_from_str(inp, self._data)
+        else:
+            raise TypeError(f'a bytes or str object expected, got {inp!r}')
+
+    @property
+    def bytes(self):
+        return cpython.PyBytes_FromStringAndSize(self._data, 16)
+
+    @property
+    def int(self):
+        if self._int is None:
+            # The cache is important because `self.int` can be
+            # used multiple times by __hash__ etc.
+            #
+            # The or 0 works around a bug interaction between cpython
+            # 3.10 and earlier and Cython ~3.0.11 in which
+            # int.from_bytes returns a "non-canonical 0" and then
+            # # Cython's implementation of & mishandles it.
+            # # See cython/cython#6480.
+            self._int = int.from_bytes(self.bytes, 'big') or 0
+        return self._int
+
+    @property
+    def is_safe(self):
+        return uuid.SafeUUID.unknown
+
+    def __str__(self):
+        cdef char[36] out
+        uuid_to_str(self._data, out)
+        return PyUnicode_FromKindAndData(PyUnicode_1BYTE_KIND, <void*>out, 36)
+
+    @property
+    def hex(self):
+        cdef char[32] out
+        uuid_to_hex(self._data, out)
+        return PyUnicode_FromKindAndData(PyUnicode_1BYTE_KIND, <void*>out, 32)
+
+    def __repr__(self):
+        return f"UUID('{self}')"
+
+    def __reduce__(self):
+        return (type(self), (self.bytes,))
+
+    def __eq__(self, other):
+        if type(other) is UUID:
+            return memcmp(self._data, (<UUID>other)._data, 16) == 0
+        if isinstance(other, std_UUID):
+            return self.int == other.int
+        return NotImplemented
+
+    def __ne__(self, other):
+        if type(other) is UUID:
+            return memcmp(self._data, (<UUID>other)._data, 16) != 0
+        if isinstance(other, std_UUID):
+            return self.int != other.int
+        return NotImplemented
+
+    def __lt__(self, other):
+        if type(other) is UUID:
+            return memcmp(self._data, (<UUID>other)._data, 16) < 0
+        if isinstance(other, std_UUID):
+            return self.int < other.int
+        return NotImplemented
+
+    def __gt__(self, other):
+        if type(other) is UUID:
+            return memcmp(self._data, (<UUID>other)._data, 16) > 0
+        if isinstance(other, std_UUID):
+            return self.int > other.int
+        return NotImplemented
+
+    def __le__(self, other):
+        if type(other) is UUID:
+            return memcmp(self._data, (<UUID>other)._data, 16) <= 0
+        if isinstance(other, std_UUID):
+            return self.int <= other.int
+        return NotImplemented
+
+    def __ge__(self, other):
+        if type(other) is UUID:
+            return memcmp(self._data, (<UUID>other)._data, 16) >= 0
+        if isinstance(other, std_UUID):
+            return self.int >= other.int
+        return NotImplemented
+
+    def __hash__(self):
+        # In EdgeDB every schema object has a uuid and there are
+        # huge hash-maps of them. We want UUID.__hash__ to be
+        # as fast as possible.
+        if self._hash is not None:
+            return self._hash
+
+        self._hash = hash(self.int)
+        return self._hash
+
+    def __int__(self):
+        return self.int
+
+    @property
+    def bytes_le(self):
+        bytes = self.bytes
+        return (bytes[4-1::-1] + bytes[6-1:4-1:-1] + bytes[8-1:6-1:-1] +
+                bytes[8:])
+
+    @property
+    def fields(self):
+        return (self.time_low, self.time_mid, self.time_hi_version,
+                self.clock_seq_hi_variant, self.clock_seq_low, self.node)
+
+    @property
+    def time_low(self):
+        return self.int >> 96
+
+    @property
+    def time_mid(self):
+        return (self.int >> 80) & 0xffff
+
+    @property
+    def time_hi_version(self):
+        return (self.int >> 64) & 0xffff
+
+    @property
+    def clock_seq_hi_variant(self):
+        return (self.int >> 56) & 0xff
+
+    @property
+    def clock_seq_low(self):
+        return (self.int >> 48) & 0xff
+
+    @property
+    def time(self):
+        return (((self.time_hi_version & 0x0fff) << 48) |
+                (self.time_mid << 32) | self.time_low)
+
+    @property
+    def clock_seq(self):
+        return (((self.clock_seq_hi_variant & 0x3f) << 8) |
+                self.clock_seq_low)
+
+    @property
+    def node(self):
+        return self.int & 0xffffffffffff
+
+    @property
+    def urn(self):
+        return 'urn:uuid:' + str(self)
+
+    @property
+    def variant(self):
+        if not self.int & (0x8000 << 48):
+            return uuid.RESERVED_NCS
+        elif not self.int & (0x4000 << 48):
+            return uuid.RFC_4122
+        elif not self.int & (0x2000 << 48):
+            return uuid.RESERVED_MICROSOFT
+        else:
+            return uuid.RESERVED_FUTURE
+
+    @property
+    def version(self):
+        # The version bits are only meaningful for RFC 4122 UUIDs.
+        if self.variant == uuid.RFC_4122:
+            return int((self.int >> 76) & 0xf)
+
+# <hack>
+# In order for `isinstance(pgproto.UUID, uuid.UUID)` to work,
+# patch __bases__ and __mro__ by injecting `uuid.UUID`.
+#
+# We apply brute-force here because the following pattern stopped
+# working with Python 3.8:
+#
+#   cdef class OurUUID:
+#       ...
+#
+#   class UUID(OurUUID, uuid.UUID):
+#       ...
+#
+# With Python 3.8 it now produces
+#
+#   "TypeError: multiple bases have instance lay-out conflict"
+#
+# error.  Maybe it's possible to fix this some other way, but
+# the best solution possible would be to just contribute our
+# faster UUID to the standard library and not have this problem
+# at all.  For now this hack is pretty safe and should be
+# compatible with future Pythons for long enough.
+#
+assert UUID.__bases__[0] is __UUIDReplaceMe
+assert UUID.__mro__[1] is __UUIDReplaceMe
+cpython.Py_INCREF(std_UUID)
+cpython.PyTuple_SET_ITEM(UUID.__bases__, 0, std_UUID)
+cpython.Py_INCREF(std_UUID)
+cpython.PyTuple_SET_ITEM(UUID.__mro__, 1, std_UUID)
+# </hack>
+
+
+cdef pg_UUID = UUID
+
+
+
+cpdef bytes randstr_16():
+    """
+    Return 16 random bytes with UUID4 version/variant bits set.
+
+    Args:
+        (none)
+
+    Returns:
+        16 random bytes with UUID4 version/variant bits set (bytes).
+    """
+    cdef:
+        unsigned char dest[16]
+        bytes result
+    with nogil:
+        c_uuid4(dest)
+    result = PyBytes_FromStringAndSize(<char*>dest, 16)
+    return result
+
+cpdef UUID uuid4():
+    """
+    Generate a random UUID (version 4).
+
+    Args:
+        (none)
+
+    Returns:
+        A new random UUID4 instance (UUID).
+    """
+    cdef:
+        unsigned char dest[16]
+        UUID result
+    with nogil:
+        c_uuid4(dest)
+    result = uuid_from_buf(<const char *>dest)
+    return result

picoid-0.0.1/src/picoid/uuid.c

@@ -0,0 +1,69 @@
+#include <stdint.h>
+#include <string.h>
+#include <stdatomic.h>
+#include <stdlib.h>
+
+#ifdef _WIN32
+    #include <windows.h>
+    #include <wincrypt.h>
+    static HCRYPTPROV hProvider = 0;
+#else
+    #include <fcntl.h>
+    #include <unistd.h>
+    #include <errno.h>
+    static int urandom_fd = -1;
+#endif
+
+#define UUID_SIZE 16
+#define BUFFER_SIZE 8192  // 8KB buffer (512 UUIDs)
+static unsigned char random_buffer[BUFFER_SIZE];
+static _Atomic size_t buffer_pos = BUFFER_SIZE;  // Start empty to force initial fill
+
+static void fill_buffer(void) {
+    #ifdef _WIN32
+        CryptGenRandom(hProvider, BUFFER_SIZE, random_buffer);
+    #else
+        if (urandom_fd != -1) {
+            ssize_t bytes_read = read(urandom_fd, random_buffer, BUFFER_SIZE);
+            if (bytes_read != BUFFER_SIZE) {
+                // Handle error - could not read enough random bytes
+                exit(1);
+            }
+        }
+    #endif
+    buffer_pos = 0;
+}
+
+static void __attribute__((constructor)) init_rng(void) {
+    #ifdef _WIN32
+        CryptAcquireContext(&hProvider, NULL, NULL, PROV_RSA_FULL, CRYPT_VERIFYCONTEXT);
+    #else
+        urandom_fd = open("/dev/urandom", O_RDONLY);
+    #endif
+    fill_buffer();  // Initial fill
+}
+
+static void __attribute__((destructor)) cleanup_rng(void) {
+    #ifdef _WIN32
+        if (hProvider) CryptReleaseContext(hProvider, 0);
+    #else
+        if (urandom_fd != -1) close(urandom_fd);
+    #endif
+}
+
+void c_uuid4(uint8_t uuid[UUID_SIZE]) {
+    size_t current_pos = atomic_fetch_add(&buffer_pos, UUID_SIZE);
+    
+    // Check if we need to refill
+    if (current_pos + UUID_SIZE > BUFFER_SIZE) {
+        fill_buffer();
+        current_pos = atomic_fetch_add(&buffer_pos, UUID_SIZE);
+    }
+    
+    // Copy bytes from buffer
+    memcpy(uuid, random_buffer + current_pos, UUID_SIZE);
+
+    // Set version and variant
+    uuid[6] = (uuid[6] & 0x0F) | 0x40;
+    uuid[8] = (uuid[8] & 0x3F) | 0x80;
+}

picoid-0.0.1/src/picoid/uuid.h

@@ -0,0 +1,8 @@
+#pragma once
+
+#include <stdint.h>
+
+#define UUID_SIZE 16
+
+// Function to generate a random UUID (version 4)
+void c_uuid4(uint8_t uuid[UUID_SIZE]);

picoid-0.0.1/src/picoid/uuid.pxd

@@ -0,0 +1,16 @@
+cdef extern from "uuid.h":
+    cdef void c_uuid4(unsigned char* uuid)
+
+################################################################################
+# Copyright (C) 2016-present the asyncpg authors and contributors
+# <see AUTHORS file>
+#
+# This module is part of asyncpg and is released under
+# the Apache 2.0 License: http://www.apache.org/licenses/LICENSE-2.0
+
+cdef extern from "hex.h":
+    cdef void uuid_to_str(const char *source, char *dest)
+    cdef void uuid_to_hex(const char *source, char *dest)
+    # cdef void uuid_to_int(const char *source, unsigned long long *dest)
+
+################################################################################

picoid-0.0.1/src/picoid.egg-info/PKG-INFO

@@ -0,0 +1,20 @@
+Metadata-Version: 2.4
+Name: picoid
+Version: 0.0.1
+Summary: Low Level UUID Implementation for Python
+Author-email: ckirua <aquipongoalgo.dsz@gmail.com>
+License-Expression: BSD-3-Clause
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: setuptools>=80.9.0
+Requires-Dist: Cython
+Requires-Dist: picobuild==0.0.5b1
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Requires-Dist: sphinx>=7.0.0; extra == "dev"
+Requires-Dist: sphinx-rtd-theme>=2.0.0; extra == "dev"
+Dynamic: license-file
+
+# picoid
+Low Level UUID Implementation for Python

picoid-0.0.1/src/picoid.egg-info/SOURCES.txt

@@ -0,0 +1,22 @@
+LICENSE
+MANIFEST.in
+README.md
+pyproject.toml
+requirements.txt
+setup.py
+src/picoid/__about__.py
+src/picoid/__init__.pxd
+src/picoid/__init__.py
+src/picoid/hex.h
+src/picoid/picoid.pxd
+src/picoid/picoid.pyi
+src/picoid/picoid.pyx
+src/picoid/uuid.c
+src/picoid/uuid.h
+src/picoid/uuid.pxd
+src/picoid.egg-info/PKG-INFO
+src/picoid.egg-info/SOURCES.txt
+src/picoid.egg-info/dependency_links.txt
+src/picoid.egg-info/requires.txt
+src/picoid.egg-info/top_level.txt
+tests/test_picoid.py

picoid-0.0.1/src/picoid.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

picoid-0.0.1/src/picoid.egg-info/requires.txt

@@ -0,0 +1,8 @@
+setuptools>=80.9.0
+Cython
+picobuild==0.0.5b1
+
+[dev]
+pytest>=8.0.0
+sphinx>=7.0.0
+sphinx-rtd-theme>=2.0.0

picoid-0.0.1/src/picoid.egg-info/top_level.txt

@@ -0,0 +1 @@
+picoid

picoid-0.0.1/tests/test_picoid.py

@@ -0,0 +1,31 @@
+"""Minimal pytest tests for picoid: every exported name works as expected."""
+
+import pytest
+
+import picoid
+
+
+def test_all_exported_names_are_available() -> None:
+    """Every name in __all__ is importable from picoid and is usable."""
+    assert hasattr(picoid, "__all__")
+    assert isinstance(picoid.__all__, tuple)
+    assert all(isinstance(name, str) for name in picoid.__all__)
+    for name in picoid.__all__:
+        assert hasattr(
+            picoid, name
+        ), f"picoid.__all__ contains {name!r} but picoid has no attribute {name!r}"
+
+
+def test_version() -> None:
+    """__version__ is a non-empty string."""
+    assert hasattr(picoid, "__version__")
+    v = picoid.__version__
+    assert isinstance(v, str)
+    assert len(v) > 0
+
+
+def test_import_from_picoid() -> None:
+    """All __all__ names can be imported via 'from picoid import ...'."""
+    for name in picoid.__all__:
+        module = __import__("picoid", fromlist=[name])
+        assert hasattr(module, name), f"from picoid import {name!r} failed"