django-multi-email-field

Common errors

• ModuleNotFoundError: No module named 'multi_email_field'

  cause The `django-multi-email-field` package is not installed or the import path is incorrect.
  fix Ensure the package is installed with `pip install django-multi-email-field`. Double-check import statements like `from multi_email_field.fields import MultiEmailField`.

• AttributeError: 'MultiEmailField' object has no attribute 'clean'

  cause This usually occurs when attempting to use the `MultiEmailField` from `multi_email_field.fields` (designed for models) directly as a form field, or vice-versa, without proper Django form integration.
  fix When defining forms, explicitly import and use `MultiEmailField` from `multi_email_field.forms`. If using a `ModelForm`, ensure the model field type is correctly mapped or overridden by the form field type.

• django.db.utils.DataError: value too long for type character varying(255)

  cause You have provided a combined string of email addresses (including commas) that exceeds the `max_length` defined for the `MultiEmailField` in your model.
  fix Increase the `max_length` argument of your `ModelMultiEmailField` in `models.py` to accommodate longer email lists, then run `makemigrations` and `migrate`.

• ValidationError: ['Enter a valid email address.']

  cause One or more email addresses in the input string are syntactically invalid according to Django's email validator.
  fix Check the input string for typos, missing '@' symbols, invalid domains, or other format errors. Each email address must pass standard email validation.

Warnings

• gotcha The `MultiEmailField` stores all email addresses as a single comma-separated string in the database, not as a list or JSON array. When retrieving directly from the database or performing raw queries, remember to parse this string.
  Fix: If you need structured data (e.g., a Python list of emails) after retrieval, manually split the string: `emails_list = instance.emails.split(',')`.
• gotcha The `max_length` argument on `MultiEmailField` applies to the *entire* comma-separated string, including commas. It does not limit the length of individual email addresses.
  Fix: Carefully calculate the maximum combined length of all emails and separators you expect. If you exceed it, a `DataError` (PostgreSQL) or `IntegrityError` (MySQL) will be raised.
• gotcha The `MultiEmailField` name is used for both the model field (`multi_email_field.fields.MultiEmailField`) and the form field (`multi_email_field.forms.MultiEmailField`). Confusing their import paths will lead to `AttributeError` or unexpected behavior.
  Fix: Always use `from multi_email_field.fields import MultiEmailField` for model definitions and `from multi_email_field.forms import MultiEmailField` for form definitions. Using aliases like `ModelMultiEmailField` and `FormMultiEmailField` (as in the quickstart) can prevent clashes.
• gotcha If any email address in the input string is invalid, the field will fail validation and return a generic `ValidationError: ['Enter a valid email address.']` for the entire field, without specifying which email was problematic.
  Fix: Provide clear user-facing guidance on input format and consider custom JavaScript validation for immediate feedback on individual emails if a highly granular error message is critical for your UI.

Install

• pip install django-multi-email-field Install stable version

Imports

• MultiEmailField
  wrong:

  from multi_email_field.forms import MultiEmailField # For model fields

  correct:

  from multi_email_field.fields import MultiEmailField

  This is the model field. Do not use the form's MultiEmailField for models.
• MultiEmailField
  wrong:

  from multi_email_field.fields import MultiEmailField # For form fields

  correct:

  from multi_email_field.forms import MultiEmailField

  This is the form field. Do not use the model's MultiEmailField for forms.
• MultiEmailWidget

  from multi_email_field.widgets import MultiEmailWidget

Quickstart

Defines a Django model (`Contact`) using `ModelMultiEmailField` and a Django form (`ContactForm`) that utilizes `FormMultiEmailField` with `MultiEmailWidget` for managing multiple email addresses. Includes the minimal Django setup required for standalone execution.

import os
from django.conf import settings
from django.db import models
from django import forms
from multi_email_field.fields import MultiEmailField as ModelMultiEmailField
from multi_email_field.forms import MultiEmailField as FormMultiEmailField
from multi_email_field.widgets import MultiEmailWidget

# Minimal Django setup (required for models/forms to be defined outside a full project)
if not settings.configured:
    settings.configure(
        INSTALLED_APPS=[
            'django.contrib.auth',
            'django.contrib.contenttypes',
            'my_app', # A dummy app for model registration
        ],
        DATABASES={'default': {'ENGINE': 'django.db.backends.sqlite3', 'NAME': ':memory:'}},
        DEBUG=True,
    )
    # Required for Django apps to be ready for model creation
    import django
    django.setup()

# Define a placeholder app to allow models to be registered
class MyAppConfig(object):
    name = 'my_app'
    label = 'my_app'

# Example Model integrating MultiEmailField
class Contact(models.Model):
    name = models.CharField(max_length=100)
    emails = ModelMultiEmailField(blank=True, default='')

    def __str__(self):
        return self.name

# Example Form using MultiEmailField and its widget
class ContactForm(forms.ModelForm):
    emails = FormMultiEmailField(
        widget=MultiEmailWidget(attrs={'rows': 3, 'placeholder': 'email1@example.com, email2@test.org'})
    )

    class Meta:
        model = Contact
        fields = ['name', 'emails']

# Example usage (uncomment to run in a script):
# from django.core.exceptions import ValidationError
# try:
#     contact_instance = Contact.objects.create(name="Jane Doe", emails="jane@example.com, jane2@test.org")
#     print(f"Created contact: {contact_instance.name} with emails: {contact_instance.emails}")
#     form = ContactForm(instance=contact_instance)
#     print("\n--- ContactForm (edit existing) ---")
#     print(form.as_p()) # Render the form fields

#     form_data = {'name': 'New User', 'emails': 'user@example.com, another@domain.com'}
#     new_form = ContactForm(form_data)
#     if new_form.is_valid():
#         print("\n--- New ContactForm (valid) ---")
#         new_contact = new_form.save()
#         print(f"Saved new contact: {new_contact.name} with emails: {new_contact.emails}")
#     else:
#         print("New form errors:", new_form.errors)

#     invalid_form_data = {'name': 'Bad User', 'emails': 'invalid-email, user@domain.com'}
#     invalid_form = ContactForm(invalid_form_data)
#     if not invalid_form.is_valid():
#         print("\n--- Invalid ContactForm (expected errors) ---")
#         print("Invalid form errors:", invalid_form.errors)
# except Exception as e:
#     print(f"An error occurred during example usage: {e}")