ulid/base32

Functionality for encoding/decoding ULID strings/bytes using Base32 format.

Note

This module makes the trade-off of code duplication for inline computations over multiple function calls for performance reasons. I’ll check metrics in the future to see how much it helps and if it’s worth it to maintain.

  • Base32 Documentation <http://www.crockford.com/wrmg/base32.html>

  • NUlid Project <https://github.com/RobThree/NUlid>

ulid.base32.ENCODING

Base32 character set. Excludes characters “I L O U”.

ulid.base32.DECODING

Array that maps encoded string char byte values to enable O(1) lookups.

ulid.base32.encode(value: Union[bytes, bytearray, memoryview]) → str

Encode the given bytes instance to a str using Base32 encoding.

Note

You should only use this method if you’ve got a bytes instance and you are unsure of what it represents. If you know the the _meaning_ of the bytes instance, you should call the encode_* method explicitly for better performance.

Parameters

value (bytes, bytearray, or memoryview) – Bytes to encode

Returns

Value encoded as a Base32 string

Return type

str

Raises

ValueError – when the value is not 6, 10, or 16 bytes long

ulid.base32.encode_ulid(value: Union[bytes, bytearray, memoryview]) → str

Encode the given buffer to a str using Base32 encoding.

Note

This uses an optimized strategy from the NUlid project for encoding ULID bytes specifically and is not meant for arbitrary encoding.

Parameters

value (bytes, bytearray, or memoryview) – Bytes to encode

Returns

Value encoded as a Base32 string

Return type

str

Raises

ValueError – when the value is not 16 bytes

ulid.base32.encode_timestamp(timestamp: Union[bytes, bytearray, memoryview]) → str

Encode the given buffer to a str using Base32 encoding.

The given bytes are expected to represent the first 6 bytes of a ULID, which are a timestamp in milliseconds.

Note

This uses an optimized strategy from the NUlid project for encoding ULID bytes specifically and is not meant for arbitrary encoding.

Parameters

timestamp (bytes, bytearray, or memoryview) – Bytes to encode

Returns

Value encoded as a Base32 string

Return type

str

Raises

ValueError – when the timestamp is not 6 bytes

ulid.base32.encode_randomness(randomness: Union[bytes, bytearray, memoryview]) → str

Encode the given buffer to a str using Base32 encoding.

The given bytes are expected to represent the last 10 bytes of a ULID, which are cryptographically secure random values.

Note

This uses an optimized strategy from the NUlid project for encoding ULID bytes specifically and is not meant for arbitrary encoding.

Parameters

randomness (bytes, bytearray, or memoryview) – Bytes to encode

Returns

Value encoded as a Base32 string

Return type

str

Raises

ValueError – when the randomness is not 10 bytes

ulid.base32.decode(value: str) → bytes

Decode the given Base32 encoded str instance to bytes.

Note

You should only use this method if you’ve got a str instance and you are unsure of what it represents. If you know the the _meaning_ of the str instance, you should call the decode_* method explicitly for better performance.

Parameters

value (str) – String to decode

Returns

Value decoded from Base32 string

Return type

bytes

Raises

  • ValueError – when value is not 10, 16, or 26 characters

  • ValueError – when value cannot be encoded in ASCII

ulid.base32.decode_ulid(value: str) → bytes

Decode the given Base32 encoded str instance to bytes.

Note

This uses an optimized strategy from the NUlid project for decoding ULID strings specifically and is not meant for arbitrary decoding.

Parameters

value (str) – String to decode

Returns

Value decoded from Base32 string

Return type

bytes

Raises

  • ValueError – when value is not 26 characters

  • ValueError – when value cannot be encoded in ASCII

ulid.base32.decode_timestamp(timestamp: str) → bytes

Decode the given Base32 encoded str instance to bytes.

The given str are expected to represent the first 10 characters of a ULID, which are the timestamp in milliseconds.

Note

This uses an optimized strategy from the NUlid project for decoding ULID strings specifically and is not meant for arbitrary decoding.

Parameters

timestamp (str) – String to decode

Returns

Value decoded from Base32 string

Return type

bytes

Raises

  • ValueError – when value is not 10 characters

  • ValueError – when value cannot be encoded in ASCII

ulid.base32.decode_randomness(randomness: str) → bytes

Decode the given Base32 encoded str instance to bytes.

The given str are expected to represent the last 16 characters of a ULID, which are cryptographically secure random values.

Note

This uses an optimized strategy from the NUlid project for decoding ULID strings specifically and is not meant for arbitrary decoding.

Parameters

randomness (str) – String to decode

Returns

Value decoded from Base32 string

Return type

bytes

Raises

  • ValueError – when value is not 16 characters

  • ValueError – when value cannot be encoded in ASCII

ulid.base32.str_to_bytes(value: str, expected_length: int) → bytes

Convert the given string to bytes and validate it is within the Base32 character set.

Parameters

  • value (str) – String to convert to bytes

  • expected_length (int) – Expected length of the input string

Returns

Value converted to bytes.

Return type

bytes