Registry / web-framework / django-multi-email-field

django-multi-email-field

JSON →
library0.8.0pypypi✓ verified 87d ago

django-multi-email-field version 0.8.0 provides a reusable model field and a form field for Django to manage lists of email addresses. It stores multiple emails as a single comma-separated string in the database and provides appropriate validation and a dedicated widget for forms. Releases are infrequent but stable, primarily for Django compatibility updates.

pip install django-multi-email-field
INSTALL
IMPORT
SIG · DJANGO-MULTI-EMAIL
D
django-multi-email-field
web-frameworkpythonv0.8.0
Install
3.5s avg
Import
588ms
Disk
65MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v0.8.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.910 runs
installs and imports cleanly · install 0.0s · import 0.614s · 66.3MB
glibc
py 3.103.910 runs
installs and imports cleanly · install 3.5s · import 0.562s · 67MB
65MB installed
● package 65MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

MultiEmailField
from multi_email_field.fields import MultiEmailField
from multi_email_field.forms import MultiEmailField # For model fields
This is the model field. Do not use the form's MultiEmailField for models.
MultiEmailField
from multi_email_field.forms import MultiEmailField
from multi_email_field.fields import MultiEmailField # For form fields
This is the form field. Do not use the model's MultiEmailField for forms.
MultiEmailWidget
from multi_email_field.widgets import MultiEmailWidget

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}")
Debug
Known issues
gotchaThe `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(',')`.
affects: 0.1.0-0.8.0
gotchaThe `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.
affects: 0.1.0-0.8.0
gotchaThe `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.
affects: 0.1.0-0.8.0
gotchaIf 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.
affects: 0.1.0-0.8.0
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'multi_email_field'
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'
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)
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.']
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.
Upgrade
Version history
0.8.0latest on PyPI · released May 16, 2025
Audit
Dependencies
DjangorequiredThis is a Django package, requiring Django>=3.2.
Agent activity
4 hits · last 30 days
node
4
Resources