| Name | django-choicefield JSON |
| Version |
0.2.3
JSON |
| download |
| home_page | |
| Summary | ChoiceField for Django models |
| upload_time | 2024-01-05 10:12:44 |
| maintainer | |
| docs_url | None |
| author | |
| requires_python | >=3.9 |
| license | |
| keywords |
choicefield
choices
django
field
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
<h1 align=center>Django ChoiceField</h1>
<p align=left>
<a href=https://github.com/flaeppe/django-choicefield/actions?query=workflow%3ACI+branch%3Amain><img src=https://github.com/flaeppe/django-choicefield/workflows/CI/badge.svg alt="CI Build Status"></a>
<a href="https://codecov.io/gh/flaeppe/django-choicefield" > <img src="https://codecov.io/gh/flaeppe/django-choicefield/branch/main/graph/badge.svg?token=SV7YKU958R"/> </a>
<a href=https://pypi.org/project/django-choicefield/><img src=https://img.shields.io/pypi/v/django-choicefield.svg?color=informational&label=PyPI alt="PyPI Package"></a>
<a href=https://pypi.org/project/django-choicefield/><img src=https://img.shields.io/pypi/pyversions/django-choicefield.svg?color=informational&label=Python alt="Python versions"></a>
</p>
### Motivation
Have you also felt annoyed by having to convert
[Django's enumeration types](https://docs.djangoproject.com/en/dev/ref/models/fields/#enumeration-types)
_back_ to its type? Using tricks seen below to cast it.
```python
class Suit(models.IntegerChoices):
DIAMOND = 1
SPADE = 2
HEART = 3
CLUB = 4
class Card(models.Model):
suit_kind = models.IntegerField(choices=Suit.choices, db_column="suit")
@property
def suit(self) -> Suit:
return Suit(self.suit_kind)
```
This is what `django-choicefield` helps out with. While it additionally supports using
Python's native [enum.Enum](https://docs.python.org/3/library/enum.html) to express
column values.
### Features
#### Using Django's enumeration types
```python
import choicefield
from django.db import models
class Suit(models.IntegerChoices):
DIAMOND = 1
SPADE = 2
HEART = 3
CLUB = 4
class Card(models.Model):
suit = choicefield.ChoiceField(Suit)
instance = Card.objects.create(suit=Suit.CLUB)
assert instance.suit is Suit.CLUB
```
There's also support for Django's `models.TextChoices`.
#### Using Python's native enumeration
```python
import choicefield
from enum import Enum
from django.db import models
class Suit(int, Enum):
DIAMOND = 1
SPADE = 2
HEART = 3
CLUB = 4
class Card(models.Model):
suit = choicefield.ChoiceField(Suit)
instance = Card.objects.create(suit=Suit.DIAMOND)
assert instance.suit is Suit.DIAMOND
```
#### Passing enum values
It's also possible to pass the _value_ of an enum, which will be converted to its
corresponding enum instance.
```python
instance = Card(suit=2)
assert instance.suit is Suit.SPADE
instance.save()
assert instance.suit is Suit.SPADE
instance = Card.objects.get(suit=2)
assert instance.suit is Suit.SPADE
```
### Getting stored database values
If you want to access the stored database values, without conversion to your enum type,
you can use the registered `__raw` transformer.
```python
Card.objects.values("suit__raw")
# <QuerySet [{'suit__raw': 2}]>
```
#### Getting unrecognized values from database
In case of e.g. a migration where an enum has changed by, say, removing a value. The
database could have values not recognized by the registered enum. Thus it could be
necessary to retrieve values _without_ casting them to an enum instance, as it'd raise
an error.
It can be done using the `__raw` transformer while also sidestepping enum validation in
filter values by using
[`Value` expressions](https://docs.djangoproject.com/en/dev/ref/models/expressions/#value-expressions)
```python
Card.objects.filter(suit=Value(1337)).values_list("suit__raw", flat=True)
# <QuerySet [(1337,)]>
```
### Installation
Using `pip`
```console
$ pip install django-choicefield
```
### Development
#### Running tests
Running the whole test matrix
```console
$ tox
```
Setting up a development environment
```console
$ tox -e dev
```
Running the test suite for one environment (non editable)
e.g. `Django==4.0.x` and `Python3.11`
```console
$ tox -e django40-py311
```
#### Start a local example project
There are a couple of shortcut commands available using
[Taskfile](https://taskfile.dev/), for your convenience.
e.g.
```console
$ task manage -- createsuperuser
$ task runserver
```
After [installing Taskfile](https://taskfile.dev/installation/) you can run
`task --list-all` to find all available commands.
### Compatibility
`django-choicefield` is tested according to the table below
| Django version | Python version |
| -------------- | -------------- |
| 5.0.x | ^3.10 |
| 4.2.x | ^3.9 |
| 4.1.x | ^3.9 |
| 4.0.x | ^3.9 |
| 3.2.x | ^3.9 |
Raw data
{
"_id": null,
"home_page": "",
"name": "django-choicefield",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": "",
"keywords": "choicefield,choices,django,field",
"author": "",
"author_email": "Petter Friberg <petter_friberg@hotmail.com>",
"download_url": "https://files.pythonhosted.org/packages/c5/e6/ffbe615067396790c1bf4de78ca7651eb6b8ddb542312928821a03c0c988/django_choicefield-0.2.3.tar.gz",
"platform": null,
"description": "<h1 align=center>Django ChoiceField</h1>\n\n<p align=left>\n <a href=https://github.com/flaeppe/django-choicefield/actions?query=workflow%3ACI+branch%3Amain><img src=https://github.com/flaeppe/django-choicefield/workflows/CI/badge.svg alt=\"CI Build Status\"></a>\n <a href=\"https://codecov.io/gh/flaeppe/django-choicefield\" > <img src=\"https://codecov.io/gh/flaeppe/django-choicefield/branch/main/graph/badge.svg?token=SV7YKU958R\"/> </a>\n <a href=https://pypi.org/project/django-choicefield/><img src=https://img.shields.io/pypi/v/django-choicefield.svg?color=informational&label=PyPI alt=\"PyPI Package\"></a>\n <a href=https://pypi.org/project/django-choicefield/><img src=https://img.shields.io/pypi/pyversions/django-choicefield.svg?color=informational&label=Python alt=\"Python versions\"></a>\n</p>\n\n### Motivation\n\nHave you also felt annoyed by having to convert\n[Django's enumeration types](https://docs.djangoproject.com/en/dev/ref/models/fields/#enumeration-types)\n_back_ to its type? Using tricks seen below to cast it.\n\n```python\nclass Suit(models.IntegerChoices):\n DIAMOND = 1\n SPADE = 2\n HEART = 3\n CLUB = 4\n\n\nclass Card(models.Model):\n suit_kind = models.IntegerField(choices=Suit.choices, db_column=\"suit\")\n\n @property\n def suit(self) -> Suit:\n return Suit(self.suit_kind)\n```\n\nThis is what `django-choicefield` helps out with. While it additionally supports using\nPython's native [enum.Enum](https://docs.python.org/3/library/enum.html) to express\ncolumn values.\n\n### Features\n\n#### Using Django's enumeration types\n\n```python\nimport choicefield\nfrom django.db import models\n\n\nclass Suit(models.IntegerChoices):\n DIAMOND = 1\n SPADE = 2\n HEART = 3\n CLUB = 4\n\n\nclass Card(models.Model):\n suit = choicefield.ChoiceField(Suit)\n\n\ninstance = Card.objects.create(suit=Suit.CLUB)\nassert instance.suit is Suit.CLUB\n```\n\nThere's also support for Django's `models.TextChoices`.\n\n#### Using Python's native enumeration\n\n```python\nimport choicefield\nfrom enum import Enum\nfrom django.db import models\n\n\nclass Suit(int, Enum):\n DIAMOND = 1\n SPADE = 2\n HEART = 3\n CLUB = 4\n\n\nclass Card(models.Model):\n suit = choicefield.ChoiceField(Suit)\n\n\ninstance = Card.objects.create(suit=Suit.DIAMOND)\nassert instance.suit is Suit.DIAMOND\n```\n\n#### Passing enum values\n\nIt's also possible to pass the _value_ of an enum, which will be converted to its\ncorresponding enum instance.\n\n```python\ninstance = Card(suit=2)\nassert instance.suit is Suit.SPADE\ninstance.save()\nassert instance.suit is Suit.SPADE\ninstance = Card.objects.get(suit=2)\nassert instance.suit is Suit.SPADE\n```\n\n### Getting stored database values\n\nIf you want to access the stored database values, without conversion to your enum type,\nyou can use the registered `__raw` transformer.\n\n```python\nCard.objects.values(\"suit__raw\")\n# <QuerySet [{'suit__raw': 2}]>\n```\n\n#### Getting unrecognized values from database\n\nIn case of e.g. a migration where an enum has changed by, say, removing a value. The\ndatabase could have values not recognized by the registered enum. Thus it could be\nnecessary to retrieve values _without_ casting them to an enum instance, as it'd raise\nan error.\n\nIt can be done using the `__raw` transformer while also sidestepping enum validation in\nfilter values by using\n[`Value` expressions](https://docs.djangoproject.com/en/dev/ref/models/expressions/#value-expressions)\n\n```python\nCard.objects.filter(suit=Value(1337)).values_list(\"suit__raw\", flat=True)\n# <QuerySet [(1337,)]>\n```\n\n### Installation\n\nUsing `pip`\n\n```console\n$ pip install django-choicefield\n```\n\n### Development\n\n#### Running tests\n\nRunning the whole test matrix\n\n```console\n$ tox\n```\n\nSetting up a development environment\n\n```console\n$ tox -e dev\n```\n\nRunning the test suite for one environment (non editable)\n\ne.g. `Django==4.0.x` and `Python3.11`\n\n```console\n$ tox -e django40-py311\n```\n\n#### Start a local example project\n\nThere are a couple of shortcut commands available using\n[Taskfile](https://taskfile.dev/), for your convenience.\n\ne.g.\n\n```console\n$ task manage -- createsuperuser\n$ task runserver\n```\n\nAfter [installing Taskfile](https://taskfile.dev/installation/) you can run\n`task --list-all` to find all available commands.\n\n### Compatibility\n\n`django-choicefield` is tested according to the table below\n\n| Django version | Python version |\n| -------------- | -------------- |\n| 5.0.x | ^3.10 |\n| 4.2.x | ^3.9 |\n| 4.1.x | ^3.9 |\n| 4.0.x | ^3.9 |\n| 3.2.x | ^3.9 |\n",
"bugtrack_url": null,
"license": "",
"summary": "ChoiceField for Django models",
"version": "0.2.3",
"project_urls": {
"Homepage": "https://github.com/flaeppe/django-choicefield",
"Source": "https://github.com/flaeppe/django-choicefield",
"Tracker": "https://github.com/flaeppe/django-choicefield/issues"
},
"split_keywords": [
"choicefield",
"choices",
"django",
"field"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "edcc830cadc12b9d9fd941ef41bcb4e93859533d4ef0e0b89130da670865c061",
"md5": "bcf84cc050e0d23853e2cab7a8d4f46a",
"sha256": "5b7eeafdc9480819fa0c2cfabae58e395026712b32ebdf01f8a2db578bc3ba01"
},
"downloads": -1,
"filename": "django_choicefield-0.2.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "bcf84cc050e0d23853e2cab7a8d4f46a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 6790,
"upload_time": "2024-01-05T10:12:43",
"upload_time_iso_8601": "2024-01-05T10:12:43.164265Z",
"url": "https://files.pythonhosted.org/packages/ed/cc/830cadc12b9d9fd941ef41bcb4e93859533d4ef0e0b89130da670865c061/django_choicefield-0.2.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "c5e6ffbe615067396790c1bf4de78ca7651eb6b8ddb542312928821a03c0c988",
"md5": "76ee8ef5d7f528f8b8e606544373fec6",
"sha256": "a5f570065c8f5ff50bdac767744f5bd8bcdc156f184df5ef3e062da304aa7eda"
},
"downloads": -1,
"filename": "django_choicefield-0.2.3.tar.gz",
"has_sig": false,
"md5_digest": "76ee8ef5d7f528f8b8e606544373fec6",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 16380,
"upload_time": "2024-01-05T10:12:44",
"upload_time_iso_8601": "2024-01-05T10:12:44.318206Z",
"url": "https://files.pythonhosted.org/packages/c5/e6/ffbe615067396790c1bf4de78ca7651eb6b8ddb542312928821a03c0c988/django_choicefield-0.2.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-01-05 10:12:44",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "flaeppe",
"github_project": "django-choicefield",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "django-choicefield"
}
