{"id":13448808,"url":"https://github.com/5monkeys/django-enumfield","last_synced_at":"2025-04-13T02:07:36.202Z","repository":{"id":6689695,"uuid":"7934826","full_name":"5monkeys/django-enumfield","owner":"5monkeys","description":"Custom Django field for using enumerations of named constants","archived":false,"fork":false,"pushed_at":"2024-01-12T18:58:57.000Z","size":206,"stargazers_count":201,"open_issues_count":11,"forks_count":45,"subscribers_count":13,"default_branch":"master","last_synced_at":"2024-05-22T15:09:13.997Z","etag":null,"topics":["django","django-rest-framework","enum","python"],"latest_commit_sha":null,"homepage":"","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/5monkeys.png","metadata":{"files":{"readme":"README.md","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":"AUTHORS","dei":null,"publiccode":null,"codemeta":null}},"created_at":"2013-01-31T10:34:44.000Z","updated_at":"2024-06-18T19:50:40.632Z","dependencies_parsed_at":"2024-01-06T11:11:59.944Z","dependency_job_id":"44716c81-f487-4bb9-b559-f33709c0dbf5","html_url":"https://github.com/5monkeys/django-enumfield","commit_stats":{"total_commits":228,"total_committers":26,"mean_commits":8.76923076923077,"dds":0.6052631578947368,"last_synced_commit":"5d7c958e657b57d21e6f549090dccf71c2e21393"},"previous_names":[],"tags_count":21,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/5monkeys%2Fdjango-enumfield","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/5monkeys%2Fdjango-enumfield/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/5monkeys%2Fdjango-enumfield/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/5monkeys%2Fdjango-enumfield/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/5monkeys","download_url":"https://codeload.github.com/5monkeys/django-enumfield/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247117749,"owners_count":20886439,"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","enum","python"],"created_at":"2024-07-31T06:00:21.577Z","updated_at":"2025-04-04T04:08:30.082Z","avatar_url":"https://github.com/5monkeys.png","language":"Python","funding_links":[],"categories":["Fields"],"sub_categories":[],"readme":"# django-enumfield\n\nProvides an enumeration Django model field (using `IntegerField`) with reusable enums and transition validation.\n\n[![Build Status](https://github.com/5monkeys/django-enumfield/workflows/Test/badge.svg)](https://github.com/5monkeys/django-enumfield/actions)\n[![PyPi Version](https://img.shields.io/pypi/v/django-enumfield.svg)](https://pypi.python.org/pypi/django-enumfield)\n[![License](https://img.shields.io/pypi/l/django-enumfield.svg)](https://pypi.python.org/pypi/django-enumfield)\n[![Python Versions](https://img.shields.io/pypi/pyversions/django-enumfield.svg)](https://pypi.python.org/pypi/django-enumfield)\n[![Wheel](https://img.shields.io/pypi/wheel/django-enumfield.svg)](https://pypi.python.org/pypi/django-enumfield)\n![Coveralls github](https://img.shields.io/coveralls/github/5monkeys/django-enumfield)\n\nInstallation\n------------\n\nCurrently, [we test](https://github.com/5monkeys/django-enumfield/actions) Django versions 2.2-4.1 and Python versions 3.7-3.11.\n\nInstall `django-enumfield` in your Python environment:\n\n```sh\n$ pip install django-enumfield\n```\n\n**Upgrading from django-enumfield 1.x?** [See the migration guide](docs/migrate-to-20.md)\n\nFor use with Django versions prior to 1.8 use version\n[`1.2.1`](https://github.com/5monkeys/django-enumfield/tree/1.2.1)\n\nFor use with Django versions prior to 1.11 use version\n[`1.5`](https://github.com/5monkeys/django-enumfield/tree/1.5)\n\nUsage\n-----\n\nCreate an `Enum`-class and pass it as first argument to the Django model `EnumField`.\n\n```python\nfrom django.db import models\nfrom django_enumfield import enum\n\n\nclass BeerStyle(enum.Enum):\n    LAGER = 0\n    STOUT = 1\n    WEISSBIER = 2\n\n\nclass Beer(models.Model):\n    style = enum.EnumField(BeerStyle, default=BeerStyle.LAGER)\n\n\n# Use .get to get enum values from either name or ints\nprint(BeerStyle.get(\"LAGER\"))  # \u003cBeerStyle.LAGER: 0\u003e\nprint(BeerStyle.get(1))  # \u003cBeerStyle.STOUT: 1\u003e\nprint(BeerStyle.get(BeerStyle.WEISSBIER))  # \u003cBeerStyle.WEISSBIER: 2\u003e\n\n# It's also possible to use the normal enum way to get the value\nprint(BeerStyle(1))  # \u003cBeerStyle.STOUT: 1\u003e\nprint(BeerStyle[\"LAGER\"])  # \u003cBeerStyle.LAGER: 0\u003e\n\n# The enum value has easy access to their value and name\nprint(BeerStyle.LAGER.value)  # 0\nprint(BeerStyle.LAGER.name)  # \"LAGER\"\n```\n\nFor more information about Python 3 enums\n(which our `Enum` inherits, `IntEnum` to be specific)\ncheckout the [docs](https://docs.python.org/3/library/enum.html).\n\n\n### Setting the default value\n\nYou can also set default value on your enum class using `__default__`\nattribute\n\n```python\nfrom django.db import models\nfrom django_enumfield import enum\n\n\nclass BeerStyle(enum.Enum):\n    LAGER = 0\n    STOUT = 1\n    WEISSBIER = 2\n\n    __default__ = LAGER\n\n\nclass BeerStyleNoDefault(enum.Enum):\n    LAGER = 0\n\n\nclass Beer(models.Model):\n    style_default_lager = enum.EnumField(BeerStyle)\n    style_default_stout = enum.EnumField(BeerStyle, default=BeerStyle.STOUT)\n    style_default_null = enum.EnumField(BeerStyleNoDefault, null=True, blank=True)\n\n\n# When you set __default__ attribute, you can access default value via\n# `.default()` method of your enum class\nassert BeerStyle.default() == BeerStyle.LAGER\n\nbeer = Beer.objects.create()\nassert beer.style_default_larger == BeerStyle.LAGER\nassert beer.style_default_stout == BeerStyle.STOUT\nassert beer.style_default_null is None\n```\n\n### Labels\n\nYou can use your own labels for `Enum` items\n\n```python\nfrom django.utils.translation import gettext_lazy\nfrom django_enumfield import enum\n\n\nclass Animals(enum.Enum):\n    CAT = 1\n    DOG = 2\n    SHARK = 3\n\n    __labels__ = {\n        CAT: gettext_lazy(\"Cat\"),\n        DOG: gettext_lazy(\"Dog\"),\n    }\n\n\nprint(Animals.CAT.label)  # \"Cat\"\nprint(Animals.SHARK.label)  # \"SHARK\"\n\n# There's also classmethods for getting the label\nprint(Animals.get_label(2))  # \"Dog\"\nprint(Animals.get_label(\"DOG\"))  # \"Dog\"\n```\n\n### Validate transitions\n\nThe `Enum`-class provides the possibility to use transition validation.\n\n```python\nfrom django.db import models\nfrom django_enumfield import enum\nfrom django_enumfield.exceptions import InvalidStatusOperationError\n\n\nclass PersonStatus(enum.Enum):\n    ALIVE = 1\n    DEAD = 2\n    REANIMATED = 3\n\n    __transitions__ = {\n        DEAD: (ALIVE,),  # Can go from ALIVE to DEAD\n        REANIMATED: (DEAD,)  # Can go from DEAD to REANIMATED\n    }\n\n\nclass Person(models.Model):\n    status = enum.EnumField(PersonStatus)\n\n# These transitions state that a PersonStatus can only go to DEAD from ALIVE and to REANIMATED from DEAD.\nperson = Person.objects.create(status=PersonStatus.ALIVE)\ntry:\n    person.status = PersonStatus.REANIMATED\nexcept InvalidStatusOperationError:\n    print(\"Person status can not go from ALIVE to REANIMATED\")\nelse:\n    # All good\n    person.save()\n```\n\n### In forms\n\nThe `Enum`-class can also be used without the `EnumField`. This is very useful in Django form `ChoiceField`s.\n\n```python\nfrom django import forms\nfrom django_enumfield import enum\nfrom django_enumfield.forms.fields import EnumChoiceField\n\n\nclass GenderEnum(enum.Enum):\n    MALE = 1\n    FEMALE = 2\n\n    __labels__ = {\n        MALE: \"Male\",\n        FEMALE: \"Female\",\n    }\n\n\nclass PersonForm(forms.Form):\n    gender = EnumChoiceField(GenderEnum)\n```\n\nRendering `PersonForm` in a template will generate a select-box with \"Male\" and \"Female\" as option labels for the gender field.\n\n\nLocal Development Environment\n-----------------------------\n\nMake sure black and isort is installed in your env with `pip install -e .[dev]`.\n\nBefore committing run `make format` to apply black and isort to all files.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F5monkeys%2Fdjango-enumfield","html_url":"https://awesome.ecosyste.ms/projects/github.com%2F5monkeys%2Fdjango-enumfield","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F5monkeys%2Fdjango-enumfield/lists"}