django-separatedvaluesfield 0.6.0
Custom field for Django to separate multiple values in database with a separator and retrieve them as list

django-separatedvaluesfield
===========================

.. image:: https://secure.travis-ci.org/thoas/django-separatedvaluesfield.png?branch=master
    :alt: Build Status
    :target: http://travis-ci.org/thoas/django-separatedvaluesfield

Alternative to CommaSeparatedIntegerField_ built-in field that supports
MultipleChoiceField_, custom separator and returns values as list.

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

Install package from PyPi_::

    pip install django-separatedvaluesfield

Or download the archive from GitHub_ and proceed to a manual installation::

    curl -L https://github.com/thoas/django-separatedvaluesfield/tarball/master | tar zx
    cd thoas-django-separatedvaluesfield
    python setup.py install

Add ``SeparatedValuesField`` to your Django model:

.. code:: python

    # models.py
    from django.db import models

    from separatedvaluesfield.models import SeparatedValuesField

    class Project(models.Model):
        name = models.CharField(max_length=150)
        languages = SeparatedValuesField(
            max_length=150,
            token=',',
            choices=(
                ('en', 'English'),
                ('fr', 'French')))

If your choices values are not strings, add the ``cast`` option with the type
you want to apply on values (defaults to ``django.utils.six.text_type``):

.. code:: python

    # models.py
    from django.db import models

    from separatedvaluesfield.models import SeparatedValuesField

    class Project(models.Model):
        name = models.CharField(max_length=150)
        languages = SeparatedValuesField(
            max_length=150,
            cast=int,
            token=',',
            choices=(
                (1, 'English'),
                (2, 'French')))

If you are running Django <= 1.6, synchronize your database using ``syncdb``::

    python manage.py syncdb

If you are running Django >= 1.7, synchronize your database using ``migrate``::

    python manage.py migrate

The ``SeparatedValuesField`` behaves like a ``CharField`` which separates values with
a token (default is ``,``).

This field is transformed as a MultipleChoiceField_ when you are
creating a ``forms.ModelForm`` with your model.

Usage
-----

.. code:: pycon

    >>> from myapp.models import Project
    >>> project = Project(name='Project with strings', languages=['fr', 'en'])
    >>> project.save() # save 'fr,en' in database for the column "languages"
    >>> project.pk
    1

    >>> project = Project.objects.get(pk=1)
    >>> project.languages
    ['fr', 'en']

    # If you added "cast" option to the field to cast to 'int'
    >>> project = Project(name='Project with integers', languages=[u'1', u'2'])
    >>> project.save() # save '1,2' in database for the column "languages"
    >>> project = Project.objects.get(pk=1)
    >>> project.languages
    [1, 2]

Contribute
----------

1. Fork the repository
2. Clone your fork
3. Create a dedicated branch (never ever work in ``master``)
4. Create your development environment with ``make dev``
5. Activate your environment with ``source .venv/bin/activate``
6. Make modifications
7. Write tests and execute them with ``make test``
8. Be sure all test pass with ``tox``
9. If all tests pass, submit a pull request

.. _CommaSeparatedIntegerField: https://docs.djangoproject.com/en/dev/ref/models/fields/#commaseparatedintegerfield
.. _PyPi: https://pypi.python.org/
.. _GitHub: https://github.com/thoas/django-separatedvaluesfield
.. _MultipleChoiceField: https://docs.djangoproject.com/en/dev/ref/forms/fields/#multiplechoicefield