short-stuff 1.0.2

Set of utilities for managing unique shortcodes.

Short Stuff

By Fox at Artconomy.com.

Short Stuff is a set of helper functions used for generating short unique identifiers, such as those used in YouTube video IDs or in URL shorteners.

Short Stuff does this by generating random byte strings, running them through base64 encoding and then doing some cleanup for compatibility.

Most distinct about the methodology is that it piggy-backs on UUIDs. That means that if you want to leverage your database or library's native UUID support, you can do so, and helper functions are provided for this.

---

Installation

Short Stuff requires (at least) Python 3.5. It has only been tested on Python 3.7. The tests use formatted strings, which were introduced in 3.6.

To install:

pip install short_stuff

Quick Guide

To generate a short code:

>>> from short_stuff import gen_shortcode
>>> gen_shortcode()
'XtFxMb7qTJ-A'

To turn this code into a UUID (such as for DB storage):

>>> from short_stuff import unslugify
>>> unslugify('XtFxMb7qTJ-A')
UUID('5ed17131-beea-4c9f-8000-000000000000')

Notice that this is a truncated UUID, with everything beyond the first eight bytes zeroed out.

To turn the UUID back into a slug:

>>> from uuid import UUID
>>> from short_stuff import slugify
>>> slugify(UUID('5ed17131-beea-4c9f-8000-000000000000'))
'XtFxMb7qTJ-A'

Django

First class support for Django is provided. Django must be installed to use these features. The ShortCodeField model field is provided and is a special wrapper around UUIDField.

from django.db import models
from short_stuff import gen_shortcode
from short_stuff.django.models import ShortCodeField


class Doohickey(models.Model):
    id = ShortCodeField(primary_key=True, db_index=True, default=gen_shortcode)

Note that in most cases you can pass UUIDs to the field and allow it to convert internally. This might be helpful if converting existing models to use shortcodes. Migrations should go smoothly, but please be sure to test!

NOTICE: Use gen_shortcode and not gen_shortcode()! if you don't omit the parentheses, the function will evaluate during the class definition and Django will attempt to set ALL new rows for the table with that default.

Now that you have the shortcodes on your models, you'll want to make it possible to refer to them in your URLs.

To do this, register the provided path converter:

from django.urls import path, register_converter
from short_stuff import ShortCodeConverter

from . import views

register_converter(converters.ShortCodeConverter, 'short_code')

urlpatterns = [
    path('doohickeys/<short_code:doohickey_id>/', views.doohickey_display),
    ...
]

Your view will then be handed the resulting shortcode string as an argument, for easy model lookup.

Additionally, a serializer field is provided for use with Django REST Framework (it must be installed to use this feature.)

from rest_framework.serializers import Serializer
from short_stuff.django.serializers import ShortCodeField

class ShortCodeSerializer(Serializer):
    test_field = ShortCodeField()

FAQ

Is eight bytes enough randomness?

Yes.

Are you sure?

If you're building something that needs more, you won't wonder. You'll know. And you'll have money to make it happen right. Hint: YouTube's using eight bytes.

Ok, but a collision could happen, right? What do I do then?

Your database should prevent the row from being inserted for you. Let it fail-- the cost of adding complexity rather than having the user resubmit a request for a 1 in 2^34 chance of a clash is not worth it.

What if I don't need UUIDs, or I'd prefer to use integers, or byte strings?

Thankfully, Python's UUID objects have properties on them that allow you to retrieve their values in the forms of strings, integers, bytes, etc. In most cases, converting to your desired format is one more line of code.

I'd like to use a different number of bytes than the default 8 that gen_shortcode provides.

You can specify the number of bytes you want to use as an argument, like this:

>>> from short_stuff import gen_shortcode
>>> gen_shortcode(10)
'_WMWaDe4RsauOQ'

Testing

To run tests, run the following from the repository root:

pip install -r testing_requirements.txt
pip install -e .
pytest

Special Thanks

Special thanks to KathTheDragon for helping me figure out the probability of collisions.

And to Amber, the love of my life, for putting up with me nerding out while I stepped through what this library does.