Metadata-Version: 2.1
Name: django-richenum
Version: 5.1.0
Summary: Django Enum library for python.
Home-page: https://github.com/hearsaycorp/django-richenum
License: MIT
Keywords: python,django,enum,richenum
Author: Hearsay Social
Author-email: opensource@hearsaysocial.com
Requires-Python: >=3.8,<4.0
Classifier: Development Status :: 5 - Production/Stable
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: Implementation :: CPython
Requires-Dist: Django (>=3.2,<4.3)
Requires-Dist: richenum
Project-URL: Repository, https://github.com/hearsaycorp/django-richenum
Description-Content-Type: text/markdown

# django-richenum

[![Latest PyPI Version](https://img.shields.io/pypi/v/django-richenum.svg)](https://pypi.python.org/pypi/django-richenum/)
[![Python versions](https://img.shields.io/pypi/pyversions/django-richenum.svg)](https://pypi.org/project/django-richenum/)
[![PyPI Downloads](https://img.shields.io/pypi/dm/django-richenum.svg)](https://pypi.org/project/django-richenum/)

## About

A Django extension of richenum for Python. If you're unfamiliar with richenums, please read up on them (see [Related Packages](#related-packages)) before using django-richenum.

### Model Fields

`IndexEnumField`  
Store ints in DB, but expose OrderedRichEnumValues in Python.

`CanonicalNameEnumField`  
Store varchar in DB, but expose RichEnumValues in Python.  
We recommend that you use `IndexEnumField` for storage and query efficiency.

`LaxIndexEnumField`  
Like `IndexEnumField`, but also allows casting to and from canonical names.  
Mainly used to help migrate existing code that uses strings as database values.

### Form Fields

`CanonicalEnumField`  
Uses the RichEnum/OrderedRichEnum `canonical_name` as form field values.

`IndexEnumField`  
Uses the OrderedRichEnum `index` as form field values.

### Django Admin

`RichEnumFieldListFilter`  
Enables filtering by RichEnum model fields in the Django admin UI.

## Links

- [GitHub: django-richenum](https://github.com/hearsaycorp/django-richenum)
- [PyPI: django-richenum](https://pypi.python.org/pypi/django-richenum/)

## Installation

```bash
pip install django-richenum
```

## Example Usage

### IndexEnumField

```python
>>> from richenum import OrderedRichEnum, OrderedRichEnumValue
>>> class MyOrderedRichEnum(OrderedRichEnum):
...    FOO = OrderedRichEnumValue(index=1, canonical_name="foo", display_name="Foo")
...    BAR = OrderedRichEnumValue(index=2, canonical_name="bar", display_name="Bar")
...
>>> from django.db import models
>>> from django_richenum.models import IndexEnumField
>>> class MyModel(models.Model):
...    my_enum = IndexEnumField(MyOrderedRichEnum, default=MyOrderedRichEnum.FOO)
...
>>> m = MyModel.objects.create(my_enum=MyOrderedRichEnum.BAR)
>>> m.save()
>>> m.my_enum
OrderedRichEnumValue - idx: 2  canonical_name: 'bar'  display_name: 'Bar'
>>> MyModel.objects.filter(my_enum=MyOrderedRichEnum.BAR)
```

### CanonicalNameEnumField

```python
>>> from richenum import RichEnum, RichEnumValue
>>> class MyRichEnum(RichEnum):
...    FOO = RichEnumValue(canonical_name="foo", display_name="Foo")
...    BAR = RichEnumValue(canonical_name="bar", display_name="Bar")
...
>>> from django.db import models
>>> from django_richenum.models import CanonicalNameEnumField
>>> class MyModel(models.Model):
...    my_enum = CanonicalNameEnumField(MyRichEnum, default=MyRichEnum.FOO)
...
>>> m = MyModel.objects.create(my_enum=MyRichEnum.BAR)
>>> m.save()
>>> m.my_enum
RichEnumValue - canonical_name: 'bar'  display_name: 'Bar'
>>> MyModel.objects.filter(my_enum=MyRichEnum.BAR)
```

### RichEnumFieldListFilter

```python
>>> from django_richenum.admin import register_admin_filters
>>> register_admin_filters()
```

## Related Packages

`richenum`  
Package implementing RichEnum and OrderedRichEnum that django-richenum depends on.

- [GitHub: richenum](https://github.com/hearsaycorp/richenum)
- [PyPI: richenum](https://pypi.python.org/pypi/richenum/)

## Notes

If you're using Django 1.7+, you'll need to use the `@deconstructible` decorator for your `RichEnumValue` and `OrderedRichEnumValue` classes so Django's migration framework knows how to serialize your `RichEnumValue` and `OrderedRichEnumValue`.

```python
>>> from django.utils.deconstruct import deconstructible
>>> from richenum import RichEnumValue, OrderedRichEnumValue
>>> @deconstructible
... class CustomRichEnumValue(RichEnumValue):
...     pass
...
>>> @deconstructible
... class CustomOrderedRichEnumValue(OrderedRichEnumValue):
...     pass
...
```

## Contributing

1. Fork the repo from [GitHub](https://github.com/hearsaycorp/django-richenum).
2. Make your changes.
3. Add unittests for your changes.
4. Run `make lint` and `make test`.
5. Add yourself to `AUTHORS.md` (in alphabetical order).
6. Send a pull request from your fork to the main repo.

# Changelog

## 5.1.0 (2023-3-4)
- Migrate to poetry

## 4.1.0 (2023-12-12)

- Support for Django 4.2
- Support for Python 3.11
- Remove support for Django 2.2, 3.0, 3.1
- Remove support for Python 3.7
- Require MySQL 8 and Postgres 12

## 3.7.0 (2019-09-05)

- Support for Django 2.3

## 3.6.0 (2019-07-09)

- Support for Django 2.2
- Support for Python 3.7
- Remove support for Django 2.0

## 3.5.0 (2018-09-10)

- Fix [deprecation of context param for Field.from_db_value](https://code.djangoproject.com/ticket/28370)
- Support for Django 2.1
- Switch tests suite to use pytest
- Remove pylint-django plugin, no longer needed

## 3.4.0 (2018-02-10)

- Drop support for old Django versions

## 3.3.0 (2018-01-21)

- removed Python 3.4
- add support for Python 3.6
- add support for Django 2.0
- Properly mark raw strings (used as regex)

## 3.2.0 (2016-08-22)

- Python 3.4 & 3.5 support

## 3.1.0 (2015-08-02)

- Django 1.10 support

## 3.0.1 (2015-07-13)

- Prepare for python 3 support

## 2.4.1 (2015-05-04)

- replace mysql client library (for tests)
- stop using lambdas

## 2.3.0 (2015-05-04)

- Support Django 1.8

## 2.2.0 (2015-03-11)

- Support ModelForms for non-SQLite DB backends

## 2.1.0 (2014-11-01)

- Support migration in Django 1.7

## 2.0.0 (2014-09-04)

- Support Django 1.7, drop support for Python 2.6.

## 1.2.2 (2014-08-02)

- Support Django 1.3

## 1.2.1 (2014-06-02)

- Remove uses of BaseException.message.

## 1.2.0 (2013-12-03)

- Add enum-aware versions of TypedMultipleChoiceField.

## 1.1.0 (2013-12-03)

- Fix form fields to support Django 1.6 (while maintaining compatibility with 1.4 and 1.5).

## 1.0.2 (2013-11-05)

- Make EnumField.run_validators a no-op. This stops some warnings from type comparison, and it doesn't seem useful in an EnumField context.

## 1.0.1 (2013-09-10)

- Support South.

## 1.0.0 (2013-08-16)

- Initial public release.

