Notification and Mailing system in App Engine.

This is a talk I gave at my company regarding how to improve the code legibility and how to build it with a clear api and documentation.

Transcript

1. Mailing and Notifications Building Blocks
2. PROBLEMS
3. Creating the email No way of seeing how an email looks like after being converted into a template. No way of testing how it will look like in different email clients.
4. Sending the email PM cannot test that emails are being sent. Developer’s email tools are poor.
5. “...whatever you do, don’t congratulate yourself too much, or berate yourself neither...”
6. A CLOSER LOOK AT send_notify
7. Code smells if language == 'es': notification_remove_msg = 'No...' else: notification_remove_msg = 'Don't...'
8. Code smells if language == 'es': notification_remove_msg = 'No...' elif language == 'de': notification_remove_msg = 'No...' elif language == 'pt': notification_remove_msg = 'No...' else: notification_remove_msg = "Don't..."
9. Inaccurate logs if not self.user.email: if log_send: logging.info('to email: ' + str(self.user.pk)) return
10. Hardcoding message = mail.EmailMessage( sender='App<hello@app.com>')
11. Not DRY if log_send: ... x3
12. DRY Don’t Repeat Yourself
13. Can’t be extended without changing or rewriting the entire code.
14. Dependencies send_notify() depends on: 1.global settings.DEBUG 2.recipient ending in ‘@app.com’ 3.parameter force_send 4.user is_active
15. Dependencies not documented def send_notify(self, notify, params, force_send=False, log_send=True): """Send a notification to user Args: notify: type of notification params: data to fill templates """
16. SOLUTIONS
17. Unix philosophy “...emphasizes building short, simple, clear, modular and extendable code...”
18. Single Responsibility Open-closed Liskov substitution Interface segregation Dependency inversion http://en.wikipedia.org/wiki/SOLID_(object-oriented_design)
19. NOTIFICATIONS
20. Language Subject Plain Text body HTML body Subject, Plain Text body and HTML body are sort of templates.
21. Basic operations Load the notification template named name and with language lang from somewhere. Render each notification template (subject, text, html) with the actual data.
22. “Loader” object class Loader(object): def get_subject(self, name, lang): """Get the subject""" def get_html(self, name, lang): """Get the html""" def get_text(self, name, lang): """Get the plain text"""
23. “Template” object class Template(object): def __init__(self, source): pass def render(self, **context): """Put context in template"""
24. Now we need to combine Loader and Template objects in a way that can be configurable.
25. “Environment” object class Environment(object): def __init__(self, loader, template_class): self.loader = loader self.template_class = template_class def get_notification(self, name, lang=None, **context): subject = self.template_class( self.loader.get_subject(name, lang)).render(**context) html = self.template_class( self.loader.get_html(name, lang)).render(**context) text = self.template_class( self.loader.get_text(name, lang)).render(**context) return Notification(name, lang, subject, html, text)
26. Putting all together
27. notifications = Environment( loader=Loader(), template_class=Template)
28. But what if I want to keep my notifications in the database from now on?
29. Custom loaders can be created by extending the base loader.
30. class FileSystemLoader(Loader): SUBJECT_FILENAME = 'subject.txt' HTML_FILENAME = 'body.html' TEXT_FILENAME = 'body.txt' def __init__(self, path): self.path = path def _read(self, name, lang, filename): with open(os.path.join(self.path, name, lang, filename)) as f: return f.read() def get_subject(self, name, lang): return self._read(name, lang, self.SUBJECT_FILENAME) def get_html(self, name, lang): return self._read(name, lang, self.HTML_FILENAME) def get_text(self, name, lang): try: text = self._read(name, lang, self.TEXT_FILENAME) except IOError: text = super().get_text(name, lang) return text
31. class DjangoTemplateLoader(FileSystemLoader): def __init__(self, template_dirs=None): self.template_dirs = template_dirs def _read(self, name, lang, filename): template_name = '/'.join((name, lang, filename)) return load_template_source( template_name, self.template_dirs)[0]
32. No Problem notifications = Environment( loader=DatastoreTemplateLoader(), template_class=DjangoTemplate)
33. But what if I want to start using Django’s template system?
34. Custom templates can be created by extending the base template.
35. class DjangoTemplate(Template): def __init__(self, source): self._template = django.template.Template(source) def render(self, **context): return self._template.render( django.template.Context(context))
36. No Problem notifications = Environment( loader=DatastoreTemplateLoader(), template_class=DjangoTemplate)
37. from .environment import notifications get_notification = notifications.get_notification
38. subject = 'email/%s/%s/subject.txt' % (name, language) message.subject = loader.get_template(subject) .render(Context(params)) body = 'email/%s/%s/body.txt' % (name, language) message.body = loader.get_template(body).render(Context(params)) message.body += notification_remove_msg + ' ' + profile_notification_url html = 'email/%s/%s/body.html' % (name, language) message.html = loader.get_template(html).render(Context(params)) message.html += '<br /><a href="%s">%s</a>' % (profile_notification_url, notification_remove_msg) “Before”
39. notification = get_notification(name, language, **params) message.subject = notification.subject message.body = notification.text message.html = notification.html “After”
40. MAILING
41. I don’t like App Engine email API because it mixes the way email are sent with the way they are represented.
42. import smtplib from email.mime.text import MIMEText msg = MIMEText('Message') msg['Subject'] = 'The subject' msg['From'] = me msg['To'] = you s = smtplib.SMTP('localhost') s.sendmail(me, [you], msg.as_string()) s.quit() I prefer the approach of the standard library
43. But we are already using App Engine API in many places.
44. Let’s try to refactor... from google.appengine.api import mail message = mail.EmailMessage(sender='...') message.to = self.user.email message.subject = '...' message.body = '...' message.html = '...' message.send()
45. ...in order to support Different kinds of messages: The actual that sends the email. One that logs the email. One that does nothing.
46. Refactor “...restructuring an existing body of code, altering its internal structure without changing its external behavior.”
47. EMAIL_MESSAGE_SETTING = 'EMAIL_MESSAGE_CLASS' def EmailMessage(message_class=None, **kwargs): if message_class is None: if not hasattr(settings, EMAIL_MESSAGE_SETTING): raise ImproperlyConfigured message_class = getattr(settings, EMAIL_MESSAGE_SETTING) if isinstance(message_class, basestring): ... return message_class(**kwargs)
48. class Message(MailerDelegator): pass class LoggingMessage(MailerDelegator): name = 'app.mail' logger = logging.getLogger(name) level = logging.DEBUG def send(self, *args, **kwargs): self.logger.log(self.level, self) Pick your “Message” class DummyMessage(MailerDelegator): def send(self, *args, **kwargs): pass
49. EMAIL_MESSAGE_CLASS = 'app.mail.LoggingMessage' Configuration
50. from app import mail msg = mail.EmailMessage() msg.send() # => Logs the message
51. class MailerDelegator(object): __slots__ = '_mailer' mailer_class = google.appengine.api.mail.EmailMessage def __init__(self, *args, **kwargs): object.__setattr__(self, '_mailer', self.mailer_class(*args, **kwargs)) def __setattr__(self, name, value): if name in self._mailer.PROPERTIES: setattr(self._mailer, name, value) else: super().__setattr__(name, value) def __getattr__(self, name): if not hasattr(self._mailer, name): raise AttributeError return getattr(self._mailer, name) def __str__(self): return self.to_mime_message().as_string()
52. Something else?...
53. Of course! Where are the docs dude!?
56. PROBLEMS SOLVED
57. Creating the email (unsolved) No way of seeing how an email looks like after being converted into a template. (unsolved) No way of testing how it will look like in different email clients.
58. Sending the email (unsolved) PM cannot test that emails are being sent. (solved) Developers email tools are poor.
59. 75% still unsolved!
60. Having better tools for doing the job is more a middle/long term investment.
61. Choose Wisely
63. Recommended
64. raise SystemExit