django-select-multiple-field 1.0.0__py3-none-any.whl

django_select_multiple_field-1.0.0.dist-info/METADATA

@@ -0,0 +1,357 @@
+Metadata-Version: 2.4
+Name: django-select-multiple-field
+Version: 1.0.0
+Summary: Select multiple choices in a single Django model field
+Project-URL: Homepage, https://kelvinwong.ca/projects/django-select-multiple-field/
+Project-URL: Repository, https://github.com/kelvinwong-ca/django-select-multiple-field
+Author-email: Kelvin Wong <code@kelvinwong.ca>
+License: BSD
+License-File: LICENSE
+Keywords: Django,Django-Select-Multiple-Field,model-field,select,select multiple
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Web Environment
+Classifier: Framework :: Django
+Classifier: Framework :: Django :: 4.2
+Classifier: Framework :: Django :: 5.2
+Classifier: Framework :: Django :: 6
+Classifier: Framework :: Django :: 6.0
+Classifier: Framework :: Django :: 6.1
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+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 :: 3.14
+Classifier: Topic :: Internet :: WWW/HTTP
+Requires-Python: >=3.10
+Requires-Dist: django>=4.2
+Description-Content-Type: text/markdown
+
+# django-select-multiple-field
+
+Store multiple choices in a single Django model field without using a many-to-many relationship.
+
+![Rendered using the multiselect.js plugin for jQuery](https://github.com/kelvinwong-ca/django-select-multiple-field/raw/master/docs/images/select_multiple_cropped.jpg)
+
+Rendered using the multiselect.js plugin for jQuery. The plugin is available here: <https://github.com/lou/multi-select>
+
+
+## Denormalization Risk (Important)
+
+This field intentionally denormalizes data by storing multiple selected choices as comma-separated text in a single column.
+
+Use it when:
+
+* you want a simple schema,
+* you do not need relational queries (joins),
+* and you mainly read/write the selected values as a list in application code.
+
+If you need robust querying like “find all cookies with topping X,” a normalized many-to-many model is usually the better choice.
+
+For example, if cookies can have toppings such as `chocolate`, `dark_chocolate`, and `white_chocolate`, a normalized design would usually use a `Topping` model and a `Cookie` model related by a `ManyToManyField`. That gives you joins, indexing, and exact filtering.
+
+With this field, you filter against the stored text value instead.
+
+```python
+# Caution: substring search can return false positives.
+Cookie.objects.filter(toppings__icontains="chocolate")
+```
+
+That kind of lookup can produce false positives because one encoded choice can appear inside another. For example, `chocolate` is a substring of `dark_chocolate`, so a substring search can match both.
+
+If that risk is unacceptable for your application, use a many-to-many relation instead.
+
+
+## Installation
+
+Install from PyPI:
+
+```bash
+pip install django-select-multiple-field
+```
+
+
+## Quick Start
+
+### Model
+
+> You must provide either `max_length` or both `choices` and `max_choices`
+
+> Choices must be strings, not integers.
+
+Add the select field choices normally in your model:
+
+```python
+# models.py
+
+from django.db import models
+
+from select_multiple_field.models import SelectMultipleField
+
+class Pizza(models.Model):
+    ANCHOVIES = 'a'
+    BLACK_OLIVES = 'b'
+    PEPPERONI = 'p'
+    MOZZARELLA = 'm'
+    TOPPING_CHOICES = (
+        (ANCHOVIES, 'Anchovies'),
+        (BLACK_OLIVES, 'Black olives'),
+        (PEPPERONI, 'Pepperoni'),
+        (MOZZARELLA, 'Mozzarella'),
+    )
+    # choices & max_choices are used to auto calc. max_length
+    toppings = SelectMultipleField(
+        max_choices=4,
+        choices=TOPPING_CHOICES,
+    )
+
+    PLAIN = 'n'
+    CHEDDAR = 'c'
+    CRUST_CHOICES = (
+        (PLAIN, 'Plain Crust'),
+        (MOZZARELLA, 'Mozzarella Stuffed Crust'),
+        (CHEDDAR, 'Cheddar Stuffed Crust'),
+    )
+    crust = SelectMultipleField(
+        max_length=6,
+        choices=CRUST_CHOICES,
+    )
+```
+
+### Encoded Length (Choose One)
+
+Underneath this field is a CharField which takes a maximum length for the encoded string. You can choose to provide a `max_length` parameter or the field will calculate it from the `choices` and the `max_choices` parameters.
+
+* `max_length` is the maximum length of the **encoded** string of choices. You need to add the maximum allowed choices and the delimiter character (usually a comma) that separates the choices when they are encoded.
+* `max_choices` is the maximum choices that can be encoded per field.
+* `choices` can be a mapping, iterable, or callable.
+
+Example encoded-length calculation:
+
+* Choice keys: `a`, `bb`, `ccc`, `dddd`
+* `max_choices=2`
+* Longest 2 keys are `dddd` and `ccc`, so encoded value is `dddd,ccc`
+* Required `max_length` is `8`
+
+## Render the form
+
+Use a generic view or a `ModelForm` as usual. In your template, use a regular form tag:
+
+```html
+<!-- template_form.html -->
+<form action="" method="post">
+  {% csrf_token %}
+  {{ form.as_p }}
+  <input type="submit" value="Submit">
+</form>
+```
+
+This renders the following HTML:
+
+```html
+<!-- create.html -->
+<form action="" method="post">
+    <p>
+      <label for="id_toppings">Toppings:</label>
+      <select multiple="multiple" id="id_toppings" name="toppings" class="select-multiple-field">
+        <option value="a">Anchovies</option>
+        <option value="b">Black olives</option>
+        <option value="p">Pepperoni</option>
+        <option value="m">Mozzarella</option>
+      </select>
+    </p>
+    <input type="submit" value="Submit">
+</form>
+```
+
+## Null Handling
+
+`SelectMultipleField` supports `null=True`, but it behaves differently from Django's standard `CharField`:
+
+| `null` | Empty Selection in DB | `to_python(None)` | `from_db_value(None)` | `get_prep_value([])` |
+|--------|----------------------|-------------------|----------------------|----------------------|
+| `False` (default) | `""` (empty string) | `[]` | `[]` | `""` |
+| `True` | `NULL` | `[]` | `[]` | `None` |
+
+**Key semantics:**
+- `null=True` changes **only database storage**. Python API always returns `[]`, never `None`
+- `to_python(None)` always returns `[]` regardless of `null` setting
+- `from_db_value(None, ...)` always returns `[]` regardless of `null` setting
+- `get_prep_value(None)` returns `None` when `null=True`, else `""`
+- `get_prep_value([])` returns `None` when `null=True`, else `""`
+
+Use `null=True` only when your database conventions require `NULL` over empty string for empty selections. For form-level optional fields, use `blank=True` instead.
+
+## Validators
+
+`SelectMultipleField` replaces Django's built-in `MaxLengthValidator` with two custom validators:
+
+### `MaxChoicesValidator`
+- **Validates**: `len(value) ≤ max_choices`
+- **Error code**: `max_choices`
+- **Message**: `"Ensure this value has at most %(limit_value)d choice(s)..."`
+
+### `MaxLengthValidator`
+- **Validates**: `len(encode_list_to_csv(value)) ≤ max_length`
+- **Error code**: `max_length`
+- **Message**: `"Ensure this value has at most %(limit_value)d character(s)..."`
+
+Both validators run during model validation. If you provide `choices` and `max_choices` but omit `max_length`, the field auto-calculates `max_length` from the longest possible encoded CSV (longest `max_choices` keys joined by delimiters). If you explicitly set `max_length` smaller than this calculated maximum, a `RuntimeWarning` is emitted at field instantiation.
+
+## Validation Error Codes
+
+The field can raise the following validation errors:
+
+| Error Code | Message Template | Triggered When |
+|------------|------------------|----------------|
+| `invalid_type` | `"Types passed as value must be string, list, tuple or None, not '%(value)s'."` | `to_python` receives non-list/tuple/str/None |
+| `invalid_choice` | `"Select a valid choice. %(value)s is not one of the available choices."` | Value not in `choices` |
+| `blank` | `"This field cannot be blank."` | `blank=False` and empty value |
+| `null` | `"This field cannot be null."` | `null=False` and `None` value |
+| `max_choices` | `"Ensure this value has at most %(limit_value)d choice(s)..."` | `len(value) > max_choices` |
+| `max_length` | `"Ensure this value has at most %(limit_value)d character(s)..."` | `len(encoded) > max_length` |
+
+## Displaying Stored Choices
+
+To display your choices, decode the field contents. You can do this with a template tag:
+
+```python
+# templatetags/pizza_tags.py
+
+def decode_pie(ingredients):
+    """Decode pizza pie toppings."""
+    decoder = dict(Pizza.TOPPING_CHOICES)
+    decoded = [decoder[t] for t in ingredients]
+    decoded.sort()
+    return ', '.join(decoded)
+
+register.filter('decode_pie', decode_pie)
+```
+
+In your template, import the tag and use it:
+
+```django
+{# details.html #}
+{% load pizza_tags %}
+
+{{ pizza.toppings|decode_pie }}
+```
+
+## Encoding the Choices
+
+The selected choices are stored as comma-delimited text. For example, a pizza with the following toppings:
+
+* Pepperoni
+* Mozzarella
+
+would be stored as:
+
+```text
+p,m
+```
+
+You can decode that string to a Python list using functions in the codecs module:
+
+```python
+>>> from select_multiple_field.codecs import decode_csv_to_list
+>>> encoded = 'a,b,c'
+>>> decoded = decode_csv_to_list(encoded)
+>>> print(decoded)
+['a', 'b', 'c']
+>>> print(type(decoded))
+<class 'list'>
+```
+
+## Custom Delimiters
+
+The CSV delimiter is configurable via Django settings:
+
+```python
+# settings.py
+SELECTMULTIPLEFIELD_DELIMITER = "|"  # Default: ","
+```
+
+**Constraints:**
+- Must be a **single character**
+- Multi-character delimiters are not supported
+- Choice values **cannot contain the delimiter** (e.g., if delimiter is `,`, a choice like `"a,b"` breaks encoding)
+
+Both `encode_list_to_csv()` and `decode_csv_to_list()` in `select_multiple_field.codecs` respect this setting automatically. Changing the delimiter on an existing database requires a data migration to re-encode stored values.
+
+The encoding method may limit your ability to search for choices.
+
+## Sample Application
+
+This repository includes sample applications under `test_projects/`. You can run the Django 4.2 integration app like this:
+
+```bash
+$ cd /path/to/django-select-multiple-field
+$ cd test_projects/django42
+$ python manage.py migrate
+$ python manage.py runserver
+Development server is running at http://127.0.0.1:8000/
+Quit the server with CONTROL-C.
+```
+
+## Versions
+
+This code was tested with the following versions of Django and Python:
+
+* Django 4.2 LTS
+  * Python 3.10
+  * Python 3.11
+  * Python 3.12
+  * Python 3.13
+* Django 5.2 LTS
+  * Python 3.10
+  * Python 3.11
+  * Python 3.12
+  * Python 3.13
+  * Python 3.14
+* Django 6.0
+  * Python 3.12
+  * Python 3.13
+  * Python 3.14
+
+## Testing
+
+Django-select-multiple-field contains two test suites: one for the field itself and one for the Django integration apps.
+
+To run the unit tests use `hatch` interactively:
+
+```bash
+hatch run tests  # All tests {unit, integration}
+hatch run i  # Integration tests
+hatch run t  # Unit tests
+```
+
+The dependencies are managed manually in your environment.
+
+To run all the tests with differing Python versions and Django versions, use `tox`:
+
+```bash
+tox  # All tests for supported versions
+tox -e py312-dj42  # All tests using Python 3.12 & Django 4.2 LTS
+```
+
+## Bugs! Help!!
+
+If you find any bugs in this software, please report them via the GitHub issue tracker or send an email to code@kelvinwong.ca. Any serious security bugs should be reported via email only.
+
+Issue tracker: <https://github.com/kelvinwong-ca/django-select-multiple-field/issues>
+
+## Links
+
+* <https://pypi.org/project/django-select-multiple-field/>
+* <https://github.com/kelvinwong-ca/django-select-multiple-field>
+
+## Thank You
+
+Thank you for taking the time to evaluate this software. I appreciate receiving feedback on your experiences using it, and I welcome code contributions and development ideas.
+
+<http://www.kelvinwong.ca/coders>

django_select_multiple_field-1.0.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+select_multiple_field/__about__.py,sha256=J-j-u0itpEFT6irdmWmixQqYMadNl1X91TxUmoiLHMI,22
+select_multiple_field/__init__.py,sha256=x21WuUxILcXS4P-TdgpzfW_B3ztw6nN0iL0YiB4bANc,60
+select_multiple_field/codecs.py,sha256=MQsyohxEaBA-_w35TQKIDBvcdH3SbYEHpzdbyW2knJ4,750
+select_multiple_field/forms.py,sha256=dAcy-AquMAsDZDFFehQILFsenkzzO1_0uBsJ9LO26L0,4644
+select_multiple_field/models.py,sha256=HhVUeE4Ba_yZOJ2rJxmGlTdrll1mJCzMwKI9Ft2MAR4,13795
+select_multiple_field/validators.py,sha256=nP_p4H79jGkz40NacnNUZUTCB70yTVRGa5tZqEAlk6c,1523
+select_multiple_field/widgets.py,sha256=MbTrH6nrh5F3Ad1RXd81vX_fxrSsypmY8sipFDj-lWk,1568
+django_select_multiple_field-1.0.0.dist-info/METADATA,sha256=9LM_zB3JeJbxtUpFxoXFmzLTT-hkdhWcu5C_G7610n4,12157
+django_select_multiple_field-1.0.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+django_select_multiple_field-1.0.0.dist-info/licenses/LICENSE,sha256=Ry1KabPjR5_tesZfixp4PFIvt6Byia_XRHv11vPCzlg,2973
+django_select_multiple_field-1.0.0.dist-info/RECORD,,

django_select_multiple_field-1.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

django_select_multiple_field-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,57 @@
+Copyright (c) Kelvin Wong <code@kelvinwong.ca> and contributors.
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+    * Redistributions of source code must retain the above copyright
+      notice, this list of conditions and the following disclaimer.
+    * Redistributions in binary form must reproduce the above copyright
+      notice, this list of conditions and the following disclaimer in the
+      documentation and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL "KELVIN WONG" BE LIABLE FOR ANY
+DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+
+########
+
+
+Some code was derived from Django which was licensed under the following terms
+
+
+Copyright (c) Django Software Foundation and individual contributors.
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+    1. Redistributions of source code must retain the above copyright notice,
+       this list of conditions and the following disclaimer.
+    
+    2. Redistributions in binary form must reproduce the above copyright
+       notice, this list of conditions and the following disclaimer in the
+       documentation and/or other materials provided with the distribution.
+
+    3. Neither the name of Django nor the names of its contributors may be
+       used to endorse or promote products derived from this software without
+       specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

select_multiple_field/__about__.py

@@ -0,0 +1 @@
+__version__ = "1.0.0"

select_multiple_field/__init__.py

@@ -0,0 +1,3 @@
+from .__about__ import __version__
+
+DEFAULT_DELIMITER = ","

select_multiple_field/codecs.py

@@ -0,0 +1,29 @@
+from django.conf import settings
+
+from . import DEFAULT_DELIMITER
+
+delimiter = getattr(settings, "SELECTMULTIPLEFIELD_DELIMITER", DEFAULT_DELIMITER)
+if len(delimiter) != 1:
+    raise ValueError("SELECTMULTIPLEFIELD_DELIMITER must be exactly one character")
+_DELIMITER = delimiter
+
+
+def decode_csv_to_list(encoded):
+    """
+    Decodes a delimiter separated string to a Python list.
+
+    Preserves order and duplicates (no sorting, no deduplication).
+    """
+    if encoded == "":
+        return []
+
+    return encoded.split(_DELIMITER)
+
+
+def encode_list_to_csv(decoded):
+    """
+    Encodes a Python list to a delimiter separated string.
+
+    Preserves order and duplicates (no sorting, no deduplication).
+    """
+    return _DELIMITER.join(decoded)

select_multiple_field/forms.py

@@ -0,0 +1,140 @@
+import warnings
+
+from django.core import validators
+from django.forms import fields
+
+from .codecs import decode_csv_to_list, encode_list_to_csv
+from .widgets import SelectMultipleWidget
+
+DEFAULT_MAX_CHOICES_ATTR = "data-max-choices"
+
+
+class SelectMultipleFormField(fields.MultipleChoiceField):
+
+    widget = SelectMultipleWidget
+
+    def __init__(
+        self,
+        max_length=None,
+        size=4,
+        max_choices=None,
+        max_choices_attr=DEFAULT_MAX_CHOICES_ATTR,
+        *args,
+        **kwargs,
+    ):
+        """
+        SelectMultipleFormField rejects items with no answer by default
+
+        max_length refers to number of characters used to store the encoded
+        list of choices (est. 2n - 1)
+
+        size is the HTML element size attribute passed to the widget
+
+        max_choices is the maximum number of choices allowed by the field
+
+        max_choices_attr is a string used as an attribute name in the widget
+        representation of max_choices (currently a data attribute)
+
+        empty_value is the value used to represent an empty field
+
+        include_blank is deprecated and will be removed in a future release.
+        Use choices=[('', '---------'), ...] instead.
+        """
+        self.max_length, self.max_choices = max_length, max_choices
+        self.size, self.max_choices_attr = size, max_choices_attr
+        self.empty_value = kwargs.pop("empty_value", [])
+        if "include_blank" in kwargs:
+            warnings.warn(
+                "include_blank is deprecated; use choices=[('', '---------'), ...] instead",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+            self.include_blank = kwargs.pop("include_blank")
+        if not hasattr(self, "empty_values"):
+            self.empty_values = list(validators.EMPTY_VALUES)
+        super(SelectMultipleFormField, self).__init__(*args, **kwargs)
+
+    def to_python(self, value):
+        """
+        Convert widget value to a Python list.
+
+        Handles lists, tuples, CSV strings, and empty values.
+
+        Returns list.
+        """
+        if isinstance(value, (list, tuple)):
+            if all(v in self.empty_values for v in value):
+                try:
+                    # must be iterable - return a copy to avoid shared mutable state
+                    iter(self.empty_value)
+                    return list(self.empty_value)
+                except TypeError:
+                    return []
+
+        elif (value == self.empty_value) or (value in self.empty_values):
+            try:
+                # must be iterable - return a copy to avoid shared mutable state
+                iter(self.empty_value)
+                return list(self.empty_value)
+            except TypeError:
+                return []
+
+        if isinstance(value, str):
+            if len(value) == 0:
+                return []
+
+            native = decode_csv_to_list(value)
+            return native
+
+        return list(value)
+
+    def get_prep_value(self, value):
+        """
+        Prepares a string for use in serializer
+        """
+        if isinstance(value, (list, tuple)):
+            if len(value) == 0:
+                return ""
+            else:
+                return encode_list_to_csv(value)
+
+        return ""
+
+    def get_choices(self, **kwargs):
+        """
+        Choices from model without initial blank choices
+
+        ie Stop widget from producing <option value="">---------</option>
+        """
+        if hasattr(self, "include_blank"):
+            #
+            # include_blank is deprecated and will be removed in a future release.
+            #
+            include_blank = self.include_blank
+            if "include_blank" in kwargs:
+                kwargs.pop("include_blank")
+        else:
+            include_blank = kwargs.pop("include_blank", False)
+
+        if hasattr(super(), "get_choices"):
+            field_options = {"include_blank": include_blank}
+            field_options.update(kwargs)
+            choices = super(SelectMultipleFormField, self).get_choices(**field_options)
+            return list(choices)
+        else:
+            return list(self.choices)
+
+    def widget_attrs(self, widget):
+        """
+        Given a Widget instance (*not* a Widget class), returns a dictionary of
+        any HTML attributes that should be added to the Widget, based on this
+        Field.
+        """
+        attrs = super(SelectMultipleFormField, self).widget_attrs(widget)
+        if self.size != 4:
+            attrs.update({"size": str(self.size)})
+
+        if self.max_choices:
+            attrs.update({self.max_choices_attr: str(self.max_choices)})
+
+        return attrs

select_multiple_field/models.py

@@ -0,0 +1,392 @@
+import warnings
+
+from django.core import exceptions, validators
+from django.db import models
+from django.utils.encoding import force_str
+from django.utils.text import capfirst
+from django.utils.translation import gettext_lazy as _
+
+import select_multiple_field.forms as forms
+
+from .codecs import decode_csv_to_list, encode_list_to_csv
+from .validators import MaxChoicesValidator, MaxLengthValidator
+
+
+class SelectMultipleField(models.CharField):
+    """Stores multiple selection choices as serialized list"""
+
+    default_error_messages = {
+        "blank": _("This field cannot be blank."),
+        "invalid_type": _(
+            "Types passed as value must be string, list, tuple or None, "
+            "not '%(value)s'."
+        ),
+        "invalid_choice": _(
+            "Select a valid choice. %(value)s is not one of the available choices."
+        ),
+        "null": _("This field cannot be null."),
+    }
+    description = _("Select multiple field")
+
+    def __init__(self, *args, **kwargs):
+        """
+        Stores selected choices as CSV in the database and as list-like values
+        in Python.
+
+        Behavior notes:
+
+        - `blank=False` means a value is required by field validation.
+        - `null=True` stores SQL NULL for empty values in the database.
+        - Python-side normalization converts `None` to an empty list in
+            `to_python()` / `from_db_value()` for a consistent in-memory API.
+        - If `choices` and `max_choices` are set and `max_length` is omitted,
+            `max_length` is computed from the longest possible encoded CSV value.
+        - If `max_length` is explicitly provided but is smaller than that
+            computed encoded length, a `RuntimeWarning` is emitted.
+
+        Extra kwargs:
+
+        - `max_choices`: optional positive integer that limits the number of
+            selected options.
+        """
+        self.max_choices = None
+        self.include_blank = False
+        self._include_blank_set = False
+
+        kwargs = kwargs.copy()
+
+        if "max_choices" in kwargs:
+            max_choices = kwargs.pop("max_choices")
+            if max_choices is not None:
+                if not isinstance(max_choices, int) or max_choices <= 0:
+                    raise ValueError("max_choices must be a positive integer")
+                self.max_choices = max_choices
+
+        if "include_blank" in kwargs:
+            #
+            # include_blank is deprecated but retained for migration compatibility.
+            #
+            include_blank = kwargs.pop("include_blank")
+            if not isinstance(include_blank, bool):
+                raise TypeError("include_blank must be a boolean")
+            self.include_blank = include_blank
+            self._include_blank_set = True
+
+        explicit_max_length = "max_length" in kwargs
+
+        super(SelectMultipleField, self).__init__(*args, **kwargs)
+
+        if self.max_length is None and self.choices and self.max_choices is not None:
+            self.max_length = self._calculate_max_encoded_length()
+        elif explicit_max_length and self.choices and self.max_choices is not None:
+            calculated = self._calculate_max_encoded_length()
+            if self.max_length < calculated:
+                warnings.warn(
+                    f"max_length={self.max_length} is too small for max_choices={self.max_choices} "
+                    f"with choices={list(self.get_choices_keys())}. "
+                    f"Encoded CSV will be up to {calculated} chars. "
+                    f"Validation will fail for max selections.",
+                    RuntimeWarning,
+                    stacklevel=2,
+                )
+
+        self.validators = [
+            v
+            for v in self.validators
+            if not isinstance(v, validators.MaxLengthValidator)
+        ]
+
+        self.validators.append(MaxLengthValidator(self.max_length))
+        if self.max_choices is not None:
+            self.validators.append(MaxChoicesValidator(self.max_choices))
+
+    def _calculate_max_encoded_length(self):
+        """
+        Calculate max encoded CSV length from choices and max_choices.
+
+        Returns the max possible length of the CSV string when max_choices
+        are selected (choices joined by commas).
+        """
+        choice_keys = self.get_choices_keys()
+        if not choice_keys:
+            return 0
+
+        sorted_keys = sorted(choice_keys, key=len, reverse=True)
+        max_keys = sorted_keys[: self.max_choices]
+
+        return len(",".join(max_keys))
+
+    def get_internal_type(self):
+        return "CharField"
+
+    def to_python(self, value):
+        """
+        When SelectMultipleField is assigned a value, this method coerces
+        into a list usable by Python
+
+        value is Encoded strings from the database or Python native types in
+        need of validation
+
+        Raises ValidationError if value is not in choices or if invalid type
+
+        Returns list
+        """
+        if value is None:
+            return []
+
+        elif isinstance(value, (list, tuple)):
+            self.validate_options_list(value)
+            return value
+
+        elif isinstance(value, str):
+            #
+            # Strings are always encoded choices
+            #
+            native = decode_csv_to_list(value)
+            return native
+
+        msg = self.error_messages["invalid_type"] % {"value": type(value)}
+        raise exceptions.ValidationError(msg)
+
+    def from_db_value(self, value, expression, connection, context=None):
+        """
+        Converts a value as returned by the database to a Python object.
+        It is the reverse of get_prep_value().
+
+        This should always return a Python list.
+        """
+        if isinstance(value, str):
+            return decode_csv_to_list(value)
+        return []
+
+    def get_prep_value(self, value):
+        """
+        Perform preliminary non-db specific value checks and conversions.
+
+        This takes a Python list and encodes it into a string form representable
+        in the database.
+
+        If value is already a string (e.g. from a raw ORM lookup like
+        .filter(tags="django,api")), it is returned as-is to avoid
+        double-encoding.
+
+        Returns a string or None (if null=True and value is empty)
+        """
+        if value is None:
+            return None if self.null else ""
+
+        # Handle already-encoded CSV string (for query lookups)
+        if isinstance(value, str):
+            return value
+
+        if len(value) == 0:
+            if self.null:
+                return None
+            return ""
+
+        return encode_list_to_csv(value)
+
+    def get_choices(self, **kwargs):
+        """
+        Choices from model without initial blank choices
+
+        ie Stop widget from producing <option value="">---------</option>
+
+        If ModelField.include_blank is set then ignore any overrides sent via
+        kwargs
+        """
+        include_blank = False
+        if getattr(self, "_include_blank_set", False):
+            include_blank = self.include_blank
+            if "include_blank" in kwargs:
+                kwargs.pop("include_blank")
+        else:
+            include_blank = kwargs.pop("include_blank", False)
+
+        field_options = {"include_blank": include_blank}
+        field_options.update(kwargs)
+        choices = super(SelectMultipleField, self).get_choices(**field_options)
+        # Convert to list for Django < 5.0 compatibility (parent returns iterable in 5.0+)
+        return list(choices)
+
+    def has_choices(self):
+        """
+        Check if the field has choices values bound to it
+        """
+        choices = getattr(self, "choices", None)
+        if choices is None:
+            choices = getattr(self, "_choices", None)
+
+        return bool(choices)
+
+    def value_to_string(self, obj):
+        """
+        Used for serialization of the expected Python list
+        """
+        if hasattr(self, "value_from_object"):
+            native = self.value_from_object(obj)
+        else:
+            # Fallback for older Django versions
+            native = getattr(obj, self.attname)
+        return encode_list_to_csv(native)
+
+    def validate(self, value, model_instance):
+        """
+        Validates value and throws ValidationError. Subclasses should override
+        this to provide validation logic.
+        """
+        if not self.editable:
+            return
+
+        if isinstance(value, str):
+            value = decode_csv_to_list(value)
+
+        # Replicate parent Field.validate() blank/null/choice checks.
+        # We don't call super().validate() because with choices set
+        # and value as a list, the parent tries to match the list
+        # against choice keys, which always fails for multi-select values.
+        # Note: run_validators() is called by Field.clean() after validate(),
+        # so we don't call it here.
+        if not self.blank and value in validators.EMPTY_VALUES:
+            raise exceptions.ValidationError(self.error_messages["blank"], code="blank")
+        if value is None and not self.null:
+            raise exceptions.ValidationError(self.error_messages["null"], code="null")
+
+        if self.has_choices() and value:
+            if isinstance(value, (list, tuple)):
+                bad_values = self._find_invalid_choices(value)
+                if bad_values:
+                    msg = self.error_messages["invalid_choice"] % {"value": bad_values}
+                    raise exceptions.ValidationError(msg)
+            else:
+                msg = self.error_messages["invalid_choice"] % {"value": value}
+                raise exceptions.ValidationError(msg)
+
+    def _find_invalid_choices(self, value):
+        """
+        Returns a list of invalid choices in value that are not in the field's choices.
+        """
+        bad_values = []
+        for opt in value:
+            if self.blank and opt in validators.EMPTY_VALUES:
+                pass
+            elif opt not in self.get_choices_keys():
+                bad_values.append(opt)
+        return bad_values
+
+    def validate_options_list(self, value):
+        """
+        Checks that all options in value list are in choices
+
+        Raises ValidationError if an option in value list is not in choices
+
+        Returns None if all values are in choices
+        """
+        bad_values = self._find_invalid_choices(value)
+        if bad_values:
+            msg = self.error_messages["invalid_choice"] % {"value": bad_values}
+            raise exceptions.ValidationError(msg)
+
+    def get_choices_keys(self, **kwargs):
+        """
+        Flattens choices and optgroup choices into a plain list of keys
+
+        Returns choices keys as list
+        """
+        if not kwargs and hasattr(self, "_flat_choices_cache"):
+            return self._flat_choices_cache
+
+        choices = self.get_choices(**kwargs)
+        flat = []
+        for key, val in choices:
+            if isinstance(val, (list, tuple)):
+                for opt_key, opt_val in val:
+                    flat.append(opt_key)
+            else:
+                flat.append(key)
+
+        if not kwargs:
+            self._flat_choices_cache = flat
+        return flat
+
+    def validate_option(self, value):
+        """
+        Legacy helper not used by the field's internal validation flow.
+
+        Checks that value is in choices.
+        """
+        if self.blank and value in validators.EMPTY_VALUES:
+            return True
+
+        flat_choices = self.get_choices_keys()
+        return value in flat_choices
+
+    def formfield(self, **kwargs):
+        """
+        This returns the correct formclass without calling super
+
+        Returns select_multiple_field.forms.SelectMultipleFormField
+        """
+        defaults = {
+            "required": not self.blank,
+            "label": capfirst(self.verbose_name),
+            "help_text": self.help_text,
+        }
+        if self.has_default():
+            if callable(self.default):
+                defaults["initial"] = self.default
+                defaults["show_hidden_initial"] = True
+            else:
+                defaults["initial"] = self.get_default()
+
+        if self.choices:
+            # Django normally includes an empty choice if blank, has_default
+            # and initial are all False, we are intentionally breaking this
+            # convention
+            include_blank = self.blank
+            defaults["choices"] = self.get_choices(include_blank=include_blank)
+            if self.null:
+                defaults["empty_value"] = None
+
+            allowed = {
+                "empty_value",
+                "choices",
+                "required",
+                "widget",
+                "label",
+                "initial",
+                "help_text",
+                "error_messages",
+                "show_hidden_initial",
+            }
+            kwargs = {k: v for k, v in kwargs.items() if k in allowed}
+
+        defaults.update(kwargs)
+        return forms.SelectMultipleFormField(**defaults)
+
+    def deconstruct(self):
+        """
+        How to reduce the field to a serializable form.
+
+        The arguments to pass to field constructor to reconstruct it.
+
+        Returns a tuple of four items:
+            the field's attribute name,
+            the full import path of the field class,
+            the positional arguments (an empty list in this case),
+            the keyword arguments (as a dict).
+        """
+        name, path, args, kwargs = super(SelectMultipleField, self).deconstruct()
+
+        if self.max_choices is not None:
+            kwargs["max_choices"] = self.max_choices
+
+        if getattr(self, "_include_blank_set", False):
+            kwargs["include_blank"] = self.include_blank
+
+        return (
+            force_str(name, strings_only=True),
+            path,
+            args,
+            kwargs,
+        )

select_multiple_field/validators.py

@@ -0,0 +1,48 @@
+from django.core import validators
+from django.utils.deconstruct import deconstructible
+from django.utils.encoding import force_str
+from django.utils.translation import ngettext_lazy
+
+from .codecs import encode_list_to_csv
+
+
+@deconstructible
+class MaxChoicesValidator(validators.BaseValidator):
+
+    message = ngettext_lazy(
+        "Ensure this value has at most %(limit_value)d choice (it has %(show_value)d).",
+        "Ensure this value has at most %(limit_value)d choices (it has %(show_value)d).",
+        "limit_value",
+    )
+    code = "max_choices"
+
+    def compare(self, a, b):
+        return a > b
+
+    def clean(self, x):
+        return len(x)
+
+
+@deconstructible
+class MaxLengthValidator(validators.BaseValidator):
+    """
+    Validates that the encoded CSV string length does not exceed max_length.
+
+    Since this field stores data as a CSV string in a CharField, max_length
+    refers to the database column width. The validator encodes the list to
+    CSV to measure the actual stored length. The double encoding (here +
+    get_prep_value) is standard — validators operate on Python values.
+    """
+
+    message = ngettext_lazy(
+        "Ensure this value has at most %(limit_value)d character (it has %(show_value)d).",
+        "Ensure this value has at most %(limit_value)d characters (it has %(show_value)d).",
+        "limit_value",
+    )
+    code = "max_length"
+
+    def compare(self, a, b):
+        return a > b
+
+    def clean(self, value):
+        return len(force_str(encode_list_to_csv(value)))

select_multiple_field/widgets.py

@@ -0,0 +1,52 @@
+import warnings
+
+from django.forms import widgets
+
+HTML_ATTR_CLASS = "select-multiple-field"
+
+
+class SelectMultipleWidget(widgets.SelectMultiple):
+    """Multiple select widget ready for jQuery multiselect.js"""
+
+    allow_multiple_selected = True
+
+    def render(self, name, value, attrs=None, choices=(), renderer=None):
+        rendered_attrs = {"class": HTML_ATTR_CLASS}
+        if attrs:
+            rendered_attrs.update(attrs)
+        if value is None:
+            value = []
+
+        original_choices = self.choices
+        try:
+            if choices:
+                self.choices = choices
+            if renderer is not None:
+                return super().render(
+                    name, value, attrs=rendered_attrs, renderer=renderer
+                )
+            else:
+                return super().render(name, value, attrs=rendered_attrs)
+        finally:
+            self.choices = original_choices
+
+    def value_from_datadict(self, data, files, name):
+        """
+        SelectMultipleWidget delegates processing of raw user data to
+        Django's SelectMultiple widget
+
+        Returns list or None
+        """
+        return super().value_from_datadict(data, files, name)
+
+
+class SelectMultipleField(SelectMultipleWidget):
+    """Deprecated — use SelectMultipleWidget instead."""
+
+    def __init__(self, *args, **kwargs):
+        warnings.warn(
+            "SelectMultipleField is deprecated; use SelectMultipleWidget instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        super().__init__(*args, **kwargs)