Metadata-Version: 2.0
Name: django-echoices
Version: 1.0.0
Summary: Choices for Django model fields as enumeration
Home-page: https://github.com/mbourqui/django-echoices
Author: Marc Bourqui
Author-email: https://github.com/mbourqui
License: GNU GPLv3
Keywords: django choices models enum
Platform: UNKNOWN
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Web Environment
Classifier: Framework :: Django
Classifier: Framework :: Django :: 1.8
Classifier: Framework :: Django :: 1.9
Classifier: Framework :: Django :: 1.10
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
Classifier: Topic :: Utilities
Requires-Dist: Django (>=1.8.18)

|Python| |Django| |License| |PyPI| |Build Status| |Coverage Status|

Django-EChoices, choices for Django model fields as enumeration
===============================================================

Features
--------

Specialized enum types
~~~~~~~~~~~~~~~~~~~~~~

-  ``enums.EChoice`` is the base enum type. Each enum element is a tuple
   ``(value, label)``, where [t]he first element in each tuple is the
   actual value to be set on the model, and the second element is the
   human-readable name 
   \ `doc <https://docs.djangoproject.com/en/1.11/ref/models/fields/#choices>`__\ .
   Values **must** be unique. Can be derived for further customization.
-  ``enums.EOrderedChoice`` supports ordering of elements.
   ``EOrderedChoice.choices()`` takes an extra optional argument,
   ``order``, which supports three values: 'sorted', 'reverse' or
   'natural' (default). If ``sorted``, the choices are ordered according
   to their value. If ``reverse``, the choices are ordered according to
   their value as if each comparison were reversed. If ``natural``, the
   order is the one used when instantiating the enumeration.
-  ``enums.EAutoChoice``, generates auto-incremented numeric values.
   It's then used like

   ::

       class EStates(EAutoChoice):
           # format is: label -> str
           CREATED = 'Created'
           SUBMITTED = 'Submitted'

Specialized model fields
~~~~~~~~~~~~~~~~~~~~~~~~

-  ``fields.EChoiceCharField`` deals directly with the enum instances
   instead of their value. Internal representation is using CharField,
   thus only works for textual labels.
-  ``fields.EChoiceIntegerField``, same as ``EChoiceCharField`` but
   using IntegerField, thus only works for numeric labels. `**Not yet
   implemented** <#1>`__.
-  ``fields.MultipleEChoiceField``, similar to previous fields, but
   supports multiple values to be selected. `**Not yet
   implemented** <#3>`__.

Requirements
------------

-  Django >= 1.8.18

Installation
------------

1. Run ``pip install django-echoices``

Usage
-----

First, define your choices enumeration (in your ``models.py`` for
example):

::

    from enum import unique
    from echoices.enums import EChoice

    @unique
    class EStates(EChoice):
        # format is: (value -> char or str or int, label -> str)
        CREATED = ('c', 'Created')
        SUBMITTED = ('s', 'Submitted')

Then, either use a regular model field:

::

    from django.db import models

    class MyModel(models.Model):
        state = models.CharField(max_length=EStates.max_value_length(),
                                 choices=EStates.choices(),
                                 default=EStates.CREATED.value)

**Note**: If your value is an ``int``, you can use
``models.IntegerField`` instead.

or a specialized field:

::

    from django.db import models
    from echoices.fields import EChoiceCharField

    class MyModel(models.Model):
        # `max_length` is set automatically
        state = EChoiceCharField(EStates, default=EStates.CREATED)

Derivation
~~~~~~~~~~

::

    from echoices.enums import EChoice

    class EMyChoice(EChoice):
        """
        You can add your own fields to the `value` and `label` ones. To do so, you have to override the
        __init__() and your signature must look like: `self, value, label, *args` where you replace `*args`
        with your own positional arguments, as you would do when defining a custom Enum.
        Do *not* call the super().__init__(), as `value` and `label` are already set by `EChoice`.

        As when dealing with a derived Enum, you can also add your own methods.

        """

        MY_CHOICE = (1, 'First choice', 'my value')

        def __init__(self, value, label, my_arg):
            self.my_arg = my_arg
            # Note: super().__init__() shall *not* be called!

.. |Python| image:: https://img.shields.io/badge/Python-3.4,3.5,3.6-blue.svg?style=flat-square
   :target: /
.. |Django| image:: https://img.shields.io/badge/Django-1.8,1.9,1.10-blue.svg?style=flat-square
   :target: /
.. |License| image:: https://img.shields.io/badge/License-GPLv3-blue.svg?style=flat-square
   :target: /LICENSE
.. |PyPI| image:: https://img.shields.io/pypi/v/django_echoices.svg?style=flat-square
   :target: https://pypi.python.org/pypi/django-echoices
.. |Build Status| image:: https://travis-ci.org/mbourqui/django-echoices.svg?branch=master
   :target: https://travis-ci.org/mbourqui/django-echoices
.. |Coverage Status| image:: https://coveralls.io/repos/github/mbourqui/django-echoices/badge.svg?branch=master
   :target: https://coveralls.io/github/mbourqui/django-echoices?branch=master


