Add simple UUID module with uuid4() by dpgeorge · Pull Request #1137 · micropython/micropython-lib

dpgeorge · 2026-07-11T05:15:38Z

Summary

This PR pulls in @andrewleech 's minimal UUID implementation from https://github.com/pfalcon/pycopy-lib (originally submitted here as #312, #313 long ago).

Then I made a few updates to it:

add manifest.py
convert test to use unittest and run it under CI
use bytes.hex() instead of binascii.hexlify().decode()
run ruff format

Testing

Test added that runs under CI.

Trade-offs and Alternatives

This adds a minimal implementation of uuid.uuid4() which is arguably the more important of the uuidX functions.

Alternatives:

Add uuid4 implementation #282 is similarly small, but didn't mask the correct bits for the UUID value
WIP: Add uuid module #504 brings in the full CPython module which is large and probably we don't need all that functionality

Generative AI

Not used.

Includes unit test. Signed-off-by: Damien George <damien@micropython.org>

And run it as part of CI. Signed-off-by: Damien George <damien@micropython.org>

Using `bytes.hex()` eliminates an import, and eliminates the call to `.decode()` to convert it to a str. Also run ruff format. Signed-off-by: Damien George <damien@micropython.org>

andrewleech

Looks great thanks.

andrewleech · 2026-07-13T21:46:49Z

+class UUID:
+    def __init__(self, bytes):
+        if len(bytes) != 16:
+            raise ValueError("bytes arg must be 16 bytes long")


I tried to test if cpython gave the save error here but it gave a much messier exception. Possibly not worth worrying about, this should be user friendly enough.

Yeah, indeed CPython does give a confusing error.

dpgeorge · 2026-07-14T00:40:17Z

Thanks for the review!

mattytrentini · 2026-07-14T01:07:47Z

+    def test_unique(self):
+        u1 = uuid.uuid4()
+        u2 = uuid.uuid4()
+        self.assertNotEqual(u1.hex, u2.hex)
+        self.assertNotEqual(str(u1), str(u2))


Are there tests to ensure that, for a given port, os.urandom provides unique results? I could only find tests/extmod/os_urandom.py.

Perhaps we should then either test urandom more thoroughly or test uuid uniqueness here more thoroughly? For comparison, CPython generates 1000 UUIDs and ensures they're all unique (see here).

Testing urandom() is out of scope of this PR. A port needs to make sure that works as expected, and then this module should just be able to rely on that.

We could add a loop here to test a few more uniqueness, but IMO 1000 is excessive.

Added a test that 10 UUIDs are unique.

mattytrentini · 2026-07-14T01:37:06Z

+        return "-".join((h[0:8], h[8:12], h[12:16], h[16:20], h[20:32]))
+
+    def __repr__(self):
+        return "<UUID: %s>" % str(self)


This repr output is different to CPython; would it be better to make it compatible?

Python 3.12.3 (main, Jun 19 2026, 12:46:00) [GCC 13.3.0] on linux Type "help", "copyright", "credits" or "license" for more information. >>> from uuid import uuid4 >>> uuid4() UUID('84da63f4-127b-4c34-a7d9-b4321bf6f794')

Yes, could make it the same as CPython, that would be easy.

Updated to match CPython.

mattytrentini · 2026-07-14T02:02:32Z

+import os
+
+
+class UUID:


I'm not sure if other methods/properties would make porting CPython code easier, it's hard to know which are in common use. version and variant seem like they would be high on the list - particularly if we decide to add support for UUIDv7 in the future - but it's probably best to hold off for now and keep it as minimal as possible.

I also don't really know what users are going to need...

dpgeorge · 2026-07-14T02:52:25Z

@mattytrentini if you think this is not enough functionality then we can consider instead your #504 implementation. That's fundamentally different in that it stores the UUID as an int and hence allows easy access of fields -- although I'm not sure how useful that will be?

mattytrentini · 2026-07-14T03:18:29Z

@mattytrentini if you think this is not enough functionality then we can consider instead your #504 implementation. That's fundamentally different in that it stores the UUID as an int and hence allows easy access of fields -- although I'm not sure how useful that will be?

No, I think this minimal approach is best, at least for now. I've tried to scour some popular applications that used uuid but of the few I looked at, they just used it without calling any other methods.

dpgeorge · 2026-07-14T03:28:01Z

It's probably a good idea to eventually support more functions, like the namespace UUIDs. And adding a version property would make sense because this uuid4() function creates RFC 4122 UUIDs.

Signed-off-by: Damien George <damien@micropython.org>

dpgeorge · 2026-07-14T04:05:29Z

I exposed the .bytes property to easily access the underlying bytes of the UUID.

mattytrentini · 2026-07-14T04:30:19Z

I think this now strikes an excellent balance between functional and minimal. Looks good to me!

dpgeorge · 2026-07-14T04:51:32Z

Thanks @mattytrentini !

dpgeorge requested review from andrewleech and mattytrentini July 11, 2026 05:15

andrewleech and others added 3 commits July 11, 2026 15:17

uuid: Provide UUID class and uuid4() implementation using os.urandom().

edc8b7c

Includes unit test. Signed-off-by: Damien George <damien@micropython.org>

uuid: Convert test to use unittest.

91b10e6

And run it as part of CI. Signed-off-by: Damien George <damien@micropython.org>

uuid: Use bytes.hex instead of binascii.hexlify.

0651951

Using `bytes.hex()` eliminates an import, and eliminates the call to `.decode()` to convert it to a str. Also run ruff format. Signed-off-by: Damien George <damien@micropython.org>

dpgeorge force-pushed the add-uuid branch from 25363cc to 0651951 Compare July 11, 2026 05:17

andrewleech approved these changes Jul 13, 2026

View reviewed changes

dpgeorge mentioned this pull request Jul 14, 2026

WIP: Add uuid module #504

Open

3 tasks

mattytrentini reviewed Jul 14, 2026

View reviewed changes

dpgeorge added 2 commits July 14, 2026 14:03

uuid: Add .bytes and make repr match CPython.

2fe05af

Signed-off-by: Damien George <damien@micropython.org>

uuid: Enhance tests.

b9aed47

Signed-off-by: Damien George <damien@micropython.org>

Uh oh!

Conversation

dpgeorge commented Jul 11, 2026

Summary

Testing

Trade-offs and Alternatives

Generative AI

Uh oh!

andrewleech left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dpgeorge commented Jul 14, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dpgeorge commented Jul 14, 2026

Uh oh!

mattytrentini commented Jul 14, 2026

Uh oh!

dpgeorge commented Jul 14, 2026

Uh oh!

dpgeorge commented Jul 14, 2026

Uh oh!

mattytrentini commented Jul 14, 2026

Uh oh!

dpgeorge commented Jul 14, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants