From bc9e6212a6ecf7b913ac332598316ecfb16638e1 Mon Sep 17 00:00:00 2001 From: medmunds Date: Tue, 11 Dec 2012 13:19:21 -0800 Subject: [PATCH] Version 0.2.0 * Release notes in readme * Update example in readme * Note deprecation of DjrillMessage class * Longer long_description for PyPI * Update authors * Bump version number (setup.py and __init__.py) --- AUTHORS.txt | 2 ++ README.rst | 62 ++++++++++++++++++++++++++++------------- djrill/__init__.py | 2 +- djrill/mail/__init__.py | 3 ++ setup.py | 13 +++++++-- 5 files changed, 59 insertions(+), 23 deletions(-) diff --git a/AUTHORS.txt b/AUTHORS.txt index 4d56db7..adf7072 100644 --- a/AUTHORS.txt +++ b/AUTHORS.txt @@ -6,3 +6,5 @@ Chris Jones Mike Edmunds ArnaudF Théo Crevon +Rafael E. Belliard +Jared Morse diff --git a/README.rst b/README.rst index 1834032..1a2553c 100644 --- a/README.rst +++ b/README.rst @@ -4,13 +4,13 @@ Djrill, for Mandrill .. image:: https://secure.travis-ci.org/brack3t/Djrill.png?branch=master :target: https://travis-ci.org/brack3t/Djrill -Djrill is an email backend and new message class for Django users that want to take advantage of the Mandrill_ transactional -email service from MailChimp_. +Djrill is an email backend for Django users who want to take advantage of the +Mandrill_ transactional email service from MailChimp_. An optional Django admin interface is included. The admin interface allows you to: * Check the status of your Mandrill API connection. -* See stats on email tags and urls. +* See stats on email senders, tags and urls. Djrill is made available under the BSD license. @@ -81,35 +81,38 @@ package, including ``send_mail``, ``send_mass_mail``, ``EmailMessage`` and ``EmailMultiAlternatives``. You can also take advantage of Mandrill-specific features like tags, metadata, -and tracking by creating a ``django.mail.EmailMessage`` (or for HTML, -``django.mail.EmailMultiAlternatives``) object and setting Mandrill-specific +and tracking by creating a Django EmailMessage_ (or for HTML, +EmailMultiAlternatives_) object and setting Mandrill-specific properties on it before calling its ``send`` method. -Example: +Example, sending HTML email with Mandrill tags and metadata: .. code:: python - from django.core.mail import EmailMultiAlternatives # or just EmailMessage if you don't need HTML + from django.core.mail import EmailMultiAlternatives - subject = "Djrill Message" - from_email = "Djrill Sender " # this has to be in your Mandrill account's sending domains - to = ["Djrill Receiver ", "djrill.two@example.com"] - reply_email = "Customer Service " # optional - text_content = "This is the text version of your email" - html_content = "

This is the HTML version of your email

" # optional, use with ``attach_alternative`` below + msg = EmailMultiAlternatives( + subject="Djrill Message", + body="This is the text version of your email", + from_email="Djrill Sender ", + to=["Djrill Receiver ", "another.person@example.com"], + headers={'Reply-To': "Service "} # optional extra headers + ) + msg.attach_alternative("

This is the HTML version of your email

", "text/html") - msg = EmailMultiAlternatives(subject, text_content, from_email, to, headers={'Reply-To': reply_email}) - msg.tags = ["one tag", "two tag", "red tag", "blue tag"] # optional, Mandrill-specific message extension - msg.metadata = {'user_id': "8675309"} # optional, Mandrill-specific message extension - msg.attach_alternative(html_content, "text/html") + # Optional Mandrill-specific extensions (see full list below): + msg.tags = ["one tag", "two tag", "red tag", "blue tag"] + msg.metadata = {'user_id': "8675309"} + + # Send it: msg.send() If the Mandrill API returns an error response for any reason, the send call will raise a ``djrill.mail.backends.djrill.DjrillBackendHTTPError`` exception (unless called with fail_silently=True). -Djrill supports most of the functionality of Django's ``EmailMessage`` and -``EmailMultiAlternatives``. Some limitations: +Djrill supports most of the functionality of Django's `EmailMessage`_ and +`EmailMultiAlternatives`_ classes. Some limitations: * Djrill accepts additional headers, but only ``Reply-To`` and ``X-*`` (since that is all that Mandrill accepts). Any other extra headers will raise a @@ -125,6 +128,10 @@ Djrill supports most of the functionality of Django's ``EmailMessage`` and which Djrill doesn't use. *Caution:* depending on the ``preserve_recipients`` setting, this could result in exposing bcc addresses to all recipients. It's probably best to just avoid bcc.) +* All email addresses (from, to, cc) can be simple ("email@example.com") or + can include a display name ("Real Name "). +* The ``from_email`` must be in one of the approved sending domains in your + Mandrill account. Many of the options from the Mandrill `messages/send.json API`_ ``message`` struct can be set directly on an ``EmailMessage`` (or subclass) object: @@ -160,7 +167,8 @@ see ``DjrillMandrillFeatureTests`` in tests.py for examples. Testing ------- -Djrill is tested against Django 1.3 and 1.4 on Python 2.6 and 2.7. +Djrill is tested against Django 1.3 and 1.4 on Python 2.6 and 2.7, and +Django 1.5beta on Python 2.7. (It may also work with Django 1.2 and Python 2.5, if you use an older version of requests compatible with that code.) @@ -179,6 +187,18 @@ or:: python runtests.py +Release Notes +------------- + +Version 0.2.0: + +* ``MANDRILL_API_URL`` is no longer required in settings.py +* Earlier versions of Djrill required use of a ``DjrillMessage`` class to + specify Mandrill-specific options. This is no longer needed -- Mandrill + options can now be set directly on a Django EmailMessage_ object or any + subclass. (Existing code can continue to use ``DjrillMessage``.) + + Thanks ------ @@ -193,5 +213,7 @@ the awesome ``requests`` library. .. _django-adminplus: https://github.com/jsocol/django-adminplus .. _mock: http://www.voidspace.org.uk/python/mock/index.html .. _django.core.mail: https://docs.djangoproject.com/en/dev/topics/email/ +.. _EmailMessage: https://docs.djangoproject.com/en/dev/topics/email/#django.core.mail.EmailMessage +.. _EmailMultiAlternatives: https://docs.djangoproject.com/en/dev/topics/email/#sending-alternative-content-types .. _messages/send.json API: https://mandrillapp.com/api/docs/messages.html#method=send diff --git a/djrill/__init__.py b/djrill/__init__.py index 97158cb..1e21173 100644 --- a/djrill/__init__.py +++ b/djrill/__init__.py @@ -1,7 +1,7 @@ from django.contrib.admin.sites import AdminSite from django.utils.text import capfirst -VERSION = (0, 1, 2) +VERSION = (0, 2, 0) __version__ = '.'.join([str(x) for x in VERSION]) diff --git a/djrill/mail/__init__.py b/djrill/mail/__init__.py index d38bed9..021b149 100644 --- a/djrill/mail/__init__.py +++ b/djrill/mail/__init__.py @@ -1,6 +1,9 @@ from django.core.mail import EmailMultiAlternatives +# DjrillMessage class is deprecated as of 0.2.0, but retained for +# compatibility with existing code. (New code can just set Mandrill-specific +# options directly on an EmailMessage or EmailMultiAlternatives object.) class DjrillMessage(EmailMultiAlternatives): alternative_subtype = "mandrill" diff --git a/setup.py b/setup.py index 22ea8ab..da91696 100644 --- a/setup.py +++ b/setup.py @@ -2,9 +2,8 @@ from setuptools import setup setup( name="djrill", - version="0.1.4.1", + version="0.2.0", description='Django email backend for Mandrill.', - long_description='Email backend and new message class to send emails through the Mandrill email service.', keywords="django, mailchimp, mandrill, email, email backend", author="Kenneth Love , Chris Jones ", author_email="kenneth@brack3t.com", @@ -23,4 +22,14 @@ setup( "Framework :: Django", "Environment :: Web Environment", ], + long_description="""\ +Djrill is an email backend for Django users who want to take advantage of the +`Mandrill `_ transactional email service from MailChimp. + +In general, Djrill "just works" with Django's built-in ``django.core.mail`` +package. You can also take advantage of Mandrill-specific features like tags, +metadata, and tracking. An optional Django admin interface is included. + +Full details are on the `project page `_. +""", )