ulid package¶

ulid module¶

This module provides immutable ULID objects (class ULID) according to the ULID spec and the functions generate() to generate ulids according to the specifications, encode() to transform a given integer to the canonical string representation of an ULID, and decode() to take a canonically encoded string and break it down into it’s timestamp and randomness components. The module also provides Monotonic sort order guarantee for ULIDs via the Monotonic class and it’s associated generate() function.

class ulid.ulid.Monotonic(seed=None)[source]¶

Bases: ulid.ulid.ULID

The Monotonic class represent an extension of the base ULID class with the addition of a monotonic sort order (correctly detects and handles the same millisecond)

MAX_EPOCH_TIME = 281474976710655¶

crockford_base = '0123456789ABCDEFGHJKMNPQRSTVWXYZ'¶

decode(s: str) → Tuple[int, int]¶

Given a properly formed ULID, return a tuple containing the timestamp and the randomness component as ints

Parameters:	s (str) – ULID string to decode
Returns:	(timestamp, randomness)
Return type:	tuple(int, int)
Raises:	TypeError, ValueError

>>> from ulid import ULID
>>> ulid = ULID()
>>> ulid.decode('01BX5ZZKBKACTAV9WEVGEMMVRY')
(1508808576371, 392928161897179156999966)

encode(i: int) → str¶

Convert a given integer into the canonical ULID string format

Parameters:	i (int) – The integer to convert
Returns:	Canonically encoded ULID string
Return type:	str
Raises:	TypeError, ValueError

>>> from ulid import ULID
>>> ulid = ULID()
>>> ulid.encode(340282366920938463463374607431768167)
00864KEJY6MZQSVCHD1SB08637

encode_timestamp(t: int) → str¶

Convert a given unix timestamp into the canonical ULID string format

Parameters:	t (int) – The unix timestamp to convert
Returns:	Canonically encoded ULID string
Return type:	str
Raises:	TypeError, ValueError

>>> from ulid import ULID
>>> ulid = ULID()
>>> ulid.encode(281474976710655)
7ZZZZZZZZZ

generate() → str[source]¶

Generate a 26 character ULID string encoded in Crockford’s Base32

Returns:	Canonically encoded ULID string
Return type:	str
Raises:	ValueError

>>> from ulid import Monotonic
>>> ulid = Monotonic()
>>> ulid.generate()
01BX5ZZKBKACTAV9WEVGEMMVRZ

pretty_print(s: str) → None¶

Print the given ULID string in a binary layout

>>> from ulid import ULID
>>> ulid = ULID()
>>> ulid.pretty_print(ulid_str)
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|                      32_bit_uint_time_high                    |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|     16_bit_uint_time_low      |       16_bit_uint_random      |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|                       32_bit_uint_random                      |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|                       32_bit_uint_random                      |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

class ulid.ulid.ULID(seed=None)[source]¶

Bases: object

Instances of the ULID class represent ULIDS as specified in the ULID spec. ULIDS have 128-bit compatibility with UUID, are Lexicographically sortable, case insensitive and URL safe

MAX_EPOCH_TIME = 281474976710655¶

crockford_base = '0123456789ABCDEFGHJKMNPQRSTVWXYZ'¶

decode(s: str) → Tuple[int, int][source]¶

Given a properly formed ULID, return a tuple containing the timestamp and the randomness component as ints

Parameters:	s (str) – ULID string to decode
Returns:	(timestamp, randomness)
Return type:	tuple(int, int)
Raises:	TypeError, ValueError

>>> from ulid import ULID
>>> ulid = ULID()
>>> ulid.decode('01BX5ZZKBKACTAV9WEVGEMMVRY')
(1508808576371, 392928161897179156999966)

encode(i: int) → str[source]¶

Convert a given integer into the canonical ULID string format

Parameters:	i (int) – The integer to convert
Returns:	Canonically encoded ULID string
Return type:	str
Raises:	TypeError, ValueError

>>> from ulid import ULID
>>> ulid = ULID()
>>> ulid.encode(340282366920938463463374607431768167)
00864KEJY6MZQSVCHD1SB08637

encode_timestamp(t: int) → str[source]¶

Convert a given unix timestamp into the canonical ULID string format

Parameters:	t (int) – The unix timestamp to convert
Returns:	Canonically encoded ULID string
Return type:	str
Raises:	TypeError, ValueError

>>> from ulid import ULID
>>> ulid = ULID()
>>> ulid.encode(281474976710655)
7ZZZZZZZZZ

generate() → str[source]¶

Generate a 26 character ULID string encoded in Crockford’s Base32

Returns:	Canonically encoded ULID string
Return type:	str

>>> from ulid import ULID
>>> ulid = ULID()
>>> ulid.generate()
01BX5ZZKBKACTAV9WEVGEMMVRZ

pretty_print(s: str) → None[source]¶

Print the given ULID string in a binary layout

>>> from ulid import ULID
>>> ulid = ULID()
>>> ulid.pretty_print(ulid_str)
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|                      32_bit_uint_time_high                    |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|     16_bit_uint_time_low      |       16_bit_uint_random      |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|                       32_bit_uint_random                      |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|                       32_bit_uint_random                      |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

Module contents¶

ULID class¶

class ulid.ULID(seed=None)[source]¶

Instances of the ULID class represent ULIDS as specified in the ULID spec. ULIDS have 128-bit compatibility with UUID, are Lexicographically sortable, case insensitive and URL safe

decode(s: str) → Tuple[int, int][source]¶

Given a properly formed ULID, return a tuple containing the timestamp and the randomness component as ints

Parameters:	s (str) – ULID string to decode
Returns:	(timestamp, randomness)
Return type:	tuple(int, int)
Raises:	TypeError, ValueError

>>> from ulid import ULID
>>> ulid = ULID()
>>> ulid.decode('01BX5ZZKBKACTAV9WEVGEMMVRY')
(1508808576371, 392928161897179156999966)

encode(i: int) → str[source]¶

Convert a given integer into the canonical ULID string format

Parameters:	i (int) – The integer to convert
Returns:	Canonically encoded ULID string
Return type:	str
Raises:	TypeError, ValueError

>>> from ulid import ULID
>>> ulid = ULID()
>>> ulid.encode(340282366920938463463374607431768167)
00864KEJY6MZQSVCHD1SB08637

encode_timestamp(t: int) → str[source]¶

Convert a given unix timestamp into the canonical ULID string format

Parameters:	t (int) – The unix timestamp to convert
Returns:	Canonically encoded ULID string
Return type:	str
Raises:	TypeError, ValueError

>>> from ulid import ULID
>>> ulid = ULID()
>>> ulid.encode(281474976710655)
7ZZZZZZZZZ

generate() → str[source]¶

Generate a 26 character ULID string encoded in Crockford’s Base32

Returns:	Canonically encoded ULID string
Return type:	str

>>> from ulid import ULID
>>> ulid = ULID()
>>> ulid.generate()
01BX5ZZKBKACTAV9WEVGEMMVRZ

pretty_print(s: str) → None[source]¶

Print the given ULID string in a binary layout

>>> from ulid import ULID
>>> ulid = ULID()
>>> ulid.pretty_print(ulid_str)
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|                      32_bit_uint_time_high                    |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|     16_bit_uint_time_low      |       16_bit_uint_random      |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|                       32_bit_uint_random                      |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|                       32_bit_uint_random                      |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

Monotonic class¶

class ulid.Monotonic(seed=None)[source]¶

The Monotonic class represent an extension of the base ULID class with the addition of a monotonic sort order (correctly detects and handles the same millisecond)

decode(s: str) → Tuple[int, int]¶

Given a properly formed ULID, return a tuple containing the timestamp and the randomness component as ints

Parameters:	s (str) – ULID string to decode
Returns:	(timestamp, randomness)
Return type:	tuple(int, int)
Raises:	TypeError, ValueError

>>> from ulid import ULID
>>> ulid = ULID()
>>> ulid.decode('01BX5ZZKBKACTAV9WEVGEMMVRY')
(1508808576371, 392928161897179156999966)

encode(i: int) → str¶

Convert a given integer into the canonical ULID string format

Parameters:	i (int) – The integer to convert
Returns:	Canonically encoded ULID string
Return type:	str
Raises:	TypeError, ValueError

>>> from ulid import ULID
>>> ulid = ULID()
>>> ulid.encode(340282366920938463463374607431768167)
00864KEJY6MZQSVCHD1SB08637

encode_timestamp(t: int) → str¶

Convert a given unix timestamp into the canonical ULID string format

Parameters:	t (int) – The unix timestamp to convert
Returns:	Canonically encoded ULID string
Return type:	str
Raises:	TypeError, ValueError

>>> from ulid import ULID
>>> ulid = ULID()
>>> ulid.encode(281474976710655)
7ZZZZZZZZZ

generate() → str[source]¶

Generate a 26 character ULID string encoded in Crockford’s Base32

Returns:	Canonically encoded ULID string
Return type:	str
Raises:	ValueError

>>> from ulid import Monotonic
>>> ulid = Monotonic()
>>> ulid.generate()
01BX5ZZKBKACTAV9WEVGEMMVRZ

pretty_print(s: str) → None¶

Print the given ULID string in a binary layout

>>> from ulid import ULID
>>> ulid = ULID()
>>> ulid.pretty_print(ulid_str)
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|                      32_bit_uint_time_high                    |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|     16_bit_uint_time_low      |       16_bit_uint_random      |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|                       32_bit_uint_random                      |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|                       32_bit_uint_random                      |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+