ulid-transform 0.10.2__cp312-cp312-macosx_14_0_arm64.whl → 0.13.1__cp312-cp312-macosx_14_0_arm64.whl

ulid_transform/__init__.py

@@ -1,21 +1,41 @@
-__version__ = "0.10.2"
+__version__ = "0.13.1"
 
-from .ulid_impl import (
-    bytes_to_ulid,
-    bytes_to_ulid_or_none,
-    ulid_at_time,
-    ulid_hex,
-    ulid_now,
-    ulid_to_bytes,
-    ulid_to_bytes_or_none,
-)
+try:
+    from ._ulid_impl import (
+        bytes_to_ulid,
+        bytes_to_ulid_or_none,
+        ulid_at_time,
+        ulid_at_time_bytes,
+        ulid_hex,
+        ulid_now,
+        ulid_now_bytes,
+        ulid_to_bytes,
+        ulid_to_bytes_or_none,
+        ulid_to_timestamp,
+    )
+except ImportError:
+    from ._py_ulid_impl import (
+        bytes_to_ulid,
+        bytes_to_ulid_or_none,
+        ulid_at_time,
+        ulid_at_time_bytes,
+        ulid_hex,
+        ulid_now,
+        ulid_now_bytes,
+        ulid_to_bytes,
+        ulid_to_bytes_or_none,
+        ulid_to_timestamp,
+    )
 
 __all__ = [
-    "ulid_now",
+    "bytes_to_ulid",
+    "bytes_to_ulid_or_none",
     "ulid_at_time",
+    "ulid_at_time_bytes",
     "ulid_hex",
+    "ulid_now",
+    "ulid_now_bytes",
     "ulid_to_bytes",
-    "bytes_to_ulid",
     "ulid_to_bytes_or_none",
-    "bytes_to_ulid_or_none",
+    "ulid_to_timestamp",
 ]

ulid_transform/__init__.pyi

@@ -0,0 +1,10 @@
+def ulid_hex() -> str: ...
+def ulid_at_time_bytes(timestamp: float) -> bytes: ...
+def ulid_now_bytes() -> bytes: ...
+def ulid_now() -> str: ...
+def ulid_at_time(timestamp: float) -> str: ...
+def ulid_to_bytes(value: str) -> bytes: ...
+def bytes_to_ulid(value: bytes) -> str: ...
+def ulid_to_bytes_or_none(ulid: str | None) -> bytes | None: ...
+def bytes_to_ulid_or_none(ulid_bytes: bytes | None) -> str | None: ...
+def ulid_to_timestamp(ulid: str | bytes) -> int: ...

ulid_transform/{ulid_impl.py → _py_ulid_impl.py}

@@ -280,6 +280,21 @@ def ulid_hex() -> str:
     return f"{int(time()*1000):012x}{getrandbits(80):020x}"
 
 
+def ulid_at_time_bytes(timestamp: float) -> bytes:
+    """Generate an ULID as 16 bytes that will work for a UUID.
+
+    uuid.UUID(bytes=ulid_bytes)
+    """
+    return int(timestamp * 1000).to_bytes(6, byteorder="big") + int(
+        getrandbits(80)
+    ).to_bytes(10, byteorder="big")
+
+
+def ulid_now_bytes() -> bytes:
+    """Generate an ULID as 16 bytes that will work for a UUID."""
+    return ulid_at_time_bytes(time())
+
+
 def ulid_now() -> str:
     """Generate a ULID."""
     return ulid_at_time(time())
@@ -302,10 +317,7 @@ def ulid_at_time(timestamp: float) -> str:
     import ulid
     ulid.parse(ulid_util.ulid())
     """
-    return _encode(
-        int((timestamp) * 1000).to_bytes(6, byteorder="big")
-        + int(getrandbits(80)).to_bytes(10, byteorder="big")
-    )
+    return _encode(ulid_at_time_bytes(timestamp))
 
 
 def _encode(ulid_bytes: bytes) -> str:
@@ -420,34 +432,23 @@ def ulid_to_bytes_or_none(ulid: str | None) -> bytes | None:
         return None
 
 
-def bytes_to_ulid_or_none(_bytes: bytes | None) -> str | None:
+def bytes_to_ulid_or_none(ulid_bytes: bytes | None) -> str | None:
     """Convert bytes to a ulid."""
-    if _bytes is None:
+    if ulid_bytes is None:
         return None
     try:
-        return bytes_to_ulid(_bytes)
+        return bytes_to_ulid(ulid_bytes)
     except ValueError:
         return None
 
 
-try:
-    from ._ulid_impl import (  # type: ignore[no-redef] # noqa: F811 F401 # pragma: no cover
-        _bytes_to_ulid as bytes_to_ulid,
-    )
-    from ._ulid_impl import (  # type: ignore[no-redef] # noqa: F811 F401 # pragma: no cover
-        _bytes_to_ulid_or_none as bytes_to_ulid_or_none,
-    )
-    from ._ulid_impl import (  # type: ignore[no-redef] # noqa: F811 F401 # pragma: no cover
-        _ulid_at_time as ulid_at_time,
-    )
-    from ._ulid_impl import (  # type: ignore[no-redef] # noqa: F811 F401 # pragma: no cover
-        _ulid_now as ulid_now,
-    )
-    from ._ulid_impl import (  # type: ignore[no-redef] # noqa: F811 F401 # pragma: no cover
-        _ulid_to_bytes as ulid_to_bytes,
-    )
-    from ._ulid_impl import (  # type: ignore[no-redef] # noqa: F811 F401 # pragma: no cover
-        _ulid_to_bytes_or_none as ulid_to_bytes_or_none,
-    )
-except ImportError:  # pragma: no cover
-    pass  # pragma: no cover
+def ulid_to_timestamp(ulid: str | bytes) -> int:
+    """
+    Get the timestamp from a ULID.
+    The returned value is in milliseconds since the UNIX epoch.
+    """
+    if not isinstance(ulid, bytes):
+        ulid_bytes = ulid_to_bytes(ulid)
+    else:
+        ulid_bytes = ulid
+    return int.from_bytes(b"\x00\x00" + ulid_bytes[:6], "big")

ulid_transform/_ulid_impl.pyx

@@ -1,41 +1,136 @@
 # distutils: language = c++
-from libcpp.string cimport string
+# cython: language_level=3, c_string_type=str, c_string_encoding=ascii
 
-from time import time
-from typing import Optional
+# The `<bytes>xxx[:N]` syntax is required for two reasons:
+# 1. When working with "ULID bytes", the buffer may contain NULs.
+# 2. When working with ULID text, the buffer is exactly 26 bytes long and not NUL-terminated.
+# See https://github.com/cython/cython/issues/3234
 
-import cython
+from libc.stdint cimport uint8_t, uint64_t
 
 
 cdef extern from "ulid_wrapper.h":
-    string _cpp_ulid_at_time(double timestamp)
-    string _cpp_ulid_to_bytes(const char * ulid_string)
-    string _cpp_ulid()
-    string _cpp_bytes_to_ulid(string ulid_bytes)
+    void _cpp_ulid(char dst[26]) nogil
+    void _cpp_ulid_bytes(uint8_t dst[16]) nogil
+    void _cpp_ulid_at_time(double epoch_time, char dst[26]) nogil
+    void _cpp_ulid_at_time_bytes(double epoch_time, uint8_t dst[16]) nogil
+    void _cpp_ulid_to_bytes(const char ulid_string[26], uint8_t dst[16]) nogil
+    void _cpp_bytes_to_ulid(const uint8_t b[16], char * dst) nogil
+    void _cpp_hexlify_16(const uint8_t b[16], char dst[32]) nogil
+    uint64_t _cpp_bytes_to_timestamp(const uint8_t b[16]) nogil
 
 
-def _ulid_now() -> str:
-    return _cpp_ulid().decode("ascii")
+def ulid_hex() -> str:
+    """Generate a ULID in lowercase hex that will work for a UUID.
 
-def _ulid_at_time(_time: float) -> str:
-    return _cpp_ulid_at_time(_time).decode("ascii")
+    This ulid should not be used for cryptographically secure
+    operations.
 
-def _ulid_to_bytes(ulid_str: str) -> bytes:
-    if len(ulid_str) != 26:
-        raise ValueError(f"ULID must be a 26 character string: {ulid_str}")
-    return _cpp_ulid_to_bytes(ulid_str.encode("ascii"))
+    This string can be converted with https://github.com/ahawker/ulid
 
-def _bytes_to_ulid(ulid_bytes: bytes) -> str:
-    if len(ulid_bytes) != 16:
-        raise ValueError(f"ULID bytes must be 16 bytes: {ulid_bytes!r}")
-    return _cpp_bytes_to_ulid(ulid_bytes).decode("ascii")
+    ulid.from_uuid(uuid.UUID(ulid_hex))
+    """
+    cdef unsigned char ulid_bytes_buf[16]
+    _cpp_ulid_bytes(ulid_bytes_buf)
+    cdef char ulid_hex_buf[32]
+    _cpp_hexlify_16(ulid_bytes_buf, ulid_hex_buf)
+    return <str>ulid_hex_buf[:32]
 
-def _ulid_to_bytes_or_none(ulid_str: Optional[str]) -> Optional[bytes]:
-    if ulid_str is None or len(ulid_str) != 26:
+
+def ulid_now_bytes() -> bytes:
+    """Generate an ULID as 16 bytes that will work for a UUID."""
+    cdef unsigned char ulid_bytes_buf[16]
+    _cpp_ulid_bytes(ulid_bytes_buf)
+    return <bytes>ulid_bytes_buf[:16]
+
+
+def ulid_at_time_bytes(timestamp: float) -> bytes:
+    """Generate an ULID as 16 bytes that will work for a UUID.
+
+    uuid.UUID(bytes=ulid_bytes)
+    """
+    cdef unsigned char ulid_bytes_buf[16]
+    _cpp_ulid_at_time_bytes(timestamp, ulid_bytes_buf)
+    return <bytes>ulid_bytes_buf[:16]
+
+
+def ulid_now() -> str:
+    """Generate a ULID."""
+    cdef char ulid_text_buf[26]
+    _cpp_ulid(ulid_text_buf)
+    return <str>ulid_text_buf[:26]
+
+
+def ulid_at_time(timestamp: float) -> str:
+    """Generate a ULID.
+
+    This ulid should not be used for cryptographically secure
+    operations.
+
+     01AN4Z07BY      79KA1307SR9X4MV3
+    |----------|    |----------------|
+     Timestamp          Randomness
+       48bits             80bits
+
+    This string can be loaded directly with https://github.com/ahawker/ulid
+
+    import ulid_transform as ulid_util
+    import ulid
+    ulid.parse(ulid_util.ulid())
+    """
+    cdef char ulid_text_buf[26]
+    _cpp_ulid_at_time(timestamp, ulid_text_buf)
+    return <str>ulid_text_buf[:26]
+
+
+def ulid_to_bytes(value: str) -> bytes:
+    """Decode a ulid to bytes."""
+    if len(value) != 26:
+        raise ValueError(f"ULID must be a 26 character string: {value}")
+    cdef unsigned char ulid_bytes_buf[16]
+    _cpp_ulid_to_bytes(value, ulid_bytes_buf)
+    return <bytes>ulid_bytes_buf[:16]
+
+
+def bytes_to_ulid(value: bytes) -> str:
+    """Encode bytes to a ulid."""
+    if len(value) != 16:
+        raise ValueError(f"ULID bytes must be 16 bytes: {value!r}")
+    cdef char ulid_text_buf[26]
+    _cpp_bytes_to_ulid(value, ulid_text_buf)
+    return <str>ulid_text_buf[:26]
+
+
+def ulid_to_bytes_or_none(ulid: str | None) -> bytes | None:
+    """Convert an ulid to bytes."""
+    if ulid is None or len(ulid) != 26:
         return None
-    return _cpp_ulid_to_bytes(ulid_str.encode("ascii"))
+    cdef unsigned char ulid_bytes_buf[16]
+    _cpp_ulid_to_bytes(ulid, ulid_bytes_buf)
+    return <bytes>ulid_bytes_buf[:16]
+
 
-def _bytes_to_ulid_or_none(ulid_bytes: Optional[bytes]) -> Optional[str]:
+def bytes_to_ulid_or_none(ulid_bytes: bytes | None) -> str | None:
+    """Convert bytes to a ulid."""
     if ulid_bytes is None or len(ulid_bytes) != 16:
         return None
-    return _cpp_bytes_to_ulid(ulid_bytes).decode("ascii")
+    cdef char ulid_text_buf[26]
+    _cpp_bytes_to_ulid(ulid_bytes, ulid_text_buf)
+    return <str>ulid_text_buf[:26]
+
+
+def ulid_to_timestamp(ulid: str | bytes) -> int:
+    """
+    Get the timestamp from a ULID.
+    The returned value is in milliseconds since the UNIX epoch.
+    """
+    cdef unsigned char ulid_bytes_buf[16]
+    if not isinstance(ulid, bytes):
+        if len(ulid) != 26:
+            raise ValueError(f"ULID must be a 26 character string: {ulid}")
+        _cpp_ulid_to_bytes(ulid, ulid_bytes_buf)
+        return _cpp_bytes_to_timestamp(ulid_bytes_buf)
+    else:
+        if len(ulid) != 16:
+            raise ValueError(f"ULID bytes must be 16 bytes: {ulid!r}")
+        return _cpp_bytes_to_timestamp(ulid)

ulid_transform/ulid_wrapper.cpp

@@ -1,32 +1,94 @@
 #include "ulid_wrapper.h"
 #include "ulid.hh"
 
-using namespace std;
+/**
+* Generate a new text ULID and write it to the provided buffer.
+* The buffer is NOT null-terminated.
+*/
+void _cpp_ulid(char dst[26]) {
+  ulid::ULID ulid;
+  ulid::EncodeTimeSystemClockNow(ulid);
+  ulid::EncodeEntropyRand(ulid);
+  ulid::MarshalTo(ulid, dst);
+}
 
-std::string _cpp_ulid() {
+/**
+* Generate a new binary ULID and write it to the provided buffer.
+*/
+void _cpp_ulid_bytes(uint8_t dst[16]) {
   ulid::ULID ulid;
   ulid::EncodeTimeSystemClockNow(ulid);
   ulid::EncodeEntropyRand(ulid);
-  return ulid::Marshal(ulid);
+  ulid::MarshalBinaryTo(ulid, dst);
+}
+
+/**
+* Generate a new text ULID at the provided epoch time and write it to the provided buffer.
+* The buffer is NOT null-terminated.
+*/
+void _cpp_ulid_at_time(double epoch_time, char dst[26]) {
+  ulid::ULID ulid;
+  ulid::EncodeTimestamp(static_cast<int64_t>(epoch_time*1000), ulid);
+  ulid::EncodeEntropyRand(ulid);
+  ulid::MarshalTo(ulid, dst);
 }
 
-std::string _cpp_ulid_at_time(double epoch_time) {
+/**
+* Generate a new binary ULID at the provided epoch time and write it to the provided buffer.
+*/
+void _cpp_ulid_at_time_bytes(double epoch_time, uint8_t dst[16]) {
   ulid::ULID ulid;
   ulid::EncodeTimestamp(static_cast<int64_t>(epoch_time*1000), ulid);
   ulid::EncodeEntropyRand(ulid);
-  return ulid::Marshal(ulid);
+  ulid::MarshalBinaryTo(ulid, dst);
 }
 
-std::string _cpp_ulid_to_bytes(const char * ulid_string) {
+/**
+* Convert a text ULID to a binary ULID.
+* The buffer passed in must contain at least 26 bytes.
+* Invalid data will result in undefined behavior.
+*/
+void _cpp_ulid_to_bytes(const char * ulid_string, uint8_t dst[16]) {
   ulid::ULID ulid;
   ulid::UnmarshalFrom(ulid_string, ulid);
-  std::vector<uint8_t> data = ulid::MarshalBinary(ulid);
-  std::string str(reinterpret_cast<char *>(data.data()), data.size());
-  return str;
+  ulid::MarshalBinaryTo(ulid, dst);
+}
+
+/**
+* Convert a binary ULID to a text ULID.
+* The buffer passed in must contain at least 16 bytes.
+* The output buffer will NOT be null-terminated.
+*/
+void _cpp_bytes_to_ulid(const uint8_t b[16], char dst[26]) {
+  ulid::ULID ulid;
+  ulid::UnmarshalBinaryFrom(b, ulid);
+  ulid::MarshalTo(ulid, dst);
+}
+
+/**
+* Convert a buffer of exactly 16 bytes to 32 hex characters.
+* The output buffer will NOT be null-terminated.
+*/
+void _cpp_hexlify_16(const uint8_t b[16], char dst[32]) {
+    static const char hexdigits[17] = "0123456789abcdef";
+    int in_index, out_index;
+    for (in_index = out_index = 0; in_index < 16; in_index++) {
+        uint8_t c = b[in_index];
+        dst[out_index++] = hexdigits[c >> 4];
+        dst[out_index++] = hexdigits[c & 0x0f];
+    }
 }
 
-std::string _cpp_bytes_to_ulid(std::string bytes_string) {
-  std::vector<uint8_t> data(bytes_string.begin(), bytes_string.end());
-  ulid::ULID ulid = ulid::UnmarshalBinary(data);
-  return ulid::Marshal(ulid);
+/**
+* Interpret the first 6 bytes of a binary ULID as a timestamp.
+*/
+uint64_t _cpp_bytes_to_timestamp(const uint8_t b[16]) {
+    uint64_t timestamp = 0;
+    timestamp |= static_cast<uint64_t>(b[0]) << 40;
+    timestamp |= static_cast<uint64_t>(b[1]) << 32;
+    timestamp |= static_cast<uint64_t>(b[2]) << 24;
+    timestamp |= static_cast<uint64_t>(b[3]) << 16;
+    timestamp |= static_cast<uint64_t>(b[4]) << 8;
+    timestamp |= static_cast<uint64_t>(b[5]);
+    return timestamp;
 }

ulid_transform/ulid_wrapper.h

@@ -1,11 +1,13 @@
-#include <string>
-
 #ifndef ULID_WRAPPER_H
 #define ULID_WRAPPER_H
+#include <stdint.h>
 
-std::string _cpp_ulid();
-std::string _cpp_ulid_at_time(double timestamp);
-std::string _cpp_ulid_to_bytes(const char * ulid_string);
-std::string _cpp_bytes_to_ulid(std::string bytes_string);
-
+void _cpp_ulid(char dst[26]);
+void _cpp_ulid_bytes(uint8_t dst[16]);
+void _cpp_ulid_at_time(double epoch_time, char dst[26]);
+void _cpp_ulid_at_time_bytes(double epoch_time, uint8_t dst[16]);
+void _cpp_ulid_to_bytes(const char * ulid_string, uint8_t dst[16]);
+void _cpp_bytes_to_ulid(const uint8_t b[16], char dst[26]);
+void _cpp_hexlify_16(const uint8_t b[16], char dst[32]);
+uint64_t _cpp_bytes_to_timestamp(const uint8_t b[16]);
 #endif

{ulid_transform-0.10.2.dist-info → ulid_transform-0.13.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: ulid-transform
-Version: 0.10.2
+Version: 0.13.1
 Summary: Create and transform ULIDs
 Home-page: https://github.com/bdraco/ulid-transform
 License: MIT

ulid_transform-0.13.1.dist-info/RECORD

@@ -0,0 +1,15 @@
+ulid_transform/_ulid_impl.pyx,sha256=C64Ca_ydLglYYadIVgrQvMMVKPbpc6nfaOHTFK66ORU,4441
+ulid_transform/__init__.pyi,sha256=eRmwQvXnwgj1mhdVokznDZVwOl2Xr_5tEAertTjkI5s,468
+ulid_transform/ulid.hh,sha256=cCMqxiPh9iw5hOxvu4czd2I6Rgnl7z9hc9c5a78qLLI,295
+ulid_transform/__init__.py,sha256=hRTpkzXAE-Z3sy9NNxkssew2iau-8OrhEbz0pJ01skI,854
+ulid_transform/ulid_uint128.hh,sha256=W_EkG8AmjhKdzkl6Wz3t5XY11sE7LgCqKBmhdxjjQ90,14815
+ulid_transform/ulid_wrapper.cpp,sha256=om3LXOJRI1zksRm3p03hFecssOdHlW0GGo8VJ9j3fIE,2798
+ulid_transform/_py_ulid_impl.py,sha256=4fiV3uTS9JI8mTKPGJDKaBQIB4R9jYRjTSSCmYID_5I,10224
+ulid_transform/ulid_struct.hh,sha256=vPUTL0wOvm0YRtLbuVZCYLyDaFmTA_WdLASQ786n4FQ,19309
+ulid_transform/_ulid_impl.cpython-312-darwin.so,sha256=Xj3DndA7pzIG9rMQ4iBihXY-T9fZltzdfZJBNGSB6Fg,103168
+ulid_transform/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+ulid_transform/ulid_wrapper.h,sha256=uDDC1AY2BkyHRkXoKso_qHK7IVrmkyZwqE2g7JtYdRQ,506
+ulid_transform-0.13.1.dist-info/RECORD,,
+ulid_transform-0.13.1.dist-info/LICENSE,sha256=gieJjxNidEKH1VXLqbV9tuqnmcnqvMqt5xcmktkn5I4,1072
+ulid_transform-0.13.1.dist-info/WHEEL,sha256=yhFWDruQeL16y7AZmR-YzCRfHXG6441RPQ3U5xtqaLo,106
+ulid_transform-0.13.1.dist-info/METADATA,sha256=LMB1c85FCU4KgDAl5v_F5ikJuHNmGWHc5aXMOIYNuyY,5389