On this page

• ULID_Factory
  • ULID_Factory
    • ULID_Factory.new_ulid()
    • ULID_Factory.to_int()
    • ULID_Factory.timestamp_ms()
    • ULID_Factory.timestamp()
    • ULID_Factory.datetime()
    • ULID_Factory.randomness()
    • ULID_Factory.is_ulid()

ULID_Factory

Use md.ULID_Factory from the public package namespace.

Implementation source

class ULID_Factory

Purpose:

Mint and read ULIDs without the external ulid dependency. Minting alone would make this module write-only, which throws away the reason to prefer a ULID over a UUID: the creation time is IN the id.

Responsibilities:

• Expose minting via new_ulid (aliased, not reimplemented).

• Decode the 48-bit timestamp back out as ms, seconds, or datetime.

• Decode the 80 random bits for tie-breaking within one millisecond.

• Validate untrusted strings without raising.

Contract:

• Every method is a static helper; this is a namespace, not an object with a lifetime. Never instantiate it.

• timestamp() and datetime() mirror the .timestamp / .datetime accessors on the external ulid package, so callers migrating off it find what they expect.

• All decoders raise on malformed input; is_ulid() is the ask-first counterpart that never raises.

• Decoding accepts the full Crockford alphabet case-insensitively, which is a superset of what new_ulid() emits.

Owned State:

None. Stateless and therefore thread-safe; no shared counter to contend on under free threading.

Lifecycle / Cleanup:

No instances and no cleanup contract. Deliberately not Cleanable - there is nothing to release.

Subsystem Context:

One of the utilities/helpers/ static namespaces alongside IDBuilder (identity FORMAT), EnumHelpers and InitHelpers. IDBuilder.create_id() mints through this module; this class owns the id VALUE, IDBuilder owns how values are joined into lineage strings.

AGENT_ACCESS: public

AGENT_PURPOSE:

access: public. Static namespace for ULID values. new_ulid() mints; timestamp_ms()/timestamp()/datetime() read the creation time back out; randomness() breaks same-millisecond ties; is_ulid() validates. Stateless - call the methods directly, never instantiate.

static new_ulid() → str

Return one freshly minted 26-character ULID string.

Contract:

• 48-bit millisecond timestamp in the high bits keeps outputs lexicographically sortable across calls in different ms.

• 80 random bits from os.urandom make collisions negligible (2^80 space per millisecond).

Returns:

A fresh 26-character ULID.

Return type:

str

static to_int(value: str) → int

Decode one ULID string back to its 128-bit integer value.

Contract:

• Accepts the canonical Crockford alphabet case-insensitively, including the I/L -> 1 and O -> 0 aliases.

• Rejects anything that is not 26 valid characters, and rejects a leading character above 7 (which would overflow 128 bits).

Parameters:

value -- The 26-character ULID string to decode.

Returns:

The 128-bit value encoded by the string.

Return type:

int

Raises:

• TypeError -- If value is not a string.

• ValueError -- If value is not a well-formed 26-character ULID.

static timestamp_ms(value: str) → int

Return the creation time encoded in a ULID, in Unix milliseconds.

Contract:

• Reads the high 48 bits, which new_ulid() fills from the millisecond wall clock at mint time.

• Milliseconds is the id's true resolution; prefer this over timestamp() when you do not want float rounding.

Parameters:

value -- The 26-character ULID string to read.

Returns:

Milliseconds since the Unix epoch.

Return type:

int

Raises:

• TypeError -- If value is not a string.

• ValueError -- If value is not a well-formed 26-character ULID.

static timestamp(value: str) → float

Return the creation time encoded in a ULID, in Unix seconds.

Contract:

• Mirrors ulid.ULID(...).timestamp on the external package.

• Millisecond resolution; the fractional part never carries more than three significant digits because that is all the id stores.

Parameters:

value -- The 26-character ULID string to read.

Returns:

Seconds since the Unix epoch.

Return type:

float

Raises:

• TypeError -- If value is not a string.

• ValueError -- If value is not a well-formed 26-character ULID.

static datetime(value: str) → datetime

Return the creation time encoded in a ULID as an aware datetime.

Contract:

• Always UTC. Never returns a naive datetime, so callers cannot accidentally compare it against local time.

• Millisecond resolution, matching what the id actually stores.

• Mirrors ulid.ULID(...).datetime on the external package.

Parameters:

value -- The 26-character ULID string to read.

Returns:

Creation time in UTC.

Return type:

datetime

Raises:

• TypeError -- If value is not a string.

• ValueError -- If value is not a well-formed 26-character ULID.

static randomness(value: str) → int

Return the 80 random bits of a ULID with the timestamp stripped off.

Contract:

• Distinguishes two ids minted in the same millisecond, where the timestamp alone cannot tell them apart.

Parameters:

value -- The 26-character ULID string to read.

Returns:

The low 80 bits of the id.

Return type:

int

Raises:

• TypeError -- If value is not a string.

• ValueError -- If value is not a well-formed 26-character ULID.

static is_ulid(value: object) → bool

Return whether a value is a well-formed ULID string.

Contract:

• Never raises. This is the ask-first counterpart to the decoders, for call sites validating untrusted input.

Parameters:

value -- Candidate to test. Any type is accepted.

Returns:

True when value decodes as a 26-character ULID.

Return type:

bool

Topic reference · Full contents