django-hashid-field 2.1.0

Features

• Stores IDs as integers in the database

• Allows lookups and filtering by hashid string or Hashid object and (optionally) integer.

• Can enable integer lookups globally or per-field

• Can be used as sort key

• Can drop-in replace an existing IntegerField (HashidField) or AutoField (HashidAutoField)

• Allows specifying a salt globally

• Supports custom salt, min_length, alphabet and allow_int_lookup settings per field

• Supports Django REST Framework Serializers

• Supports common filtering lookups, such as field__icontains so that Django Admin search_fields works out of the box.

• Supports subquery lookups with field__in=queryset

• Supports hashing operations so the fields can be used in Dictionaries and Sets.

Requirements

This module is tested and known to work with:

• Python 2.7, 3.5

• Django 1.8, 1.9, 1.10, 1.11, 2.0

• Hashids 1.2

• Django REST Framework 3.7

Installation

Install the package (preferably in a virtualenv):

$ pip install django-hashid-field

Configure a global SALT for all HashidFields to use by default in your settings.py.

HASHID_FIELD_SALT = "a long and secure salt value that is not the same as SECRET_KEY"
# Note: You can generate a secure key with:
#     from django.core.management.utils import get_random_secret_key; print(get_random_secret_key())

Add it to your model

from hashid_field import HashidField

class Book(models.Model):
    reference_id = HashidField()

Migrate your database

$ ./manage.py makemigrations
$ ./manage.py migrate

Upgrading

Potentially breaking changes in 2.0.0 depending on your usage and configuration, specifically if you rely on integer lookups (now off by default) or exceptions for invalid lookup values.

Please see the Change Log

Basic Usage

Use your field like you would any other, for the most part. You can assign integers:

>>> b = Book()
>>> b.reference_id = 123
>>> b.reference_id
Hashid(123): OwLxW8D

You can assign valid hashids. It’s valid only if it can be decoded into an integer based on your settings:

>>> b.reference_id = 'r8636LO'
>>> b.reference_id
Hashid(456): r8636LO

You can access your field with either hashid strings or Hashid objects:

>>> Book.objects.filter(reference_id='OwLxW8D')
<QuerySet [<Book:  (OwLxW8D)>]>
>>> b = Book.objects.get(reference_id='OwLxW8D')
>>> b
<Book:  (OwLxW8D)>
>>> h = b.reference_id
>>> h
Hashid(123): OwLxW8D
>>> Book.objects.filter(reference_id=h)
<Book:  (OwLxW8D)>

You can lookup objects with integers if you set HASHID_FIELD_ALLOW_INT_LOOKUP = True or allow_int_lookup=True as a parameter to the field.

reference_id = HashidField(allow_int_lookup=True)

Now integer lookups are allowed. Useful if migrating an existing AutoField to a HashidAutoField, but you need to allow lookups with older integers.

>>> Book.objects.filter(reference_id=123)
<QuerySet [<Book:  (OwLxW8D)>]>

The objects returned from a HashidField are an instance of the class Hashid, and allow basic access to the original integer or the hashid:

>>> from hashid_field import Hashid
>>> h = Hashid(123)
>>> h.id
123
>>> h.hashid
'Mj3'
>>> print(h)
Mj3
>>> repr(h)
'Hashid(123): Mj3'

Hashid Auto Field

Along with HashidField there is also a HashidAutoField that works in the same way, but that auto-increments just like an AutoField.

from hashid_field import HashidAutoField

class Book(models.Model):
    serial_id = HashidAutoField(primary_key=True)

The only difference is that if you don’t assign a value to it when you save, it will auto-generate a value from your database, just as an AutoField would do. Please note that HashidAutoField inherits from AutoField and there can only be one AutoField on a model at a time.

>>> b = Book()
>>> b.save()
>>> b.serial_id
Hashid(1): AJEM7LK

It can be dropped into an existing model that has an auto-created AutoField (all models do by default) as long as you give it the same name and set primary_key=True. So if you have this model:

class Author(models.Model):
    name = models.CharField(max_length=40)

Then Django has created a field for you called ‘id’ automatically. We just need to override that by specifying our own field with primary_key set to True.

class Author(models.Model):
    id = HashidAutoField(primary_key=True)
    name = models.CharField(max_length=40)

And now you can use the ‘id’ or ‘pk’ attributes on your model instances:

>>> a = Author.objects.create(name="John Doe")
>>> a.id
Hashid(60): N8VNa8z
>>> Author.objects.get(pk='N8VNa8z')
<Author: Author object>

Global Settings

Field Parameters

Besides the standard field options, there are settings you can tweak that are specific to HashidField and AutoHashidField.

Please note that changing any of the values for salt, min_length or alphabet will affect the obfuscation of the integers that are stored in the database, and will change what are considered “valid” hashids. If you have links or URLs that include your HashidField values, then they will stop working after changing any of these values. It’s highly advised that you don’t change any of these settings once you publish any references to your field.

Hashid Class

Operations with a HashidField or HashidAutoField return a Hashid object. This simple class does the heavy lifting of converting integers and hashid strings back and forth. There shouldn’t be any need to instantiate these manually.

Primary Key Related Fields

Any models that have a ForeignKey to another model that uses a Hashid*Field as its Primary Key will need to explicitly define how the PrimaryKeyRelatedField should serialize and deserialize the resulting value using the pk_field argument. For the given Author model defined above that has an id = HashidAutoField(primary_key=True) set, your BookSerializer should look like the following.

from rest_framework import serializers
from hashid_field.rest import HashidSerializerCharField


class BookSerializer(serializers.ModelSerializer):
    author = serializers.PrimaryKeyRelatedField(pk_field=HashidSerializerCharField(source_field='library.Author.id'), read_only=True)

    class Meta:
        model = Book
        fields = ('id', 'author')

Make sure you pass the source field to the HashidSerializer*Field so that it can copy the ‘salt’, ‘min_length’ and ‘alphabet’ as described above.

This example sets read_only=True but you can explicitly define a queryset or override get_queryset(self) to allow read-write behavior.

For a ManyToManyField, you must also remember to pass many=True to the PrimaryKeyRelatedField.

HashidSerializerCharField

Serialize a Hashid*Field to a Hashids string, de-serialize either a valid Hashids string or integer into a Hashid*Field.

HashidSerializerIntegerField

Serialize a Hashid*Field to an integer, de-serialize either a valid Hashids string or integer into a Hashid*Field. See HashidSerializerCharField for parameters.