Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

Deprecation of Delivery class; renamed to Mailer; fixes #32.

  • Loading branch information...
commit 7f77883a31dbb7f8fb6a59631fed2384dc7dac44 1 parent 3e73500
@amcgregor amcgregor authored
View
8 README.textile
@@ -68,13 +68,13 @@ If you would like to make changes and contribute them back to the project, fork
h2(#basic). %3.% Basic Usage
-To use Marrow Mailer you instantiate a @marrow.mailer.Delivery@ object with the configuration, then pass @Message@ instances to the @Delivery@ instance's @send()@ method. This allows you to configure multiple delivery mechanisms and choose, within your code, how you want each message delivered. The configuration is a dictionary of dot-notation keys and their values. Each manager and transport has their own configuration keys.
+To use Marrow Mailer you instantiate a @marrow.mailer.Mailer@ object with the configuration, then pass @Message@ instances to the @Mailer@ instance's @send()@ method. This allows you to configure multiple delivery mechanisms and choose, within your code, how you want each message delivered. The configuration is a dictionary of dot-notation keys and their values. Each manager and transport has their own configuration keys.
Configuration keys may utilize a shared, common prefix, such as @mail.@. By default no prefix is assumed. Manager and transport configurations are each additionally prefixed with @manager.@ and @transport.@, respectively. The following is an example of how to send a message by SMTP:
-<pre><code>from marrow.mailer import Delivery, Message
+<pre><code>from marrow.mailer import Mailer, Message
-mailer = Delivery(dict(
+mailer = Mailer(dict(
transport = dict(
use = 'smtp',
host = 'localhost')))
@@ -398,7 +398,7 @@ Additionally, a transport must not:
A transport may:
-# Return data from the @deliver()@ method; this data will be passed through as the return value of the @Delivery.send()@ call or Future callback response value.
+# Return data from the @deliver()@ method; this data will be passed through as the return value of the @Mailer.send()@ call or Future callback response value.
h3(#exceptions). %7.3.% Exceptions
View
4 examples/imap.py
@@ -1,8 +1,8 @@
import logging
-from marrow.mailer import Message, Delivery
+from marrow.mailer import Message, Mailer
logging.basicConfig(level=logging.DEBUG)
-mail = Delivery({
+mail = Mailer({
'manager.use': 'futures',
'transport.use': 'imap',
'transport.host': '',
View
4 examples/maildir.py
@@ -1,8 +1,8 @@
import logging
-from marrow.mailer import Message, Delivery
+from marrow.mailer import Message, Mailer
logging.basicConfig(level=logging.INFO)
-mail = Delivery({'manager.use': 'immediate', 'transport.use': 'maildir', 'transport.directory': 'data/maildir'})
+mail = Mailer({'manager.use': 'immediate', 'transport.use': 'maildir', 'transport.directory': 'data/maildir'})
mail.start()
message = Message([('Alice Bevan-McGregor', 'alice@gothcandy.com')], [('Alice Two', 'alice.mcgregor@me.com')], "This is a test message.", plain="Testing!")
View
4 examples/mbox.py
@@ -1,8 +1,8 @@
import logging
-from marrow.mailer import Message, Delivery
+from marrow.mailer import Message, Mailer
logging.basicConfig(level=logging.INFO)
-mail = Delivery({'manager.use': 'immediate', 'transport.use': 'mbox', 'transport.file': 'data/mbox'})
+mail = Mailer({'manager.use': 'immediate', 'transport.use': 'mbox', 'transport.file': 'data/mbox'})
mail.start()
message = Message([('Alice Bevan-McGregor', 'alice@gothcandy.com')], [('Alice Two', 'alice.mcgregor@me.com')], "This is a test message.", plain="Testing!")
View
4 examples/smtp.py
@@ -1,8 +1,8 @@
import logging
-from marrow.mailer import Message, Delivery
+from marrow.mailer import Message, Mailer
logging.basicConfig(level=logging.INFO)
-mail = Delivery({
+mail = Mailer({
'manager.use': 'futures',
'transport.use': 'smtp',
'transport.host': '',
View
17 marrow/mailer/__init__.py
@@ -19,12 +19,12 @@
from marrow.util.object import load_object
-__all__ = ['Delivery', 'Message']
+__all__ = ['Mailer', 'Delivery', 'Message']
log = __import__('logging').getLogger(__name__)
-class Delivery(object):
+class Mailer(object):
"""The primary marrow.mailer interface.
Instantiate and configure marrow.mailer, then use the instance to initiate mail delivery.
@@ -34,7 +34,7 @@ class Delivery(object):
"""
def __repr__(self):
- return "Delivery(manager=%s, transport=%s)" % (self.Manager.__name__, self.Transport.__name__)
+ return "Mailer(manager=%s, transport=%s)" % (self.Manager.__name__, self.Transport.__name__)
def __init__(self, config, prefix=None):
self.manager, self.Manager = None, None
@@ -94,7 +94,7 @@ def _load(spec, group):
def start(self):
if self.running:
- log.warning("Attempt made to start an already running delivery service.")
+ log.warning("Attempt made to start an already running Mailer service.")
return
log.info("Mail delivery service starting.")
@@ -108,7 +108,7 @@ def start(self):
def stop(self):
if not self.running:
- log.warning("Attempt made to stop an already stopped delivery service.")
+ log.warning("Attempt made to stop an already stopped Mailer service.")
return
log.info("Mail delivery service stopping.")
@@ -137,6 +137,13 @@ def send(self, message):
return result
+class Delivery(Mailer):
+ def __init__(self, *args, **kw):
+ import warnings
+ warnings.warn("Use of the Delivery class is deprecated; use Mailer instead.", DeprecationWarning)
+ super(Delivery, self).__init__(*args, **kw)
+
+
# Import-time side-effect: un-fscking the default use of base-64 encoding for UTF-8 e-mail.
charset.add_charset('utf-8', charset.SHORTEST, charset.QP, 'utf-8')
charset.add_charset('utf8', charset.SHORTEST, charset.QP, 'utf8')
View
59 tests/test_core.py
@@ -1,12 +1,13 @@
# encoding: utf-8
-"""Test the primary configurator interface, Delivery."""
+"""Test the primary configurator interface, Mailer."""
import logging
+import warnings
from unittest import TestCase
-from marrow.mailer import Delivery
+from marrow.mailer import Mailer, Delivery
from marrow.mailer.exc import MailerNotRunning
from marrow.mailer.manager.immediate import ImmediateManager
from marrow.mailer.transport.mock import MockTransport
@@ -23,19 +24,31 @@
class TestLookup(TestCase):
def test_load_literal(self):
- self.assertEqual(Delivery._load(ImmediateManager, None), ImmediateManager)
+ self.assertEqual(Mailer._load(ImmediateManager, None), ImmediateManager)
def test_load_dotcolon(self):
- self.assertEqual(Delivery._load('marrow.mailer.manager.immediate:ImmediateManager', None), ImmediateManager)
+ self.assertEqual(Mailer._load('marrow.mailer.manager.immediate:ImmediateManager', None), ImmediateManager)
def test_load_entrypoint(self):
- self.assertEqual(Delivery._load('immediate', 'marrow.mailer.manager'), ImmediateManager)
+ self.assertEqual(Mailer._load('immediate', 'marrow.mailer.manager'), ImmediateManager)
class TestInitialization(TestCase):
+ def test_deprecation(self):
+ with warnings.catch_warnings(record=True) as w:
+ warnings.simplefilter("always")
+
+ Delivery(base_config)
+
+ self.assertEqual(len(w), 1, "No, or more than one, warning issued.")
+ self.assertTrue(issubclass(w[-1].category, DeprecationWarning), "Category of warning is not DeprecationWarning.")
+ self.assertIn('deprecated', str(w[-1].message), "Warning does not include 'deprecated'.")
+ self.assertIn('Mailer', str(w[-1].message), "Warning does not include correct class name.")
+ self.assertIn('Delivery', str(w[-1].message), "Warning does not include old class name.")
+
def test_standard(self):
log.info("Testing configuration: %r", dict(base_config))
- a = Delivery(base_config)
+ a = Mailer(base_config)
self.assertEqual(a.Manager, ImmediateManager)
self.assertEqual(a.Transport, MockTransport)
@@ -43,16 +56,16 @@ def test_standard(self):
def test_bad_manager(self):
config = dict(manager=dict(use=object()), transport=dict(use='mock'))
log.info("Testing configuration: %r", dict(config))
- self.assertRaises(TypeError, Delivery, config)
+ self.assertRaises(TypeError, Mailer, config)
def test_bad_transport(self):
config = dict(manager=dict(use='immediate'), transport=dict(use=object()))
log.info("Testing configuration: %r", dict(config))
- self.assertRaises(TypeError, Delivery, config)
+ self.assertRaises(TypeError, Mailer, config)
def test_repr(self):
- a = Delivery(base_config)
- self.assertEqual(repr(a), "Delivery(manager=ImmediateManager, transport=MockTransport)")
+ a = Mailer(base_config)
+ self.assertEqual(repr(a), "Mailer(manager=ImmediateManager, transport=MockTransport)")
def test_prefix(self):
config = {
@@ -61,7 +74,7 @@ def test_prefix(self):
}
log.info("Testing configuration: %r", dict(config))
- a = Delivery(config, 'mail')
+ a = Mailer(config, 'mail')
self.assertEqual(a.Manager, ImmediateManager)
self.assertEqual(a.Transport, MockTransport)
@@ -73,7 +86,7 @@ def test_deep_prefix(self):
}
log.info("Testing configuration: %r", dict(config))
- a = Delivery(config, 'marrow.mailer')
+ a = Mailer(config, 'marrow.mailer')
self.assertEqual(a.Manager, ImmediateManager)
self.assertEqual(a.Transport, MockTransport)
@@ -85,7 +98,7 @@ def test_manager_entrypoint_failure(self):
}
log.info("Testing configuration: %r", dict(config))
- self.assertRaises(LookupError, Delivery, config)
+ self.assertRaises(LookupError, Mailer, config)
def test_manager_dotcolon_failure(self):
config = {
@@ -94,11 +107,11 @@ def test_manager_dotcolon_failure(self):
}
log.info("Testing configuration: %r", dict(config))
- self.assertRaises(ImportError, Delivery, config)
+ self.assertRaises(ImportError, Mailer, config)
config['manager.use'] = 'marrow.mailer.manager.immediate:FooManager'
log.info("Testing configuration: %r", dict(config))
- self.assertRaises(AttributeError, Delivery, config)
+ self.assertRaises(AttributeError, Mailer, config)
def test_transport_entrypoint_failure(self):
config = {
@@ -107,7 +120,7 @@ def test_transport_entrypoint_failure(self):
}
log.info("Testing configuration: %r", dict(config))
- self.assertRaises(LookupError, Delivery, config)
+ self.assertRaises(LookupError, Mailer, config)
def test_transport_dotcolon_failure(self):
config = {
@@ -116,18 +129,18 @@ def test_transport_dotcolon_failure(self):
}
log.info("Testing configuration: %r", dict(config))
- self.assertRaises(ImportError, Delivery, config)
+ self.assertRaises(ImportError, Mailer, config)
config['manager.use'] = 'marrow.mailer.transport.mock:FooTransport'
log.info("Testing configuration: %r", dict(config))
- self.assertRaises(AttributeError, Delivery, config)
+ self.assertRaises(AttributeError, Mailer, config)
class TestMethods(TestCase):
def test_startup(self):
messages = logging.getLogger().handlers[0].buffer
- interface = Delivery(base_config)
+ interface = Mailer(base_config)
interface.start()
self.assertEqual(len(messages), 5)
@@ -137,12 +150,12 @@ def test_startup(self):
interface.start()
self.assertEqual(len(messages), 6)
- self.assertEqual(messages[-1].getMessage(), "Attempt made to start an already running delivery service.")
+ self.assertEqual(messages[-1].getMessage(), "Attempt made to start an already running Mailer service.")
interface.stop()
def test_shutdown(self):
- interface = Delivery(base_config)
+ interface = Mailer(base_config)
interface.start()
logging.getLogger().handlers[0].truncate()
@@ -157,12 +170,12 @@ def test_shutdown(self):
interface.stop()
self.assertEqual(len(messages), 6)
- self.assertEqual(messages[-1].getMessage(), "Attempt made to stop an already stopped delivery service.")
+ self.assertEqual(messages[-1].getMessage(), "Attempt made to stop an already stopped Mailer service.")
def test_send(self):
message = Bunch(id='foo')
- interface = Delivery(base_config)
+ interface = Mailer(base_config)
self.assertRaises(MailerNotRunning, interface.send, message)
View
6 tests/test_issue_2.py
@@ -7,7 +7,7 @@
from unittest import TestCase
from nose.tools import ok_, eq_, raises
-from marrow.mailer import Delivery
+from marrow.mailer import Mailer
log = logging.getLogger('tests')
@@ -15,8 +15,8 @@
def test_issue_2():
- mail = Delivery({
- 'manager': 'immediate',
+ mail = Mailer({
+ 'manager.use': 'immediate',
'transport.use': 'smtp',
'transport.host': 'secure.emailsrvr.com',
'transport.tls': 'ssl'
View
2  tests/test_message.py
@@ -13,7 +13,7 @@
from email.mime.text import MIMEText
from email.utils import formatdate, parsedate_tz
-from marrow.mailer import Delivery, Message
+from marrow.mailer import Message
from marrow.mailer.address import AddressList
from nose.tools import raises
Please sign in to comment.
Something went wrong with that request. Please try again.