DOCSEARCHbyAlgolia
Submit Docs

shortuuid Documentation

repository·master·Indexed 25 days ago

https://github.com/skorokithakis/shortuuid

A Python library for generating concise, unambiguous, and URL-safe UUIDs by translating standard UUIDs into a base57 alphabet. It provides tools for encoding and decoding UUIDs, generating cryptographically secure random strings, and a specialized ShortUUIDField for Django models. The library includes a CLI for generating, encoding, and decoding UUIDs, and supports custom alphabets and legacy decoding for versions prior to 1.0.0.

Tokens
2.2K
Snippets
5
Records
24
Agent score
79%

What's inside shortuuid

  2. Migrate from legacy ShortUUID versions

    master

    Versions of shortuuid prior to 1.0.0 generated UUIDs with the Most Significant Byte (MSB) reversed. If you have legacy UUID strings stored, you must use the legacy=True flag when decoding them.

    To migrate legacy strings to the new format, decode them with the legacy flag and then re-encode them.

  3. Use ShortUUIDField in Django models

    master

    The shortuuid.django_fields.ShortUUIDField can be used in Django models to generate random short UUIDs. It behaves similarly to CharField but with specific arguments for ID generation.

    Supported arguments:

    • length: The length of the generated ID.
    • alphabet: The alphabet to use.
    • dont_sort_alphabet: Whether to prevent alphabet sorting.
    • prefix: A string to prepend to the ID.
    • primary_key: Whether this field is the model's primary key.

    Note: The default argument is removed as the field generates IDs automatically.

    from shortuuid.django_fields import ShortUUIDField

class MyModel(models.Model):
    # Primary key with custom length and alphabet
    id = ShortUUIDField(
        length=16,
        max_length=40,
        prefix="id_",
        alphabet="abcdefg1234",
        dont_sort_alphabet=False,
        primary_key=True,
    )

    # Standard short UUID
    api_key = ShortUUIDField()

  4. Encode and decode UUIDs

    master

    You can convert standard Python uuid.UUID objects to short strings and back using encode() and decode().

    Warning on truncation: If you truncate a short string (e.g., s[:7]), decoding it will result in a UUID with the remaining bits set to zero. While the resulting UUID won't be universally unique, the collision probability remains very low.

  5. Generate cryptographically secure random strings

    master

    Use the ShortUUID class to generate cryptographically secure random strings (internally using os.urandom()) by calling the .random() method.

    import shortuuid

# Generate a secure random string of a specific length
shortuuid.ShortUUID().random(length=22)

  7. Configure and manage the alphabet

    master

    The alphabet determines the characters used in the generated IDs. The default alphabet is 23456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz (matching [2-9A-HJ-NP-Za-km-z]{22}).

    • Use get_alphabet() to view the current alphabet.
    • Use set_alphabet(alphabet, dont_sort_alphabet=False) to define a custom alphabet.

    Note on sorting: By default, shortuuid sorts and removes duplicates from your provided alphabet to ensure consistency. To prevent this behavior and preserve your exact character order, set dont_sort_alphabet=True.

  8. Generate short UUIDs

    master

    You can generate concise, URL-safe UUIDs using the top-level uuid() function. By default, it produces a 22-character string using a base57 alphabet.

    To generate a version 5 UUID, pass a name (such as a DNS or URL) to the function, which will use the appropriate namespace (uuid.NAMESPACE_DNS or uuid.NAMESPACE_URL).

    import shortuuid

# Generate a standard short UUID
shortuuid.uuid()

# Generate a version 5 UUID using a name as a namespace
shortuuid.uuid(name="example.com")

  12. Use the ShortUUID class for custom encoding

    master
    The ShortUUID class allows you to create instances with a custom alphabet for encoding and decoding UUIDs. By default, it uses a concise alphabet that excludes ambiguous characters. You can control whether the alphabet is sorted automatically using dont_sort_alphabet.