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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: python-ulid
-Version: 2.6.0
+Version: 3.0.0
 Summary: Universally unique lexicographically sortable identifier
 Project-URL: Homepage, https://github.com/mdomke/python-ulid
 Project-URL: Documentation, https://python-ulid.readthedocs.io

python_ulid-3.0.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+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,,

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

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

ulid/__init__.py

@@ -4,10 +4,10 @@ import functools
 import os
 import time
 import uuid
-from collections.abc import Callable
 from datetime import datetime
 from datetime import timezone
 from typing import Any
+from typing import cast
 from typing import Generic
 from typing import TYPE_CHECKING
 from typing import TypeVar
@@ -17,6 +17,8 @@ from ulid import constants
 
 
 if TYPE_CHECKING:  # pragma: no cover
+    from collections.abc import Callable
+
     from pydantic import GetCoreSchemaHandler
     from pydantic import ValidatorFunctionWrapHandler
     from pydantic_core import CoreSchema
@@ -29,7 +31,6 @@ except ImportError:  # pragma: no cover
 
 __version__ = version("python-ulid")
 
-
 T = TypeVar("T", bound=type)
 R = TypeVar("R")
 
@@ -44,7 +45,7 @@ class validate_type(Generic[T]):  # noqa: N801
             if not isinstance(value, self.types):
                 message = "Value has to be of type "
                 message += " or ".join([t.__name__ for t in self.types])
-                raise ValueError(message)
+                raise TypeError(message)
             return func(cls, value)
 
         return wrapped
@@ -74,23 +75,17 @@ class ULID:
 
     Args:
         value (bytes, None):  A sequence of 16 bytes representing an encoded ULID.
-        validate (bool): If set to `True` validate if the timestamp part is valid.
 
     Raises:
         ValueError: If the provided value is not a valid encoded ULID.
     """
 
-    def __init__(self, value: bytes | None = None, validate: bool = True) -> None:
+    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
         )
-        if value is not None and validate:
-            try:
-                self.datetime  # noqa: B018
-            except ValueError as err:
-                raise ValueError("ULID timestamp is out of range.") from err
 
     @classmethod
     @validate_type(datetime)
@@ -108,7 +103,7 @@ class ULID:
 
     @classmethod
     @validate_type(int, float)
-    def from_timestamp(cls: type[U], value: int | float) -> U:
+    def from_timestamp(cls: type[U], value: float) -> U:
         """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.
@@ -137,7 +132,7 @@ class ULID:
             >>> ULID.from_uuid(uuid4())
             ULID(27Q506DP7E9YNRXA0XVD8Z5YSG)
         """
-        return cls(value.bytes, validate=False)
+        return cls(value.bytes)
 
     @classmethod
     @validate_type(bytes)
@@ -163,13 +158,45 @@ class ULID:
         """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:
+        """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.
+        """
+        if isinstance(value, ULID):
+            return cast(U, value)
+        if isinstance(value, uuid.UUID):
+            return cls.from_uuid(value)
+        if isinstance(value, str):
+            len_value = len(value)
+            if len_value == constants.UUID_REPR_LEN:
+                return cls.from_uuid(uuid.UUID(value))
+            if len_value == constants.HEX_REPR_LEN:
+                return cls.from_hex(value)
+            if len_value == constants.REPR_LEN:
+                return cls.from_str(value)
+            raise ValueError(f"Cannot parse ULID from string of length {len_value}")
+        if isinstance(value, int):
+            if len(str(value)) == constants.INT_REPR_LEN:
+                return cls.from_int(value)
+            return cls.from_timestamp(value)
+        if isinstance(value, float):
+            return cls.from_timestamp(value)
+        if isinstance(value, datetime):
+            return cls.from_datetime(value)
+        if isinstance(value, bytes):
+            return cls.from_bytes(value)
+        raise TypeError(f"Cannot parse ULID from type {type(value)}")
+
     @property
     def milliseconds(self) -> int:
         """The timestamp part as epoch time in milliseconds.
 
         Examples:
 
-            >>> ulid.timestamp
+            >>> ulid.milliseconds
             1588257207560
         """
         return int.from_bytes(self.bytes[: constants.TIMESTAMP_LEN], byteorder="big")
@@ -239,22 +266,22 @@ class ULID:
     def __lt__(self, other: Any) -> bool:
         if isinstance(other, ULID):
             return self.bytes < other.bytes
-        elif isinstance(other, int):
+        if isinstance(other, int):
             return int(self) < other
-        elif isinstance(other, bytes):
+        if isinstance(other, bytes):
             return self.bytes < other
-        elif isinstance(other, str):
+        if isinstance(other, str):
             return str(self) < other
         return NotImplemented
 
-    def __eq__(self, other: Any) -> bool:
+    def __eq__(self, other: object) -> bool:
         if isinstance(other, ULID):
             return self.bytes == other.bytes
-        elif isinstance(other, int):
+        if isinstance(other, int):
             return int(self) == other
-        elif isinstance(other, bytes):
+        if isinstance(other, bytes):
             return self.bytes == other
-        elif isinstance(other, str):
+        if isinstance(other, str):
             return str(self) == other
         return NotImplemented
 
@@ -267,14 +294,12 @@ class ULID:
 
         return core_schema.no_info_wrap_validator_function(
             cls._pydantic_validate,
-            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.bytes_schema(min_length=16, max_length=16),
-                ]
-            ),
+            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.bytes_schema(min_length=16, max_length=16),
+            ]),
             serialization=core_schema.to_string_ser_schema(
                 when_used="json-unless-none",
             ),

ulid/__main__.py

@@ -4,17 +4,21 @@ import argparse
 import shutil
 import sys
 import textwrap
-from collections.abc import Callable
-from collections.abc import Sequence
 from datetime import datetime
 from functools import partial
 from typing import Any
+from typing import TYPE_CHECKING
 from uuid import UUID
 
 import ulid
 from ulid import ULID
 
 
+if TYPE_CHECKING:  # pragma: no cover
+    from collections.abc import Callable
+    from collections.abc import Sequence
+
+
 def make_parser(prog: str | None = None) -> argparse.ArgumentParser:
     parser = argparse.ArgumentParser(
         prog=prog,
@@ -135,30 +139,30 @@ def show(args: argparse.Namespace) -> str:
     ulid: ULID = ULID.from_str(from_value_or_stdin(args.ulid))
     if args.uuid:
         return str(ulid.to_uuid())
-    elif args.uuid4:
+    if args.uuid4:
         return str(ulid.to_uuid4())
-    elif args.hex:
+    if args.hex:
         return ulid.hex
-    elif args.int:
+    if args.int:
         return str(int(ulid))
-    elif args.timestamp:
+    if args.timestamp:
         return str(ulid.timestamp)
-    elif args.datetime:
+    if args.datetime:
         return ulid.datetime.isoformat()
-    else:
-        return textwrap.dedent(
-            f"""
-            ULID:      {ulid!s}
-            Hex:       {ulid.hex}
-            Int:       {int(ulid)}
-            Timestamp: {ulid.timestamp}
-            Datetime:  {ulid.datetime.isoformat()}
-            """
-        ).strip()
+    return textwrap.dedent(
+        f"""
+        ULID:      {ulid!s}
+        Hex:       {ulid.hex}
+        Int:       {int(ulid)}
+        Timestamp: {ulid.timestamp}
+        Datetime:  {ulid.datetime.isoformat()}
+        """
+    ).strip()
 
 
 def entrypoint() -> None:  # pragma: no cover
-    print(main(sys.argv[1:]))
+    if (value := main(sys.argv[1:])) is not None:
+        print(value)  # noqa: T201
 
 
 if __name__ == "__main__":  # pragma: no cover

ulid/base32.py

@@ -153,46 +153,42 @@ def encode_timestamp(binary: bytes) -> str:
     if len(binary) != constants.TIMESTAMP_LEN:
         raise ValueError("Timestamp value has to be exactly 6 bytes long.")
     lut = ENCODE
-    return "".join(
-        [
-            lut[(binary[0] & 224) >> 5],
-            lut[(binary[0] & 31)],
-            lut[(binary[1] & 248) >> 3],
-            lut[((binary[1] & 7) << 2) | ((binary[2] & 192) >> 6)],
-            lut[((binary[2] & 62) >> 1)],
-            lut[((binary[2] & 1) << 4) | ((binary[3] & 240) >> 4)],
-            lut[((binary[3] & 15) << 1) | ((binary[4] & 128) >> 7)],
-            lut[(binary[4] & 124) >> 2],
-            lut[((binary[4] & 3) << 3) | ((binary[5] & 224) >> 5)],
-            lut[(binary[5] & 31)],
-        ]
-    )
+    return "".join([
+        lut[(binary[0] & 224) >> 5],
+        lut[(binary[0] & 31)],
+        lut[(binary[1] & 248) >> 3],
+        lut[((binary[1] & 7) << 2) | ((binary[2] & 192) >> 6)],
+        lut[((binary[2] & 62) >> 1)],
+        lut[((binary[2] & 1) << 4) | ((binary[3] & 240) >> 4)],
+        lut[((binary[3] & 15) << 1) | ((binary[4] & 128) >> 7)],
+        lut[(binary[4] & 124) >> 2],
+        lut[((binary[4] & 3) << 3) | ((binary[5] & 224) >> 5)],
+        lut[(binary[5] & 31)],
+    ])
 
 
 def encode_randomness(binary: bytes) -> str:
     if len(binary) != constants.RANDOMNESS_LEN:
         raise ValueError("Randomness value has to be exactly 10 bytes long.")
     lut = ENCODE
-    return "".join(
-        [
-            lut[(binary[0] & 248) >> 3],
-            lut[((binary[0] & 7) << 2) | ((binary[1] & 192) >> 6)],
-            lut[(binary[1] & 62) >> 1],
-            lut[((binary[1] & 1) << 4) | ((binary[2] & 240) >> 4)],
-            lut[((binary[2] & 15) << 1) | ((binary[3] & 128) >> 7)],
-            lut[(binary[3] & 124) >> 2],
-            lut[((binary[3] & 3) << 3) | ((binary[4] & 224) >> 5)],
-            lut[(binary[4] & 31)],
-            lut[(binary[5] & 248) >> 3],
-            lut[((binary[5] & 7) << 2) | ((binary[6] & 192) >> 6)],
-            lut[(binary[6] & 62) >> 1],
-            lut[((binary[6] & 1) << 4) | ((binary[7] & 240) >> 4)],
-            lut[((binary[7] & 15) << 1) | ((binary[8] & 128) >> 7)],
-            lut[(binary[8] & 124) >> 2],
-            lut[((binary[8] & 3) << 3) | ((binary[9] & 224) >> 5)],
-            lut[(binary[9] & 31)],
-        ]
-    )
+    return "".join([
+        lut[(binary[0] & 248) >> 3],
+        lut[((binary[0] & 7) << 2) | ((binary[1] & 192) >> 6)],
+        lut[(binary[1] & 62) >> 1],
+        lut[((binary[1] & 1) << 4) | ((binary[2] & 240) >> 4)],
+        lut[((binary[2] & 15) << 1) | ((binary[3] & 128) >> 7)],
+        lut[(binary[3] & 124) >> 2],
+        lut[((binary[3] & 3) << 3) | ((binary[4] & 224) >> 5)],
+        lut[(binary[4] & 31)],
+        lut[(binary[5] & 248) >> 3],
+        lut[((binary[5] & 7) << 2) | ((binary[6] & 192) >> 6)],
+        lut[(binary[6] & 62) >> 1],
+        lut[((binary[6] & 1) << 4) | ((binary[7] & 240) >> 4)],
+        lut[((binary[7] & 15) << 1) | ((binary[8] & 128) >> 7)],
+        lut[(binary[8] & 124) >> 2],
+        lut[((binary[8] & 3) << 3) | ((binary[9] & 224) >> 5)],
+        lut[(binary[9] & 31)],
+    ])
 
 
 def decode(encoded: str) -> bytes:
@@ -210,16 +206,17 @@ def decode_timestamp(encoded: str) -> bytes:
         raise ValueError("ULID timestamp has to be exactly 10 characters long.")
     lut = DECODE
     values: bytes = bytes(encoded, "ascii")
-    return bytes(
-        [
-            ((lut[values[0]] << 5) | lut[values[1]]) & 0xFF,
-            ((lut[values[2]] << 3) | (lut[values[3]] >> 2)) & 0xFF,
-            ((lut[values[3]] << 6) | (lut[values[4]] << 1) | (lut[values[5]] >> 4)) & 0xFF,
-            ((lut[values[5]] << 4) | (lut[values[6]] >> 1)) & 0xFF,
-            ((lut[values[6]] << 7) | (lut[values[7]] << 2) | (lut[values[8]] >> 3)) & 0xFF,
-            ((lut[values[8]] << 5) | (lut[values[9]])) & 0xFF,
-        ]
-    )
+    # https://github.com/ulid/spec?tab=readme-ov-file#overflow-errors-when-parsing-base32-strings
+    if lut[values[0]] > 7:  # noqa: PLR2004
+        raise ValueError(f"Timestamp value {encoded} is too large and will overflow 128-bits.")
+    return bytes([
+        ((lut[values[0]] << 5) | lut[values[1]]) & 0xFF,
+        ((lut[values[2]] << 3) | (lut[values[3]] >> 2)) & 0xFF,
+        ((lut[values[3]] << 6) | (lut[values[4]] << 1) | (lut[values[5]] >> 4)) & 0xFF,
+        ((lut[values[5]] << 4) | (lut[values[6]] >> 1)) & 0xFF,
+        ((lut[values[6]] << 7) | (lut[values[7]] << 2) | (lut[values[8]] >> 3)) & 0xFF,
+        ((lut[values[8]] << 5) | (lut[values[9]])) & 0xFF,
+    ])
 
 
 def decode_randomness(encoded: str) -> bytes:
@@ -227,17 +224,15 @@ def decode_randomness(encoded: str) -> bytes:
         raise ValueError("ULID randomness has to be exactly 16 characters long.")
     lut = DECODE
     values = bytes(encoded, "ascii")
-    return bytes(
-        [
-            ((lut[values[0]] << 3) | (lut[values[1]] >> 2)) & 0xFF,
-            ((lut[values[1]] << 6) | (lut[values[2]] << 1) | (lut[values[3]] >> 4)) & 0xFF,
-            ((lut[values[3]] << 4) | (lut[values[4]] >> 1)) & 0xFF,
-            ((lut[values[4]] << 7) | (lut[values[5]] << 2) | (lut[values[6]] >> 3)) & 0xFF,
-            ((lut[values[6]] << 5) | (lut[values[7]])) & 0xFF,
-            ((lut[values[8]] << 3) | (lut[values[9]] >> 2)) & 0xFF,
-            ((lut[values[9]] << 6) | (lut[values[10]] << 1) | (lut[values[11]] >> 4)) & 0xFF,
-            ((lut[values[11]] << 4) | (lut[values[12]] >> 1)) & 0xFF,
-            ((lut[values[12]] << 7) | (lut[values[13]] << 2) | (lut[values[14]] >> 3)) & 0xFF,
-            ((lut[values[14]] << 5) | (lut[values[15]])) & 0xFF,
-        ]
-    )
+    return bytes([
+        ((lut[values[0]] << 3) | (lut[values[1]] >> 2)) & 0xFF,
+        ((lut[values[1]] << 6) | (lut[values[2]] << 1) | (lut[values[3]] >> 4)) & 0xFF,
+        ((lut[values[3]] << 4) | (lut[values[4]] >> 1)) & 0xFF,
+        ((lut[values[4]] << 7) | (lut[values[5]] << 2) | (lut[values[6]] >> 3)) & 0xFF,
+        ((lut[values[6]] << 5) | (lut[values[7]])) & 0xFF,
+        ((lut[values[8]] << 3) | (lut[values[9]] >> 2)) & 0xFF,
+        ((lut[values[9]] << 6) | (lut[values[10]] << 1) | (lut[values[11]] >> 4)) & 0xFF,
+        ((lut[values[11]] << 4) | (lut[values[12]] >> 1)) & 0xFF,
+        ((lut[values[12]] << 7) | (lut[values[13]] << 2) | (lut[values[14]] >> 3)) & 0xFF,
+        ((lut[values[14]] << 5) | (lut[values[15]])) & 0xFF,
+    ])

ulid/constants.py

@@ -8,3 +8,8 @@ BYTES_LEN = TIMESTAMP_LEN + RANDOMNESS_LEN
 TIMESTAMP_REPR_LEN = 10
 RANDOMNESS_REPR_LEN = 16
 REPR_LEN = TIMESTAMP_REPR_LEN + RANDOMNESS_REPR_LEN
+
+INT_REPR_LEN = 37
+
+HEX_REPR_LEN = 32
+UUID_REPR_LEN = 36  # UUID with dash-separated segments

python_ulid-2.6.0.dist-info/RECORD

@@ -1,10 +0,0 @@
-ulid/__init__.py,sha256=BziBUk2I6PxKvymNA0ddyUcfF9b_Zv7PKsTPV_ojixI,9929
-ulid/__main__.py,sha256=Cmg0NEz3GUZ2WhsZVpY3-Kq-JOkxJFaLsRNgj3Aosyw,5341
-ulid/base32.py,sha256=aj8pfBmuvviEJtdcGGiGImdSN_UMdVsBvIXlFkiqD1o,5963
-ulid/constants.py,sha256=N_nw4W2ciXO8C1IeuO3YK3j4_x9QW-0KyvrSQUuM-G4,241
-ulid/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-python_ulid-2.6.0.dist-info/METADATA,sha256=NxDvmvrp4DzyfibtLfBPh3D605fWHRY_p709_rxwwG0,5782
-python_ulid-2.6.0.dist-info/WHEEL,sha256=zEMcRr9Kr03x1ozGwg5v9NQBKn3kndp6LSoSlVg-jhU,87
-python_ulid-2.6.0.dist-info/entry_points.txt,sha256=9214ghzfSgS8a-TjjlWDF7bI7KSaeewOCBKn5uz7bdU,50
-python_ulid-2.6.0.dist-info/licenses/LICENSE,sha256=DiDPNhW5yUHIqaKowvX0c1c9xWiI0xW4ji8R9N2NJbw,1056
-python_ulid-2.6.0.dist-info/RECORD,,