# dj_enum
[](https://github.com/themrinalsinha/dj_enum/actions/workflows/checks_and_tests.yaml)
It includes a `StateChoiceField` that comes with reusable `TextChoices` and validation for state changes. This feature enhances flexibility and data integrity.
## Requirements
- Python 3.6+
- Django 2.2+
## Installation
To set up `dj_enum`, you can easily install it with pip.
```shell
$ pip install dj_enum
```
## Example
Consider a scenario where we have a model called `Order` that includes the storage of the order's payment status. This payment status can fall into one of the following in `PaymentStatus`.
It also defines the state transitions that are allowed for each state. For example, a payment status of `IN_PROGRESS` can only be changed to `FAILED` or `COMPLETED`. This is done by defining the `__states__` attribute in the `PaymentStatus` class which extends `StateEnum`.
```python
class PaymentStatus(StateEnum):
NOT_STARTED = "not_started", "Not Started"
IN_PROGRESS = "in_progress", "In Progress"
COMPLETED = "completed", "Completed"
FAILED = "failed", "Failed"
CANCELLED = "cancelled", "Cancelled"
NOT_REQUIRED = "not_required", "Not Required"
__states__ = {
NOT_STARTED: (),
IN_PROGRESS: (NOT_STARTED, FAILED),
FAILED: (IN_PROGRESS,),
COMPLETED: (IN_PROGRESS, NOT_REQUIRED),
NOT_REQUIRED: (IN_PROGRESS,),
CANCELLED: (NOT_STARTED, NOT_REQUIRED, FAILED, COMPLETED),
}
```
Model `Order` can be defined as follows. The `payment_status` field is defined as a `StateChoiceField` with the `PaymentStatus` enum class.
```python
class Orders(models.Model):
product_name = models.CharField(max_length=100)
payment_status = StateChoiceField(
PaymentStatus, default=PaymentStatus.NOT_STARTED, max_length=20
)
created_at = models.DateTimeField(auto_now_add=True)
updated_at = models.DateTimeField(auto_now=True)
```
**Usage**
```shell
>>> order = Order.objects.create(product_name="Product 1")
>>> order.payment_status
<PaymentStatus.NOT_STARTED: 'not_started'>
>>> order.payment_status = PaymentStatus.IN_PROGRESS
>>> order.save()
>>> order.payment_status
<PaymentStatus.IN_PROGRESS: 'in_progress'>
# Now, if we try to change the payment status to CANCELLED, it will raise a InvalidTransitionError error.
>>> order.payment_status = PaymentStatus.CANCELLED
dj_enum.exceptions.InvalidTransitionError: [in_progress -> cancelled is not a valid transition for PaymentStatus']
```
Raw data
{
"_id": null,
"home_page": "https://github.com/themrinalsinha/dj_enum",
"name": "dj-enum",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.6, <4",
"maintainer_email": "",
"keywords": "dj_enum",
"author": "Mrinal Sinha",
"author_email": "me@mrinal.xyz",
"download_url": "https://files.pythonhosted.org/packages/e4/20/4dcd1a120495449cebb1ba7c25f792ca5ef7e9af505c5b65e5c23b7b7b58/dj_enum-0.0.3.tar.gz",
"platform": null,
"description": "# dj_enum\n[](https://github.com/themrinalsinha/dj_enum/actions/workflows/checks_and_tests.yaml)\n\nIt includes a `StateChoiceField` that comes with reusable `TextChoices` and validation for state changes. This feature enhances flexibility and data integrity.\n\n## Requirements\n- Python 3.6+\n- Django 2.2+\n\n## Installation\nTo set up `dj_enum`, you can easily install it with pip.\n```shell\n$ pip install dj_enum\n```\n\n## Example\nConsider a scenario where we have a model called `Order` that includes the storage of the order's payment status. This payment status can fall into one of the following in `PaymentStatus`.\n\nIt also defines the state transitions that are allowed for each state. For example, a payment status of `IN_PROGRESS` can only be changed to `FAILED` or `COMPLETED`. This is done by defining the `__states__` attribute in the `PaymentStatus` class which extends `StateEnum`.\n```python\nclass PaymentStatus(StateEnum):\n NOT_STARTED = \"not_started\", \"Not Started\"\n IN_PROGRESS = \"in_progress\", \"In Progress\"\n COMPLETED = \"completed\", \"Completed\"\n FAILED = \"failed\", \"Failed\"\n CANCELLED = \"cancelled\", \"Cancelled\"\n NOT_REQUIRED = \"not_required\", \"Not Required\"\n\n __states__ = {\n NOT_STARTED: (),\n IN_PROGRESS: (NOT_STARTED, FAILED),\n FAILED: (IN_PROGRESS,),\n COMPLETED: (IN_PROGRESS, NOT_REQUIRED),\n NOT_REQUIRED: (IN_PROGRESS,),\n CANCELLED: (NOT_STARTED, NOT_REQUIRED, FAILED, COMPLETED),\n }\n```\nModel `Order` can be defined as follows. The `payment_status` field is defined as a `StateChoiceField` with the `PaymentStatus` enum class.\n```python\nclass Orders(models.Model):\n product_name = models.CharField(max_length=100)\n payment_status = StateChoiceField(\n PaymentStatus, default=PaymentStatus.NOT_STARTED, max_length=20\n )\n created_at = models.DateTimeField(auto_now_add=True)\n updated_at = models.DateTimeField(auto_now=True)\n```\n\n**Usage**\n```shell\n>>> order = Order.objects.create(product_name=\"Product 1\")\n>>> order.payment_status\n<PaymentStatus.NOT_STARTED: 'not_started'>\n\n>>> order.payment_status = PaymentStatus.IN_PROGRESS\n>>> order.save()\n\n>>> order.payment_status\n<PaymentStatus.IN_PROGRESS: 'in_progress'>\n\n# Now, if we try to change the payment status to CANCELLED, it will raise a InvalidTransitionError error.\n>>> order.payment_status = PaymentStatus.CANCELLED\n\ndj_enum.exceptions.InvalidTransitionError: [in_progress -> cancelled is not a valid transition for PaymentStatus']\n```\n",
"bugtrack_url": null,
"license": "",
"summary": "A Django enum field",
"version": "0.0.3",
"project_urls": {
"Homepage": "https://github.com/themrinalsinha/dj_enum"
},
"split_keywords": [
"dj_enum"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "db10da5033cbecab4dfb8959226c29ed9cb230440b8e02685f86b1a1cfcf85d3",
"md5": "5b2da7e1640dcb42f9e09a2643b69de6",
"sha256": "63b941286a336c0e2af7d06234299b44297482d707f2b7f96a2e30dbad60d139"
},
"downloads": -1,
"filename": "dj_enum-0.0.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "5b2da7e1640dcb42f9e09a2643b69de6",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6, <4",
"size": 7358,
"upload_time": "2023-11-04T19:43:57",
"upload_time_iso_8601": "2023-11-04T19:43:57.655496Z",
"url": "https://files.pythonhosted.org/packages/db/10/da5033cbecab4dfb8959226c29ed9cb230440b8e02685f86b1a1cfcf85d3/dj_enum-0.0.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "e4204dcd1a120495449cebb1ba7c25f792ca5ef7e9af505c5b65e5c23b7b7b58",
"md5": "4a51ed2b1b9f6465f18be093f311a10f",
"sha256": "c3887089ec15cba72f73a09d8b3f2642c66e92e88e650eb35377c36218180457"
},
"downloads": -1,
"filename": "dj_enum-0.0.3.tar.gz",
"has_sig": false,
"md5_digest": "4a51ed2b1b9f6465f18be093f311a10f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6, <4",
"size": 6915,
"upload_time": "2023-11-04T19:43:59",
"upload_time_iso_8601": "2023-11-04T19:43:59.652577Z",
"url": "https://files.pythonhosted.org/packages/e4/20/4dcd1a120495449cebb1ba7c25f792ca5ef7e9af505c5b65e5c23b7b7b58/dj_enum-0.0.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-11-04 19:43:59",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "themrinalsinha",
"github_project": "dj_enum",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "dj-enum"
}
JSON
