# Django Hashids
[](https://github.com/ericls/django-hashids/actions)
[](https://codecov.io/gh/ericls/django-hashids)
[](https://pypi.org/project/django-hashids/)
[](https://pypi.org/project/django-hashids/)
[](https://github.com/ericls/django-hashids/blob/master/LICENSE)
django-hashids is a simple and non-intrusive hashids library for Django. It acts as a model field, but it does not touch the database or change the model.
# Features
- Proxy the internal model `pk` field without storing the value in the database.
- Allows lookups and filtering by hashid string.
- Can be used as sort key
- Allows specifying a salt, min_length and alphabet globally
- Supports custom salt, min_length, and alphabet per field
- Supports Django REST Framework Serializers
- Supports exact ID searches in Django Admin when field is specified in search_fields.
- Supports common filtering lookups, such as __iexact, __contains, __icontains, though matching is the same as __exact.
- Supports other lookups: isnull, gt, gte, lt and lte.
# Install
```bash
pip install django-hashids
```
`django-hashids` is tested with Django 1.11, 2.2, 3.0, 3.1, 3.2, 4.0 and python 3.6, 3.7, 3.8, 3.9, 3.10.
# Usage
Add `HashidsField` to any model
```python
from django_hashids import HashidsField
class TestModel(Model):
hashid = HashidsField(real_field_name="id")
```
`TestModel.hashid` field will proxy `TestModel.id` field but all queries will return and receive hashids strings. `TestModel.id` will work as before.
## Examples
```python
instance = TestModel.objects.create()
instance2 = TestModel.objects.create()
instance.id # 1
instance2.id # 2
# Allows access to the field
instance.hashid # '1Z'
instance2.hashid # '4x'
# Allows querying by the field
TestModel.objects.get(hashid="1Z")
TestModel.objects.filter(hashid="1Z")
TestModel.objects.filter(hashid__in=["1Z", "4x"])
TestModel.objects.filter(hashid__gt="1Z") # same as id__gt=1, would return instance 2
# Allows usage in queryset.values
TestModel.objects.values_list("hashid", flat=True) # ["1Z", "4x"]
TestModel.objects.filter(hashid__in=TestModel.objects.values("hashid"))
```
## Config
The folloing attributes can be added in settings file to set default arguments of `HashidsField`:
1. `DJANGO_HASHIDS_SALT`: default salt
2. `DJANGO_HASHIDS_MIN_LENGTH`: default minimum length
3. `DJANGO_HASHIDS_ALPHABET`: default alphabet
`HashidsField` does not reqiure any arguments but the followinig arguments can be supplied to modify its behavior.
| Name | Description |
| ------------------ | :-------------------------------------------------------: |
| `real_field_name` | The proxied field name |
| `hashids_instance` | The hashids instance used to encode/decode for this field |
| `salt` | The salt used for this field to generate hashids |
| `min_length` | The minimum length of hashids generated for this field |
| `alphabet` | The alphabet used by this field to generate hashids |
The argument `hashids_instance` is mutually exclusive to `salt`, `min_length` and `alphabet`. See [hashids-python](https://github.com/davidaurelio/hashids-python) for more info about the arguments.
Some common Model arguments such as `verbose_name` are also supported.
Raw data
{
"_id": null,
"home_page": "https://github.com/ericls/django-hashids",
"name": "django-hashids",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.6.2,<4",
"maintainer_email": "",
"keywords": "django,hashids,hashid",
"author": "Shen Li",
"author_email": "dustet@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/90/f6/9e77ca7feab48bb5eafab8684ba7905b8f11a3217f033b23b4c8c2bdec46/django_hashids-0.7.0.tar.gz",
"platform": null,
"description": "# Django Hashids\n[](https://github.com/ericls/django-hashids/actions)\n[](https://codecov.io/gh/ericls/django-hashids)\n[](https://pypi.org/project/django-hashids/)\n[](https://pypi.org/project/django-hashids/)\n[](https://github.com/ericls/django-hashids/blob/master/LICENSE)\n\ndjango-hashids is a simple and non-intrusive hashids library for Django. It acts as a model field, but it does not touch the database or change the model.\n\n# Features\n- Proxy the internal model `pk` field without storing the value in the database.\n- Allows lookups and filtering by hashid string.\n- Can be used as sort key\n- Allows specifying a salt, min_length and alphabet globally\n- Supports custom salt, min_length, and alphabet per field\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 other lookups: isnull, gt, gte, lt and lte.\n\n# Install\n\n```bash\npip install django-hashids\n```\n\n`django-hashids` is tested with Django 1.11, 2.2, 3.0, 3.1, 3.2, 4.0 and python 3.6, 3.7, 3.8, 3.9, 3.10.\n\n# Usage\n\nAdd `HashidsField` to any model\n\n```python\nfrom django_hashids import HashidsField\n\nclass TestModel(Model):\n hashid = HashidsField(real_field_name=\"id\")\n```\n\n`TestModel.hashid` field will proxy `TestModel.id` field but all queries will return and receive hashids strings. `TestModel.id` will work as before.\n\n## Examples\n\n```python\ninstance = TestModel.objects.create()\ninstance2 = TestModel.objects.create()\ninstance.id # 1\ninstance2.id # 2\n\n# Allows access to the field\ninstance.hashid # '1Z'\ninstance2.hashid # '4x'\n\n# Allows querying by the field\nTestModel.objects.get(hashid=\"1Z\")\nTestModel.objects.filter(hashid=\"1Z\")\nTestModel.objects.filter(hashid__in=[\"1Z\", \"4x\"])\nTestModel.objects.filter(hashid__gt=\"1Z\") # same as id__gt=1, would return instance 2\n\n# Allows usage in queryset.values\nTestModel.objects.values_list(\"hashid\", flat=True) # [\"1Z\", \"4x\"]\nTestModel.objects.filter(hashid__in=TestModel.objects.values(\"hashid\"))\n\n```\n\n## Config\n\nThe folloing attributes can be added in settings file to set default arguments of `HashidsField`:\n1. `DJANGO_HASHIDS_SALT`: default salt\n2. `DJANGO_HASHIDS_MIN_LENGTH`: default minimum length\n3. `DJANGO_HASHIDS_ALPHABET`: default alphabet\n\n`HashidsField` does not reqiure any arguments but the followinig arguments can be supplied to modify its behavior.\n\n| Name | Description |\n| ------------------ | :-------------------------------------------------------: |\n| `real_field_name` | The proxied field name |\n| `hashids_instance` | The hashids instance used to encode/decode for this field |\n| `salt` | The salt used for this field to generate hashids |\n| `min_length` | The minimum length of hashids generated for this field |\n| `alphabet` | The alphabet used by this field to generate hashids |\n\nThe argument `hashids_instance` is mutually exclusive to `salt`, `min_length` and `alphabet`. See [hashids-python](https://github.com/davidaurelio/hashids-python) for more info about the arguments.\n\nSome common Model arguments such as `verbose_name` are also supported.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Non-intrusive hashids library for Django",
"version": "0.7.0",
"split_keywords": [
"django",
"hashids",
"hashid"
],
"urls": [
{
"comment_text": "",
"digests": {
"md5": "d5e6d2993b919bd7217c0cef1d7b80b6",
"sha256": "a5d91bda97c46afa08972d9e85143af79d9e2f8d754f3d3f0df6b8ac8f57b92b"
},
"downloads": -1,
"filename": "django_hashids-0.7.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d5e6d2993b919bd7217c0cef1d7b80b6",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6.2,<4",
"size": 5478,
"upload_time": "2022-12-07T02:38:34",
"upload_time_iso_8601": "2022-12-07T02:38:34.985714Z",
"url": "https://files.pythonhosted.org/packages/50/0b/9dd1fac03e3e0907444592647dfafb2fdc54615da05bd86b6d271e2f838d/django_hashids-0.7.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"md5": "8a5ea49ee56965d761f0e464f9f28a14",
"sha256": "dce33e6f002308cbe03ca9ec80e27ce6b469e3abf2a42df8ba3381724683690b"
},
"downloads": -1,
"filename": "django_hashids-0.7.0.tar.gz",
"has_sig": false,
"md5_digest": "8a5ea49ee56965d761f0e464f9f28a14",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6.2,<4",
"size": 5306,
"upload_time": "2022-12-07T02:38:37",
"upload_time_iso_8601": "2022-12-07T02:38:37.074237Z",
"url": "https://files.pythonhosted.org/packages/90/f6/9e77ca7feab48bb5eafab8684ba7905b8f11a3217f033b23b4c8c2bdec46/django_hashids-0.7.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2022-12-07 02:38:37",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "ericls",
"github_project": "django-hashids",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "django-hashids"
}
JSON
