lastuuid 0.1.2__cp311-cp311-win32.whl → 0.2.2__cp311-cp311-win32.whl

lastuuid/__init__.py

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

lastuuid/dummies.py

@@ -1,8 +1,15 @@
-"""A dummy uuid usefull for unit testing purpose."""
+"""
+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 typing import Iterator
 from uuid import UUID
 
+__all__ = ["uuidgen"]
+
 
 def gen_id() -> Iterator[int]:
     num = 0
@@ -17,6 +24,43 @@ next_id = gen_id()
 def uuidgen(i: int = 0, j: int = 0, k: int = 0, x: int = 0, y: int = 0) -> UUID:
     """
     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.
+
+    ```python
+    >>> from lastuuid.dummies import uuidgen
+    >>> uuidgen()
+    UUID('00000000-0000-0000-0000-000000000001')
+    >>> uuidgen()
+    UUID('00000000-0000-0000-0000-000000000002')
+    ```
+
     """
     if i == 0 and y == 0:
         y = next(next_id)

lastuuid/lastuuid.pyi

@@ -1,9 +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,83 @@
+"""
+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.
+
+
+```{important}
+In a distributed system, relying solely on a datetime or UUIDv7 for sorting
+has limitations.
+While UUIDv7 ensures sequential ordering on a single machine, there is no guarantee
+that a UUIDv7 generated later on one machine will be greater than one generated
+earlier on another machine.
+
+This documentation does not cover the book Designing Data-Intensive Applications ;).
+```
+"""
+
+from datetime import UTC, date, datetime, time, timedelta
+from typing_extensions import Tuple
+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.2.2.dist-info/METADATA

@@ -0,0 +1,98 @@
+Metadata-Version: 2.4
+Name: lastuuid
+Version: 0.2.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: Guillaume Gauvrit <guillaume@gauvr.it>
+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)
+[![Maintainability](https://api.codeclimate.com/v1/badges/8e7293fabe7508b2ec6c/maintainability)](https://codeclimate.com/github/mardiros/lastuuid/maintainability)
+
+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)
+
+```
+
+#### 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.2.2.dist-info/RECORD

@@ -0,0 +1,9 @@
+lastuuid-0.2.2.dist-info/METADATA,sha256=_Inh1YdmPXQaKA9R8-o7bSriL_ZwyEYB-6Bx7HwaLA4,3494
+lastuuid-0.2.2.dist-info/WHEEL,sha256=cazBU6xJtRuKVkT3lvqxOZ_3XVozNavIaITeCYtVC60,92
+lastuuid/dummies.py,sha256=DD8trFboMNNEAknUk2SoQH7C15WJAK6MV9FUS_FFCJc,1950
+lastuuid/lastuuid.pyi,sha256=hu4g_4eOmq8ixpQ2E3FhjD1xfdtPqNRJI4iFm6mMCTU,354
+lastuuid/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+lastuuid/utils.py,sha256=Ocx0R9aXmIcj2hgsnwrtvjArFryRiao6BzhWBePX7R8,2917
+lastuuid/__init__.py,sha256=yW5FLV4ITqTqPOxW-_Lha9ge5jjAfDUz2auXqboXnYU,131
+lastuuid/lastuuid.cp311-win32.pyd,sha256=m-2xcbKP7kQtsULPTjvJJJLRA-hc3jIH4UpqCDbTiD8,194560
+lastuuid-0.2.2.dist-info/RECORD,,

{lastuuid-0.1.2.dist-info → lastuuid-0.2.2.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: maturin (1.7.8)
+Generator: maturin (1.8.2)
 Root-Is-Purelib: false
 Tag: cp311-cp311-win32

lastuuid-0.1.2.dist-info/METADATA

@@ -1,101 +0,0 @@
-Metadata-Version: 2.4
-Name: lastuuid
-Version: 0.1.2
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Rust
-Summary: UUID gen for the python standard library.
-Keywords: environment,substitution,variables
-Author: Guillaume Gauvrit <guillaume@gauvr.it>
-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://github.com/mardiros/lastuuid/blob/main/README.md
-Project-URL: Repository, https://github.com/mardiros/lastuuid.git
-Project-URL: Issues, https://github.com/mardiros/lastuuid/issues
-Project-URL: Changelog, https://github.com/mardiros/lastuuid/blob/main/CHANGELOG.md
-
-# lastuuid - yet another uuid library
-
-UUID type is awesome, but, at the moment, the UUID type in the standard library
-does not support the uuid7 format.
-
-This is where lastuuid library is usefull.
-
-## 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 Dummy(BaseModel):
-    id: UUID = Field(default_factory=uuid7)
-
-```
-
-#### 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
-```
-
-### Testing with uuid without a brain
-
-The uuidgen method is not made for production code, it is not suited to be
-fast, it is here to generate uuid has autoincrement or as redictable ids,
-because UUID are made to create an identifier before it's saved into a
-database.
-
-
-Autoincrement your uuid in a test suite avoid some brain pain:
-
-```python
->>> from lastuuid.dummies import uuidgen
->>> uuidgen()
-UUID('00000000-0000-0000-0000-000000000001')
->>> uuidgen()
-UUID('00000000-0000-0000-0000-000000000002')
-```
-
-Or even more usefull:
-
-UUID predicted, where only the first bunch of bytes needs to be read; or a few,
-to arrange some object ids.
-
-
-```python
->>> from lastuuid.dummies import uuidgen
->>> uuidgen(1)
-UUID('00000001-0000-0000-0000-000000000000')
->>> uuidgen(1, 2, 3, 4, 5)
-UUID('00000001-0002-0003-0004-000000000005')
-```
-

lastuuid-0.1.2.dist-info/RECORD

@@ -1,8 +0,0 @@
-lastuuid-0.1.2.dist-info/METADATA,sha256=rvx50UZUSvA6VpX5t24NKyMcqjh9uHu9LI6LVg-uDsI,2870
-lastuuid-0.1.2.dist-info/WHEEL,sha256=cIWnBshq9UErEeNtadr9w7TUZu32emQUVzK31LjJSaM,92
-lastuuid/dummies.py,sha256=appIhKdQLL_8Mo5Xb0fzYjBV6w3iJrHZzgk-JNAnej0,520
-lastuuid/lastuuid.pyi,sha256=UWNZIdqlzkbln21QRVGqfOX8sn6FLJUjbG3jlAT22O4,192
-lastuuid/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-lastuuid/__init__.py,sha256=GwcZ4cGLHj95prUoK_-Te0TY3gxoLguXp-OEMIJNJzo,52
-lastuuid/lastuuid.cp311-win32.pyd,sha256=P_ajE9DwLWvmSwP8VXAYt-IKolN5Ko2T4QAwF5NGZk0,167936
-lastuuid-0.1.2.dist-info/RECORD,,