lastuuid 0.4.2__cp313-cp313-win_arm64.whl

lastuuid/__init__.py

@@ -0,0 +1,9 @@
+"""
+lastuuid API.
+"""
+from .lastuuid import uuid7, uuid7_to_datetime
+
+__all__ = [
+    "uuid7",
+    "uuid7_to_datetime",
+]

lastuuid/dummies.py

@@ -0,0 +1,106 @@
+"""
+A dummy uuid usefull for unit testing purpose.
+
+UUID generated here are full of 0, they does not respect any kind of UUID version,
+they remove a bit of cognitive load while testing.
+"""
+
+from collections.abc import Callable
+from typing import Iterator
+from uuid import UUID
+
+from lastuuid.factories import LastUUIDFactory
+
+__all__ = ["uuidgen", "uuid7gen"]
+
+
+def gen_id() -> Iterator[int]:
+    num = 0
+    while True:
+        num += 1
+        yield num
+
+
+next_id = gen_id()
+
+
+def _uuidgen(i: int = 0, j: int = 0, k: int = 0, x: int = 0, y: int = 0) -> UUID:
+    if i == 0 and y == 0:
+        y = next(next_id)
+    return UUID(f"{i:0>8}-{j:0>4}-{k:0>4}-{x:0>4}-{y:0>12}")
+
+
+uuidgen: Callable[..., UUID] = LastUUIDFactory[None](None, _uuidgen)  # type: ignore
+"""
+A UUID generator that makes UUIDs more readable for humans.
+
+# Generate autoincrement UUID that you need to predict
+
+Sometime you prepare fixtures with well known UUID and you want to repeat them,
+
+uuidgen(1) is more readable that UUID('00000001-0000-0000-0000-000000000000'),
+this is why this function is made for.
+Every section of the uuid can be filled out using `i`, `j`, `k`, `x`, `y` but,
+I personnaly never use more than `i` and `j`.
+
+```python
+>>> from lastuuid.dummies import uuidgen
+>>> uuidgen(1)
+UUID('00000001-0000-0000-0000-000000000000')
+>>> uuidgen(1, 2)
+UUID('00000001-0002-0000-0000-000000000000')
+>>> uuidgen(1, 2, 3, 4, 5)
+UUID('00000001-0002-0003-0004-000000000005')
+```
+
+```{tip}
+if you don't want a dependency for that, the standard library let you write
+UUID(int=1) which produce UUID('00000000-0000-0000-0000-000000000001').
+```
+
+# Generate autoincrement UUID that you don't need to predict
+
+Without any parameter, it will generate UUID where the last bits are incremented.
+It also keep the 10 lasts created values.
+
+```python
+>>> from lastuuid.dummies import uuidgen
+>>> uuidgen()
+UUID('00000000-0000-0000-0000-000000000001')
+>>> uuidgen.last
+UUID('00000000-0000-0000-0000-000000000001')
+>>> uuidgen()
+UUID('00000000-0000-0000-0000-000000000002')
+>>> uuidgen.last
+UUID('00000000-0000-0000-0000-000000000002')
+>>> uuidgen.lasts[1]
+UUID('00000000-0000-0000-0000-000000000001')
+```
+
+"""
+
+uuid7gen: Callable[..., UUID] = LastUUIDFactory[None](None)  # type: ignore
+"""
+Generate uuid7 and store the last generated values to get them
+using last and lasts property.
+
+```python
+>>> from lastuuid.dummies import uuid7gen
+>>> uuid7gen()
+UUID('019b5cb2-2fea-7572-8fc6-84fc550278e8')
+>>> uuid7gen.last
+UUID('019b5cb2-2fea-7572-8fc6-84fc550278e8')
+>>> uuid7gen.lasts
+[UUID('019b5cb2-2fea-7572-8fc6-84fc550278e8')]
+>>> uuid7gen()
+UUID('019b5cb2-82e5-709d-a24d-7dba31eb3e82')
+>>> uuid7gen.last
+UUID('019b5cb2-82e5-709d-a24d-7dba31eb3e82')
+>>> uuid7gen.last[0]
+UUID('019b5cb2-82e5-709d-a24d-7dba31eb3e82')
+>>> uuid7gen.lasts[1]
+UUID('019b5cb2-2fea-7572-8fc6-84fc550278e8')
+```
+
+See also {class}`lastuuid.factories.LastUUIDFactory`.
+"""

lastuuid/factories.py

@@ -0,0 +1,104 @@
+"""
+Factories for new types.
+"""
+
+from collections import deque
+from collections.abc import Callable
+from typing import Any, Deque, Generic, TypeVar
+from uuid import UUID
+
+from .lastuuid import uuid7
+
+__all__ = [
+    "NewTypeFactory",
+    "LastUUIDFactory",
+]
+
+
+T = TypeVar("T", bound=UUID)
+
+
+class NewTypeFactory(Generic[T]):
+    """
+    Factory for NewType UUIDs
+    """
+
+    def __init__(self, newtype: Any, id_factory: Callable[[], UUID] = uuid7):
+        """
+        Create a factory of type that store the last instances.
+
+        :param newtype: the type to be used
+        :param id_factory: the factory to use, uuid7 by default.
+        """
+        self._newtype = newtype
+        self._id_factory = id_factory
+
+    def __call__(self, *args: Any, **kwargs: Any) -> T:
+        """Generate a new value."""
+        val = self._id_factory(*args, **kwargs)  # type: ignore
+        if self._newtype:
+            val: T = self._newtype(val)  # cast to NewType
+        return val
+
+
+class LastUUIDFactory(NewTypeFactory[T]):
+    """
+    Keep last UUID generated.
+
+    ```python
+    >>> from typing import NewType
+    >>> from uuid import UUID
+    >>> from lastuuid.utils import LastUUIDFactory
+    >>> ClientId = NewType("ClientId", UUID)
+    >>> client_id_factory = LastUUIDFactory[ClientId](ClientId)
+    >>> client_id_factory()
+    UUID('019b4f7d-f9d1-7d46-922a-7b83c4462366')
+    >>> client_id_factory()
+    UUID('019b4f7d-f9d2-7471-b6bb-c48f31146c56')
+    >>> client_id_factory()
+    UUID('019b4f7d-f9d2-7471-b6bb-c490f5b50e3a')
+    >>> client_id_factory.last
+    UUID('019b4f7d-f9d2-7471-b6bb-c490f5b50e3a')
+    >>> client_id_factory.lasts[0]
+    UUID('019b4f7d-f9d2-7471-b6bb-c490f5b50e3a')
+    >>> client_id_factory.lasts[1]
+    UUID('019b4f7d-f9d2-7471-b6bb-c48f31146c56')
+    >>> client_id_factory.lasts[2]
+    UUID('019b4f7d-f9d1-7d46-922a-7b83c4462366')
+    ```
+    """
+    def __init__(
+        self,
+        newtype: Any,
+        id_factory: Callable[[], UUID] = uuid7,
+        cache_size: int = 10,
+    ):
+        """
+        Create a factory of type that store the last instances.
+
+        :param newtype: the type to be used
+        :param cache_size: size of the queue that saved the last uuids
+        """
+        super().__init__(newtype, id_factory)
+        self._cache: Deque[T] = deque(maxlen=cache_size)
+
+    def __call__(self, *args: Any, **kwargs: Any) -> T:
+        """Generate the id and cache it."""
+        val = super().__call__(*args, **kwargs)
+        self._cache.append(val)
+        return val
+
+    @property
+    def last(self) -> T:
+        """Most recently generated UUID-NewType instance."""
+        return self._cache[-1]
+
+    @property
+    def lasts(self) -> list[T]:
+        """
+        Returns a list of the last N generated UUID-NewType instances.
+
+        The list is ordered from most recent to oldest.
+        The most recent value is accessible via `last`.
+        """
+        return list(reversed(self._cache))

lastuuid/lastuuid.pyi

@@ -0,0 +1,14 @@
+"""Pyo3 binding interface definition."""
+
+from uuid import UUID
+from datetime import datetime, timezone
+
+
+def uuid7() -> UUID:
+    """
+    Generate an uuid using uuidv7 format, the best format that feet in a BTree.
+    """
+
+
+def uuid7_to_datetime(uuid7: UUID, tz=timezone.utc) -> datetime:
+    """Extract the datetime part of an uuid 7."""

lastuuid/utils.py

@@ -0,0 +1,72 @@
+"""
+Utilities methods that may be used for database querying purpose.
+
+Because UUIDv7 are timestamped ordered and monotonically increasing,
+there are a good solution for generating primary keys.
+
+The design of UUIDv7 feet well with the design of BTree.
+
+Because they contains a date time, a UUID range can be compute
+in order to retrieve UUIDs generated at a given time.
+
+"""
+
+from datetime import UTC, date, datetime, time, timedelta
+from uuid import UUID
+
+__all__ = [
+    "uuid7_bounds_from_datetime",
+    "uuid7_bounds_from_date",
+]
+
+
+def _datetime_to_uuid7_lowest(dt: datetime) -> UUID:
+    unix_ts_ms = int(dt.timestamp() * 1000)
+    version = 0x07
+    var = 2
+    final_bytes = unix_ts_ms.to_bytes(6)
+    final_bytes += (version << 12).to_bytes(2)
+    final_bytes += ((var << 62) + 0x3000000000000000).to_bytes(8)
+    return UUID(bytes=final_bytes)
+
+
+def uuid7_bounds_from_datetime(
+    dt_lower: datetime,
+    dt_upper: datetime | None = None,
+) -> tuple[UUID, UUID]:
+    """
+    Get uuid bound for a half-open interval.
+
+    This function can be usefull to search for any rows based on a uuid7 in a sql query.
+    If one parameter is set, then the search is based on a millisecond, because uuid7
+    are only millisecond precision.
+
+    The returned bound are half open, so the upper bound, from the ``dt_upper`` will
+    not include in the result, only the first value to be excluded.
+
+    If the the second parameter is ommited, then the bound only contains a millisecond,
+    of dt_lower.
+
+    :param dt_lower: the included left bound of the range.
+    :param dt_upper: the excluded right bound of the range.
+    """
+    return _datetime_to_uuid7_lowest(dt_lower), _datetime_to_uuid7_lowest(
+        dt_upper or (dt_lower + timedelta(milliseconds=1))
+    )
+
+
+def uuid7_bounds_from_date(dt: date, tz=UTC) -> tuple[UUID, UUID]:
+    """
+    Get uuid bound for a particular day.
+
+    This function can be usefull to search for any rows based on a uuid7 in a sql query.
+    The right bound return is the first uuid of the next day that should be excluded.
+
+    :param dt: the included left bound of the range.
+    :param tz: the timezone used to compute the UUID, it should always be ommited.
+    """
+    return _datetime_to_uuid7_lowest(
+        datetime.combine(dt, time=time(tzinfo=tz))
+    ), _datetime_to_uuid7_lowest(
+        datetime.combine(dt + timedelta(days=1), time=time(tzinfo=tz))
+    )

lastuuid-0.4.2.dist-info/METADATA

@@ -0,0 +1,124 @@
+Metadata-Version: 2.4
+Name: lastuuid
+Version: 0.4.2
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Rust
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Dist: furo>=2024.5.6 ; extra == 'docs'
+Requires-Dist: linkify-it-py>=2.0.3,<3 ; extra == 'docs'
+Requires-Dist: myst-parser>=3.0.0,<4 ; python_full_version < '3.10' and extra == 'docs'
+Requires-Dist: myst-parser>=4.0.0,<5 ; python_full_version >= '3.10' and extra == 'docs'
+Requires-Dist: sphinx>=7.0.1,<8 ; extra == 'docs'
+Requires-Dist: sphinx-autodoc2>=0.5.0,<1 ; extra == 'docs'
+Provides-Extra: docs
+Summary: Fast UUIDv7 Compatible with standard library type, and utils.
+Keywords: uuid,UUIDv7
+Author-email: Guillaume Gauvrit <guillaume@gauvr.it>
+License: MIT License
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
+Project-URL: Homepage, https://github.com/mardiros/lastuuid
+Project-URL: Documentation, https://mardiros.github.io/lastuuid/
+Project-URL: Repository, https://github.com/mardiros/lastuuid.git
+Project-URL: Issues, https://github.com/mardiros/lastuuid/issues
+Project-URL: Changelog, https://mardiros.github.io/lastuuid/changelog.html
+
+# lastuuid - yet another uuid library
+
+[![Documentation](https://github.com/mardiros/lastuuid/actions/workflows/publish-doc.yml/badge.svg)](https://mardiros.github.io/lastuuid/)
+[![Continuous Integration](https://github.com/mardiros/lastuuid/actions/workflows/tests.yml/badge.svg)](https://github.com/mardiros/lastuuid/actions/workflows/tests.yml)
+
+UUID type is awesome, but, at the moment, the UUID type in the standard library
+does not support the uuid7 format.
+
+**lastuuid** provide **fast UUIDv7 generation** made by the
+[rust crate uuid7](https://crates.io/crates/uuid7) **compatible with Pydantic**.
+
+It has additional features that may helps for testing or inspecting UUIDv7.
+
+```{note}
+lastuuid is a developer joke based on the nature of UUIDv7,
+
+where the most recently generated UUID is always the last one when sorted.
+```
+
+## Usage
+
+### UUID7
+
+```python
+>>> from lastuuid import uuid7
+>>> uuid7()
+UUID('019316cc-f99a-77b3-89d5-ed8c3cf1f50e')
+```
+
+There is no parameter here, the uuid is generated from the current time.
+
+The implementation of uuid7 algorithm is made in the uuid7 rust crate.
+
+#### Pydantic
+
+This lib has been created because all the other library that implement uuid7
+create there own UUID type, so its not easy to use with pydantic.
+
+```python
+from uuid import UUID
+from pydantic import BaseModel, Field
+
+from lastuuid import uuid7
+
+
+class Event(BaseModel):
+    id: UUID = Field(default_factory=uuid7)
+
+```
+
+#### NewType
+
+
+The NewTypeFactory will generate an uuid7 for a new defined type.
+
+```python
+from typing import NewType
+
+from uuid import UUID
+from pydantic import BaseModel, Field
+
+from lastuuid.utils import NewTypeFactory
+
+
+MessageID = NewType("MessageID", UUID)
+message_id = NewTypeFactory[MessageID](MessageID)
+
+
+class Message(BaseModel):
+    id: UUID = Field(default_factory=message_id)
+
+```
+
+The message_id here will generate a uuid7 typed MessageID,
+
+this avoid to write `MessageID(uuid7())` to have a MessageID typed uuid.
+
+
+#### Performance
+
+On my machine the uuid7 is as fast (or slow) as the native uuid4.
+
+```bash
+$ python -m timeit "from lastuuid import uuid7; uuid7()"
+200000 loops, best of 5: 1.8 usec per loop
+
+$ python -m timeit "from uuid import uuid4; uuid4()"
+200000 loops, best of 5: 1.82 usec per loop
+```
+
+### Read More
+
+There are other usefull function in the library that cab be found in the
+[API documentation](https://mardiros.github.io/lastuuid/).
+
+https://mardiros.github.io/lastuuid/
+

lastuuid-0.4.2.dist-info/RECORD

@@ -0,0 +1,10 @@
+lastuuid-0.4.2.dist-info/METADATA,sha256=Q8jchvK6MUmSgQdwuaEz4DNpQR39AjrS8OyQyvZyzjQ,3843
+lastuuid-0.4.2.dist-info/WHEEL,sha256=J5COssFJIeAczlAAep7Aav_aPF47wuQgCP8ZUSEsJZE,97
+lastuuid/__init__.py,sha256=yW5FLV4ITqTqPOxW-_Lha9ge5jjAfDUz2auXqboXnYU,131
+lastuuid/dummies.py,sha256=q1HKwlKsf0UDvI_Z9mksxstaksIGTwv4DyXvTAqKJ4Y,3018
+lastuuid/factories.py,sha256=-VhQkx5wMJgdB8i8F22uqE8p4O3qu6Qfwefs-ElGUg8,3062
+lastuuid/lastuuid.cp313-win_arm64.pyd,sha256=pnzsiJY3CsoieSqN9EQ6fS7BqnJdKoWlwz2PJc847H0,216064
+lastuuid/lastuuid.pyi,sha256=hu4g_4eOmq8ixpQ2E3FhjD1xfdtPqNRJI4iFm6mMCTU,354
+lastuuid/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+lastuuid/utils.py,sha256=s0jFEy6bb022FAX8hjchSPFaRKErN_KggvCWN989-6M,2479
+lastuuid-0.4.2.dist-info/RECORD,,

lastuuid-0.4.2.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: maturin (1.10.2)
+Root-Is-Purelib: false
+Tag: cp313-cp313-win_arm64