Metadata-Version: 2.1
Name: django_enum_choices
Version: 0.0.8
Summary: A custom Django field able to use subclasses of Python's internal `Enum` class as choices
Home-page: https://github.com/HackSoftware/django-enum-choices
Author: Vasil Slavov
Author-email: vasil.slavov@hacksoft.io
License: MIT
Description: 
        # django-enum-choices
        
        **Library is still work in progress & unstable. When officially launched, we'll announce it.**
        
        A custom Django choice field to use with [Python enums.](https://docs.python.org/3/library/enum.html)
        
        ## Installation
        
        ```bash
        pip install django_enum_choices
        ```
        
        ## Basic Usage
        
        ```python
        from django import models
        
        from django_enum_choices.fields import EnumChoiceField
        
        
        from enum import Enum
        
        class FooBarEnumeration(Enum):
            FOO = 'foo'
            BAR = 'bar'
        
        
        class MyModel(models.Model):
            foo_bar_field = EnumChoiceField(FooBarEnumeration)
        ```
        
        **Model creation**
        
        ```python
        instance = MyModel.objects.create(foo_bar_field=FooBarEnumeration.BAR)
        ```
        
        **Changing enum values**
        
        ```python
        instance.foo_bar_field = FooBarEnumeration.FOO
        instance.save()
        ```
        
        **Filtering**
        
        ```python
        MyModel.objects.filter(foo_bar_field=FooBarEnumeration.FOO)
        ```
        
        ## Usage with Django Rest Framework
        
        ```python
        from rest_framework import serializers
        
        from django_enum_choices.serializers import EnumChoiceField
        
        class MyModelSerializer(serializers.ModelSerializer):
            foo_bar_field = EnumChoiceField(FooBarEnumeration)
        
            class Meta:
                model = MyModel
                fields = ('foo_bar_field', )
        ```
        
        In `python manage.py shell`:
        
        ```
        In [1]: instance = MyModel.objects.create(foo_bar_field=FooBarEnumeration.BAR)
        In [2]: MyModelSerializer(instance).data
        Out[2]: {'foo_bar_field': 'bar'}
        ```
        
        ### Caveat
        
        If you don't explicitly specify the `foo_bar_field = EnumChoiceField(FooBarEnumeration)`, then you need to include the `EnumChoiceModelSerializerMixin`:
        
        ```python
        from rest_framework import serializers
        
        from django_enum_choices.serializers import EnumChoiceModelSerializerMixin
        
        class MyModelSerializer(EnumChoiceModelSerializerMixin, serializers.ModelSerializer):
            class Meta:
                model = MyModel
                fields = ('foo_bar_field', )
        ```
        
        By default `ModelSerializer.build_standard_field` coerces any field that has a model field with choices to `ChoiceField` wich returns the value directly.
        
        Since enum values resemble `EnumClass.ENUM_INSTANCE` they won't be able to be encoded by the `JSONEncoder` when being passed to a `Response`.
        
        That's why we need the mixin.
        
        ## Implementation details
        
        * `EnumChoiceField` is a subclass of `CharField`.
        * Only subclasses of `Enum` are valid arguments for `EnumChoiceField`.
        * `choices` are generated from the values of the enumeration, like `(str(value), str(value))`, meaning you can put any valid Python object there.
        * `max_length`, if passed, is ignored. `max_length` is automatically calculated from the longest choice.
        
        
        For example, lets have the following case:
        
        ```python
        class Value:
            def __init__(self, value):
                self.value = value
        
            def __str__(self):
                return str(self.value)
        
        
        class Enumeration(Enum):
            A = Value(1)
            B = Value('foo')
        
        
        class SomeModel(models.Model):
            enumeration = EnumChoiceField(Enumeration)
        ```
        
        We'll have the following:
        
        * `SomeModel.enumeration.choices == (('1', '1'), ('foo', 'foo'))`
        * `SomeModel.enumeration.max_length == 3`
        
        ## Development
        
        ```bash
        git clone https://github.com/HackSoftware/django-enum-choices.git
        pip install -e some-directory/django_enum_choices
        ```
        
Platform: UNKNOWN
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Framework :: Django
Classifier: Framework :: Django :: 1.10
Classifier: Framework :: Django :: 1.11
Classifier: Framework :: Django :: 2.1
Classifier: Framework :: Django :: 2.2
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.5.0
Description-Content-Type: text/markdown
