documentation minor updates
This commit is contained in:
parent
27bf2546cf
commit
f887803832
2
LICENSE
2
LICENSE
|
@ -1,4 +1,4 @@
|
||||||
Copyright 2013 Sergey Lavrinenko
|
Copyright 2013-2015 Sergey Lavrinenko
|
||||||
|
|
||||||
Licensed under the Apache License, Version 2.0 (the "License");
|
Licensed under the Apache License, Version 2.0 (the "License");
|
||||||
you may not use this file except in compliance with the License.
|
you may not use this file except in compliance with the License.
|
||||||
|
|
225
README.rst
225
README.rst
|
@ -1,220 +1,39 @@
|
||||||
python-emails
|
python-emails
|
||||||
=============
|
~~~~~~~~~~~~~
|
||||||
|
|
||||||
Modern email handling in python.
|
Modern python library for email.
|
||||||
|
|
||||||
|
Build message:
|
||||||
|
|
||||||
.. code-block:: python
|
.. code-block:: python
|
||||||
|
|
||||||
m = emails.Message(html=T("<html><p>Build passed: {{ project_name }} <img src='cid:icon.png'> ..."),
|
>>> import emails
|
||||||
text=T("Build passed: {{ project_name }} ..."),
|
>>> message = emails.html(html="<p>Hi!<br>Here is your receipt...",
|
||||||
subject=T("Passed: {{ project_name }}#{{ build_id }}"),
|
subject="Your receipt No. 567098123",
|
||||||
mail_from=("CI", "ci@mycompany.com"))
|
mail_from=('Some Store', 'store@somestore.com'))
|
||||||
m.attach(filename="icon.png", content_disposition="inline", data=open("icon.png"))
|
>>> message.attach(data=open('bill.pdf'), filename='bill.pdf')
|
||||||
response = m.send(render={"project_name": "user/project1", "build_id": 121},
|
|
||||||
to='somebody@mycompany.com',
|
|
||||||
smtp={"host":"mx.mycompany.com", "port": 25})
|
|
||||||
|
|
||||||
if response.status_code not in [250, ]:
|
send message and get response from smtp server:
|
||||||
# message is not sent, retry later
|
|
||||||
...
|
|
||||||
|
|
||||||
See `the same code, without Emails <https://gist.github.com/lavr/fc1972c125ccaf4d4b91>`_.
|
|
||||||
|
|
||||||
Emails code is not much simpler than `the same code in django <https://gist.github.com/lavr/08708b15d33fc2ad718b>`_,
|
|
||||||
but it is still more elegant, can be used in django environment and has html transformation methods
|
|
||||||
(see ``HTML Transformer`` section).
|
|
||||||
|
|
||||||
|
|
||||||
Features
|
|
||||||
--------
|
|
||||||
|
|
||||||
- HTML-email message abstraction
|
|
||||||
- Method to transform html body:
|
|
||||||
|
|
||||||
- css inlining (using peterbe's premailer)
|
|
||||||
- image inlining
|
|
||||||
- DKIM signature
|
|
||||||
- Message loaders
|
|
||||||
- Send directly or via django email backend
|
|
||||||
|
|
||||||
|
|
||||||
Examples
|
|
||||||
--------
|
|
||||||
|
|
||||||
Create message:
|
|
||||||
|
|
||||||
.. code-block:: python
|
.. code-block:: python
|
||||||
|
|
||||||
import emails
|
>>> r = message.send(to='s@lavr.me', smtp={'host': 'aspmx.l.google.com', 'timeout': 5})
|
||||||
message = emails.html(html=open('letter.html'),
|
>>> assert r.status_code == 250
|
||||||
subject='Friday party',
|
|
||||||
mail_from=('Company Team', 'contact@mycompany.com'))
|
|
||||||
|
|
||||||
|
and more:
|
||||||
|
|
||||||
Attach files or inline images:
|
* DKIM signature
|
||||||
|
* Render body from template
|
||||||
|
* Flask extension and Django integration
|
||||||
|
* Message body transformation methods
|
||||||
|
* Load message from url or from file
|
||||||
|
|
||||||
.. code-block:: python
|
|
|
||||||
|
|
||||||
message.attach(data=open('event.ics'), filename='Event.ics')
|
See **documentation** on `python-emails.readthedocs.org <http://python-emails.readthedocs.org/>`_
|
||||||
message.attach(data=open('image.png'), filename='image.png',
|
|
||||||
content_disposition='inline')
|
|
||||||
|
|
||||||
Use templates:
|
|
|
||||||
|
|
|
||||||
.. code-block:: python
|
|
||||||
|
|
||||||
from emails.template import JinjaTemplate as T
|
|
||||||
|
|
||||||
message = emails.html(subject=T('Payment Receipt No.{{ billno }}'),
|
|
||||||
html=T('<p>Dear {{ name }}! This is a receipt...'),
|
|
||||||
mail_from=('ABC', 'robot@mycompany.com'))
|
|
||||||
|
|
||||||
message.send(to=('John Brown', 'jbrown@gmail.com'),
|
|
||||||
render={'name': 'John Brown', 'billno': '141051906163'})
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
Add DKIM signature:
|
|
||||||
|
|
||||||
.. code-block:: python
|
|
||||||
|
|
||||||
message.dkim(key=open('my.key'), domain='mycompany.com', selector='newsletter')
|
|
||||||
|
|
||||||
Generate email.message or rfc822 string:
|
|
||||||
|
|
||||||
.. code-block:: python
|
|
||||||
|
|
||||||
m = message.as_message()
|
|
||||||
s = message.as_string()
|
|
||||||
|
|
||||||
|
|
||||||
Send and get response from smtp server:
|
|
||||||
|
|
||||||
.. code-block:: python
|
|
||||||
|
|
||||||
r = message.send(to=('John Brown', 'jbrown@gmail.com'),
|
|
||||||
render={'field1': 'X'},
|
|
||||||
smtp={'host':'smtp.mycompany.com', 'port': 465, 'ssl': True})
|
|
||||||
assert r.status_code == 250
|
|
||||||
|
|
||||||
|
|
||||||
Django
|
|
||||||
------
|
|
||||||
|
|
||||||
DjangoMessage helper sends via django configured email backend:
|
|
||||||
|
|
||||||
.. code-block:: python
|
|
||||||
|
|
||||||
from emails.django_ import DjangoMessage as Message
|
|
||||||
message = Message(...)
|
|
||||||
message.send(mail_to=('John Brown', 'jbrown@gmail.com'),
|
|
||||||
context={'field1': 'X'})
|
|
||||||
|
|
||||||
Flask
|
|
||||||
-----
|
|
||||||
|
|
||||||
For flask integration take a look at `flask-emails <https://github.com/lavr/flask-emails>`_
|
|
||||||
|
|
||||||
|
|
||||||
HTML transformer
|
|
||||||
----------------
|
|
||||||
|
|
||||||
Message HTML body can be modified with 'transformer' object:
|
|
||||||
|
|
||||||
.. code-block:: python
|
|
||||||
|
|
||||||
>>> message = emails.Message(html="<img src='promo.png'>")
|
|
||||||
>>> message.transformer.apply_to_images(func=lambda src, **kw: 'http://mycompany.tld/images/'+src)
|
|
||||||
>>> message.transformer.save()
|
|
||||||
>>> message.html
|
|
||||||
u'<html><body><img src="http://mycompany.tld/images/promo.png"></body></html>'
|
|
||||||
|
|
||||||
Code example to make images inline:
|
|
||||||
|
|
||||||
.. code-block:: python
|
|
||||||
|
|
||||||
>>> message = emails.Message(html="<img src='promo.png'>")
|
|
||||||
>>> message.attach(filename='promo.png', data=open('promo.png'))
|
|
||||||
>>> message.attachments['promo.png'].is_inline = True
|
|
||||||
>>> message.transformer.synchronize_inline_images()
|
|
||||||
>>> message.transformer.save()
|
|
||||||
>>> message.html
|
|
||||||
u'<html><body><img src="cid:promo.png"></body></html>'
|
|
||||||
|
|
||||||
|
|
||||||
Loaders
|
|
||||||
-------
|
|
||||||
|
|
||||||
python-emails ships with couple of loaders.
|
|
||||||
|
|
||||||
Load message from url:
|
|
||||||
|
|
||||||
.. code-block:: python
|
|
||||||
|
|
||||||
import emails.loader
|
|
||||||
message = emails.loader.from_url(url="http://xxx.github.io/newsletter/2015-08-14/index.html")
|
|
||||||
|
|
||||||
|
|
||||||
Load from zipfile or directory:
|
|
||||||
|
|
||||||
.. code-block:: python
|
|
||||||
|
|
||||||
message = emails.loader.from_zipfile(open('design_pack.zip'))
|
|
||||||
message = emails.loader.from_directory('/home/user/design_pack')
|
|
||||||
|
|
||||||
Zipfile and directory loaders require at least one html file (with "html" extension).
|
|
||||||
|
|
||||||
|
|
||||||
Install
|
|
||||||
-------
|
|
||||||
|
|
||||||
Install from pypi:
|
|
||||||
|
|
||||||
.. code-block:: bash
|
|
||||||
|
|
||||||
$ [sudo] pip install emails
|
|
||||||
|
|
||||||
Install on Ubuntu from PPA:
|
|
||||||
|
|
||||||
.. code-block:: bash
|
|
||||||
|
|
||||||
$ [sudo] add-apt-repository ppa:lavrme/python-emails-ppa
|
|
||||||
$ [sudo] apt-get update
|
|
||||||
$ [sudo] apt-get install python-emails
|
|
||||||
|
|
||||||
|
|
||||||
TODO
|
|
||||||
----
|
|
||||||
|
|
||||||
- Documentation
|
|
||||||
- Increase test coverage
|
|
||||||
- Feature: load message from rfc2822
|
|
||||||
- Feature: export message to directory or zipfile
|
|
||||||
- Distribution: deb package (`debianization example <https://github.com/lavr/python-emails-debian/>`_)
|
|
||||||
- Distribution: rpm package
|
|
||||||
- Other: Flask extension
|
|
||||||
- Feature: ESP integration - Amazon SES, SendGrid, ...
|
|
||||||
|
|
||||||
|
|
||||||
How to Help
|
|
||||||
-----------
|
|
||||||
|
|
||||||
Library is under development and contributions are welcome.
|
|
||||||
|
|
||||||
1. Open an issue to start a discussion around a bug or a feature.
|
|
||||||
2. Fork the repository on GitHub and start making your changes to a new branch.
|
|
||||||
3. Write a test which shows that the bug was fixed.
|
|
||||||
4. Send a pull request. Make sure to add yourself to `AUTHORS <https://github.com/lavr/python-emails/blob/master/README.rst>`_.
|
|
||||||
|
|
||||||
|
|
||||||
See also
|
|
||||||
--------
|
|
||||||
|
|
||||||
There are plenty other python email-around libraries that may fit your needs:
|
|
||||||
|
|
||||||
- `premailer <https://github.com/peterbe/premailer>`_
|
|
||||||
- `flask-mail <https://github.com/mattupstate/flask-mail>`_
|
|
||||||
- `pyzmail <http://www.magiksys.net/pyzmail/>`_
|
|
||||||
|
|
||||||
.. image:: https://travis-ci.org/lavr/python-emails.png?branch=master
|
.. image:: https://travis-ci.org/lavr/python-emails.png?branch=master
|
||||||
:target: https://travis-ci.org/lavr/python-emails
|
:target: https://travis-ci.org/lavr/python-emails
|
||||||
|
|
|
@ -10,6 +10,7 @@ html_sidebars = {
|
||||||
html_theme_options = {
|
html_theme_options = {
|
||||||
'github_user': 'lavr',
|
'github_user': 'lavr',
|
||||||
'github_repo': 'python-emails',
|
'github_repo': 'python-emails',
|
||||||
|
'github_banner': True,
|
||||||
'travis_button': True,
|
'travis_button': True,
|
||||||
'code_font_size': '0.8em'
|
'code_font_size': '0.8em'
|
||||||
}
|
}
|
||||||
|
|
|
@ -66,7 +66,7 @@ Send and get response from smtp server:
|
||||||
.. code-block:: python
|
.. code-block:: python
|
||||||
|
|
||||||
r = message.send(to=('John Brown', 'jbrown@gmail.com'),
|
r = message.send(to=('John Brown', 'jbrown@gmail.com'),
|
||||||
render={'field1': 'X'},
|
render={'name': 'John'},
|
||||||
smtp={'host':'smtp.mycompany.com', 'port': 465, 'ssl': True})
|
smtp={'host':'smtp.mycompany.com', 'port': 465, 'ssl': True})
|
||||||
assert r.status_code == 250
|
assert r.status_code == 250
|
||||||
|
|
||||||
|
|
|
@ -36,3 +36,5 @@ but it is still more elegant, can be used in django environment and has html tra
|
||||||
.. include:: todo.rst
|
.. include:: todo.rst
|
||||||
|
|
||||||
.. include:: howtohelp.rst
|
.. include:: howtohelp.rst
|
||||||
|
|
||||||
|
.. include:: links.rst
|
||||||
|
|
|
@ -7,17 +7,3 @@ There are plenty other python email-around libraries that may fit your needs:
|
||||||
- `premailer <https://github.com/peterbe/premailer>`_
|
- `premailer <https://github.com/peterbe/premailer>`_
|
||||||
- `flask-mail <https://github.com/mattupstate/flask-mail>`_
|
- `flask-mail <https://github.com/mattupstate/flask-mail>`_
|
||||||
- `pyzmail <http://www.magiksys.net/pyzmail/>`_
|
- `pyzmail <http://www.magiksys.net/pyzmail/>`_
|
||||||
|
|
||||||
.. image:: https://travis-ci.org/lavr/python-emails.png?branch=master
|
|
||||||
:target: https://travis-ci.org/lavr/python-emails
|
|
||||||
|
|
||||||
.. image:: https://img.shields.io/pypi/v/emails.svg
|
|
||||||
:target: https://pypi.python.org/pypi/emails
|
|
||||||
|
|
||||||
.. image:: http://allmychanges.com/p/python/emails/badge/
|
|
||||||
:target: http://allmychanges.com/p/python/emails/?utm_source=badge
|
|
||||||
|
|
||||||
.. image:: https://coveralls.io/repos/lavr/python-emails/badge.svg?branch=master
|
|
||||||
:target: https://coveralls.io/r/lavr/python-emails?branch=master
|
|
||||||
|
|
||||||
|
|
||||||
|
|
|
@ -1,27 +1,42 @@
|
||||||
# coding: utf-8
|
# coding: utf-8
|
||||||
from __future__ import unicode_literals
|
|
||||||
"""
|
"""
|
||||||
python emails library
|
python-emails
|
||||||
~~~~~~~~~~~~~~~~~~~~~
|
~~~~~~~~~~~~~
|
||||||
|
|
||||||
emails is a python library for dealing with html-emails.
|
Modern python library for email.
|
||||||
|
|
||||||
Usage:
|
Build message:
|
||||||
|
|
||||||
>>> import emails
|
>>> import emails
|
||||||
>>> message = emails.html(html="<p>Hi!<br>Here is your receipt...",
|
>>> message = emails.html(html="<p>Hi!<br>Here is your receipt...",
|
||||||
subject="Your receipt No. 567098123",
|
subject="Your receipt No. 567098123",
|
||||||
mail_from=('Some Store', 'store@somestore.com'))
|
mail_from=('Some Store', 'store@somestore.com'))
|
||||||
>>> message.send( to = 's@lavr.me', smtp={ 'host': 'aspmx.l.google.com' } )
|
>>> message.attach(data=open('bill.pdf'), filename='bill.pdf')
|
||||||
|
|
||||||
|
send message and get response from smtp server:
|
||||||
|
|
||||||
|
>>> r = message.send(to='s@lavr.me', smtp={'host': 'aspmx.l.google.com', 'timeout': 5})
|
||||||
|
>>> assert r.status_code == 250
|
||||||
|
|
||||||
|
and more:
|
||||||
|
|
||||||
|
* DKIM signature
|
||||||
|
* Render body from template
|
||||||
|
* Flask extension and Django integration
|
||||||
|
* Message body transformation methods
|
||||||
|
* Load message from url or from file
|
||||||
|
|
||||||
|
|
||||||
More examples is at <https://github.com/lavr/python-emails/README.rst>.
|
Links
|
||||||
|
`````
|
||||||
|
|
||||||
:copyright: (c) 2013 by Sergey Lavrinenko.
|
* `documentation <http://python-emails.readthedocs.org/>`_
|
||||||
:license: Apache 2.0, see LICENSE for more details.
|
* `source code <http://github.com/lavr/python-emails>`_
|
||||||
|
|
||||||
"""
|
"""
|
||||||
|
|
||||||
|
from __future__ import unicode_literals
|
||||||
|
|
||||||
__title__ = 'emails'
|
__title__ = 'emails'
|
||||||
__version__ = '0.4.2'
|
__version__ = '0.4.2'
|
||||||
__author__ = 'Sergey Lavrinenko'
|
__author__ = 'Sergey Lavrinenko'
|
||||||
|
|
38
setup.py
38
setup.py
|
@ -1,5 +1,41 @@
|
||||||
#!/usr/bin/env python
|
#!/usr/bin/env python
|
||||||
# -*- coding: utf-8 -*-
|
# -*- coding: utf-8 -*-
|
||||||
|
"""
|
||||||
|
python-emails
|
||||||
|
~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
Modern python library for email.
|
||||||
|
|
||||||
|
Build message:
|
||||||
|
|
||||||
|
>>> import emails
|
||||||
|
>>> message = emails.html(html="<p>Hi!<br>Here is your receipt...",
|
||||||
|
subject="Your receipt No. 567098123",
|
||||||
|
mail_from=('Some Store', 'store@somestore.com'))
|
||||||
|
>>> message.attach(data=open('bill.pdf'), filename='bill.pdf')
|
||||||
|
|
||||||
|
send message and get response from smtp server:
|
||||||
|
|
||||||
|
>>> r = message.send(to='s@lavr.me', smtp={'host': 'aspmx.l.google.com', 'timeout': 5})
|
||||||
|
>>> assert r.status_code == 250
|
||||||
|
|
||||||
|
and more:
|
||||||
|
|
||||||
|
* DKIM signature
|
||||||
|
* Render body from template
|
||||||
|
* Flask extension and Django integration
|
||||||
|
* Message body transformation methods
|
||||||
|
* Load message from url or from file
|
||||||
|
|
||||||
|
|
||||||
|
Links
|
||||||
|
`````
|
||||||
|
|
||||||
|
* `documentation <http://python-emails.readthedocs.org/>`_
|
||||||
|
* `source code <http://github.com/lavr/python-emails>`_
|
||||||
|
|
||||||
|
"""
|
||||||
|
|
||||||
import codecs
|
import codecs
|
||||||
import os
|
import os
|
||||||
import re
|
import re
|
||||||
|
@ -72,7 +108,7 @@ def find_version(*file_paths):
|
||||||
settings.update(
|
settings.update(
|
||||||
name='emails',
|
name='emails',
|
||||||
version=find_version('emails/__init__.py'),
|
version=find_version('emails/__init__.py'),
|
||||||
description='Elegant and simple email library for python 2/3',
|
description='Modern python library for emails.',
|
||||||
long_description=open('README.rst').read(),
|
long_description=open('README.rst').read(),
|
||||||
author='Sergey Lavrinenko',
|
author='Sergey Lavrinenko',
|
||||||
author_email='s@lavr.me',
|
author_email='s@lavr.me',
|
||||||
|
|
Reference in New Issue