Debian Codegraph @

django_templated_email.egg-info/PKG-INFO

raw
1 Metadata-Version: 2.1
2 Name: django-templated-email
3 Version: 3.0.0
4 Summary: A Django oriented templated / transaction email abstraction
5 Home-page: http://github.com/vintasoftware/django-templated-email/
6 Author: Bradley Whittington
7 Author-email: [email protected]
8 License: MIT
9 Description: ==============================
10 Django-Templated-Email
11 ==============================
12
13 |GitterBadge|_ |PypiversionBadge|_ |PythonVersionsBadge|_ |LicenseBadge|_
14
15 :Info: A Django oriented templated email sending class
16 :Author: Bradley Whittington (http://github.com/bradwhittington, http://twitter.com/darb)
17 :Tests: |TravisBadge|_ |CoverageBadge|_
18
19
20 Overview
21 =================
22 django-templated-email is oriented towards sending templated emails.
23 The library supports template inheritance, adding cc'd and bcc'd recipients,
24 configurable template naming and location.
25
26 The send_templated_email method can be thought of as the render_to_response
27 shortcut for email.
28
29 Make sure you are reading the correct documentation:
30
31 develop branch: https://github.com/vintasoftware/django-templated-email/blob/develop/README.rst
32
33 stable pypi/master: https://github.com/vintasoftware/django-templated-email/blob/master/README.rst
34
35
36 Requirements
37 =================
38 * Python (3.6, 3.7, 3.8, 3.9)
39 * Django (2.2, 3.1, 3.2)
40
41 We **highly recommend** and only officially support the latest patch release of
42 each Python and Django series.
43
44
45 Getting going - installation
46 ==============================
47
48 Installing::
49
50 pip install django-templated-email
51
52 You can add the following to your settings.py (but it works out the box):
53
54 .. code-block:: python
55
56 TEMPLATED_EMAIL_BACKEND = 'templated_email.backends.vanilla_django.TemplateBackend'
57
58 # You can use a shortcut version
59 TEMPLATED_EMAIL_BACKEND = 'templated_email.backends.vanilla_django'
60
61 # You can also use a class directly
62 from templated_email.backends.vanilla_django import TemplateBackend
63 TEMPLATED_EMAIL_BACKEND = TemplateBackend
64
65
66 Sending templated emails
67 ==============================
68
69 Example usage using vanilla_django TemplateBackend backend
70
71 Python to send mail:
72
73 .. code-block:: python
74
75 from templated_email import send_templated_mail
76 send_templated_mail(
77 template_name='welcome',
78 from_email='[email protected]',
79 recipient_list=['[email protected]'],
80 context={
81 'username':request.user.username,
82 'full_name':request.user.get_full_name(),
83 'signup_date':request.user.date_joined
84 },
85 # Optional:
86 # cc=['[email protected]'],
87 # bcc=['[email protected]'],
88 # headers={'My-Custom-Header':'Custom Value'},
89 # template_prefix="my_emails/",
90 # template_suffix="email",
91 )
92
93 If you would like finer control on sending the email, you can use **get_templated_email**, which will return a django **EmailMessage** object, prepared using the **vanilla_django** backend:
94
95 .. code-block:: python
96
97 from templated_email import get_templated_mail
98 get_templated_mail(
99 template_name='welcome',
100 from_email='[email protected]',
101 to=['[email protected]'],
102 context={
103 'username':request.user.username,
104 'full_name':request.user.get_full_name(),
105 'signup_date':request.user.date_joined
106 },
107 # Optional:
108 # cc=['[email protected]'],
109 # bcc=['[email protected]'],
110 # headers={'My-Custom-Header':'Custom Value'},
111 # template_prefix="my_emails/",
112 # template_suffix="email",
113 )
114
115 You can also **cc** and **bcc** recipients using **cc=['[email protected]']**.
116
117 Your template
118 -------------
119
120 The templated_email/ directory needs to be the templates directory.
121
122 The backend will look in *my_app/templates/templated_email/welcome.email* :
123
124 .. code-block:: python
125
126 {% block subject %}My subject for {{username}}{% endblock %}
127 {% block plain %}
128 Hi {{full_name}},
129
130 You just signed up for my website, using:
131 username: {{username}}
132 join date: {{signup_date}}
133
134 Thanks, you rock!
135 {% endblock %}
136
137 If you want to include an HTML part to your emails, simply use the 'html' block :
138
139 .. code-block:: python
140
141 {% block html %}
142 <p>Hi {{full_name}},</p>
143
144 <p>You just signed up for my website, using:
145 <dl>
146 <dt>username</dt><dd>{{username}}</dd>
147 <dt>join date</dt><dd>{{signup_date}}</dd>
148 </dl>
149 </p>
150
151 <p>Thanks, you rock!</p>
152 {% endblock %}
153
154 The plain part can also be calculated from the HTML using `html2text <https://pypi.python.org/pypi/html2text>`_. If you don't specify the plain block and `html2text <https://pypi.python.org/pypi/html2text>`_ package is installed, the plain part will be calculated from the HTML part. You can disable this behaviour in settings.py :
155
156 .. code-block:: python
157
158 TEMPLATED_EMAIL_AUTO_PLAIN = False
159
160 You can also specify a custom function that converts from HTML to the plain part :
161
162 .. code-block:: python
163
164 def convert_html_to_text(html):
165 ...
166
167 TEMPLATED_EMAIL_PLAIN_FUNCTION = convert_html_to_text
168
169 You can globally override the template dir, and file extension using the following variables in settings.py :
170
171 .. code-block:: python
172
173 TEMPLATED_EMAIL_TEMPLATE_DIR = 'templated_email/' #use '' for top level template dir, ensure there is a trailing slash
174 TEMPLATED_EMAIL_FILE_EXTENSION = 'email'
175
176 You can also set a value for **template_prefix** and **template_suffix** for every time you call **send_templated_mail**, if you wish to store a set of templates in a different directory. Remember to include a trailing slash.
177
178 Using with `Django Anymail <https://github.com/anymail/django-anymail>`_
179 =========================================================================
180
181 Anymail integrates several transactional email service providers (ESPs) into Django, with a consistent API that lets you use ESP-added features without locking your code to a particular ESP. It supports Mailgun, Postmark, SendGrid, SparkPost and more.
182
183 You can use it with django-templated-email, just follow their instructions in their `quick start <https://anymail.readthedocs.io/en/latest/quickstart/>`_ to configure it.
184
185 Optionally you can use their custom `EmailMessage <https://anymail.readthedocs.io/en/latest/sending/anymail_additions/#anymail.message.AnymailMessage>`_ class with django-templated-email by using the following settings:
186
187 .. code-block:: python
188
189 # This replaces django.core.mail.EmailMessage
190 TEMPLATED_EMAIL_EMAIL_MESSAGE_CLASS='anymail.message.AnymailMessage'
191
192 # This replaces django.core.mail.EmailMultiAlternatives
193 TEMPLATED_EMAIL_EMAIL_MULTIALTERNATIVES_CLASS='anymail.message.AnymailMessage'
194
195
196 Inline images
197 ==============
198
199 You can add inline images to your email using the *InlineImage* class.
200
201 First get the image content from a file or a *ImageField*:
202
203 .. code-block:: python
204
205 # From a file
206 with open('pikachu.png', 'rb') as pikachu:
207 image = pikachu.read()
208
209 # From an ImageField
210 # Suppose we have this model
211 class Company(models.Model):
212 logo = models.ImageField()
213
214 image = company.logo.read()
215
216 Then create an instance of *InlineImage*:
217
218 .. code-block:: python
219
220 from templated_email import InlineImage
221
222 inline_image = InlineImage(filename="pikachu.png", content=image)
223
224 Now pass the object on the context to the template when you send the email.
225
226 .. code-block:: python
227
228 send_templated_mail(template_name='welcome',
229 from_email='[email protected]',
230 recipient_list=['[email protected]'],
231 context={'pikachu_image': inline_image})
232
233 Finally in your template add the image on the html template block:
234
235 .. code-block:: html
236
237 <img src="{{ pikachu_image }}">
238
239 Note: All *InlineImage* objects you add to the context will be attached to the e-mail, even if they are not used in the template.
240
241
242 Add link to view the email on the web
243 =====================================
244
245 .. code-block:: python
246
247 # Add templated email to INSTALLED_APPS
248 INSTALLED_APPS = [
249 ...
250 'templated_email'
251 ]
252
253 .. code-block:: python
254
255 # and this to your url patterns
256 url(r'^', include('templated_email.urls', namespace='templated_email')),
257
258 .. code-block:: python
259
260 # when sending the email use the *create_link* parameter.
261 send_templated_mail(
262 template_name='welcome', from_email='[email protected]',
263 recipient_list=['[email protected]'],
264 context={}, create_link=True)
265
266 And, finally add the link to your template.
267
268 .. code-block:: html
269
270 <!-- With the 'if' the link will only appear on the email. -->
271 {% if email_uuid %}
272 <!-- Note: you will need to add your site since you will need to access
273 it from the email -->
274 You can view this e-mail on the web here:
275 <a href="http://www.yoursite.com{% url 'templated_email:show_email' uuid=email_uuid %}">
276 here
277 </a>
278 {% endif %}
279
280 Notes:
281 - A copy of the rendered e-mail will be stored on the database. This can grow
282 if you send too many e-mails. You are responsible for managing it.
283 - If you use *InlineImage* all images will be uploaded to your media storage,
284 keep that in mind too.
285
286
287 Class Based Views
288 ==================
289
290 It's pretty common for emails to be sent after a form is submitted. We include a mixin
291 to be used with any view that inherit from Django's FormMixin.
292
293 In your view add the mixin and the usual Django's attributes:
294
295 .. code-block:: python
296
297 from templated_email.generic_views import TemplatedEmailFormViewMixin
298
299 class AuthorCreateView(TemplatedEmailFormViewMixin, CreateView):
300 model = Author
301 fields = ['name', 'email']
302 success_url = '/create_author/'
303 template_name = 'authors/create_author.html'
304
305 By default the template will have the *form_data* if the form is valid or *from_errors* if the
306 form is not valid in it's context.
307
308 You can view an example `here <tests/generic_views/>`_
309
310 Now you can use the following attributes/methods to customize it's behavior:
311
312 Attributes:
313
314 **templated_email_template_name** (mandatory if you don't implement **templated_email_get_template_names()**):
315 String naming the template you want to use for the email.
316 ie: templated_email_template_name = 'welcome'.
317
318 **templated_email_send_on_success** (default: True):
319 This attribute tells django-templated-email to send an email if the form is valid.
320
321 **templated_email_send_on_failure** (default: False):
322 This attribute tells django-templated-email to send an email if the form is invalid.
323
324 **templated_email_from_email** (default: **settings.TEMPLATED_EMAIL_FROM_EMAIL**):
325 String containing the email to send the email from.
326
327 Methods:
328
329 **templated_email_get_template_names(self, valid)** (mandatory if you don't set **templated_email_template_name**):
330 If the method returns a string it will use it as the template to render the email. If it returns a list it will send
331 the email *only* with the first existing template.
332
333 **templated_email_get_recipients(self, form)** (mandatory):
334 Return the recipient list to whom the email will be sent to.
335 ie:
336
337 .. code-block:: python
338
339 def templated_email_get_recipients(self, form):
340 return [form.data['email']]
341
342 **templated_email_get_context_data(**kwargs)** (optional):
343 Use this method to add extra data to the context used for rendering the template. You should get the parent class's context from
344 calling super.
345 ie:
346
347 .. code-block:: python
348
349 def templated_email_get_context_data(self, **kwargs):
350 context = super(ThisClassView, self).templated_email_get_context_data(**kwargs)
351 # add things to context
352 return context
353
354 **templated_email_get_send_email_kwargs(self, valid, form)** (optional):
355 Add or change the kwargs that will be used to send the e-mail. You should call super to get the default kwargs.
356 ie:
357
358 .. code-block:: python
359
360 def templated_email_get_send_email_kwargs(valid, form):
361 kwargs = super(ThisClassView, self).templated_email_get_send_email_kwargs(valid, form)
362 kwargs['bcc'] = ['[email protected]']
363 return kwargs
364
365 **templated_email_send_templated_mail(*args, **kwargs)** (optional):
366 This method calls django-templated-email's *send_templated_mail* method. You could change this method to use
367 a celery's task for example or to handle errors.
368
369
370 Future Plans
371 =============
372
373 See https://github.com/vintasoftware/django-templated-email/issues?state=open
374
375 Using django_templated_email in 3rd party applications
376 =======================================================
377
378 If you would like to use django_templated_email to handle mail in a reusable application, you should note that:
379
380 * Your calls to **send_templated_mail** should set a value for **template_dir**, so you can keep copies of your app-specific templates local to your app (although the loader will find your email templates if you store them in *<your app>/templates/templated_email*, if **TEMPLATED_EMAIL_TEMPLATE_DIR** has not been overridden)
381 * If you do (and you should) set a value for **template_dir**, remember to include a trailing slash, i.e. *'my_app_email/'*
382 * The deployed app may use a different backend which doesn't use the django templating backend, and as such make a note in your README warning developers that if they are using django_templated_email already, with a different backend, they will need to ensure their email provider can send all your templates (ideally enumerate those somewhere convenient)
383
384 Notes on specific backends
385 ==============================
386
387 Using vanilla_django
388 --------------------------
389
390 This is the default backend, and as such requires no special configuration, and will work out of the box. By default it assumes the following settings (should you wish to override them):
391
392 .. code-block:: python
393
394 TEMPLATED_EMAIL_TEMPLATE_DIR = 'templated_email/' #Use '' for top level template dir
395 TEMPLATED_EMAIL_FILE_EXTENSION = 'email'
396
397 For legacy purposes you can specify email subjects in your settings file (but, the preferred method is to use a **{% block subject %}** in your template):
398
399 .. code-block:: python
400
401 TEMPLATED_EMAIL_DJANGO_SUBJECTS = {
402 'welcome':'Welcome to my website',
403 }
404
405 Additionally you can call **send_templated_mail** and optionally override the following parameters::
406
407 template_prefix='your_template_dir/' # Override where the method looks for email templates (alternatively, use template_dir)
408 template_suffix='email' # Override the file extension of the email templates (alternatively, use file_extension)
409 cc=['[email protected]'] # Set a CC on the mail
410 bcc=['[email protected]'] # Set a BCC on the mail
411 template_dir='your_template_dir/' # Override where the method looks for email templates
412 connection=your_connection # Takes a django mail backend connection, created using **django.core.mail.get_connection**
413 auth_user='username' # Override the user that the django mail backend uses, per **django.core.mail.send_mail**
414 auth_password='password' # Override the password that the django mail backend uses, per **django.core.mail.send_mail**
415
416
417 Releasing a new version of this package:
418 ========================================
419
420 Update CHANGELOG file.
421
422 Execute the following commands::
423
424 bumpversion [major,minor,patch]
425 python setup.py publish
426 git push origin --tags
427
428
429 Commercial Support
430 ==================
431
432 This library, as others, is used in projects of Vinta clients. We are always looking for exciting work, so if you need any commercial support, feel free to get in touch: [email protected]
433
434
435
436 .. _Django: http://djangoproject.com
437 .. |GitterBadge| image:: https://badges.gitter.im/vintasoftware/django-templated-email.svg
438 .. _GitterBadge: https://gitter.im/vintasoftware/django-templated-email?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge
439 .. |TravisBadge| image:: https://travis-ci.org/vintasoftware/django-templated-email.svg?branch=develop
440 .. _TravisBadge: https://travis-ci.org/vintasoftware/django-templated-email
441 .. |CoverageBadge| image:: https://coveralls.io/repos/github/vintasoftware/django-templated-email/badge.svg?branch=develop
442 .. _CoverageBadge: https://coveralls.io/github/vintasoftware/django-templated-email?branch=develop
443 .. |PypiversionBadge| image:: https://img.shields.io/pypi/v/django-templated-email.svg
444 .. _PypiversionBadge: https://pypi.python.org/pypi/django-templated-email
445 .. |PythonVersionsBadge| image:: https://img.shields.io/pypi/pyversions/django-templated-email.svg
446 .. _PythonVersionsBadge: https://pypi.python.org/pypi/django-templated-email
447 .. |LicenseBadge| image:: https://img.shields.io/pypi/l/django-templated-email.svg
448 .. _LicenseBadge: https://github.com/vintasoftware/django-templated-email/blob/develop/LICENSE
449
450 Platform: any
451 Classifier: Development Status :: 5 - Production/Stable
452 Classifier: Intended Audience :: Developers
453 Classifier: License :: OSI Approved :: MIT License
454 Classifier: Operating System :: OS Independent
455 Classifier: Programming Language :: Python :: 3.6
456 Classifier: Programming Language :: Python :: 3.7
457 Classifier: Programming Language :: Python :: 3.8
458 Classifier: Programming Language :: Python :: 3.9
459 Classifier: Topic :: Software Development :: Libraries :: Python Modules
460 Classifier: Framework :: Django
461 Description-Content-Type: text/x-rst