python-ulid 2.1.0__py3-none-any.whl → 2.3.0__py3-none-any.whl

{python_ulid-2.1.0.dist-info → python_ulid-2.3.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.3
 Name: python-ulid
-Version: 2.1.0
+Version: 2.3.0
 Summary: Universally unique lexicographically sortable identifier
 Author-email: Martin Domke <mail@martindomke.net>
 License-Expression: MIT
@@ -15,8 +15,11 @@ Classifier: Programming Language :: Python
 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: Topic :: Software Development :: Libraries
 Requires-Python: >=3.9
+Provides-Extra: pydantic
+Requires-Dist: pydantic>=2.0; extra == 'pydantic'
 Description-Content-Type: text/x-rst
 
 
@@ -57,6 +60,12 @@ Use ``pip`` to install the library
 
   $ pip install python-ulid
 
+to include Pydantic support install the optional dependency like so
+
+.. code-block:: bash
+
+  $ pip install python-ulid[pydantic]
+
 .. installation-end
 
 .. usage-begin
@@ -82,8 +91,8 @@ or use one of the named constructors
    >>> ULID.from_datetime(datetime.datetime.now())
    ULID(01E75J2XBK390V2XRH44EHC10X)
 
-There are several options for encoding the ``ULID`` object (e.g. string, hex, int),
-as well as to access the timestamp attribute in different formats:
+There are several options for encoding the ``ULID`` object
+(e.g. string, hex, int, bytes, UUID):
 
 .. code-block:: pycon
 
@@ -91,22 +100,54 @@ as well as to access the timestamp attribute in different formats:
    '01BTGNYV6HRNK8K8VKZASZCFPE'
    >>> ulid.hex
    '015ea15f6cd1c56689a373fab3f63ece'
+   >>> int(ulid)
+   1820576928786795198723644692628913870
+   >>> bytes(ulid)
+   b'\x01^\xa1_l\xd1\xc5f\x89\xa3s\xfa\xb3\xf6>\xce'
+   >>> ulid.to_uuid()
+   UUID('015ea15f-6cd1-c566-89a3-73fab3f63ece')
+
+It is also possible to directly access the timestamp component of a ``ULID``,
+either in UNIX epoch or as ``datetime.datetime``
+
+.. code-block:: pycon
+
    >>> ulid.timestamp
    1505945939.153
    >>> ulid.datetime
    datetime.datetime(2017, 9, 20, 22, 18, 59, 153000, tzinfo=datetime.timezone.utc)
-   >>> ulid.to_uuid()
-   UUID('015ea15f-6cd1-c566-89a3-73fab3f63ece')
 
 .. usage-end
 
+.. pydantic-begin
+
+Pydantic integration
+---------------------
+
+The ``ULID`` class can be directly used for the popular data validation library
+`Pydantic <https://docs.pydantic.dev/latest/>`_ like so
+
+.. code-block:: python
+
+  from pydantic import BaseModel
+  from ulid import ULID
+
+
+  class Model(BaseModel):
+    ulid: ULID
+
+  model = Model(ulid="DX89370400440532013000")  # OK
+  model = Model(ulid="not-a-ulid")  # Raises ValidationError
+
+.. pydantic-end
+
 .. cli-begin
 
 Command line interface
 -----------------------
 
 The package comes with a CLI interface that can be invoked either by the script name
-`ulid` or as python module `python -m ulid`. The CLI allows you to generate, inspect
+``ulid`` or as python module ``python -m ulid``. The CLI allows you to generate, inspect
 and convert ULIDs, e.g.
 
 .. code-block:: bash
@@ -124,8 +165,26 @@ and convert ULIDs, e.g.
    Timestamp: 1695219822.248
    Datetime:  2023-09-20 14:23:42.248000+00:00
 
+There are several flags to select specific output formats for the ``show`` command, e.g.
+
+
+.. code-block:: bash
+
+   $ ulid show --datetime 01HASFKBN8SKZTSVVS03K5AMMS
+   2023-09-20 14:23:42.248000+00:00
+
+The special character ``-`` allows to read values from ``stdin`` so that they can be piped. E.g.
+
+.. code-block:: bash
+
    $ echo 01HASFKBN8SKZTSVVS03K5AMMS | ulid show --uuid -
-   018ab2f9-aea8-ccff-acef-7900e6555299
+   018ab2f9-aea8-4cff-acef-7900e6555299
+
+   $ date --iso-8601 | python -m ulid build --from-datetime -
+   01HAT9PVR02T3S13XB48S7GEHE
+
+For a full overview of flags for the ``build`` and ``show`` commands use the ``--help`` option
+(e.g. ``ulid show --help``).
 
 .. cli-end
 
@@ -135,3 +194,7 @@ Other implementations
 * `ahawker/ulid <https://github.com/ahawker/ulid>`_
 * `valohai/ulid2 <https://github.com/valohai/ulid2>`_
 * `mdipierro/ulid <https://github.com/mdipierro/ulid>`_
+* `oklog/ulid <https://github.com/oklog/ulid>`_
+* `ulid/javascript <https://github.com/ulid/javascript>`_
+* `RobThree/NUlid <https://github.com/RobThree/NUlid>`_
+* `imdario/go-ulid <https://github.com/imdario/go-ulid>`_

python_ulid-2.3.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+ulid/__init__.py,sha256=0mApsC1fFWyQnZgbJqU-fX0gV-Qj2l_jX3IEwbwKzxw,9114
+ulid/__main__.py,sha256=Cmg0NEz3GUZ2WhsZVpY3-Kq-JOkxJFaLsRNgj3Aosyw,5341
+ulid/base32.py,sha256=OkU4FBqohJgV_ZRc3dTbjPlUTSSeC9ddFlPXD2vA8vc,5832
+ulid/constants.py,sha256=N_nw4W2ciXO8C1IeuO3YK3j4_x9QW-0KyvrSQUuM-G4,241
+ulid/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+python_ulid-2.3.0.dist-info/METADATA,sha256=91xx1_CVxuIoS3Wj7vXRyxA0Z5nF8gxEZtLy4Egt1zg,5382
+python_ulid-2.3.0.dist-info/WHEEL,sha256=bq9SyP5NxIRA9EpQgMCd-9RmPHWvbH-4lTDGwxgIR64,87
+python_ulid-2.3.0.dist-info/entry_points.txt,sha256=9214ghzfSgS8a-TjjlWDF7bI7KSaeewOCBKn5uz7bdU,50
+python_ulid-2.3.0.dist-info/licenses/LICENSE,sha256=DiDPNhW5yUHIqaKowvX0c1c9xWiI0xW4ji8R9N2NJbw,1056
+python_ulid-2.3.0.dist-info/RECORD,,

{python_ulid-2.1.0.dist-info → python_ulid-2.3.0.dist-info}/WHEEL

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

ulid/__init__.py

@@ -9,15 +9,21 @@ from datetime import datetime
 from datetime import timezone
 from typing import Any
 from typing import Generic
+from typing import TYPE_CHECKING
 from typing import TypeVar
 
 from ulid import base32
 from ulid import constants
 
 
+if TYPE_CHECKING:  # pragma: no cover
+    from pydantic import GetCoreSchemaHandler
+    from pydantic import ValidatorFunctionWrapHandler
+    from pydantic_core import CoreSchema
+
 try:
     from importlib.metadata import version
-except ImportError:
+except ImportError:  # pragma: no cover
     from importlib_metadata import version  # type: ignore
 
 
@@ -44,6 +50,9 @@ class validate_type(Generic[T]):  # noqa: N801
         return wrapped
 
 
+U = TypeVar("U", bound="ULID")
+
+
 @functools.total_ordering
 class ULID:
     """The :class:`ULID` object consists of a timestamp part of 48 bits and of 80 random bits.
@@ -67,11 +76,13 @@ 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()).bytes
+        self.bytes: bytes = (
+            value or ULID.from_timestamp(time.time_ns() // constants.NANOSECS_IN_MILLISECS).bytes
+        )
 
     @classmethod
     @validate_type(datetime)
-    def from_datetime(cls, value: datetime) -> ULID:
+    def from_datetime(cls: type[U], value: datetime) -> U:
         """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.
 
@@ -85,7 +96,7 @@ class ULID:
 
     @classmethod
     @validate_type(int, float)
-    def from_timestamp(cls, value: int | float) -> ULID:
+    def from_timestamp(cls: type[U], value: int | 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.
@@ -104,7 +115,7 @@ class ULID:
 
     @classmethod
     @validate_type(uuid.UUID)
-    def from_uuid(cls, value: uuid.UUID) -> ULID:
+    def from_uuid(cls: type[U], value: uuid.UUID) -> U:
         """Create a new :class:`ULID`-object from a :class:`uuid.UUID`. The timestamp part will be
         random in that case.
 
@@ -118,25 +129,25 @@ class ULID:
 
     @classmethod
     @validate_type(bytes)
-    def from_bytes(cls, bytes_: bytes) -> ULID:
+    def from_bytes(cls: type[U], bytes_: bytes) -> U:
         """Create a new :class:`ULID`-object from sequence of 16 bytes."""
         return cls(bytes_)
 
     @classmethod
     @validate_type(str)
-    def from_hex(cls, value: str) -> ULID:
+    def from_hex(cls: type[U], value: str) -> U:
         """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, string: str) -> ULID:
+    def from_str(cls: type[U], string: str) -> U:
         """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, value: int) -> ULID:
+    def from_int(cls: type[U], value: int) -> U:
         """Create a new :class:`ULID`-object from an `int`."""
         return cls(int.to_bytes(value, constants.BYTES_LEN, "big"))
 
@@ -209,6 +220,10 @@ class ULID:
         """Encode this object as an integer."""
         return int.from_bytes(self.bytes, byteorder="big")
 
+    def __bytes__(self) -> bytes:
+        """Encode this object as byte sequence."""
+        return self.bytes
+
     def __lt__(self, other: Any) -> bool:
         if isinstance(other, ULID):
             return self.bytes < other.bytes
@@ -233,3 +248,34 @@ class ULID:
 
     def __hash__(self) -> int:
         return hash(self.bytes)
+
+    @classmethod
+    def __get_pydantic_core_schema__(cls, source: Any, handler: GetCoreSchemaHandler) -> CoreSchema:
+        from pydantic_core import core_schema
+
+        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),
+                ]
+            ),
+        )
+
+    @classmethod
+    def _pydantic_validate(cls, value: Any, handler: ValidatorFunctionWrapHandler) -> Any:
+        from pydantic_core import PydanticCustomError
+
+        try:
+            if isinstance(value, int):
+                ulid = cls.from_int(value)
+            elif isinstance(value, str):
+                ulid = cls.from_str(value)
+            elif isinstance(value, ULID):
+                ulid = value
+            else:
+                ulid = cls.from_bytes(value)
+        except ValueError as err:
+            raise PydanticCustomError("ulid_format", "Unrecognized format") from err
+        return handler(ulid)

ulid/__main__.py

@@ -1,10 +1,14 @@
+from __future__ import annotations
+
 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 uuid import UUID
 
 import ulid
@@ -47,37 +51,31 @@ def make_parser(prog: str | None = None) -> argparse.ArgumentParser:
     )
     b.add_argument(
         "--from-int",
-        type=int,
         metavar="<int>",
         help="create from integer",
     )
     b.add_argument(
         "--from-hex",
-        type=str,
         metavar="<str>",
         help="create from 32 character hex value",
     )
     b.add_argument(
         "--from-str",
-        type=str,
         metavar="<str>",
         help="create from base32 encoded string of length 26",
     )
     b.add_argument(
         "--from-timestamp",
-        type=parse_numeric,
         metavar="<int|float>",
         help="create from timestamp either as float in secs or int as millis",
     )
     b.add_argument(
         "--from-datetime",
-        type=datetime.fromisoformat,
         metavar="<iso8601>",
         help="create from datetime. The timestamp part of the ULID will be taken from the datetime",
     )
     b.add_argument(
         "--from-uuid",
-        type=UUID,
         metavar="<uuid>",
         help="create from given UUID. The timestamp part will be random.",
     )
@@ -85,7 +83,8 @@ def make_parser(prog: str | None = None) -> argparse.ArgumentParser:
 
     s = subparsers.add_parser("show", help="show properties of a ULID")
     s.add_argument("ulid", help="the ULID to inspect. The special value - reads from stdin")
-    s.add_argument("--uuid", action="store_true", help="convert to UUID")
+    s.add_argument("--uuid", action="store_true", help="convert to fully random UUID")
+    s.add_argument("--uuid4", action="store_true", help="convert to RFC 4122 compliant UUIDv4")
     s.add_argument("--hex", action="store_true", help="convert to hex")
     s.add_argument("--int", action="store_true", help="convert to int")
     s.add_argument("--timestamp", "--ts", action="store_true", help="show timestamp")
@@ -94,6 +93,18 @@ def make_parser(prog: str | None = None) -> argparse.ArgumentParser:
     return parser
 
 
+def main(argv: Sequence[str], prog: str | None = None) -> str:
+    args = make_parser(prog).parse_args(argv)
+    return args.func(args)
+
+
+def from_value_or_stdin(value: str, convert: Callable[[str], Any] | None = None) -> Any:
+    value = sys.stdin.readline().strip() if value == "-" else value
+    if convert is not None:
+        return convert(value)
+    return value
+
+
 def parse_numeric(s: str) -> int | float:
     try:
         return int(s)
@@ -101,60 +112,54 @@ def parse_numeric(s: str) -> int | float:
         return float(s)
 
 
-def main(argv: Sequence[str], prog: str | None = None) -> None:
-    args = make_parser(prog).parse_args(argv)
-    args.func(args)
-
-
-def build(args: argparse.Namespace) -> None:
+def build(args: argparse.Namespace) -> str:
     ulid: ULID
     if args.from_int is not None:
-        ulid = ULID.from_int(args.from_int)
+        ulid = ULID.from_int(from_value_or_stdin(args.from_int, int))
     elif args.from_hex is not None:
-        ulid = ULID.from_hex(args.from_hex)
+        ulid = ULID.from_hex(from_value_or_stdin(args.from_hex))
     elif args.from_str is not None:
-        ulid = ULID.from_str(args.from_str)
+        ulid = ULID.from_str(from_value_or_stdin(args.from_str))
     elif args.from_timestamp is not None:
-        ulid = ULID.from_timestamp(args.from_timestamp)
+        ulid = ULID.from_timestamp(from_value_or_stdin(args.from_timestamp, parse_numeric))
     elif args.from_datetime is not None:
-        ulid = ULID.from_datetime(args.from_datetime)
+        ulid = ULID.from_datetime(from_value_or_stdin(args.from_datetime, datetime.fromisoformat))
     elif args.from_uuid is not None:
-        ulid = ULID.from_uuid(args.from_uuid)
+        ulid = ULID.from_uuid(from_value_or_stdin(args.from_uuid, UUID))
     else:
         ulid = ULID()
-    print(ulid)
+    return str(ulid)
 
 
-def show(args: argparse.Namespace) -> None:
-    value = sys.stdin.readline().strip() if args.ulid == "-" else args.ulid
-    ulid: ULID = ULID.from_str(value)
+def show(args: argparse.Namespace) -> str:
+    ulid: ULID = ULID.from_str(from_value_or_stdin(args.ulid))
     if args.uuid:
-        print(ulid.to_uuid())
+        return str(ulid.to_uuid())
+    elif args.uuid4:
+        return str(ulid.to_uuid4())
     elif args.hex:
-        print(ulid.hex)
+        return ulid.hex
     elif args.int:
-        print(int(ulid))
+        return str(int(ulid))
     elif args.timestamp:
-        print(ulid.timestamp)
+        return str(ulid.timestamp)
     elif args.datetime:
-        print(ulid.datetime)
+        return ulid.datetime.isoformat()
     else:
-        print(
-            textwrap.dedent(
-                f"""
-                ULID:      {ulid!s}
-                Hex:       {ulid.hex}
-                Int:       {int(ulid)}
-                Timestamp: {ulid.timestamp}
-                Datetime:  {ulid.datetime}
-                """
-            ).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:
-    main(sys.argv[1:])
+def entrypoint() -> None:  # pragma: no cover
+    print(main(sys.argv[1:]))
 
 
-if __name__ == "__main__":
+if __name__ == "__main__":  # pragma: no cover
     main(sys.argv[1:], "python -m ulid")

ulid/constants.py

@@ -1,4 +1,5 @@
 MILLISECS_IN_SECS = 1000
+NANOSECS_IN_MILLISECS = 1000000
 
 TIMESTAMP_LEN = 6
 RANDOMNESS_LEN = 10

python_ulid-2.1.0.dist-info/RECORD

@@ -1,10 +0,0 @@
-ulid/__init__.py,sha256=QctfUYCnmrMlSxlxFVol47UOC5wzc5kPR0CAMUXxdVI,7516
-ulid/__main__.py,sha256=RXiQNtc31xZOxqPmsnRHJMSnbvIiLHyBIFHcWC-Pka8,4817
-ulid/base32.py,sha256=OkU4FBqohJgV_ZRc3dTbjPlUTSSeC9ddFlPXD2vA8vc,5832
-ulid/constants.py,sha256=LHZ167q6iOJJ3giBcbNEwM-ahJYIrSvQ-1hHhpvLhHE,209
-ulid/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-python_ulid-2.1.0.dist-info/METADATA,sha256=i2Y5w0DtmNSfTf4f0PU5gXxUKIwu9OkP_ViKrgrLfiw,3676
-python_ulid-2.1.0.dist-info/WHEEL,sha256=9QBuHhg6FNW7lppboF2vKVbCGTVzsFykgRQjjlajrhA,87
-python_ulid-2.1.0.dist-info/entry_points.txt,sha256=9214ghzfSgS8a-TjjlWDF7bI7KSaeewOCBKn5uz7bdU,50
-python_ulid-2.1.0.dist-info/licenses/LICENSE,sha256=DiDPNhW5yUHIqaKowvX0c1c9xWiI0xW4ji8R9N2NJbw,1056
-python_ulid-2.1.0.dist-info/RECORD,,