[Feature request] Ability to define the timestamp part for generation functions

[attevaltojarvi]

Hi, and thanks for this package!

I'm proposing an update for the uuid6, uuid7 and uuid8 functions, where you could optionally specify the timestamp that gets used when generating the UUID value. For example for the uuid7 function:

def uuid7(timestamp_ms: int = None) -> UUID:
    global _last_v7_timestamp

    if timestamp_ms is None:
        nanoseconds = time.time_ns()
        timestamp_ms = nanoseconds // 10**6
    # (rest of function)

I haven't checked whether this isn't allowed in the spec, but I feel that this would be really useful in situations where you need to generate UUIDs for historical data, where you have the records' creation timestamp available:

# Django model example

for obj in Model.objects.iterator():
    timestamp = calendar.timegm(obj.created_at.utctimetuple())
    timestamp_ms = timestamp * 10**3
    obj.new_id = uuid7(timestamp_ms)
    obj.save()

This would allow for updating a system to start creating new records with the current timestamp, and a data migration for historical data, retaining the sortability by the UUID timestamp part.

Thanks in advance!

[oittaa]

Sorry I hadn't checked GitHub in a moment. While these options sound like a nice idea, I'm a bit worried that people would misuse these functions. v6 has a weird offset by Microsoft, v7 uses milliseconds since epoch, v8 nanoseconds... Does anyone have suggestions how to reasonably avoid disasters like mixing nanoseconds and milliseconds?

[attevaltojarvi]

I personally think that the function signatures should just be clearly defined on which type they expect to receive:

def uuid7(at_milliseconds: int = None) -> UUID:
    ...
    

def uuid8(at_nanoseconds: int = None) -> UUID:
    ...

Getting the order of magnitude wrong is just a bad user error you can make with any other 3rd party library.