Welcome to time-uuid’s documentation!

time_uuid is a lightweight Python library for sensibly dealing with UUIDv1 (or TimeUUIDs as we like to sometimes call them). It allows you to create UUIDv1s in a variety of different ways. Take a look at the docs for the interface.

The Interface

class time_uuid.TimeUUID(hex=None, bytes=None, bytes_le=None, fields=None, int=None, version=None)

A class that makes dealing with time and V1 UUIDs much easiser. Offers accurate comparison (compares accurately with other TimeUUIDs and UUIDv1), a way to get TimeUUIDs with UTC-timestamps (instead of the default localtime), an easy way to get the UTC datetime object from it, and default encoding and decoding methods.

classmethod convert(value, randomize=True, lowest_val=False)

Try to convert a number of different types to a TimeUUID. Works for datetimes, ints (which it treats as timestamps) and UUIDs.

See with_timestamp() for descriptions of the randomize and lowest_val arguments.

Parameters:value – An instance of UUID, TimeUUID, datetime or timestamp int or float Returns:A TimeUUID object Return type:TimeUUID

get_datetime()

Return the UTC datetime object

get_timestamp()

Return the timestamp

classmethod with_timestamp(timestamp, randomize=True, lowest_val=False)

Create a TimeUUID with any timestamp. Be sure that the timestamp is created with the correct offset. If you are using time.time() be sure to know that in python, it may be offset by your machine’s time zone!

Parameters:

• timestamp (float) – A timestamp, like that returned by utctime() or py:func:time.time.
• randomize (bool) – will create a UUID with randomish bits. This overrides it’s counterpart: lowest_val If randomize is False and lowest_val is False, it will generate a UUID with the highest possible clock seq for the same timestamp, otherwise generating a UUID with the lowest possible clock seq for the same timestamp. Defaults to True
• lowest_val (bool) – will create a UUID with the lowest possible clock seq if randomize is False if set to True, otherwise generating the highest possible. Defaults to False

Returns:

A TimeUUID object

Return type:

TimeUUID

classmethod with_utc(d, randomize=True, lowest_val=False)

Create a TimeUUID with any datetime in UTC. Only use this if you are sure you are creating your datetime objects properly and can predict how the TimeUUID will sort (if that is at all necessary).

See with_timestamp() for a description of how randomize and lowest_val arguments work.

Parameters:d (TimeUUID) – A datetime object Returns:A TimeUUID object

classmethod with_utcnow(randomize=True)

Create a TimeUUID with the current datetime in UTC. Every TimeUUID generated this way, on this machine, will supersede the TimeUUID generated before it, by use of a mutex.

Parameters:randomize – Whether or not to randomize the other bits in the UUID.

Defaults to True :type randomize: bool

Returns:A TimeUUID object Return type:TimeUUID

time_uuid.utctime()

Generate a timestamp from the current time in UTC. Returns exactly the same thing as :py:func`time.time` but with a UTC offset instead of a local one

Returns:a timestamp Return type:float

time_uuid.mkutime(d)

Generate a UTC timestamp from the datetime object.

Parameters:d (datetime) – a datetime object

Recipes

Sorting TimeUUID

TimeUUIDs can be sorted sorted. They will be sorted, first by the date component, then by the random component in a consistent way:

>>> import random, time_uuid
>>> rand_time = lambda: float(random.randrange(0,30))+time_uuid.utctime()
>>> uuids = [time_uuid.TimeUUID.with_timestamp(rand_time()) for i in xrange(3)]
[TimeUUID('2e4ac100-31f1-11e2-9286-14109fcdd33b'),
 TimeUUID('2db393a2-31f1-11e2-abda-14109fcdd33b'),
 TimeUUID('2987779e-31f1-11e2-a699-14109fcdd33b')]
>>> list(sorted(uuids))
[TimeUUID('2987779e-31f1-11e2-a699-14109fcdd33b'),
 TimeUUID('2db393a2-31f1-11e2-abda-14109fcdd33b'),
 TimeUUID('2e4ac100-31f1-11e2-9286-14109fcdd33b')]

Creating lower and upper bounds for range searches with TimeUUIDs

If you are using a database in which TimeUUIDs are a first-class data type, you can use TimeUUID to generate upper and lower bounds for range queries:

>>> import time_uuid, datetime
>>> floor_day = lambda d: datetime.datetime(year=d.year, month=d.month, day=d.day)
>>> yesterday = floor_day(datetime.datetime.utcnow() - datetime.datetime.timedelta(days=1))
>>> today = floor_day(datetime.datetime.utcnow())
>>> lower_bound = time_uuid.TimeUUID.with_utc(yesterday, randomize=False, lowest_val=True)
>>> upper_bound = time_uuid.TimeUUID.with_utc(today, randomize=False, lowest_val=False)

Indices and tables

• Index
• Module Index
• Search Page