From 07c1a00dc15b38f17ab51f50f4f7b14773f290ae Mon Sep 17 00:00:00 2001 From: androiddrew Date: Tue, 30 Jan 2018 10:26:09 -0500 Subject: [PATCH] Added addtional detail to README and correct dealt setting for MAIL_SERVER --- README.md | 73 ++++++++++++++++++++++++++++++++------------ apistar_mail/mail.py | 2 +- 2 files changed, 55 insertions(+), 20 deletions(-) diff --git a/README.md b/README.md index 82016d3..3484a1d 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,7 @@ # apistar-mail --- - `apistar-mail` provides a simple interface to set up SMTP with your APIStar application and send messages from your view functions. Please note this work derives largely from the [flask_mail](https://github.com/mattupstate/flask-mail) extension by 'Dan Jacob' but has been modified extensively to remove Python 2 support and be used as an APIStar component. +Provides a simple interface to set up SMTP with your [APIStar](https://github.com/encode/apistar) application and send messages from your view functions. Please note this work derives largely from the [Flask-Mail](https://github.com/mattupstate/flask-mail) extension by 'Dan Jacob' and contributors, but has been modified extensively to remove Python 2 support and be used as an APIStar component. ## Installation @@ -10,25 +10,39 @@ ## Usage -### Setup +### Example Setup -To send mail messages from your view functions you must include the `MAIL` dictionary in your settings and the mail_component in your component list. +To send mail messages from your view functions you must include the `MAIL` dictionary in your settings, the mail_component in your component list, and the Mail component as a dependency in your view. Here we have a minimally viable app capable of sending an email message and returning a 204 response code: -``` -from apistar import WSGIApp as App -from apistar_mail import mail_component +```python +from apistar import Route +from apistar.frameworks.wsgi import WSGIApp as App +from apistar_mail import mail_component, Mail, Message settings = { 'MAIL': { 'MAIL_SERVER': 'smtp.example.com', - 'MAIL_USERNAME': 'drew@example.com', + 'MAIL_USERNAME': 'me@example.com', 'MAIL_PASSWORD': 'dontcommitthistoversioncontrol', 'MAIL_PORT': 587, 'MAIL_USE_TLS': True, - 'MAIL_DEFAULT_SENDER': 'drew@example.com' + 'MAIL_DEFAULT_SENDER': 'me@example.com' } } + +def send_a_message(mail: Mail): + msg = Message('Hello', + sender='me@example.com', + recipients=['you@example.com']) + mail.send(msg) + return + + +routes = [ + Route('/', 'POST', send_a_message) +] + components = [ mail_component ] @@ -38,18 +52,22 @@ app = App( routes=routes, components=components ) + +if __name__ == '__main__': + app.main() + ``` ### Sending Messages -To send a message first include the Mail component for injection into your view. Then create an instance of Message, and pass it to your Mail component using `mail.send(msg)` +To send a message ,first include the Mail component for injection into your view. Then create an instance of Message, and pass it to your Mail component using `mail.send(msg)` -``` +```python from apistar_mail import Mail, Message def send_a_message(mail:Mail): msg = Message('Hello', - sender='drew@example.com' + sender='drew@example.com', recipients=['you@example.com']) mail.send(msg) return @@ -57,21 +75,21 @@ def send_a_message(mail:Mail): Your message recipients can be set in bulk or individually: -``` +```python msg.recipients = ['you@example.com', 'me@example.com'] msg.add_recipient('otherperson@example.com') ``` If you have set `MAIL_DEFAULT_SENDER` you don’t need to set the message sender explicitly, as it will use this configuration value by default: -``` +```python msg = Message('Hello', recipients=['you@example.com']) ``` The sender can also be passed as a two element tuple containing a name and email address which will be split like so: -``` +```python msg = Message('Hello', sender=('Me', 'me@example.com')) @@ -80,21 +98,38 @@ assert msg.sender == 'Me ' A Message can contain a body and/or HTML: -``` +```python msg.body = 'message body' msg.html = 'Hello apistar_mail!' ``` -### Testing +### Configuration Options + +apistar-mail is configured through the inclusion of the `MAIL` dictionary in your apistar settings. These are the available options: + +* 'MAIL_SERVER': default 'localhost' +* 'MAIL_USERNAME': default None +* 'MAIL_PASSWORD': default None +* 'MAIL_PORT': default 25 +* 'MAIL_USE_TLS': default False +* 'MAIL_USE_SSL': default False +* 'MAIL_DEFAULT_SENDER': default None +* 'MAIL_DEBUG': default False +* 'MAIL_MAX_EMAILS': default None +* 'MAIL_SUPPRESS_SEND': default False +* 'MAIL_ASCII_ATTACHMENTS': False + + +## Testing To run the test suite with coverage first install the package in editable mode with it's testing requirements: -`pip install -e ".[testing]"` +`$ pip install -e ".[testing]"` To run the project's tests -`pytest --cov` +`$ pytest --cov` To run tests against multiple python interpreters use: -`tox` \ No newline at end of file +`$ tox` \ No newline at end of file diff --git a/apistar_mail/mail.py b/apistar_mail/mail.py index 299af76..4cf90db 100644 --- a/apistar_mail/mail.py +++ b/apistar_mail/mail.py @@ -423,7 +423,7 @@ class Mail: settings: The application settings dictionary """ mail_config = settings.get('MAIL') - self.mail_server = mail_config.get('MAIL_SERVER') + self.mail_server = mail_config.get('MAIL_SERVER', 'localhost') self.mail_user = mail_config.get('MAIL_USERNAME') self.mail_password = mail_config.get('MAIL_PASSWORD') self.mail_port = mail_config.get('MAIL_PORT', 25)