# django-enum
[](https://opensource.org/licenses/MIT)
[](https://docs.astral.sh/ruff)
[](https://pypi.python.org/pypi/django-enum/)
[](https://pypi.python.org/pypi/django-enum/)
[](https://pypi.org/project/django-enum/)
[](https://pypi.python.org/pypi/django-enum)
[](http://django-enum.readthedocs.io/?badge=latest/)
[](https://codecov.io/gh/bckohan/django-enum)
[](https://github.com/bckohan/django-enum/actions/workflows/test.yml)
[](https://github.com/bckohan/django-enum/actions/workflows/lint.yml)
---------------------------------------------------------------------------------------------------
[](https://www.postgresql.org/)
[](https://www.mysql.com/)
[](https://mariadb.org/)
[](https://www.sqlite.org/)
[](https://www.oracle.com/database/)
---------------------------------------------------------------------------------------------------
🚨 **See [migration guide](https://django-enum.readthedocs.io/en/latest/changelog.html#migration-1-x-to-2-x) for notes on 1.x to 2.x migration.** 🚨
Full and natural support for [enumerations](https://docs.python.org/3/library/enum.html#enum.Enum) as Django model fields.
Many packages aim to ease usage of Python enumerations as model fields. Most were superseded when Django provided ``TextChoices`` and ``IntegerChoices`` types. The motivation for [django-enum](https://django-enum.readthedocs.io) was to:
* Work with any Python PEP 435 Enum including those that do not derive from Django's TextChoices and IntegerChoices.
* Coerce fields to instances of the Enum type by default.
* Allow strict adherence to Enum values to be disabled.
* Handle migrations appropriately. (See [migrations](https://django-enum.readthedocs.io/en/latest/usage.html#migrations))
* Integrate as fully as possible with [Django's](https://www.djangoproject.com) existing level of enum support.
* Support [enum-properties](https://pypi.org/project/enum-properties) to enable richer enumeration types. (A less awkward alternative to dataclass enumerations with more features)
* Represent enum fields with the smallest possible column type.
* Support bit mask queries using standard Python Flag enumerations.
* Be as simple and light-weight an extension to core [Django](https://www.djangoproject.com) as possible.
* Enforce enumeration value consistency at the database level using check constraints by default.
* (TODO) Support native database enumeration column types when available.
[django-enum](https://django-enum.readthedocs.io) works in concert with [Django's](https://www.djangoproject.com) built in ``TextChoices`` and ``IntegerChoices`` to provide a new model field type, ``EnumField``, that resolves the correct native [Django](https://www.djangoproject.com) field type for the given enumeration based on its value type and range. For example, ``IntegerChoices`` that contain values between 0 and 32767 become [PositiveSmallIntegerField](https://docs.djangoproject.com/en/stable/ref/models/fields/#positivesmallintegerfield).
```python
from django.db import models
from django_enum import EnumField
class MyModel(models.Model):
class TextEnum(models.TextChoices):
VALUE0 = 'V0', 'Value 0'
VALUE1 = 'V1', 'Value 1'
VALUE2 = 'V2', 'Value 2'
class IntEnum(models.IntegerChoices):
ONE = 1, 'One'
TWO = 2, 'Two',
THREE = 3, 'Three'
# this is equivalent to:
# CharField(max_length=2, choices=TextEnum.choices, null=True, blank=True)
txt_enum = EnumField(TextEnum, null=True, blank=True)
# this is equivalent to
# PositiveSmallIntegerField(choices=IntEnum.choices, default=IntEnum.ONE.value)
int_enum = EnumField(IntEnum, default=IntEnum.ONE)
```
``EnumField`` **is more than just an alias. The fields are now assignable and accessible as their enumeration type rather than by-value:**
```python
instance = MyModel.objects.create(
txt_enum=MyModel.TextEnum.VALUE1,
int_enum=3 # by-value assignment also works
)
assert instance.txt_enum == MyModel.TextEnum('V1')
assert instance.txt_enum.label == 'Value 1'
assert instance.int_enum == MyModel.IntEnum['THREE']
assert instance.int_enum.value == 3
```
## Flag Support
[Flag](https://docs.python.org/3/library/enum.html#enum.Flag) types are also seamlessly supported! This allows a database column to behave like a bit mask and is an alternative to multiple boolean columns. There are mostly positive performance implications for using a bit mask instead of booleans depending on the size of the bit mask and the types of queries you will run against it. For bit masks more than a few bits long the size reduction both speeds up queries and reduces the required storage space. See the documentation for [discussion and benchmarks](https://django-enum.readthedocs.io/en/latest/performance.html#flags).
```python
class Permissions(IntFlag):
READ = 1**2
WRITE = 2**2
EXECUTE = 3**2
class FlagExample(models.Model):
permissions = EnumField(Permissions)
FlagExample.objects.create(permissions=Permissions.READ | Permissions.WRITE)
# get all models with RW:
FlagExample.objects.filter(permissions__has_all=Permissions.READ | Permissions.WRITE)
```
## Complex Enumerations
[django-enum](https://django-enum.readthedocs.io) supports enum types that do not derive from Django's ``IntegerChoices`` and ``TextChoices``. This allows us to use other libs like [enum-properties](https://pypi.org/project/enum-properties) which makes possible very rich enumeration fields:
``?> pip install enum-properties``
```python
from enum_properties import StrEnumProperties
from django.db import models
class TextChoicesExample(models.Model):
class Color(StrEnumProperties):
label: Annotated[str, Symmetric()]
rgb: Annotated[t.Tuple[int, int, int], Symmetric()]
hex: Annotated[str, Symmetric(case_fold=True)]
# name value label rgb hex
RED = "R", "Red", (1, 0, 0), "ff0000"
GREEN = "G", "Green", (0, 1, 0), "00ff00"
BLUE = "B", "Blue", (0, 0, 1), "0000ff"
# any named s() values in the Enum's inheritance become properties on
# each value, and the enumeration value may be instantiated from the
# property's value
color = EnumField(Color)
instance = TextChoicesExample.objects.create(
color=TextChoicesExample.Color('FF0000')
)
assert instance.color == TextChoicesExample.Color('Red')
assert instance.color == TextChoicesExample.Color('R')
assert instance.color == TextChoicesExample.Color((1, 0, 0))
# direct comparison to any symmetric value also works
assert instance.color == 'Red'
assert instance.color == 'R'
assert instance.color == (1, 0, 0)
# save by any symmetric value
instance.color = 'FF0000'
# access any enum property right from the model field
assert instance.color.hex == 'ff0000'
# this also works!
assert instance.color == 'ff0000'
# and so does this!
assert instance.color == 'FF0000'
instance.save()
# filtering works by any symmetric value or enum type instance
assert TextChoicesExample.objects.filter(
color=TextChoicesExample.Color.RED
).first() == instance
assert TextChoicesExample.objects.filter(color=(1, 0, 0)).first() == instance
assert TextChoicesExample.objects.filter(color='FF0000').first() == instance
```
While they should be unnecessary if you need to integrate with code that expects an interface fully compatible with Django's ``TextChoices`` and ``IntegerChoices`` django-enum provides ``TextChoices``, ``IntegerChoices``, ``FlagChoices`` and ``FloatChoices`` types that derive from enum-properties and Django's ``Choices``. So the above enumeration could also be written:
```python
from django_enum.choices import TextChoices
class Color(TextChoices):
# label is added as a symmetric property by the base class
rgb: Annotated[t.Tuple[int, int, int], Symmetric()]
hex: Annotated[str, Symmetric(case_fold=True)]
# name value label rgb hex
RED = "R", "Red", (1, 0, 0), "ff0000"
GREEN = "G", "Green", (0, 1, 0), "00ff00"
BLUE = "B", "Blue", (0, 0, 1), "0000ff"
```
## Installation
1. Clone django-enum from [GitHub](https://github.com/bckohan/django-enum) or install a release off [pypi](https://pypi.org/project/django-enum):
```bash
pip install django-enum
```
``django-enum`` has several optional dependencies that are not pulled in by default. ``EnumFields`` work seamlessly with all Django apps that work with model fields with choices without any additional work. Optional integrations are provided with several popular libraries to extend this basic functionality.
Integrations are provided that leverage [enum-properties](https://pypi.org/project/enum-properties) to make enumerations do more work and to provide extended functionality for [django-filter](https://pypi.org/project/django-filter) and [djangorestframework](https://www.django-rest-framework.org).
```bash
pip install enum-properties
pip install django-filter
pip install djangorestframework
```
## Continuous Integration
Like with Django, Postgres is the preferred database for support. The full test suite is run against all combinations of currently supported versions of Django, Python, and Postgres as well as psycopg3 and psycopg2. The other RDBMS supported by Django are also tested including SQLite, MySQL, MariaDB and Oracle. For these RDBMS (with the exception of Oracle), tests are run against the minimum and maximum supported version combinations to maximize coverage breadth.
**See the [latest test runs](https://github.com/bckohan/django-enum/actions/workflows/test.yml) for our current test matrix**
*For Oracle, only the latest version of the free database is tested against the minimum and maximum supported versions of Python, Django and the cx-Oracle driver.*
## Further Reading
Consider using [django-render-static](https://pypi.org/project/django-render-static) to make your enumerations [DRY](https://en.wikipedia.org/wiki/Don%27t_repeat_yourself) across the full stack!
Please report bugs and discuss features on the [issues page](https://github.com/bckohan/django-enum/issues).
[Contributions](https://github.com/bckohan/django-enum/blob/main/CONTRIBUTING.md) are encouraged!
[Full documentation at read the docs.](https://django-enum.readthedocs.io)
Raw data
{
"_id": null,
"home_page": "https://django-enum.rtfd.io",
"name": "django-enum",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.8",
"maintainer_email": null,
"keywords": "enum, properties, defines, field, django, database, bitmask, mask, bitfield, flags",
"author": "Brian Kohan",
"author_email": "bckohan@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/47/b5/466ac9e47aaeaf0c63a7c269ee5f47a8be8400917b5f079a01f280221ace/django_enum-2.0.2.tar.gz",
"platform": null,
"description": "# django-enum\n\n[](https://opensource.org/licenses/MIT)\n[](https://docs.astral.sh/ruff)\n[](https://pypi.python.org/pypi/django-enum/)\n[](https://pypi.python.org/pypi/django-enum/)\n[](https://pypi.org/project/django-enum/)\n[](https://pypi.python.org/pypi/django-enum)\n[](http://django-enum.readthedocs.io/?badge=latest/)\n[](https://codecov.io/gh/bckohan/django-enum)\n[](https://github.com/bckohan/django-enum/actions/workflows/test.yml)\n[](https://github.com/bckohan/django-enum/actions/workflows/lint.yml)\n\n---------------------------------------------------------------------------------------------------\n\n[](https://www.postgresql.org/)\n[](https://www.mysql.com/)\n[](https://mariadb.org/)\n[](https://www.sqlite.org/)\n[](https://www.oracle.com/database/)\n\n---------------------------------------------------------------------------------------------------\n\n\ud83d\udea8 **See [migration guide](https://django-enum.readthedocs.io/en/latest/changelog.html#migration-1-x-to-2-x) for notes on 1.x to 2.x migration.** \ud83d\udea8\n\nFull and natural support for [enumerations](https://docs.python.org/3/library/enum.html#enum.Enum) as Django model fields.\n\nMany packages aim to ease usage of Python enumerations as model fields. Most were superseded when Django provided ``TextChoices`` and ``IntegerChoices`` types. The motivation for [django-enum](https://django-enum.readthedocs.io) was to:\n\n* Work with any Python PEP 435 Enum including those that do not derive from Django's TextChoices and IntegerChoices.\n* Coerce fields to instances of the Enum type by default.\n* Allow strict adherence to Enum values to be disabled.\n* Handle migrations appropriately. (See [migrations](https://django-enum.readthedocs.io/en/latest/usage.html#migrations))\n* Integrate as fully as possible with [Django's](https://www.djangoproject.com) existing level of enum support.\n* Support [enum-properties](https://pypi.org/project/enum-properties) to enable richer enumeration types. (A less awkward alternative to dataclass enumerations with more features)\n* Represent enum fields with the smallest possible column type.\n* Support bit mask queries using standard Python Flag enumerations.\n* Be as simple and light-weight an extension to core [Django](https://www.djangoproject.com) as possible.\n* Enforce enumeration value consistency at the database level using check constraints by default.\n* (TODO) Support native database enumeration column types when available.\n\n[django-enum](https://django-enum.readthedocs.io) works in concert with [Django's](https://www.djangoproject.com) built in ``TextChoices`` and ``IntegerChoices`` to provide a new model field type, ``EnumField``, that resolves the correct native [Django](https://www.djangoproject.com) field type for the given enumeration based on its value type and range. For example, ``IntegerChoices`` that contain values between 0 and 32767 become [PositiveSmallIntegerField](https://docs.djangoproject.com/en/stable/ref/models/fields/#positivesmallintegerfield).\n\n```python\n\n from django.db import models\n from django_enum import EnumField\n\n class MyModel(models.Model):\n\n class TextEnum(models.TextChoices):\n\n VALUE0 = 'V0', 'Value 0'\n VALUE1 = 'V1', 'Value 1'\n VALUE2 = 'V2', 'Value 2'\n\n class IntEnum(models.IntegerChoices):\n\n ONE = 1, 'One'\n TWO = 2, 'Two',\n THREE = 3, 'Three'\n\n # this is equivalent to:\n # CharField(max_length=2, choices=TextEnum.choices, null=True, blank=True)\n txt_enum = EnumField(TextEnum, null=True, blank=True)\n\n # this is equivalent to\n # PositiveSmallIntegerField(choices=IntEnum.choices, default=IntEnum.ONE.value)\n int_enum = EnumField(IntEnum, default=IntEnum.ONE)\n```\n\n``EnumField`` **is more than just an alias. The fields are now assignable and accessible as their enumeration type rather than by-value:**\n\n```python\n\n instance = MyModel.objects.create(\n txt_enum=MyModel.TextEnum.VALUE1,\n int_enum=3 # by-value assignment also works\n )\n\n assert instance.txt_enum == MyModel.TextEnum('V1')\n assert instance.txt_enum.label == 'Value 1'\n\n assert instance.int_enum == MyModel.IntEnum['THREE']\n assert instance.int_enum.value == 3\n```\n\n## Flag Support\n\n[Flag](https://docs.python.org/3/library/enum.html#enum.Flag) types are also seamlessly supported! This allows a database column to behave like a bit mask and is an alternative to multiple boolean columns. There are mostly positive performance implications for using a bit mask instead of booleans depending on the size of the bit mask and the types of queries you will run against it. For bit masks more than a few bits long the size reduction both speeds up queries and reduces the required storage space. See the documentation for [discussion and benchmarks](https://django-enum.readthedocs.io/en/latest/performance.html#flags).\n\n```python\n\n class Permissions(IntFlag):\n\n READ = 1**2\n WRITE = 2**2\n EXECUTE = 3**2\n\n\n class FlagExample(models.Model):\n\n permissions = EnumField(Permissions)\n\n\n FlagExample.objects.create(permissions=Permissions.READ | Permissions.WRITE)\n\n # get all models with RW:\n FlagExample.objects.filter(permissions__has_all=Permissions.READ | Permissions.WRITE)\n```\n\n## Complex Enumerations\n\n[django-enum](https://django-enum.readthedocs.io) supports enum types that do not derive from Django's ``IntegerChoices`` and ``TextChoices``. This allows us to use other libs like [enum-properties](https://pypi.org/project/enum-properties) which makes possible very rich enumeration fields:\n\n``?> pip install enum-properties``\n\n```python\n\n from enum_properties import StrEnumProperties\n from django.db import models\n\n class TextChoicesExample(models.Model):\n\n class Color(StrEnumProperties):\n\n label: Annotated[str, Symmetric()]\n rgb: Annotated[t.Tuple[int, int, int], Symmetric()]\n hex: Annotated[str, Symmetric(case_fold=True)]\n\n # name value label rgb hex\n RED = \"R\", \"Red\", (1, 0, 0), \"ff0000\"\n GREEN = \"G\", \"Green\", (0, 1, 0), \"00ff00\"\n BLUE = \"B\", \"Blue\", (0, 0, 1), \"0000ff\"\n\n # any named s() values in the Enum's inheritance become properties on\n # each value, and the enumeration value may be instantiated from the\n # property's value\n\n color = EnumField(Color)\n\n instance = TextChoicesExample.objects.create(\n color=TextChoicesExample.Color('FF0000')\n )\n assert instance.color == TextChoicesExample.Color('Red')\n assert instance.color == TextChoicesExample.Color('R')\n assert instance.color == TextChoicesExample.Color((1, 0, 0))\n\n # direct comparison to any symmetric value also works\n assert instance.color == 'Red'\n assert instance.color == 'R'\n assert instance.color == (1, 0, 0)\n\n # save by any symmetric value\n instance.color = 'FF0000'\n\n # access any enum property right from the model field\n assert instance.color.hex == 'ff0000'\n\n # this also works!\n assert instance.color == 'ff0000'\n\n # and so does this!\n assert instance.color == 'FF0000'\n\n instance.save()\n\n # filtering works by any symmetric value or enum type instance\n assert TextChoicesExample.objects.filter(\n color=TextChoicesExample.Color.RED\n ).first() == instance\n\n assert TextChoicesExample.objects.filter(color=(1, 0, 0)).first() == instance\n\n assert TextChoicesExample.objects.filter(color='FF0000').first() == instance\n```\n\nWhile they should be unnecessary if you need to integrate with code that expects an interface fully compatible with Django's ``TextChoices`` and ``IntegerChoices`` django-enum provides ``TextChoices``, ``IntegerChoices``, ``FlagChoices`` and ``FloatChoices`` types that derive from enum-properties and Django's ``Choices``. So the above enumeration could also be written:\n\n```python\n\n from django_enum.choices import TextChoices\n\n class Color(TextChoices):\n\n # label is added as a symmetric property by the base class\n\n rgb: Annotated[t.Tuple[int, int, int], Symmetric()]\n hex: Annotated[str, Symmetric(case_fold=True)]\n\n # name value label rgb hex\n RED = \"R\", \"Red\", (1, 0, 0), \"ff0000\"\n GREEN = \"G\", \"Green\", (0, 1, 0), \"00ff00\"\n BLUE = \"B\", \"Blue\", (0, 0, 1), \"0000ff\"\n\n```\n\n## Installation\n\n1. Clone django-enum from [GitHub](https://github.com/bckohan/django-enum) or install a release off [pypi](https://pypi.org/project/django-enum):\n\n```bash\n pip install django-enum\n```\n\n``django-enum`` has several optional dependencies that are not pulled in by default. ``EnumFields`` work seamlessly with all Django apps that work with model fields with choices without any additional work. Optional integrations are provided with several popular libraries to extend this basic functionality.\n\nIntegrations are provided that leverage [enum-properties](https://pypi.org/project/enum-properties) to make enumerations do more work and to provide extended functionality for [django-filter](https://pypi.org/project/django-filter) and [djangorestframework](https://www.django-rest-framework.org).\n\n```bash\n pip install enum-properties\n pip install django-filter\n pip install djangorestframework\n```\n\n## Continuous Integration\n\nLike with Django, Postgres is the preferred database for support. The full test suite is run against all combinations of currently supported versions of Django, Python, and Postgres as well as psycopg3 and psycopg2. The other RDBMS supported by Django are also tested including SQLite, MySQL, MariaDB and Oracle. For these RDBMS (with the exception of Oracle), tests are run against the minimum and maximum supported version combinations to maximize coverage breadth.\n\n**See the [latest test runs](https://github.com/bckohan/django-enum/actions/workflows/test.yml) for our current test matrix**\n\n*For Oracle, only the latest version of the free database is tested against the minimum and maximum supported versions of Python, Django and the cx-Oracle driver.*\n\n## Further Reading\n\nConsider using [django-render-static](https://pypi.org/project/django-render-static) to make your enumerations [DRY](https://en.wikipedia.org/wiki/Don%27t_repeat_yourself) across the full stack!\n\nPlease report bugs and discuss features on the [issues page](https://github.com/bckohan/django-enum/issues).\n\n[Contributions](https://github.com/bckohan/django-enum/blob/main/CONTRIBUTING.md) are encouraged!\n\n[Full documentation at read the docs.](https://django-enum.readthedocs.io)",
"bugtrack_url": null,
"license": "MIT",
"summary": "Full and natural support for enumerations as Django model fields.",
"version": "2.0.2",
"project_urls": {
"Homepage": "https://django-enum.rtfd.io",
"Repository": "https://github.com/bckohan/django-enum"
},
"split_keywords": [
"enum",
" properties",
" defines",
" field",
" django",
" database",
" bitmask",
" mask",
" bitfield",
" flags"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "c8a49a0ce6e8adc1bfe7c24de8f913f3acdad32f30e3f179410b50e6693f8adb",
"md5": "b94b53e3031439200276ee0f2db5ea0e",
"sha256": "5843285f6286cb49ba041607cf3ba554e7eb5c5e8426bab79105d2a766bffb58"
},
"downloads": -1,
"filename": "django_enum-2.0.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "b94b53e3031439200276ee0f2db5ea0e",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.8",
"size": 29002,
"upload_time": "2024-09-25T15:10:12",
"upload_time_iso_8601": "2024-09-25T15:10:12.815590Z",
"url": "https://files.pythonhosted.org/packages/c8/a4/9a0ce6e8adc1bfe7c24de8f913f3acdad32f30e3f179410b50e6693f8adb/django_enum-2.0.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "47b5466ac9e47aaeaf0c63a7c269ee5f47a8be8400917b5f079a01f280221ace",
"md5": "1e903e83dc256db4a83fe0ca46c41b9f",
"sha256": "d431dc997392824671d27a1233d2bada0e386c4df6cfd4ed049161219693a5d8"
},
"downloads": -1,
"filename": "django_enum-2.0.2.tar.gz",
"has_sig": false,
"md5_digest": "1e903e83dc256db4a83fe0ca46c41b9f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.8",
"size": 29724,
"upload_time": "2024-09-25T15:10:18",
"upload_time_iso_8601": "2024-09-25T15:10:18.230292Z",
"url": "https://files.pythonhosted.org/packages/47/b5/466ac9e47aaeaf0c63a7c269ee5f47a8be8400917b5f079a01f280221ace/django_enum-2.0.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-09-25 15:10:18",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "bckohan",
"github_project": "django-enum",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "django-enum"
}
JSON
