python-ulid 2.4.0.post0__tar.gz → 2.6.0__tar.gz

{python_ulid-2.4.0.post0 → python_ulid-2.6.0}/CHANGELOG.rst

@@ -5,6 +5,22 @@ Changelog
 
 Versions follow `Semantic Versioning <http://www.semver.org>`_
 
+`2.6.0`_ - 2024-05-26
+---------------------
+Changed
+~~~~~~~
+* Provide more sophisticated validation when creating ``ULID``s from user input. When using
+  ``ULID.from_str`` we will check if the characters match the base32 alphabet. In general, it is
+  ensured that the timestamp part of the ULID is not out of range.
+
+`2.5.0`_ - 2024-04-26
+---------------------
+
+Changed
+~~~~~~~
+* Generate a more accurate JSON schema with Pydantic's ``BaseModel.model_json_schema()``. This
+  includes a specification for string and byte representations.
+
 `2.4.0`_ - 2024-04-02
 ---------------------
 
@@ -151,6 +167,8 @@ Changed
 * The package now has no external dependencies.
 * The test-coverage has been raised to 100%.
 
+.. _2.6.0: https://github.com/mdomke/python-ulid/compare/2.5.0...2.6.0
+.. _2.5.0: https://github.com/mdomke/python-ulid/compare/2.4.0...2.5.0
 .. _2.4.0: https://github.com/mdomke/python-ulid/compare/2.3.0...2.4.0
 .. _2.3.0: https://github.com/mdomke/python-ulid/compare/2.2.0...2.3.0
 .. _2.2.0: https://github.com/mdomke/python-ulid/compare/2.1.0...2.2.0

{python_ulid-2.4.0.post0 → python_ulid-2.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: python-ulid
-Version: 2.4.0.post0
+Version: 2.6.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-2.4.0.post0 → python_ulid-2.6.0}/tests/test_ulid.py

@@ -5,6 +5,7 @@ from collections.abc import Callable
 from datetime import datetime
 from datetime import timedelta
 from datetime import timezone
+from typing import Optional
 from typing import Union
 
 import pytest
@@ -148,15 +149,17 @@ Params = Union[bytes, str, int, float]
 @pytest.mark.parametrize(
     ("constructor", "value"),
     [
-        (ULID, b"sdf"),
-        (ULID.from_timestamp, b"not-a-timestamp"),
-        (ULID.from_datetime, time.time()),
-        (ULID.from_bytes, b"not-enough"),
-        (ULID.from_bytes, 123),
-        (ULID.from_str, "not-enough"),
-        (ULID.from_str, 123),
-        (ULID.from_int, "not-an-int"),
-        (ULID.from_uuid, "not-a-uuid"),
+        (ULID, b"sdf"),  # invalid length
+        (ULID.from_timestamp, b"not-a-timestamp"),  # invalid type
+        (ULID.from_datetime, time.time()),  # invalid type
+        (ULID.from_bytes, b"not-enough"),  # invalid length
+        (ULID.from_bytes, 123),  # invalid type
+        (ULID.from_str, "not-enough"),  # invalid length
+        (ULID.from_str, 123),  # inavlid type
+        (ULID.from_str, "notavalidulidnotavalidulid"),  # invalid alphabet
+        (ULID.from_str, "Z" * 26),  # invalid timestamp
+        (ULID.from_int, "not-an-int"),  # invalid type
+        (ULID.from_uuid, "not-a-uuid"),  # invalid type
     ],
 )
 def test_ulid_invalid_input(constructor: Callable[[Params], ULID], value: Params) -> None:
@@ -168,7 +171,7 @@ def test_pydantic_protocol() -> None:
     ulid = ULID()
 
     class Model(BaseModel):
-        ulid: ULID
+        ulid: Optional[ULID] = None
 
     for value in [ulid, str(ulid), int(ulid), bytes(ulid)]:
         model = Model(ulid=value)
@@ -188,3 +191,23 @@ def test_pydantic_protocol() -> None:
     model_json = model.model_dump_json()
     assert isinstance(json.loads(model_json)["ulid"], str)
     assert Model.model_validate_json(model_json) == model
+
+    model_json_schema = model.model_json_schema()
+    assert "properties" in model_json_schema
+    assert "ulid" in model_json_schema["properties"]
+    assert "anyOf" in model_json_schema["properties"]["ulid"]
+    assert {
+        "maxLength": 26,
+        "minLength": 26,
+        "pattern": "[A-Z0-9]{26}",
+        "type": "string",
+    } in model_json_schema["properties"]["ulid"]["anyOf"]
+    assert {
+        "maxLength": 16,
+        "minLength": 16,
+        "type": "string",
+        "format": "binary",
+    } in model_json_schema["properties"]["ulid"]["anyOf"]
+    assert {
+        "type": "null",
+    } in model_json_schema["properties"]["ulid"]["anyOf"]

{python_ulid-2.4.0.post0 → python_ulid-2.6.0}/ulid/__init__.py

@@ -71,14 +71,26 @@ class ULID:
         >>> ulid = ULID()
         >>> str(ulid)
         '01E75PVKXA3GFABX1M1J9NZZNF'
+
+    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) -> None:
+    def __init__(self, value: bytes | None = None, validate: bool = True) -> 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)
@@ -125,7 +137,7 @@ class ULID:
             >>> ULID.from_uuid(uuid4())
             ULID(27Q506DP7E9YNRXA0XVD8Z5YSG)
         """
-        return cls(value.bytes)
+        return cls(value.bytes, validate=False)
 
     @classmethod
     @validate_type(bytes)
@@ -259,6 +271,8 @@ class ULID:
                 [
                     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(

{python_ulid-2.4.0.post0 → python_ulid-2.6.0}/ulid/base32.py

@@ -198,6 +198,8 @@ def encode_randomness(binary: bytes) -> str:
 def decode(encoded: str) -> bytes:
     if len(encoded) != constants.REPR_LEN:
         raise ValueError("Encoded ULID has to be exactly 26 characters long.")
+    if any((c not in ENCODE) for c in encoded):
+        raise ValueError(f"Encoded ULID can only consist of letters in {ENCODE}.")
     return decode_timestamp(encoded[: constants.TIMESTAMP_REPR_LEN]) + decode_randomness(
         encoded[constants.TIMESTAMP_REPR_LEN :]
     )