{"id":13468717,"url":"https://github.com/nshafer/django-hashid-field","last_synced_at":"2025-05-16T02:05:30.818Z","repository":{"id":39104659,"uuid":"69611679","full_name":"nshafer/django-hashid-field","owner":"nshafer","description":"Django Model Field that uses Hashids to obscure the value","archived":false,"fork":false,"pushed_at":"2024-05-03T22:30:55.000Z","size":361,"stargazers_count":371,"open_issues_count":0,"forks_count":41,"subscribers_count":11,"default_branch":"master","last_synced_at":"2025-04-08T12:07:02.210Z","etag":null,"topics":["django","django-rest-framework","hashid","hashids"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nshafer.png","metadata":{"files":{"readme":"README.rst","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-09-29T22:04:50.000Z","updated_at":"2025-01-01T01:51:56.000Z","dependencies_parsed_at":"2024-05-03T22:47:38.419Z","dependency_job_id":"0115b096-9e16-4c66-a0a9-2a1a8cb8b2ba","html_url":"https://github.com/nshafer/django-hashid-field","commit_stats":{"total_commits":247,"total_committers":16,"mean_commits":15.4375,"dds":"0.11336032388663964","last_synced_commit":"829a460c47e98f182e6fa609164fbabd2ad6014c"},"previous_names":[],"tags_count":32,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nshafer%2Fdjango-hashid-field","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nshafer%2Fdjango-hashid-field/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nshafer%2Fdjango-hashid-field/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nshafer%2Fdjango-hashid-field/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nshafer","download_url":"https://codeload.github.com/nshafer/django-hashid-field/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254453646,"owners_count":22073616,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["django","django-rest-framework","hashid","hashids"],"created_at":"2024-07-31T15:01:17.373Z","updated_at":"2025-05-16T02:05:30.784Z","avatar_url":"https://github.com/nshafer.png","language":"Python","funding_links":[],"categories":["Python"],"sub_categories":[],"readme":".. image:: https://github.com/nshafer/django-hashid-field/actions/workflows/tests.yml/badge.svg?branch=master\n    :target: https://github.com/nshafer/django-hashid-field/actions/workflows/tests.yml?query=branch%3Amaster\n.. image:: https://badge.fury.io/py/django-hashid-field.svg\n    :target: https://badge.fury.io/py/django-hashid-field\n\nWARNING! This module is retired!\n================================\n\n**This library has been retired. It is no longer recommended for new projects. Existing projects do not require**\n**changes, but should consider migrating to a different library. See the**\n`RETIRED \u003chttps://github.com/nshafer/django-hashid-field/blob/master/RETIRED.md\u003e`_\n**document for more information.**\n\nDjango Hashid Field\n===================\n\nA custom Model Field that uses the `Hashids \u003chttp://hashids.org/\u003e`_ `library \u003chttps://pypi.python.org/pypi/hashids/\u003e`_\nto obfuscate an IntegerField or AutoField. It can be used in new models or dropped in place of an existing IntegerField,\nexplicit AutoField, or an automatically generated AutoField.\n\nFeatures\n--------\n\n* Stores IDs as integers in the database\n* Allows lookups and filtering by hashid string or Hashid object and (optionally) integer.\n* Can enable integer lookups globally or per-field\n* Can be used as sort key\n* Allows specifying a salt, min_length and alphabet globally\n* Supports custom *salt*, *min_length*, *alphabet*, *prefix* and *allow_int_lookup* settings per field\n* Allows prefixing hashids with custom string, e.g. `prefix=\"user_\"` for hashids like \"user_h6ks82g\"\n* Can drop-in replace an existing IntegerField (HashidField) or AutoField (HashidAutoField)\n* Supports \"Big\" variants for large integers: BigHashidField, BigHashidAutoField\n* Supports Django 3.2 setting `DEFAULT_AUTO_FIELD = 'hashid_field.BigHashidAutoField'`\n* Supports Django REST Framework Serializers\n* Supports exact ID searches in Django Admin when field is specified in search_fields.\n* Supports common filtering lookups, such as ``__iexact``, ``__contains``, ``__icontains``, though matching is the same as ``__exact``.\n* Supports subquery lookups with ``field__in=queryset``\n* Supports other lookups: `isnull`, `gt`, `gte`, `lt` and `lte`.\n* Supports hashing operations so the fields can be used in Dictionaries and Sets.\n\nRequirements\n------------\n\nThis module is tested and known to work with:\n\n* Python 3.7, 3.8, 3.9, 3.10, 3.11, 3.12\n* Django 3.2, 4.2, 5.0\n* Hashids 1.3\n* Django REST Framework 3.14\n\n*Please Note*: Python 2.x is at its end of life and is no longer supported.\n\nInstallation\n------------\n\nInstall the package (preferably in a virtualenv):\n\n.. code-block:: bash\n\n    $ pip install django-hashid-field\n\nConfigure a global SALT for all HashidFields to use by default in your settings.py. (*Note*: Using a global salt for all\nfields will result in IDs from different fields/models being the same. If you want to have unique hashid strings for the\nsame id, then also configure per-field salts as described in Field Parameters below.)\n\n.. code-block:: python\n\n    HASHID_FIELD_SALT = \"a long and secure salt value that is not the same as SECRET_KEY\"\n    # Note: You can generate a secure key with:\n    #     from django.core.management.utils import get_random_secret_key; print(get_random_secret_key())\n\nAdd it to your model\n\n.. code-block:: python\n\n    from hashid_field import HashidField\n\n    class Book(models.Model):\n        reference_id = HashidField()\n\nMigrate your database\n\n.. code-block:: bash\n\n    $ ./manage.py makemigrations\n    $ ./manage.py migrate\n\nBasic Usage\n-----------\n\nUse your field like you would any other, for the most part. You can assign integers:\n\n.. code-block:: python\n\n    \u003e\u003e\u003e b = Book()\n    \u003e\u003e\u003e b.reference_id = 123\n    \u003e\u003e\u003e b.reference_id\n    Hashid(123): OwLxW8D\n\nYou can assign valid hashids. It's valid only if it can be decoded into an integer based on your settings:\n\n.. code-block:: python\n\n    \u003e\u003e\u003e b.reference_id = 'r8636LO'\n    \u003e\u003e\u003e b.reference_id\n    Hashid(456): r8636LO\n\nYou can access your field with either hashid strings or Hashid objects:\n\n.. code-block:: python\n\n    \u003e\u003e\u003e Book.objects.filter(reference_id='OwLxW8D')\n    \u003cQuerySet [\u003cBook:  (OwLxW8D)\u003e]\u003e\n    \u003e\u003e\u003e b = Book.objects.get(reference_id='OwLxW8D')\n    \u003e\u003e\u003e b\n    \u003cBook:  (OwLxW8D)\u003e\n    \u003e\u003e\u003e h = b.reference_id\n    \u003e\u003e\u003e h\n    Hashid(123): OwLxW8D\n    \u003e\u003e\u003e Book.objects.filter(reference_id=h)\n    \u003cBook:  (OwLxW8D)\u003e\n\nYou can lookup objects with integers if you set ``HASHID_FIELD_ALLOW_INT_LOOKUP = True`` or ``allow_int_lookup=True``\nas a parameter to the field.\n\n.. code-block:: python\n\n    reference_id = HashidField(allow_int_lookup=True)\n\nNow integer lookups are allowed. Useful if migrating an existing AutoField to a HashidAutoField, but you need to allow\nlookups with older integers.\n\n.. code-block:: python\n\n    \u003e\u003e\u003e Book.objects.filter(reference_id=123)\n    \u003cQuerySet [\u003cBook:  (OwLxW8D)\u003e]\u003e\n\nBy default, the objects returned from a HashidField are an instance of the class Hashid (this can be disabled globally\nor per-field), and allow basic access to the original integer or the hashid:\n\n.. code-block:: python\n\n    \u003e\u003e\u003e from hashid_field import Hashid\n    \u003e\u003e\u003e h = Hashid(123)\n    \u003e\u003e\u003e h.id\n    123\n    \u003e\u003e\u003e h.hashid\n    'Mj3'\n    \u003e\u003e\u003e print(h)\n    Mj3\n    \u003e\u003e\u003e repr(h)\n    'Hashid(123): Mj3'\n\nHashid Auto Field\n-----------------\n\nAlong with ``HashidField`` there is also a ``HashidAutoField`` that works in the same way, but that auto-increments just\nlike an ``AutoField``.\n\n.. code-block:: python\n\n    from hashid_field import HashidAutoField\n\n    class Book(models.Model):\n        serial_id = HashidAutoField(primary_key=True)\n\nThe only difference is that if you don't assign a value to it when you save, it will auto-generate a value from your\ndatabase, just as an AutoField would do. Please note that ``HashidAutoField`` inherits from ``AutoField`` and there can\nonly be one ``AutoField`` on a model at a time.\n\n.. code-block:: python\n\n    \u003e\u003e\u003e b = Book()\n    \u003e\u003e\u003e b.save()\n    \u003e\u003e\u003e b.serial_id\n    Hashid(1): AJEM7LK\n\nIt can be dropped into an existing model that has an auto-created AutoField (all models do by default) as long as you\ngive it the same name and set ``primary_key=True``. So if you have this model:\n\n.. code-block:: python\n\n    class Author(models.Model):\n        name = models.CharField(max_length=40)\n\nThen Django has created a field for you called 'id' automatically. We just need to override that by specifying our own\nfield with *primary_key* set to True.\n\n.. code-block:: python\n\n    class Author(models.Model):\n        id = HashidAutoField(primary_key=True)\n        name = models.CharField(max_length=40)\n\nAnd now you can use the 'id' or 'pk' attributes on your model instances:\n\n.. code-block:: python\n\n    \u003e\u003e\u003e a = Author.objects.create(name=\"John Doe\")\n    \u003e\u003e\u003e a.id\n    Hashid(60): N8VNa8z\n    \u003e\u003e\u003e Author.objects.get(pk='N8VNa8z')\n    \u003cAuthor: Author object\u003e\n\nIn Django 3.2 a new setting, \"DEFAULT_AUTO_FIELD\" was added to change all auto-generated AutoFields to a specific class.\nThis is fully supported with django-hashid-field, and can be enabled with:\n\n.. code-block:: python\n\n    DEFAULT_AUTO_FIELD = 'hashid_field.HashidAutoField'\n    DEFAULT_AUTO_FIELD = 'hashid_field.BigHashidAutoField'\n\nCare must be given, as this will alter ALL models in your project. Usually you would only set this in a new project.\nAlso, since this changes the auto-generated field, only global settings will be used for that field. If you desire\nspecific settings for different models, then using this setting is not advised.\n\nDjango may configure the per-app `default_auto_field` when a new app is created. This will prevent the global setting\nfrom taking affect. If you are attempting to use the global setting, you should check your app configs in\n`project/app_name/apps.py` to ensure they don't interfere.\n\n.. code-block:: python\n\n    from django.apps import AppConfig\n\n\n    class ScheduleConfig(AppConfig):\n        default_auto_field = 'django.db.models.BigAutoField'\n        name = 'schedule'\n\n\nGlobal Settings\n---------------\n\nHASHID_FIELD_SALT\n~~~~~~~~~~~~~~~~~\n\nYou can optionally set a global Salt to be used by all HashFields and HashidAutoFields in your project. Do not use the\nsame string as your SECRET_KEY, as this could lead to your SECRET_KEY being exposed to an attacker.\nPlease note that changing this value will cause all HashidFields to change their values, and any previously published\nIDs will become invalid.\nCan be overridden by the field definition if you desire unique hashid strings for a given field, as described in\nField Parameters below.\n\n:Type:    string\n:Default: \"\"\n:Note:    The upstream hashids-python library [only considers the first 43 characters of the salt](https://github.com/davidaurelio/hashids-python/issues/43).\n:Example:\n    .. code-block:: python\n\n        HASHID_FIELD_SALT = \"a long and secure salt value that is not the same as SECRET_KEY\"\n\nHASHID_FIELD_MIN_LENGTH\n~~~~~~~~~~~~~~~~~~~~~~~\n\nDefault minimum length for (non-Big) HashidField and AutoHashidField.\nIt is suggested to use 7 for HashidField and HashidAutoField, so that all possible values\n(up to 2147483647) are the same length.\n\n:Type:    integer\n:Default: 7\n:Example:\n    .. code-block:: python\n\n        HASHID_FIELD_MIN_LENGTH = 20\n\nHASHID_FIELD_BIG_MIN_LENGTH\n~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nDefault minimum length for BigHashidField and BigHashidAutoField.\nIt is suggested to use 13 for BigHashidField and BigHashidAutoField, so that all possible values\n(up to 9223372036854775807) are the same length.\n\n:Type:    integer\n:Default: 13\n:Example:\n    .. code-block:: python\n\n        HASHID_FIELD_BIG_MIN_LENGTH = 30\n\nHASHID_FIELD_ALPHABET\n~~~~~~~~~~~~~~~~~~~~~~~\n\nThe default alphabet to use for characters in generated Hashids strings. Must be at least 16 unique characters.\n\n:Type:    string\n:Default: \"abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890\"\n:Example:\n    .. code-block:: python\n\n        HASHID_FIELD_ALPHABET = \"0123456789abcdef\"\n\nHASHID_FIELD_ALLOW_INT_LOOKUP\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nAllow lookups or fetches of fields using the underlying integer that's stored in the database.\nDisabled by default to prevent users from being to do a sequential scan of objects by pulling objects by\nintegers (1, 2, 3) instead of Hashid strings (\"Ba9p1AG\", \"7V9gk9Z\", \"wro12zm\").\nCan be overridden by the field definition.\n\n:Type:    boolean\n:Default: False\n:Example:\n    .. code-block:: python\n\n        HASHID_FIELD_ALLOW_INT_LOOKUP = True\n\nHASHID_FIELD_LOOKUP_EXCEPTION\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nBy default any invalid hashid strings or integer lookups when integer lookups are turned off will result in an\nEmptyResultSet being returned. Enable this to instead throw a ValueError exception (similar to the behavior prior to 2.0).\n\n:Type:    boolean\n:Default: False\n:Example:\n    .. code-block:: python\n\n        HASHID_FIELD_LOOKUP_EXCEPTION = True\n\nHASHID_FIELD_ENABLE_HASHID_OBJECT\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nThe default behavior is to return an instance of the Hashid object (described below) in each instance of your Model.\nThis makes it possible to get both the integer and hashid version of the field. However, other django modules, serializers,\netc may be confused and not know how to handle a Hashid object, so you can turn them off here. Instead, a string\nof the hashid will be returned, and a new attribute with the suffix `_hashid` will be created on each instance with the\nHashid object. So if you have `key = HashidField(...)` then `key_hashid` will be created on each instance.\nCan be overriden by the field definition.\n\n:Type:    boolean\n:Default: True\n:Example:\n    .. code-block:: python\n\n        HASHID_FIELD_ENABLE_HASHID_OBJECT = False\n\nHASHID_FIELD_ENABLE_DESCRIPTOR\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nBy default a Hashid*Field on a model will replace the original value returned from the database with a Descriptor\nthat attempts to convert values that are set on that field of an instance with a new Hashid object (or string if\nENABLE_HASHID_OBJECT is False), regardless if you set an integer or a valid hashid. For the most part this is\ncompletely invisible and benign, however if you have issues due to this descriptor, you can disable it here, or\non the field, and the raw value will not be replaced with the Descriptor.\nCan be overriden by the field definition.\n\n\n:Type:    boolean\n:Default: True\n:Example:\n    .. code-block:: python\n\n        HASHID_FIELD_ENABLE_DESCRIPTOR = False\n\n\n\nField Parameters\n----------------\n\nBesides the standard field options, there are settings you can tweak that are specific to HashidField and\nAutoHashidField.\n\n**Please note** that changing any of the values for ``salt``, ``min_length``, ``alphabet`` or ``prefix`` *will* affect\nthe obfuscation of the integers that are stored in the database, and will change what are considered \"valid\" hashids.\nIf you have links or URLs that include your HashidField values, then they will stop working after changing any of these\nvalues. It's highly advised that you don't change any of these settings once you publish any references to your field.\n\nsalt\n~~~~\n\nLocal overridable salt for hashids generated specifically for this field.\nSet this to a unique value for each field if you want the IDs for that field to be different to the same IDs\non another field. e.g. so that `book.id = Hashid(5): 0Q8Kg9r` and `author.id = Hashid(5): kp0eq0V`.\nSuggestion: `fieldname = HashIdField(salt=\"modelname_fieldname_\" + settings.HASHID_FIELD_SALT)`\nSee HASHID_FIELD_SALT above.\n\n:Type:    string\n:Default: settings.HASHID_FIELD_SALT, \"\"\n:Note:    The upstream hashids-python library [only considers the first 43 characters of the salt](https://github.com/davidaurelio/hashids-python/issues/43).\n:Example:\n    .. code-block:: python\n\n        reference_id = HashidField(salt=\"Some salt value\")\n\nmin_length\n~~~~~~~~~~\n\nGenerate hashid strings of this minimum length, regardless of the value of the integer that is being encoded.\nThis defaults to 7 for the field since the maximum IntegerField value can be encoded in 7 characters with\nthe default *alphabet* setting of 62 characters.\n\n:Type:     int\n:Default:  7\n:Example:\n    .. code-block:: python\n\n        reference_id = HashidField(min_length=15)\n\nalphabet\n~~~~~~~~\n\nThe set of characters to generate hashids from. Must be at least 16 characters.\n\n:Type:    string of characters\n:Default: Hashids.ALPHABET, which is \"abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890\"\n:Example:\n    .. code-block:: python\n\n        # Only use numbers and lower-case letters\n        reference_id = HashidField(alphabet=\"0123456789abcdefghijklmnopqrstuvwxyz\")\n\nprefix\n~~~~~~\n\nAn optional string prefix that will be prepended to all generated hashids. Also affects validation, so only hashids\nthat have this prefix will be considered correct.\n\nIMPORTANT: Do not end your prefix with an underscore, as this can cause issues with the Django admin. See Known Issues\nbelow.\n\n:Type:    String\n:Default: \"\"\n:Example:\n    .. code-block:: python\n\n        # Including the type of id in the id itself:\n        reference_id = HashidField(prefix=\"order-\")\n\nallow_int_lookup\n~~~~~~~~~~~~~~~~\n\nLocal field override for default global on whether or not integer lookups for this field should be allowed.\nSee HASHID_FIELD_ALLOW_INT_LOOKUP above.\n\n:Type:    boolean\n:Default: settings.HASHID_FIELD_ALLOW_INT_LOOKUP, False\n:Example:\n    .. code-block:: python\n\n        reference_id = HashidField(allow_int_lookup=True)\n\n\nenable_hashid_object\n~~~~~~~~~~~~~~~~~~~~\n\nLocal field override for whether or not to return Hashid objects or plain strings.\nCan be safely changed without affecting any existing hashids.\nSee HASHID_FIELD_ENABLE_HASHID_OBJECT above.\n\n:Type:    boolean\n:Default: settings.HASHID_FIELD_ENABLE_HASHID_OBJECT, True\n:Example:\n    .. code-block:: python\n\n        reference_id = HashidField(enable_hashid_object=False)\n\nenable_descriptor\n~~~~~~~~~~~~~~~~~\n\nLocal field override for whether or not to use the Descriptor on instances of the field.\nCan be safely changed without affecting any existing hashids.\nSee HASHID_FIELD_ENABLE_DESCRIPTOR above.\n\n:Type:    boolean\n:Default: settings.HASHID_FIELD_ENABLE_DESCRIPTOR, True\n:Example:\n    .. code-block:: python\n\n        reference_id = HashidField(enable_descriptor=False)\n\n\nHashid Class\n------------\n\nOperations with a HashidField or HashidAutoField return a ``Hashid`` object (unless disabled).\nThis simple class does the heavy lifting of converting integers and hashid strings back and forth.\nThere shouldn't be any need to instantiate these manually.\n\nMethods\n~~~~~~~\n\n\\__init__(value, salt=\"\", min_length=0, alphabet=Hashids.ALPHABET, prefix=\"\", hashids=None):\n^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^\n\n:value: **REQUIRED** Integer you wish to *encode* or hashid you wish to *decode*\n:salt: Salt to use. **Default**: \"\" (empty string)\n:min_length: Minimum length of encoded hashid string. **Default**: 0\n:alphabet: The characters to use in the encoded hashid string. **Default**: Hashids.ALPHABET\n:prefix: String prefix prepended to hashid strings. **Default**: \"\" (empty string)\n:hashids: Instance of hashids.Hashids to use for encoding/decoding instead of instantiating another.\n\nRead-Only Properties\n~~~~~~~~~~~~~~~~~~~~\n\nid\n^^\n\n:type: Int\n:value: The *decoded* integer\n\nhashid\n^^^^^^\n\n:type: String\n:value: The *encoded* hashid string\n\nhashids\n^^^^^^^\n\n:type: Hashids()\n:value: The instance of the Hashids class that is used to *encode* and *decode*\n\nprefix\n^^^^^^\n\n:type: String\n:value: The prefix prepended to hashid strings\n\n\nDjango REST Framework Integration\n=================================\n\nIf you wish to use a HashidField or HashidAutoField with a DRF ModelSerializer, there is one extra step that you must\ntake. Automatic declaration of any Hashid*Fields will result in an ImproperlyConfigured exception being thrown. You\nmust explicitly declare them in your Serializer, as there is no way for the generated field to know how to work with\na Hashid*Field, specifically what 'salt', 'min_length' and 'alphabet' to use, and can lead to very difficult errors or\nbehavior to debug, or in the worst case, corruption of your data. Here is an example:\n\n.. code-block:: python\n\n    from rest_framework import serializers\n    from hashid_field.rest import HashidSerializerCharField\n\n\n    class BookSerializer(serializers.ModelSerializer):\n        reference_id = HashidSerializerCharField(source_field='library.Book.reference_id')\n\n        class Meta:\n            model = Book\n            fields = ('id', 'reference_id')\n\n\n    class AuthorSerializer(serializers.ModelSerializer):\n        id = HashidSerializerCharField(source_field='library.Author.id', read_only=True)\n\n        class Meta:\n            model = Author\n            fields = ('id', 'name')\n\nThe ``source_field`` allows the HashidSerializerCharField to copy the 'salt', 'min_length' and 'alphabet' settings from\nthe given field at ``app_name.model_name.field_name`` so that it can be defined in just one place. Explicit settings are\nalso possible:\n\n.. code-block:: python\n\n    reference_id = HashidSerializerCharField(salt=\"a different salt\", min_length=10, alphabet=\"ABCDEFGHIJKLMNOPQRSTUVWXYZ\")\n\nIf nothing is given, then the field will use the same global settings as a Hashid*Field. It is very important that the\noptions for the serializer field matches the model field, or else strange errors or data corruption can occur.\n\nHashidSerializerCharField will serialize the value into a Hashids string, but will deserialize either a Hashids string or\ninteger and save it into the underlying Hashid*Field properly. There is also a HashidSerializerIntegerField that will\nserialize the Hashids into an un-encoded integer as well.\n\nPrimary Key Related Fields\n--------------------------\n\nAny models that have a ForeignKey to another model that uses a Hashid*Field as its Primary Key will need to explicitly\ndefine how the\n`PrimaryKeyRelatedField \u003chttp://www.django-rest-framework.org/api-guide/relations/#primarykeyrelatedfield\u003e`_\nshould serialize and deserialize the resulting value using the ``pk_field`` argument. If you don't you will get an error\nsuch as \"Hashid(60): N8VNa8z is not JSON serializable\". We have to tell DRF how to serialize/deserialize Hashid*Fields.\n\nFor the given ``Author`` model defined\nabove that has an ``id = HashidAutoField(primary_key=True)`` set, your BookSerializer should look like the following.\n\n.. code-block:: python\n\n    from rest_framework import serializers\n    from hashid_field.rest import HashidSerializerCharField\n\n\n    class BookSerializer(serializers.ModelSerializer):\n        author = serializers.PrimaryKeyRelatedField(\n            pk_field=HashidSerializerCharField(source_field='library.Author.id'),\n            read_only=True)\n\n        class Meta:\n            model = Book\n            fields = ('id', 'author')\n\nMake sure you pass the source field to the HashidSerializer*Field so that it can copy the 'salt', 'min_length' and 'alphabet'\nas described above.\n\nThis example sets ``read_only=True`` but you can explicitly define a ``queryset`` or override ``get_queryset(self)`` to allow\nread-write behavior.\n\n.. code-block:: python\n\n    author = serializers.PrimaryKeyRelatedField(\n        pk_field=HashidSerializerCharField(source_field='library.Author.id'),\n        queryset=Author.objects.all())\n\nFor a ManyToManyField, you must also remember to pass ``many=True`` to the ``PrimaryKeyRelatedField``.\n\n\nHashidSerializerCharField\n-------------------------\n\nSerialize a Hashid\\*Field to a Hashids string, de-serialize either a valid Hashids string or integer into a\nHashid\\*Field (if allow_int_lookup is enabled.)\n\nParameters\n~~~~~~~~~~\n\nsource_field\n^^^^^^^^^^^^\n\nA 3-field dotted notation of the source field to load matching 'salt', 'min_length' and 'alphabet' settings from. Must\nbe in the format of \"app_name.model_name.field_name\". Example: \"library.Book.reference_id\".\n\nsalt, min_length, alphabet, prefix, allow_int_lookup\n^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^\n\nSee `Field Parameters`_\n\n\nHashidSerializerIntegerField\n----------------------------\n\nSerialize a Hashid\\*Field to an integer, de-serialize either a valid Hashids string or integer into a\nHashid\\*Field. See `HashidSerializerCharField`_ for parameters.\n\n*Please Note*: This field will always serialize to an integer and thus will also de-serialize integers into valid\nobjects, regardless of the `allow_int_lookup` setting.\n\nKnown Issues\n============\n\n'Hashid' object is not iterable\n-------------------------------\n\nWith Django 5.0, attempting to filter on a field that is a ForeignKey to another model that uses a Hashid*Field as its\nprimary key will result in an error such as \"'Hashid' object is not iterable\". The workaround is to specify the exact\nfield of the related model to filter on. e.g. instead of `list_filter = ['author']` use `list_filter = ['author__name']`.\n\nAdmin can't find objects with a prefix that ends in an underscore\n-----------------------------------------------------------------\n\nThe Django admin has a `quote` and `unquote` function that attempts to encode non-alphanumeric characters in primary\nkeys using the format of `_xx` where `xx` is the hex value of the character. This can be a problem if you are using\na prefix that ends in an underscore, as there's a chance that your Hashid primary key will be something like,\n\"user_3Ej8Kjm\". The Django admin will attempt to `unquote` that to \"user\u003ej8Kjm\" by swapping the \"_3E\" with a \"\u003e\"\ncharacter, but that isn't valid and so it can't find the object. It will throw an error like, \"Admin Object with id\n'prefix\u003c2345678' doesn't exist. Perhaps it was deleted?\"\n\nThe workaround is to not use a prefix that ends in an underscore. You can end it with a character right after the\nunderscore that can't be used in hexidecimal, though, so it still looks right. e.g. `prefix=\"user_g\"` so that the above\nexample would actually be \"user_g3Ej8Kjm\", and \"_3E\" can't be matched. Or you can use any other character, such as\na hyphen, .e.g `prefix=\"user-\"`.\n\nDevelopment\n===========\n\nHere are some rough instructions on how to set up a dev environment to develop this module. Modify as needed. The\nsandbox is a django project that uses django-hashid-id, and is useful for developing features with.\n\n- ``git clone https://github.com/nshafer/django-hashid-field.git \u0026\u0026 cd django-hashid-field``\n- ``mkvirtualenv -a . -p /usr/bin/python3 -r sandbox/requirements.txt django-hashid-field``\n- ``python setup.py develop``\n- ``sandbox/manage.py migrate``\n- ``sandbox/manage.py createsuperuser``\n- ``sandbox/manage.py loaddata authors books editors``\n- ``sandbox/manage.py runserver``\n- ``python runtests.py``\n\nFor any pull requests, clone the repo and push to it, then create the PR.\n\nTo install the latest development version, use:\n\n```\npip install git+https://github.com/nshafer/django-hashid-field.git\n```\n\nLICENSE\n=======\n\nMIT License. You may use this in commercial and non-commercial projects with proper attribution.\nPlease see the `LICENSE \u003chttps://github.com/nshafer/django-hashid-field/blob/master/LICENSE\u003e`_\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnshafer%2Fdjango-hashid-field","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnshafer%2Fdjango-hashid-field","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnshafer%2Fdjango-hashid-field/lists"}