diff --git a/LICENSE b/LICENSE index b2f4c07..ea7608c 100644 --- a/LICENSE +++ b/LICENSE @@ -1,4 +1,4 @@ -Copyright 2013 Sergey Lavrinenko +Copyright 2013-2015 Sergey Lavrinenko Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. diff --git a/README.rst b/README.rst index c283306..db2d258 100644 --- a/README.rst +++ b/README.rst @@ -1,220 +1,39 @@ python-emails -============= +~~~~~~~~~~~~~ -Modern email handling in python. +Modern python library for email. + +Build message: .. code-block:: python - m = emails.Message(html=T("

Build passed: {{ project_name }} ..."), - text=T("Build passed: {{ project_name }} ..."), - subject=T("Passed: {{ project_name }}#{{ build_id }}"), - mail_from=("CI", "ci@mycompany.com")) - m.attach(filename="icon.png", content_disposition="inline", data=open("icon.png")) - response = m.send(render={"project_name": "user/project1", "build_id": 121}, - to='somebody@mycompany.com', - smtp={"host":"mx.mycompany.com", "port": 25}) + >>> import emails + >>> message = emails.html(html="

Hi!
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') - if response.status_code not in [250, ]: - # message is not sent, retry later - ... - -See `the same code, without Emails `_. - -Emails code is not much simpler than `the same code in django `_, -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: +send message and get response from smtp server: .. code-block:: python - import emails - message = emails.html(html=open('letter.html'), - subject='Friday party', - mail_from=('Company Team', 'contact@mycompany.com')) + >>> r = message.send(to='s@lavr.me', smtp={'host': 'aspmx.l.google.com', 'timeout': 5}) + >>> assert r.status_code == 250 +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') - message.attach(data=open('image.png'), filename='image.png', - content_disposition='inline') +See **documentation** on `python-emails.readthedocs.org `_ -Use templates: - -.. code-block:: python - - from emails.template import JinjaTemplate as T - - message = emails.html(subject=T('Payment Receipt No.{{ billno }}'), - html=T('

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 `_ - - -HTML transformer ----------------- - -Message HTML body can be modified with 'transformer' object: - -.. code-block:: python - - >>> message = emails.Message(html="") - >>> message.transformer.apply_to_images(func=lambda src, **kw: 'http://mycompany.tld/images/'+src) - >>> message.transformer.save() - >>> message.html - u'' - -Code example to make images inline: - -.. code-block:: python - - >>> message = emails.Message(html="") - >>> 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'' - - -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 `_) -- 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 `_. - - -See also --------- - -There are plenty other python email-around libraries that may fit your needs: - - - `premailer `_ - - `flask-mail `_ - - `pyzmail `_ +| +| .. image:: https://travis-ci.org/lavr/python-emails.png?branch=master :target: https://travis-ci.org/lavr/python-emails diff --git a/docs/conf_theme_alabaster.py b/docs/conf_theme_alabaster.py index de45467..7963f9d 100644 --- a/docs/conf_theme_alabaster.py +++ b/docs/conf_theme_alabaster.py @@ -10,6 +10,7 @@ html_sidebars = { html_theme_options = { 'github_user': 'lavr', 'github_repo': 'python-emails', + 'github_banner': True, 'travis_button': True, 'code_font_size': '0.8em' } diff --git a/docs/examples.rst b/docs/examples.rst index f7cdeab..3684a7d 100644 --- a/docs/examples.rst +++ b/docs/examples.rst @@ -66,7 +66,7 @@ Send and get response from smtp server: .. code-block:: python r = message.send(to=('John Brown', 'jbrown@gmail.com'), - render={'field1': 'X'}, + render={'name': 'John'}, smtp={'host':'smtp.mycompany.com', 'port': 465, 'ssl': True}) assert r.status_code == 250 diff --git a/docs/index.rst b/docs/index.rst index f83f39f..21702d8 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -36,3 +36,5 @@ but it is still more elegant, can be used in django environment and has html tra .. include:: todo.rst .. include:: howtohelp.rst + +.. include:: links.rst diff --git a/docs/links.rst b/docs/links.rst index e19624c..fd6482a 100644 --- a/docs/links.rst +++ b/docs/links.rst @@ -7,17 +7,3 @@ There are plenty other python email-around libraries that may fit your needs: - `premailer `_ - `flask-mail `_ - `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 - - diff --git a/emails/__init__.py b/emails/__init__.py index 20e1fb2..8c2d6ed 100644 --- a/emails/__init__.py +++ b/emails/__init__.py @@ -1,27 +1,42 @@ # 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 >>> message = emails.html(html="

Hi!
Here is your receipt...", subject="Your receipt No. 567098123", 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 . +Links +````` -:copyright: (c) 2013 by Sergey Lavrinenko. -:license: Apache 2.0, see LICENSE for more details. +* `documentation `_ +* `source code `_ """ +from __future__ import unicode_literals + __title__ = 'emails' __version__ = '0.4.2' __author__ = 'Sergey Lavrinenko' diff --git a/setup.py b/setup.py index 35794d1..8967e33 100644 --- a/setup.py +++ b/setup.py @@ -1,5 +1,41 @@ #!/usr/bin/env python # -*- coding: utf-8 -*- +""" +python-emails +~~~~~~~~~~~~~ + +Modern python library for email. + +Build message: + + >>> import emails + >>> message = emails.html(html="

Hi!
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 `_ +* `source code `_ + +""" + import codecs import os import re @@ -72,7 +108,7 @@ def find_version(*file_paths): settings.update( name='emails', 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(), author='Sergey Lavrinenko', author_email='s@lavr.me',