|MIT license| |PyPI version fury.io| |PyPI pyversions| |PyPi djversions| |PyPI status| |Documentation Status|
|Code Cov| |Test Status|
.. |MIT license| image:: https://img.shields.io/badge/License-MIT-blue.svg
:target: https://lbesson.mit-license.org/
.. |PyPI version fury.io| image:: https://badge.fury.io/py/django-enum.svg
:target: https://pypi.python.org/pypi/django-enum/
.. |PyPI pyversions| image:: https://img.shields.io/pypi/pyversions/django-enum.svg
:target: https://pypi.python.org/pypi/django-enum/
.. |PyPI djversions| image:: https://img.shields.io/pypi/djversions/django-enum.svg
:target: https://pypi.org/project/django-enum/
.. |PyPI status| image:: https://img.shields.io/pypi/status/django-enum.svg
:target: https://pypi.python.org/pypi/django-enum
.. |Documentation Status| image:: https://readthedocs.org/projects/django-enum/badge/?version=latest
:target: http://django-enum.readthedocs.io/?badge=latest/
.. |Code Cov| image:: https://codecov.io/gh/bckohan/django-enum/branch/main/graph/badge.svg?token=0IZOKN2DYL
:target: https://codecov.io/gh/bckohan/django-enum
.. |Test Status| image:: https://github.com/bckohan/django-enum/workflows/test/badge.svg
:target: https://github.com/bckohan/django-enum/actions
.. _Django: https://www.djangoproject.com/
.. _GitHub: https://github.com/bckohan/django-enum
.. _PyPI: https://pypi.python.org/pypi/django-enum
.. _Enum: https://docs.python.org/3/library/enum.html#enum.Enum
.. _enumerations: https://docs.python.org/3/library/enum.html#enum.Enum
.. _ValueError: https://docs.python.org/3/library/exceptions.html#ValueError
.. _DRY: https://en.wikipedia.org/wiki/Don%27t_repeat_yourself
Django Enum
###########
Full and natural support for enumerations_ as Django model fields.
Many packages aim to ease usage of Python enumerations as model fields. Most
were made obsolete when Django provided ``TextChoices`` and ``IntegerChoices``
types. The motivation for `django-enum <https://django-enum.readthedocs.io/en/latest/>`_
was to:
* Always automatically coerce fields to instances of the Enum type.
* Allow strict adherence to Enum values to be disabled.
* Be compatible with Enum classes that do not derive from Django's Choices.
* Handle migrations appropriately. (See `migrations <https://django-enum.readthedocs.io/en/latest/usage.html#migrations>`_)
* Integrate as fully as possible with Django_'s existing level of enum support.
* Integrate with `enum-properties <https://pypi.org/project/enum-properties/>`_ to enable richer enumeration types.
* Represent enum fields with the smallest possible column type.
* Be as simple and light-weight an extension to core Django as possible.
`django-enum <https://django-enum.readthedocs.io/en/latest/>`_ works in concert
with Django_'s built in ``TextChoices`` and ``IntegerChoices`` to provide a
new model field type, ``EnumField``, that resolves the correct native Django_
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>`_.
.. code:: 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)
int_enum = EnumField(IntEnum)
``EnumField`` **is more than just an alias. The fields are now assignable and
accessible as their enumeration type rather than by-value:**
.. code:: 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
`django-enum <https://django-enum.readthedocs.io/en/latest/>`_ also provides
``IntegerChoices`` and ``TextChoices`` types that extend from
`enum-properties <https://pypi.org/project/enum-properties/>`_ which makes
possible very rich enumeration fields.
``?> pip install enum-properties``
.. code:: python
from enum_properties import s
from django_enum import TextChoices # use instead of Django's TextChoices
from django.db import models
class TextChoicesExample(models.Model):
class Color(TextChoices, s('rgb'), s('hex', 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
.. note::
Consider using
`django-render-static <https://pypi.org/project/django-render-static/>`_
to make your enumerations DRY_ 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.rst>`_
are encouraged!
`Full documentation at read the docs. <https://django-enum.readthedocs.io/en/latest/>`_
Installation
------------
1. Clone django-enum from GitHub_ or install a release off PyPI_ :
.. code:: bash
pip install django-enum
.. note::
``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>`_.
.. code:: bash
pip install enum-properties
pip install django-filter
pip install djangorestframework
If features are utilized that require a missing optional dependency an
exception will be thrown.
Raw data
{
"_id": null,
"home_page": "https://django-enum.readthedocs.io",
"name": "django-enum",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7,<4.0",
"maintainer_email": "",
"keywords": "enum,properties,defines,field,django,database",
"author": "Brian Kohan",
"author_email": "bckohan@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/9d/e6/b70af4a5606fec26ee3865ad1e2c3dd862e345be0723ed626347238f0c03/django_enum-1.3.1.tar.gz",
"platform": null,
"description": "|MIT license| |PyPI version fury.io| |PyPI pyversions| |PyPi djversions| |PyPI status| |Documentation Status|\n|Code Cov| |Test Status|\n\n.. |MIT license| image:: https://img.shields.io/badge/License-MIT-blue.svg\n :target: https://lbesson.mit-license.org/\n\n.. |PyPI version fury.io| image:: https://badge.fury.io/py/django-enum.svg\n :target: https://pypi.python.org/pypi/django-enum/\n\n.. |PyPI pyversions| image:: https://img.shields.io/pypi/pyversions/django-enum.svg\n :target: https://pypi.python.org/pypi/django-enum/\n\n.. |PyPI djversions| image:: https://img.shields.io/pypi/djversions/django-enum.svg\n :target: https://pypi.org/project/django-enum/\n\n.. |PyPI status| image:: https://img.shields.io/pypi/status/django-enum.svg\n :target: https://pypi.python.org/pypi/django-enum\n\n.. |Documentation Status| image:: https://readthedocs.org/projects/django-enum/badge/?version=latest\n :target: http://django-enum.readthedocs.io/?badge=latest/\n\n.. |Code Cov| image:: https://codecov.io/gh/bckohan/django-enum/branch/main/graph/badge.svg?token=0IZOKN2DYL\n :target: https://codecov.io/gh/bckohan/django-enum\n\n.. |Test Status| image:: https://github.com/bckohan/django-enum/workflows/test/badge.svg\n :target: https://github.com/bckohan/django-enum/actions\n\n\n.. _Django: https://www.djangoproject.com/\n.. _GitHub: https://github.com/bckohan/django-enum\n.. _PyPI: https://pypi.python.org/pypi/django-enum\n.. _Enum: https://docs.python.org/3/library/enum.html#enum.Enum\n.. _enumerations: https://docs.python.org/3/library/enum.html#enum.Enum\n.. _ValueError: https://docs.python.org/3/library/exceptions.html#ValueError\n.. _DRY: https://en.wikipedia.org/wiki/Don%27t_repeat_yourself\n\nDjango Enum\n###########\n\nFull and natural support for enumerations_ as Django model fields.\n\nMany packages aim to ease usage of Python enumerations as model fields. Most\nwere made obsolete when Django provided ``TextChoices`` and ``IntegerChoices``\ntypes. The motivation for `django-enum <https://django-enum.readthedocs.io/en/latest/>`_\nwas to:\n\n* Always automatically coerce fields to instances of the Enum type.\n* Allow strict adherence to Enum values to be disabled.\n* Be compatible with Enum classes that do not derive from Django's Choices.\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 existing level of enum support.\n* Integrate with `enum-properties <https://pypi.org/project/enum-properties/>`_ to enable richer enumeration types.\n* Represent enum fields with the smallest possible column type.\n* Be as simple and light-weight an extension to core Django as possible.\n\n`django-enum <https://django-enum.readthedocs.io/en/latest/>`_ works in concert\nwith Django_'s built in ``TextChoices`` and ``IntegerChoices`` to provide a\nnew model field type, ``EnumField``, that resolves the correct native Django_\nfield type for the given enumeration based on its value type and range. For\nexample, ``IntegerChoices`` that contain values between 0 and 32767 become\n`PositiveSmallIntegerField <https://docs.djangoproject.com/en/stable/ref/models/fields/#positivesmallintegerfield>`_.\n\n.. code:: 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)\n int_enum = EnumField(IntEnum)\n\n\n``EnumField`` **is more than just an alias. The fields are now assignable and\naccessible as their enumeration type rather than by-value:**\n\n.. code:: 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`django-enum <https://django-enum.readthedocs.io/en/latest/>`_ also provides\n``IntegerChoices`` and ``TextChoices`` types that extend from\n`enum-properties <https://pypi.org/project/enum-properties/>`_ which makes\npossible very rich enumeration fields.\n\n``?> pip install enum-properties``\n\n.. code:: python\n\n from enum_properties import s\n from django_enum import TextChoices # use instead of Django's TextChoices\n from django.db import models\n\n class TextChoicesExample(models.Model):\n\n class Color(TextChoices, s('rgb'), s('hex', 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\n.. note::\n\n Consider using\n `django-render-static <https://pypi.org/project/django-render-static/>`_\n to make your enumerations DRY_ across the full stack!\n\nPlease report bugs and discuss features on the\n`issues page <https://github.com/bckohan/django-enum/issues>`_.\n\n`Contributions <https://github.com/bckohan/django-enum/blob/main/CONTRIBUTING.rst>`_\nare encouraged!\n\n`Full documentation at read the docs. <https://django-enum.readthedocs.io/en/latest/>`_\n\nInstallation\n------------\n\n1. Clone django-enum from GitHub_ or install a release off PyPI_ :\n\n.. code:: bash\n\n pip install django-enum\n\n.. note::\n\n ``django-enum`` has several optional dependencies that are not pulled in\n by default. ``EnumFields`` work seamlessly with all Django apps that\n work with model fields with choices without any additional work. Optional\n integrations are provided with several popular libraries to extend this\n basic functionality.\n\nIntegrations are provided that leverage\n`enum-properties <https://pypi.org/project/enum-properties/>`_ to make\nenumerations do more work and to provide extended functionality for\n`django-filter <https://pypi.org/project/django-filter/>`_ and\n`djangorestframework <https://www.django-rest-framework.org>`_.\n\n.. code:: bash\n\n pip install enum-properties\n pip install django-filter\n pip install djangorestframework\n\nIf features are utilized that require a missing optional dependency an\nexception will be thrown.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Full and natural support for enumerations as Django model fields.",
"version": "1.3.1",
"project_urls": {
"Homepage": "https://django-enum.readthedocs.io",
"Repository": "https://github.com/bckohan/django-enum"
},
"split_keywords": [
"enum",
"properties",
"defines",
"field",
"django",
"database"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "d8f4ad8078f73a686f511e869926e9fa4279f78ee72e47e5092734053abb914e",
"md5": "8dc89006901b9554489937684d17bd7a",
"sha256": "6be9c278e5d6bf273401ab49e2aa46f5e72b537db53ba68dc26bd25cd3c75efc"
},
"downloads": -1,
"filename": "django_enum-1.3.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "8dc89006901b9554489937684d17bd7a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7,<4.0",
"size": 15972,
"upload_time": "2024-03-03T07:19:17",
"upload_time_iso_8601": "2024-03-03T07:19:17.147297Z",
"url": "https://files.pythonhosted.org/packages/d8/f4/ad8078f73a686f511e869926e9fa4279f78ee72e47e5092734053abb914e/django_enum-1.3.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "9de6b70af4a5606fec26ee3865ad1e2c3dd862e345be0723ed626347238f0c03",
"md5": "8bebcf970bca31695583168570308ea0",
"sha256": "8013199f7334dd29e5a3b9ce9b65e92a89b4f1cb3c06b3bac59edb1b2edc1788"
},
"downloads": -1,
"filename": "django_enum-1.3.1.tar.gz",
"has_sig": false,
"md5_digest": "8bebcf970bca31695583168570308ea0",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7,<4.0",
"size": 15863,
"upload_time": "2024-03-03T07:19:19",
"upload_time_iso_8601": "2024-03-03T07:19:19.249902Z",
"url": "https://files.pythonhosted.org/packages/9d/e6/b70af4a5606fec26ee3865ad1e2c3dd862e345be0723ed626347238f0c03/django_enum-1.3.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-03-03 07:19:19",
"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
