lastuuid 0.1.1__cp310-cp310-macosx_10_12_x86_64.whl → 0.2.1__cp310-cp310-macosx_10_12_x86_64.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

@@ -3,6 +3,8 @@
 from typing import Iterator
 from uuid import UUID
 
+__all__ = ["uuidgen"]
+
 
 def gen_id() -> Iterator[int]:
     num = 0

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,72 @@
+"""
+Utilities methods that may be used for database querying purpose.
+
+uuid7 are timestamped sorted, so there are a good solution for generating
+primary keys. Because they contains a date time, a UUID range can be compute
+in order to retrieve UUIDs generated at a given time.
+
+Note that in any distribyted system, only using a datetime, or an uuid
+has its limit to properly sort items. This documentation does not cover
+the design data intensive application book ;).
+"""
+
+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.1.dist-info/METADATA

@@ -0,0 +1,96 @@
+Metadata-Version: 2.4
+Name: lastuuid
+Version: 0.2.1
+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.
+
+You may find plenty of library that implement uuid7, but they have downside,
+such has ignoring pull request to fix issues, or not compatible with Pydantic.
+
+```{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 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
+```
+
+### 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.1.dist-info/RECORD

@@ -0,0 +1,9 @@
+lastuuid-0.2.1.dist-info/METADATA,sha256=L3PIVuRQrjOFjyF-JbNsSRYNYAWdEn49d72veTLBOyY,3363
+lastuuid-0.2.1.dist-info/WHEEL,sha256=Nvf9uS0ipTkasVzlCrL-zmcxhW_z3aj8r383FZQZHis,106
+lastuuid/lastuuid.pyi,sha256=s-ll8KBbUeUUqQz087pADg3Y3HLnOikty6dpmYC8fMs,340
+lastuuid/__init__.py,sha256=QwhIMAj4P8cB98_6Qj3mUceQXkHtS9G3bNfGrgb-R1w,122
+lastuuid/utils.py,sha256=PPxM7WYP_Bjy1uXn_dg6rc1GMVEkleh2Z0vjb91XXUo,2538
+lastuuid/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+lastuuid/dummies.py,sha256=0YcdycGKVya59RUnBZSlJg49WeYwjxBcVZKEwuflu4E,520
+lastuuid/lastuuid.cpython-310-darwin.so,sha256=bvkBLrkHFKrq2myAr9xd8h5nRU3XYwVtTK7GqUE9U2g,479640
+lastuuid-0.2.1.dist-info/RECORD,,

{lastuuid-0.1.1.dist-info → lastuuid-0.2.1.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: maturin (1.7.4)
+Generator: maturin (1.8.2)
 Root-Is-Purelib: false
 Tag: cp310-cp310-macosx_10_12_x86_64

lastuuid-0.1.1.dist-info/METADATA

@@ -1,90 +0,0 @@
-Metadata-Version: 2.3
-Name: lastuuid
-Version: 0.1.1
-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.
-
-## 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 brain
-
-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 event more readable;
-UUID predicted, where only the first bytes needs to be read.
-
-```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.1.dist-info/RECORD

@@ -1,8 +0,0 @@
-lastuuid-0.1.1.dist-info/METADATA,sha256=aNObGTSbwFTdlW45XWcGMmRGMnK_5FsEwwHqJEk27kc,2460
-lastuuid-0.1.1.dist-info/WHEEL,sha256=LVI1AVbYRTYC5adM2lSivmcJtOl9s941xFznjYMT5P8,106
-lastuuid/lastuuid.pyi,sha256=PJe_XMTEAMFtsfRfo4HNWHTwPdtMl_hSTQJU6jNIKfY,183
-lastuuid/__init__.py,sha256=J0y-_0o53066oeP1gXBC2MmmBFj0EeETiskPnY4SqKc,49
-lastuuid/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-lastuuid/dummies.py,sha256=4ekFj4XZ3LsCUr7dxnnEoQUo8mydox8aso6Vp89V1is,497
-lastuuid/lastuuid.cpython-310-darwin.so,sha256=74X_DyACESG5-uijWoan9SU4Dglnrn4yQIamxTwbgL0,436376
-lastuuid-0.1.1.dist-info/RECORD,,