aminalaee/uuid-utils

Python bindings to Rust UUID

Python UUID Utils

---

Python UUID implementation using Rust's UUID library. This will make uuid4 function around 10x faster.

This package can be a drop-in replacement to the standard library UUID which implements existing UUID versions like V4 in Rust and also adds draft UUID versions like V6.

Avaialble UUID versions:

• uuid1 - Version 1 UUIDs using a timestamp and monotonic counter.
• uuid3 - Version 3 UUIDs based on the MD5 hash of some data.
• uuid4 - Version 4 UUIDs with random data.
• uuid5 - Version 5 UUIDs based on the SHA1 hash of some data.
• uuid6 - Version 6 UUIDs using a timestamp and monotonic counter.
• uuid7 - Version 7 UUIDs using a Unix timestamp ordered by time.
• uuid8 - Version 8 UUIDs using user-defined data.

^{Please note that UUID versions 6, 7 and 8 are still in draft RFC.}

Installation

Using pip:

$ pip install uuid-utils

or, using conda:

$ conda install -c conda-forge uuid-utils

Example

>>> import uuid_utils as uuid

>>> # make a random UUID
>>> uuid.uuid4()
UUID('ffe95fcc-b818-4aca-a350-e0a35b9de6ec')

>>> # make a random UUID using a Unix timestamp which is time-ordered.
>>> uuid.uuid7()
UUID('018afa4a-0d21-7e6c-b857-012bc678552b')

>>> # make a UUID using a SHA-1 hash of a namespace UUID and a name
>>> uuid.uuid5(uuid.NAMESPACE_DNS, 'python.org')
UUID('886313e1-3b8a-5372-9b90-0c9aee199e5d')

>>> # make a UUID using an MD5 hash of a namespace UUID and a name
>>> uuid.uuid3(uuid.NAMESPACE_DNS, 'python.org')
UUID('6fa459ea-ee8a-3ca4-894e-db77e160355e')

Compat module

In some cases you might need UUID instances to be returned from the standrad-library uuid, not a custom UUID class. In that case you can use the uuid_utils.compat which comes with a performance penalty in comparison with the uuid_utils default behaviour, but still faster than the standard-library.

>>> import uuid_utils.compat as uuid

>>> # make a random UUID
>>> uuid.uuid4()
UUID('ffe95fcc-b818-4aca-a350-e0a35b9de6ec')

Benchmarks

Benchmark	Min	Max	Mean	Min (+)	Max (+)	Mean (+)
UUID V1	0.058	0.059	0.058	0.005 (12.0x)	0.005 (11.9x)	0.005 (12.0x)
UUID V3	0.063	0.064	0.063	0.008 (7.9x)	0.008 (8.1x)	0.008 (8.0x)
UUID V4	0.041	0.041	0.041	0.004 (11.1x)	0.004 (10.8x)	0.004 (10.9x)
UUID V5	0.064	0.066	0.065	0.008 (8.1x)	0.008 (8.1x)	0.008 (8.1x)
UUID from hex	0.024	0.025	0.024	0.004 (6.7x)	0.004 (6.6x)	0.004 (6.6x)
UUID from bytes	0.024	0.025	0.024	0.004 (6.7x)	0.004 (6.6x)	0.004 (6.7x)
UUID from int	0.024	0.025	0.024	0.004 (6.6x)	0.004 (6.7x)	0.004 (6.6x)
UUID from fields	0.028	0.028	0.028	0.009 (3.1x)	0.009 (3.1x)	0.009 (3.1x)

How to develop locally

$ make build
$ make test

Or:

$ RUSTFLAGS="--cfg uuid_unstable" maturin develop --release

uuid-utils's Issues

Does it meets the final specs?

Since RFC 9562 is final now, I was wondering if this implementation is already compliant with finalized UUID7.

[Bug] Import name is wrong.

Expected:

To use uuid-utils the README.md mentions to:

import uuid_utils as uuid

Current:

To actually be able to import uuid-utils, you need to:

import _uuid_utils as uuid

[Feature request] Possibility to return native python UUID type

Would it be possible to add a parameter, that a native python UUID is returned instead of the uuid-utils UUID type?

Background: Some packages like psycopg2 expect a native python UUID returned back instead of sth. customized.

Add method to get timestamp

No module named 'uuid_utils._uuid_utils'"

environments

• uuid-utils version: 0.6.1
• AWS Lambda python runtime: 3.11
• OS: Ubuntu: 20.04.4

way to reproduce:

1. I am using python3.8 environment locally
2. I pip install -r $dir/requirements.txt --target $lambda_function_dir/third_party ( where I put the uuid_utils==0.6.1 in the requirements.txt )
3. I zipped all the dependencies needed to run in AWS Lambda, then I uploaded this zipped package to Lambda.

Issue Statement:

but when I create an test event and invoke the lambda function, it throws an error No module named 'uuid_utils._uuid_utils'

Test Event Name
update-sites

Response
{
  "errorMessage": "Unable to import module 'lambda_function': No module named 'uuid_utils._uuid_utils'",
  "errorType": "Runtime.ImportModuleError",
  "requestId": "7d706df9-dd9f-49d4-80ae-ea0dee96a5cc",
  "stackTrace": []
}

Function Logs
START RequestId: 7d706df9-dd9f-49d4-80ae-ea0dee96a5cc Version: $LATEST
[ERROR] Runtime.ImportModuleError: Unable to import module 'lambda_function': No module named 'uuid_utils._uuid_utils'
Traceback (most recent call last):END RequestId: 7d706df9-dd9f-49d4-80ae-ea0dee96a5cc
REPORT RequestId: 7d706df9-dd9f-49d4-80ae-ea0dee96a5cc	Duration: 8.30 ms	Billed Duration: 9 ms	Memory Size: 128 MB	Max Memory Used: 59 MB	Init Duration: 261.54 ms

Request ID
7d706df9-dd9f-49d4-80ae-ea0dee96a5cc

additional context

locally run this lambda function is fine. I think there might be something wrong when creating this pip package.

`uuid`'s `fast-rng` feature doesn't mesh with python's frequent use of fork

We've been debugging an issue today after introducing uuid-utils into our backend workers, which use Celery. Celery workers use fork(2) (at least in some configurations) to spin up worker processes.

The rand crate, which rust's uuid crate uses if you pass the fast-rng crate, doesn't seem to reseed the RNG on a fork. In Rust land, I suppose this normally isn't an issue because it seems pretty rare to use fork. In python, it's a lot more common, causing a situation where the rng isn't reseeded when forking out celery workers.

Enjoy some repros:

fn main() {
    // first, just make sure the rng is initialized in the parent process
    let _ = uuid::Uuid::new_v4();
    let tid = unsafe { libc::fork() };
    println!("{:?} from {tid}", uuid::Uuid::new_v4());
}

import sys
import uuid_utils
sys.modules["uuid"] = uuid_utils
import os

import uuid

a = uuid.uuid4()
print(f"a = {a}")
os.fork()
b = uuid.uuid4()
print(f"b = {b}")

I suppose this is technically not a bug, I'm just interested in your take on this. Ultimately it's kind of a culture issue that python forks, but as of now it's a tradeoff between the "just works"-ness of this as a library and generating uuids very quickly.

Versions

• uuid_utils 0.6.1
• cpython 3.12.0
• macos and linux

[Bug] Issue with python 3.12 support

I'm using the devcontainer mcr.microsoft.com/vscode/devcontainers/python:3.12-bullseye as an environment.

If I try to install the latest verson of uuid-utils it fails:

vscode ➜ /dev (master) $ pip install uuid-utils
Defaulting to user installation because normal site-packages is not writeable
Collecting uuid-utils
  Downloading uuid_utils-0.4.0.tar.gz (15 kB)
  Installing build dependencies ... done
  Getting requirements to build wheel ... done
  Preparing metadata (pyproject.toml) ... error
  error: subprocess-exited-with-error
  
  × Preparing metadata (pyproject.toml) did not run successfully.
  │ exit code: 1
  ╰─> [6 lines of output]
      Checking for Rust toolchain....
      
      Cargo, the Rust package manager, is not installed or is not on PATH.
      This package requires Rust and Cargo to compile extensions. Install it through
      the system's package manager or via https://rustup.rs/
      
      [end of output]
  
  note: This error originates from a subprocess, and is likely not a problem with pip.
error: metadata-generation-failed

× Encountered error while generating package metadata.
╰─> See above for output.

note: This is an issue with the package mentioned above, not pip.
hint: See above for details.

It works if you change the devcontainer to python:3.11-bullseye

Incompatible with Django

It doesn't work correctly as a drop-in replacement with Django.

I have a uuid field:

uuid = models.UUIDField(default=uuid.uuid4(), editable=False)

If I replace the standard uuid module with uuid_utils and run stress tests I'll end with a crash at some point with

django.core.exceptions.ValidationError: ['“771202f8-71eb-483b-b553-c3f9d9ef216a” is not a valid UUID.']

It happens somewhere when calling the standard package with

AttributeError: 'uuid_utils.UUID' object has no attribute 'replace'

Any idea what to do?