shortuuid: Generate Concise, Unambiguous, and URL-Safe UUIDs in Python

Introduction

shortuuid is a straightforward Python library that generates concise, unambiguous, and URL-safe UUIDs. It's particularly useful when you need non-sequential IDs that are visible to users and must be as short and easy to use as possible. The library achieves this by taking standard UUIDs, generated by Python's built-in uuid module, and translating them into a base57 representation. This base57 alphabet uses lowercase and uppercase letters and digits, carefully excluding characters that can be easily confused, such as 'l', '1', 'I', 'O', and '0'.

Installation

To install shortuuid, you will need Python 3.6+.

There are several installation options:

• With pip (preferred): Run pip install shortuuid.
• With setuptools: Run easy_install shortuuid.
• From source: Download the source from the GitHub repository and run python setup.py install.

Examples

Here's how to use shortuuid in your projects:

Basic UUID Generation:

>>> import shortuuid
>>> shortuuid.uuid()
'vytxeTZskVKR7C7WgdSP3d'

Version 5 UUIDs with Namespaces:

>>> shortuuid.uuid(name="example.com")
'exu3DTbj2ncsn9tLdLWspw'

>>> shortuuid.uuid(name="<http://example.com>")
'shortuuid.uuid(name="<http://example.com>")'

Generating Random Strings:

>>> shortuuid.ShortUUID().random(length=22)
'RaF56o2r58hTKT7AYS9doj'

Inspecting and Setting the Alphabet:

>>> shortuuid.get_alphabet()
'23456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz'

>>> shortuuid.set_alphabet("aaaaabcdefgh1230123")
>>> shortuuid.uuid()
'0agee20aa1hehebcagddhedddc0d2chhab3b'

Encoding and Decoding Existing UUIDs:

>>> import uuid
>>> u = uuid.uuid4()
>>> u
UUID('6ca4f0f8-2508-4bac-b8f1-5d1e3da2247a')

>>> s = shortuuid.encode(u)
>>> s
'MLpZDiEXM4VsUryR9oE8uc'

>>> shortuuid.decode(s) == u
True

Class-based Usage for Multiple Alphabets:

>>> su = shortuuid.ShortUUID(alphabet="01345678")
>>> su.uuid()
'034636353306816784480643806546503818874456'

Command-line Usage:

$ shortuuid
fZpeF6gcskHbSpTgpQCkcJ

Django Field Integration:

shortuuid also provides a Django field for convenience, allowing you to easily integrate short UUIDs into your models:

from shortuuid.django_fields import ShortUUIDField

class MyModel(models.Model):
    id = ShortUUIDField(
        length=16,
        max_length=40,
        prefix="id_",
        alphabet="abcdefg1234",
        primary_key=True,
    )
    api_key = ShortUUIDField()

Why Use It

shortuuid offers a compelling solution for generating identifiers that are both unique and user-friendly. Its core advantage lies in producing concise, unambiguous, and URL-safe IDs, which significantly improves readability and usability in contexts where IDs are exposed to users. By meticulously removing similar-looking characters from its alphabet, it minimizes confusion and errors. The library's flexibility, allowing custom alphabets and length truncation, makes it adaptable to various project requirements. Furthermore, its seamless integration with Django provides an easy way to incorporate these benefits into web applications.

Links

• GitHub Repository: https://github.com/skorokithakis/shortuuid