Upgrading from 1.x¶
Djrill 2.0 includes some breaking changes from 1.x. These changes should have minimal (or no) impact on most Djrill users, but if you are upgrading please review the major topics below to see if they apply to you.
Djrill 1.4 tried to warn you if you were using Djrill features expected to change in 2.0. If you are seeing any deprecation warnings with Djrill 1.4, you should fix them before upgrading to 2.0. (Warnings appear in the console when running Django in debug mode.)
Please see the release notes for a list of new features and improvements in Djrill 2.0.
Dropped support for Django 1.3, Python 2.6, and Python 3.2¶
Although Djrill may still work with these older configurations, we no longer test against them. Djrill now requires Django 1.4 or later and Python 2.7, 3.3, or 3.4.
If you require support for these earlier versions, you should not upgrade to Djrill 2.0. Djrill 1.4 remains available on pypi, and will continue to receive security fixes.
Earlier versions of Djrill included a custom Django admin site. The equivalent functionality is available in Mandrill’s dashboard, and Djrill 2.0 drops support for it.
Although most Djrill users were unaware the admin site existed, many did follow the earlier versions’ instructions to enable it.
If you have added DjrillAdminSite, you will need to remove it for Djrill 2.0.
from djrill import DjrillAdminSite # REMOVE this admin.site = DjrillAdminSite() # REMOVE this admin.autodiscover() # REMOVE this if you added it only for Djrill
INSTALLED_APPS = ( ... # If you added SimpleAdminConfig only for Djrill: 'django.contrib.admin.apps.SimpleAdminConfig', # REMOVE this 'django.contrib.admin', # ADD this default back ... )
(These instructions assume you had changed to SimpleAdminConfig solely for DjrillAdminSite. If you are using it for custom admin sites with any other Django apps you use, you should leave it SimpleAdminConfig in place, but still remove the references to DjrillAdminSite.)
Added exception for invalid or rejected recipients¶
Djrill 2.0 raises a new
djrill.MandrillRecipientsRefused exception when
all recipients of a message are invalid or rejected by Mandrill. (This parallels
the behavior of Django’s default
SMTP email backend,
all recipients are refused.)
Your email-sending code should handle this exception (along with other
exceptions that could occur during a send). However, if you want to retain the
Djrill 1.x behavior and treat invalid or rejected recipients as successful sends,
you can set
True in your settings.py.
Other 2.0 breaking changes¶
Code that will be affected by these changes is far less common than for the changes listed above, but they may impact some uses:
- Removed unintended date-to-string conversion
If your code was inadvertently relying on Djrill to automatically convert date or datetime values to strings in
metadata, or other Mandrill message attributes, you must now explicitly do the string conversion yourself. See Formatting Merge Data for an explanation. (Djrill 1.4 reported a DeprecationWarning for this case.)
(This does not affect
send_at, where Djrill specifically allows date or datetime values.)
- Removed DjrillMessage class
DjrillMessageclass has not been needed since Djrill 0.2. You should replace any uses of it with the standard
EmailMessageclass. (Djrill 1.4 reported a DeprecationWarning for this case.)
- Removed DjrillBackendHTTPError
- This exception was deprecated in Djrill 0.3. Replace uses of it
djrill.MandrillAPIError. (Djrill 1.4 reported a DeprecationWarning for this case.)
- Refactored Djrill backend and exceptions
- Several internal details of
djrill.mail.backends.DjrillBackendand Djrill’s exception classes have been significantly updated for 2.0. The intent is to make it easier to maintain and extend the backend (including creating your own subclasses to override Djrill’s default behavior). As a result, though, any existing code that depended on undocumented Djrill internals may need to be updated.