Repository files navigation

AULID is auniversally unique lexicographically sortable identifier. It is

• 128-bit compatible withUUID
• 1.21e+24 unique ULIDs per millisecond
• Lexicographically sortable!
• Canonically encoded as a 26 character string, as opposed to the 36 character UUID
• Uses Crockford's base32 for better efficiency and readability (5 bits per character)
• Case insensitive
• No special characters (URL safe)

In general the structure of a ULID is as follows:

 01AN4Z07BY      79KA1307SR9X4MV3|----------|    |----------------| Timestamp          Randomness   48bits             80bits

For more information have a look at the originalspecification.

Usepip to install the library

$ pip install python-ulid

to include Pydantic support install the optional dependency like so

$ pip install python-ulid[pydantic]

Create a newULID object from the current timestamp

>>>from ulidimportULID>>> ULID()ULID(01E75HZVW36EAZKMF1W7XNMSB4)

or use one of the named constructors

>>>import time, datetime>>>ULID.from_timestamp(time.time())ULID(01E75J1MKKWMGG0N5MBHFMRC84)>>>ULID.from_datetime(datetime.datetime.now())ULID(01E75J2XBK390V2XRH44EHC10X)

There are several options for encoding theULID object(e.g. string, hex, int, bytes, UUID):

>>>str(ulid)'01BTGNYV6HRNK8K8VKZASZCFPE'>>> ulid.hex'015ea15f6cd1c56689a373fab3f63ece'>>>int(ulid)1820576928786795198723644692628913870>>>bytes(ulid)b'\x01^\xa1_l\xd1\xc5f\x89\xa3s\xfa\xb3\xf6>\xce'>>> ulid.to_uuid()UUID('015ea15f-6cd1-c566-89a3-73fab3f63ece')

It is also possible to directly access the timestamp component of aULID,either in UNIX epoch or asdatetime.datetime

>>> ulid.timestamp1505945939.153>>> ulid.datetimedatetime.datetime(2017, 9, 20, 22, 18, 59, 153000, tzinfo=datetime.timezone.utc)

TheULID class can be directly used for the popular data validation libraryPydantic like so

frompydanticimportBaseModelfromulidimportULIDclassModel(BaseModel):ulid:ULIDmodel=Model(ulid="DX89370400440532013000")# OKmodel=Model(ulid="not-a-ulid")# Raises ValidationError

The package comes with a CLI interface that can be invoked either by the script nameulid or as python modulepython -m ulid. The CLI allows you to generate, inspectand convert ULIDs, e.g.

$ ulid build01HASFKBN8SKZTSVVS03K5AMMS$ ulid build --from-datetime=2023-09-23T10:20:3001HB0J0F5GCKEXNSWVAD5PEAC1$ ulid show 01HASFKBN8SKZTSVVS03K5AMMSULID:      01HASFKBN8SKZTSVVS03K5AMMSHex:       018ab2f9aea8ccffacef7900e6555299Int:       2049395013039097460549394558635823769Timestamp: 1695219822.248Datetime:  2023-09-20 14:23:42.248000+00:00

There are several flags to select specific output formats for theshow command, e.g.

$ ulid show --datetime 01HASFKBN8SKZTSVVS03K5AMMS2023-09-20 14:23:42.248000+00:00

The special character- allows to read values fromstdin so that they can be piped. E.g.

$echo 01HASFKBN8SKZTSVVS03K5AMMS| ulid show --uuid -018ab2f9-aea8-4cff-acef-7900e6555299$ date --iso-8601| python -m ulid build --from-datetime -01HAT9PVR02T3S13XB48S7GEHE

For a full overview of flags for thebuild andshow commands use the--help option(e.g.ulid show --help).

• ahawker/ulid
• valohai/ulid2
• mdipierro/ulid
• oklog/ulid
• ulid/javascript
• RobThree/NUlid
• imdario/go-ulid