python-ulid 3.0.0__py3-none-any.whl → 3.1.0__py3-none-any.whl

{python_ulid-3.0.0.dist-info → python_ulid-3.1.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
-Metadata-Version: 2.3
+Metadata-Version: 2.4
 Name: python-ulid
-Version: 3.0.0
+Version: 3.1.0
 Summary: Universally unique lexicographically sortable identifier
 Project-URL: Homepage, https://github.com/mdomke/python-ulid
 Project-URL: Documentation, https://python-ulid.readthedocs.io
@@ -22,6 +22,7 @@ Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Software Development :: Libraries
 Requires-Python: >=3.9
 Provides-Extra: pydantic

python_ulid-3.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+ulid/__init__.py,sha256=g9Fb4nyq2mt3wGtLdmv3h9HutFJXLsrv_3HiVM-Qph8,12419
+ulid/__main__.py,sha256=TUo3dkWkJLfzRJyd55nfqGqvv1NcG7fBpsZHIi_p4rw,5421
+ulid/base32.py,sha256=iUE5BGPW5Dul-Eu3ITvcymk8acNkIFAVTlrL12YIPKI,5961
+ulid/constants.py,sha256=lbCLRNQXq8qnOdz_w-nJf_j5dC2X7Gjv-8GJUbs5jX8,503
+ulid/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+python_ulid-3.1.0.dist-info/METADATA,sha256=TM_dpKEq830WTj6mahb6qF_5wiVnL6-Rau-6REqSoSQ,5833
+python_ulid-3.1.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+python_ulid-3.1.0.dist-info/entry_points.txt,sha256=9214ghzfSgS8a-TjjlWDF7bI7KSaeewOCBKn5uz7bdU,50
+python_ulid-3.1.0.dist-info/licenses/LICENSE,sha256=DiDPNhW5yUHIqaKowvX0c1c9xWiI0xW4ji8R9N2NJbw,1056
+python_ulid-3.1.0.dist-info/RECORD,,

{python_ulid-3.0.0.dist-info → python_ulid-3.1.0.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: hatchling 1.25.0
+Generator: hatchling 1.27.0
 Root-Is-Purelib: true
 Tag: py3-none-any

ulid/__init__.py

@@ -6,12 +6,15 @@ import time
 import uuid
 from datetime import datetime
 from datetime import timezone
+from threading import Lock
 from typing import Any
 from typing import cast
 from typing import Generic
 from typing import TYPE_CHECKING
 from typing import TypeVar
 
+from typing_extensions import Self
+
 from ulid import base32
 from ulid import constants
 
@@ -51,11 +54,44 @@ class validate_type(Generic[T]):  # noqa: N801
         return wrapped
 
 
-U = TypeVar("U", bound="ULID")
+class ValueProvider:
+    def __init__(self) -> None:
+        self.lock = Lock()
+        self.prev_timestamp = constants.MIN_TIMESTAMP
+        self.prev_randomness = constants.MIN_RANDOMNESS
+
+    def timestamp(self, value: float | None = None) -> int:
+        if value is None:
+            value = time.time_ns() // constants.NANOSECS_IN_MILLISECS
+        elif isinstance(value, float):
+            value = int(value * constants.MILLISECS_IN_SECS)
+        if value > constants.MAX_TIMESTAMP:
+            raise ValueError("Value exceeds maximum possible timestamp")
+        return value
+
+    def randomness(self) -> bytes:
+        with self.lock:
+            current_timestamp = self.timestamp()
+            if current_timestamp == self.prev_timestamp:
+                if self.prev_randomness == constants.MAX_RANDOMNESS:
+                    raise ValueError("Randomness within same millisecond exhausted")
+                randomness = self.increment_bytes(self.prev_randomness)
+            else:
+                randomness = os.urandom(constants.RANDOMNESS_LEN)
+
+            self.prev_randomness = randomness
+            self.prev_timestamp = current_timestamp
+        return randomness
+
+    def increment_bytes(self, value: bytes) -> bytes:
+        length = len(value)
+        return (int.from_bytes(value, byteorder="big") + 1).to_bytes(length, byteorder="big")
 
 
 @functools.total_ordering
 class ULID:
+    provider = ValueProvider()
+
     """The :class:`ULID` object consists of a timestamp part of 48 bits and of 80 random bits.
 
     .. code-block:: text
@@ -83,13 +119,11 @@ class ULID:
     def __init__(self, value: bytes | None = None) -> None:
         if value is not None and len(value) != constants.BYTES_LEN:
             raise ValueError("ULID has to be exactly 16 bytes long.")
-        self.bytes: bytes = (
-            value or ULID.from_timestamp(time.time_ns() // constants.NANOSECS_IN_MILLISECS).bytes
-        )
+        self.bytes: bytes = value or ULID.from_timestamp(self.provider.timestamp()).bytes
 
     @classmethod
     @validate_type(datetime)
-    def from_datetime(cls: type[U], value: datetime) -> U:
+    def from_datetime(cls, value: datetime) -> Self:
         """Create a new :class:`ULID`-object from a :class:`datetime`. The timestamp part of the
         `ULID` will be set to the corresponding timestamp of the datetime.
 
@@ -103,7 +137,7 @@ class ULID:
 
     @classmethod
     @validate_type(int, float)
-    def from_timestamp(cls: type[U], value: float) -> U:
+    def from_timestamp(cls, value: float) -> Self:
         """Create a new :class:`ULID`-object from a timestamp. The timestamp can be either a
         `float` representing the time in seconds (as it would be returned by :func:`time.time()`)
         or an `int` in milliseconds.
@@ -114,15 +148,13 @@ class ULID:
             >>> ULID.from_timestamp(time.time())
             ULID(01E75QWN5HKQ0JAVX9FG1K4YP4)
         """
-        if isinstance(value, float):
-            value = int(value * constants.MILLISECS_IN_SECS)
-        timestamp = int.to_bytes(value, constants.TIMESTAMP_LEN, "big")
-        randomness = os.urandom(constants.RANDOMNESS_LEN)
+        timestamp = int.to_bytes(cls.provider.timestamp(value), constants.TIMESTAMP_LEN, "big")
+        randomness = cls.provider.randomness()
         return cls.from_bytes(timestamp + randomness)
 
     @classmethod
     @validate_type(uuid.UUID)
-    def from_uuid(cls: type[U], value: uuid.UUID) -> U:
+    def from_uuid(cls, value: uuid.UUID) -> Self:
         """Create a new :class:`ULID`-object from a :class:`uuid.UUID`. The timestamp part will be
         random in that case.
 
@@ -136,37 +168,38 @@ class ULID:
 
     @classmethod
     @validate_type(bytes)
-    def from_bytes(cls: type[U], bytes_: bytes) -> U:
+    def from_bytes(cls, bytes_: bytes) -> Self:
         """Create a new :class:`ULID`-object from sequence of 16 bytes."""
         return cls(bytes_)
 
     @classmethod
     @validate_type(str)
-    def from_hex(cls: type[U], value: str) -> U:
+    def from_hex(cls, value: str) -> Self:
         """Create a new :class:`ULID`-object from 32 character string of hex values."""
         return cls.from_bytes(bytes.fromhex(value))
 
     @classmethod
     @validate_type(str)
-    def from_str(cls: type[U], string: str) -> U:
+    def from_str(cls, string: str) -> Self:
         """Create a new :class:`ULID`-object from a 26 char long string representation."""
         return cls(base32.decode(string))
 
     @classmethod
     @validate_type(int)
-    def from_int(cls: type[U], value: int) -> U:
+    def from_int(cls, value: int) -> Self:
         """Create a new :class:`ULID`-object from an `int`."""
         return cls(int.to_bytes(value, constants.BYTES_LEN, "big"))
 
     @classmethod
-    def parse(cls: type[U], value: Any) -> U:
+    def parse(cls, value: Any) -> Self:
         """Create a new :class:`ULID`-object from a given value.
 
-        .. note:: This method should only be used when the caller is trying to parse a ULID from
-        a value when they're unsure what format/primitive type it will be given in.
+        .. note::
+            This method should only be used when the caller is trying to parse a ULID from
+            a value when they're unsure what format/primitive type it will be given in.
         """
         if isinstance(value, ULID):
-            return cast(U, value)
+            return cast(Self, value)
         if isinstance(value, uuid.UUID):
             return cls.from_uuid(value)
         if isinstance(value, str):
@@ -190,7 +223,7 @@ class ULID:
             return cls.from_bytes(value)
         raise TypeError(f"Cannot parse ULID from type {type(value)}")
 
-    @property
+    @functools.cached_property
     def milliseconds(self) -> int:
         """The timestamp part as epoch time in milliseconds.
 
@@ -201,7 +234,7 @@ class ULID:
         """
         return int.from_bytes(self.bytes[: constants.TIMESTAMP_LEN], byteorder="big")
 
-    @property
+    @functools.cached_property
     def timestamp(self) -> float:
         """The timestamp part as epoch time in seconds.
 
@@ -212,7 +245,7 @@ class ULID:
         """
         return self.milliseconds / constants.MILLISECS_IN_SECS
 
-    @property
+    @functools.cached_property
     def datetime(self) -> datetime:
         """Return the timestamp part as timezone-aware :class:`datetime` in UTC.
 
@@ -223,7 +256,7 @@ class ULID:
         """
         return datetime.fromtimestamp(self.timestamp, timezone.utc)
 
-    @property
+    @functools.cached_property
     def hex(self) -> str:
         """Encode the :class:`ULID`-object as a 32 char sequence of hex values."""
         return self.bytes.hex()
@@ -297,7 +330,11 @@ class ULID:
             core_schema.union_schema([
                 core_schema.is_instance_schema(ULID),
                 core_schema.no_info_plain_validator_function(ULID),
-                core_schema.str_schema(pattern=r"[A-Z0-9]{26}", min_length=26, max_length=26),
+                core_schema.str_schema(
+                    pattern=rf"[0-7][{base32.ENCODE}]{{25}}",
+                    min_length=26,
+                    max_length=26,
+                ),
                 core_schema.bytes_schema(min_length=16, max_length=16),
             ]),
             serialization=core_schema.to_string_ser_schema(
@@ -309,6 +346,7 @@ class ULID:
     def _pydantic_validate(cls, value: Any, handler: ValidatorFunctionWrapHandler) -> Any:
         from pydantic_core import PydanticCustomError
 
+        ulid: ULID
         try:
             if isinstance(value, int):
                 ulid = cls.from_int(value)

ulid/constants.py

@@ -1,6 +1,12 @@
 MILLISECS_IN_SECS = 1000
 NANOSECS_IN_MILLISECS = 1000000
 
+MIN_RANDOMNESS = b"\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00"
+MAX_RANDOMNESS = b"\xff\xff\xff\xff\xff\xff\xff\xff\xff\xff"
+
+MIN_TIMESTAMP = 0
+MAX_TIMESTAMP = 2**48 - 1
+
 TIMESTAMP_LEN = 6
 RANDOMNESS_LEN = 10
 BYTES_LEN = TIMESTAMP_LEN + RANDOMNESS_LEN

python_ulid-3.0.0.dist-info/RECORD

@@ -1,10 +0,0 @@
-ulid/__init__.py,sha256=yoBtXpTz-t8xnfOHtM70-hYIeYKk75ya7t6B6uWILhg,10971
-ulid/__main__.py,sha256=TUo3dkWkJLfzRJyd55nfqGqvv1NcG7fBpsZHIi_p4rw,5421
-ulid/base32.py,sha256=iUE5BGPW5Dul-Eu3ITvcymk8acNkIFAVTlrL12YIPKI,5961
-ulid/constants.py,sha256=tJByGuryoTT_xfECvpMNPNwRvZMp2K_ZlZ7tOLeaXJs,335
-ulid/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-python_ulid-3.0.0.dist-info/METADATA,sha256=82s8fmElXLy5Um_bjqhtZfiXd54YF0TDI2iOlKliLMs,5782
-python_ulid-3.0.0.dist-info/WHEEL,sha256=1yFddiXMmvYK7QYTqtRNtX66WJ0Mz8PYEiEUoOUUxRY,87
-python_ulid-3.0.0.dist-info/entry_points.txt,sha256=9214ghzfSgS8a-TjjlWDF7bI7KSaeewOCBKn5uz7bdU,50
-python_ulid-3.0.0.dist-info/licenses/LICENSE,sha256=DiDPNhW5yUHIqaKowvX0c1c9xWiI0xW4ji8R9N2NJbw,1056
-python_ulid-3.0.0.dist-info/RECORD,,