diff --git a/README.rst b/README.rst index ebcdec7..7db88c9 100644 --- a/README.rst +++ b/README.rst @@ -61,6 +61,13 @@ Using notification classes Changelog --------- +**v0.3** + +* *backwards incompatible* Guessing the file extension with the + ``mimetypes`` package proved to be inconsistent across systems. + ``TemplatedEmailBackend`` now makes uses explicitly declared file + extensions. + **v0.2** * Made the API saner to use (*backwards incompatible*): diff --git a/docs/index.rst b/docs/index.rst index ebcdec7..9a09e14 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -70,3 +70,82 @@ Changelog - ``yell.decorators.yelling`` became ``yell.decorators.notification`` +==== +yell +==== + +Pluggable notifications for your Python apps. + +`yell` is not a notification storage or delivery backend but a set of APIs that make it easy to add your own delivery mechanisms. + +The full documentation is available `here `_. + + +Using notification decorators +----------------------------- + +:: + + from yell import notify + from yell.decorators import notification + + @notification(name = 'buffalo') + def buffalo_printer(message): + print message + + @notification(name = 'buffalo') + def buffalo_saver(message): + save(message) + + notify("buffalo", _("Buffalo buffalo Buffalo buffalo buffalo buffalo Buffalo buffalo")) + + +Using notification classes +-------------------------- + +:: + + from yell import Notification, notify + + class Buffalo(Notification): + name = "buffalo" + message = _("Buffalo buffalo Buffalo buffalo buffalo buffalo Buffalo buffalo") + + def notify(self, *args, **kwargs): + print self.message + + class BuffaloEmail(Buffalo): + def notify(self, *args, **kwargs): + send_mail("Buffalo", self.message, 'buffalo@example.com', [kwargs.get('user').email]) + + class BuffaloDatabase(Buffalo): + def notify(self, *args, **kwargs): + BuffaloModel.objects.create(user = kwargs.get('user')) + + # The default behaviour is to use every notification backend with the same + # name + notify("buffalo", user = User.objects.get(id=1)) + + # Only send emails + notify("buffalo", user = User.objects.get(id=1), backends = [BuffaloEmail]) + + +Changelog +--------- + +**v0.3** + +* *backwards incompatible* Guessing the file extension with the + ``mimetypes`` package proved to be inconsistent across systems. + ``TemplatedEmailBackend`` now makes uses explicitly declared file + extensions. + +**v0.2** + +* Made the API saner to use (*backwards incompatible*): + + - ``yell.Yell`` became ``yell.Notification`` + - ``yell.yell`` became ``yell.notify`` + - ``yell.decorators.yelling`` became ``yell.decorators.notification`` + + diff --git a/yell/__init__.py b/yell/__init__.py index c4396b5..6c42464 100644 --- a/yell/__init__.py +++ b/yell/__init__.py @@ -1,4 +1,4 @@ -__version__ = "0.2" +__version__ = "0.3" import registry diff --git a/yell/backends/django.py b/yell/backends/django.py index 5a15534..38baef9 100644 --- a/yell/backends/django.py +++ b/yell/backends/django.py @@ -4,7 +4,7 @@ from django import template from django.core.mail import send_mail, EmailMultiAlternatives from yell import Notification -import mimetypes + class EmailBackend(Notification): @@ -101,7 +101,10 @@ class SignupMessage(TemplatedEmailBackend): * `yell/signup.html` """ - content_types = ['text/plain', 'text/html'] + content_types = ( + ('text/plain', '.txt'), + ('text/html', '.html') + ) """ Default content types to render """ @@ -109,15 +112,22 @@ class SignupMessage(TemplatedEmailBackend): # Memoize _body = None + def get_path(self, name, ext): + """ + Get the path to a given template name. Override if you wish to + store your templates in a custom folder outside of `yell/`. + """ + return os.paht.join('yell', '{0}{1}'.format(name, ext)) + def get_body(self, *args, **kwargs): """ - Render message bodies by guessing the file extension from - :attr:`content_types` + Render message bodies by using all the content types defined + in :attr:`content_types` """ if self._body is None: self._body = {} - for ctype in self.content_types: - tpl = template.loader.get_template('yell/%s%s' % (self.name, mimetypes.guess_extension(ctype))) + for ctype, ext in self.content_types: + tpl = template.loader.get_template(self.get_path(self.name, ext)) self._body[ctype] = tpl.render(template.Context(kwargs)) return self._body