ulid/api¶
Defines the public API of the ulid package.
-
ulid.api.
new
() → ulid.ulid.ULID¶ Create a new
ULID
instance.The timestamp and randomness values are created from the instance
Provider
.- Returns
ULID from current timestamp
- Return type
-
ulid.api.
parse
(value: Union[int, float, str, bytes, bytearray, memoryview, uuid.UUID, ulid.ulid.ULID]) → ulid.ulid.ULID¶ Create a new
ULID
instance from the given value.Note
This method should only be used when the caller is trying to parse a ULID from
a value when they’re unsure what format/primitive type it will be given in.
- Parameters
value (
ULIDPrimitive
) – ULID value of any supported type- Returns
ULID from value
- Return type
- Raises
ValueError – when unable to parse a ULID from the value
-
ulid.api.
create
(timestamp: Union[int, float, str, bytes, bytearray, memoryview, datetime.datetime, ulid.ulid.Timestamp, ulid.ulid.ULID], randomness: Union[int, float, str, bytes, bytearray, memoryview, ulid.ulid.Randomness, ulid.ulid.ULID]) → ulid.ulid.ULID¶ Create a new
ULID
instance using the given timestamp and randomness values.The following types are supported for timestamp values:
The following types are supported for randomness values:
- Parameters
timestamp (See docstring for types) – Unix timestamp in seconds
randomness (See docstring for types) – Random bytes
- Returns
ULID using given timestamp and randomness
- Return type
- Raises
ValueError – when a value is an unsupported type
ValueError – when a value is a string and cannot be Base32 decoded
ValueError – when a value is or was converted to incorrect bit length
-
ulid.api.
from_bytes
(value: Union[bytes, bytearray, memoryview]) → ulid.ulid.ULID¶ Create a new
ULID
instance from the givenbytes
,bytearray
, ormemoryview
value.- Parameters
value (
bytes
,bytearray
, ormemoryview
) – 16 bytes- Returns
ULID from buffer value
- Return type
- Raises
ValueError – when the value is not 16 bytes
-
ulid.api.
from_int
(value: int) → ulid.ulid.ULID¶ Create a new
ULID
instance from the givenint
value.- Parameters
value (
int
) – 128 bit integer- Returns
ULID from integer value
- Return type
- Raises
ValueError – when the value is not a 128 bit integer
-
ulid.api.
from_str
(value: str) → ulid.ulid.ULID¶ Create a new
ULID
instance from the givenstr
value.- Parameters
value (
str
) – Base32 encoded string- Returns
ULID from string value
- Return type
- Raises
ValueError – when the value is not 26 characters or malformed
-
ulid.api.
from_uuid
(value: uuid.UUID) → ulid.ulid.ULID¶
-
ulid.api.
from_timestamp
(timestamp: Union[int, float, str, bytes, bytearray, memoryview, datetime.datetime, ulid.ulid.Timestamp, ulid.ulid.ULID]) → ulid.ulid.ULID¶ Create a new
ULID
instance using a timestamp value of a supported type.The following types are supported for timestamp values:
- Parameters
timestamp (See docstring for types) – Timestamp in milliseconds
- Returns
ULID using given timestamp and new randomness
- Return type
- Raises
ValueError – when the value is an unsupported type
ValueError – when the value is a string and cannot be Base32 decoded
ValueError – when the value is or was converted to something 48 bits
-
ulid.api.
from_randomness
(randomness: Union[int, float, str, bytes, bytearray, memoryview, ulid.ulid.Randomness, ulid.ulid.ULID]) → ulid.ulid.ULID¶ Create a new
ULID
instance using the given randomness value of a supported type.The following types are supported for randomness values:
- Parameters
randomness (See docstring for types) – Random bytes
- Returns
ULID using new timestamp and given randomness
- Return type
- Raises
ValueError – when the value is an unsupported type
ValueError – when the value is a string and cannot be Base32 decoded
ValueError – when the value is or was converted to something 80 bits
-
class
ulid.api.
Timestamp
(buffer: Union[bytes, bytearray, memoryview])¶ Represents the timestamp portion of a ULID.
Unix time (time since epoch) in milliseconds.
First 48 bits of ULID when in binary format.
First 10 characters of ULID when in string format.
-
property
str
¶ Computes the string value of the timestamp from the underlying
memoryview
in Base32 encoding.- Returns
Timestamp in Base32 string form.
- Return type
- Raises
ValueError – if underlying
memoryview
cannot be encoded
-
property
timestamp
¶ Computes the Unix time (seconds since epoch) from its
memoryview
.- Returns
Timestamp in Unix time (seconds since epoch) form.
- Return type
-
property
datetime
¶ Creates a
datetime
instance (assumes UTC) from the Unix time value of the timestamp with millisecond precision.- Returns
Timestamp in datetime form.
- Return type
-
property
bin
¶ Computes the binary string value of the underlying
memoryview
.- Returns
Memory in binary string form
- Return type
-
property
bytes
¶ Computes the bytes value of the underlying
memoryview
.- Returns
Memory in bytes form
- Return type
-
property
float
¶ Computes the float value of the underlying
memoryview
in big-endian byte order.- Returns
Bytes in float form.
- Return type
-
property
hex
¶ Computes the hexadecimal string value of the underlying
memoryview
.- Returns
Memory in hexadecimal string form
- Return type
-
property
int
¶ Computes the integer value of the underlying
memoryview
in big-endian byte order.- Returns
Bytes in integer form.
- Return type
-
property
oct
¶ Computes the octal string value of the underlying
memoryview
.- Returns
Memory in octal string form
- Return type
-
class
ulid.api.
Randomness
(buffer: Union[bytes, bytearray, memoryview])¶ Represents the randomness portion of a ULID.
Cryptographically secure random values.
Last 80 bits of ULID when in binary format.
Last 16 characters of ULID when in string format.
-
property
str
¶ Computes the string value of the randomness from the underlying
memoryview
in Base32 encoding.- Returns
Timestamp in Base32 string form.
- Return type
- Raises
ValueError – if underlying
memoryview
cannot be encoded
-
property
bin
¶ Computes the binary string value of the underlying
memoryview
.- Returns
Memory in binary string form
- Return type
-
property
bytes
¶ Computes the bytes value of the underlying
memoryview
.- Returns
Memory in bytes form
- Return type
-
property
float
¶ Computes the float value of the underlying
memoryview
in big-endian byte order.- Returns
Bytes in float form.
- Return type
-
property
hex
¶ Computes the hexadecimal string value of the underlying
memoryview
.- Returns
Memory in hexadecimal string form
- Return type
-
property
int
¶ Computes the integer value of the underlying
memoryview
in big-endian byte order.- Returns
Bytes in integer form.
- Return type
-
property
oct
¶ Computes the octal string value of the underlying
memoryview
.- Returns
Memory in octal string form
- Return type
-
class
ulid.api.
ULID
(buffer: Union[bytes, bytearray, memoryview])¶ Represents a ULID.
128 bits in binary format.
26 characters in string format.
16 octets.
Network byte order, big-endian, most significant bit first.
-
property
str
¶ Computes the string value of the ULID from its
memoryview
in Base32 encoding.- Returns
ULID in Base32 string form.
- Return type
- Raises
ValueError – if underlying
memoryview
cannot be encoded
-
timestamp
() → ulid.ulid.Timestamp¶ Creates a
Timestamp
instance that maps to the first 48 bits of this ULID.- Returns
Timestamp from first 48 bits.
- Return type
-
randomness
() → ulid.ulid.Randomness¶ Creates a
Randomness
instance that maps to the last 80 bits of this ULID.- Returns
Timestamp from first 48 bits.
- Return type
-
property
uuid
¶ Creates a
UUID
instance of the ULID from itsbytes
representation.- Returns
UUIDv4 from the ULID bytes
- Return type
-
property
bin
¶ Computes the binary string value of the underlying
memoryview
.- Returns
Memory in binary string form
- Return type
-
property
bytes
¶ Computes the bytes value of the underlying
memoryview
.- Returns
Memory in bytes form
- Return type
-
property
float
¶ Computes the float value of the underlying
memoryview
in big-endian byte order.- Returns
Bytes in float form.
- Return type
-
property
hex
¶ Computes the hexadecimal string value of the underlying
memoryview
.- Returns
Memory in hexadecimal string form
- Return type
-
property
int
¶ Computes the integer value of the underlying
memoryview
in big-endian byte order.- Returns
Bytes in integer form.
- Return type
-
property
oct
¶ Computes the octal string value of the underlying
memoryview
.- Returns
Memory in octal string form
- Return type