Skip to content
/ ulid2 Public

ULID (Universally Unique Lexicographically Sortable Identifier) encoding and decoding for Python.

License

Notifications You must be signed in to change notification settings

valohai/ulid2

Repository files navigation

ulid2

MIT License Test codecov

ULID (Universally Unique Lexicographically Sortable Identifier) encoding and decoding for Python.

  • Python 2.7 and 3.x compatible
  • Supports binary ULIDs
  • Supports bidirectional conversion of base32 ULIDs
  • Supports expressing ULIDs as UUIDs

Usage

Generating ULIDs

  • Use ulid2.generate_binary_ulid() to generate a raw binary ULID
  • Use ulid2.generate_ulid_as_uuid() to generate an ULID as an uuid.UUID
  • Use ulid2.generate_ulid_as_base32() to generate an ULID as ASCII

These functions accept optional arguments:

  • timestamp: a datetime.datetime or integer UNIX timestamp to base the ULID on.
  • monotonic: boolean; whether to attempt to ensure ULIDs are monotonically increasing. Monotonic behavior is not guaranteed when used from multiple threads.

Parsing ULIDs

  • Use ulid2.get_ulid_time(ulid) to get the time from an ULID (in any format)

Converting ULIDs

  • Use ulid2.ulid_to_base32(ulid) to convert an ULID to its ASCII representation
  • Use ulid2.ulid_to_uuid(ulid) to convert an ULID to its UUID representation
  • Use ulid2.ulid_to_binary(ulid) to convert an ULID to its binary representation

Base32

  • Use ulid2.encode_ulid_base32(binary) to convert 16 bytes to 26 ASCII characters
  • Use ulid2.decode_ulid_base32(ascii) to convert 26 ASCII characters to 16 bytes

Django compatibility

As ulid2 is capable of expressing ULIDs as Python UUIDs, it's directly compatible with Django's UUIDFields. For instance, to ULID-ify a model's primary key, simply

from django.db import models
from ulid2 import generate_ulid_as_uuid

class MyModel(models.Model):
    id = models.UUIDField(default=generate_ulid_as_uuid, primary_key=True)

and you're done!

Why the 2 in the name?

ulid is already taken by mdipierro's implementation. :)

Prior Art

About

ULID (Universally Unique Lexicographically Sortable Identifier) encoding and decoding for Python.

Topics

Resources

License

Stars

Watchers

Forks

Packages

No packages published

Contributors 4

  •  
  •  
  •  
  •  

Languages