Merge pull request #9 from ibnpaul/amqp-refactor

Replace AMQP publisher internals with latest internal version

CHANGELOG.md

@@ -0,0 +1,16 @@
+# Release History
+
+## 2.0.0 (2017-04-20)
+- Move Mixin and AMQP client to separate files
+- Replace AMQP connection handling code with latest internal version
+- Provide ability to register callbacks for ready, unavailable, and persistent failure states
+- Remove default AMQP URL from AMQP class, url is now a required parameter for install
+- Rename amqp_publish 'message' parameter to 'body'
+- Add properties for all AMQP states
+- Provide mandatory AMQP properties (app_id, correlation_id, message_id, timestamp) automatically
+    - Mandatory properties cannot be overridden
+- Add unit test coverage for new functionality
+    - Test execution requires a running AMQP server
+
+## 0.1.0 (2015-09-08)
+- Initial release

README.rst

@@ -25,6 +25,10 @@ Requirements
 
 Example
 -------
+
+You may optionally install ``sprockets.mixins.correlation`` into your request handler to take advantage of automatic correlation_id fetching.
+Otherwise, be sure to set correlation_id as an instance variable on your request handler before sending AMQP messages.
+
 This examples demonstrates the most basic usage of ``sprockets.mixins.amqp``
 
 .. code:: bash
@@ -46,24 +50,48 @@ This examples demonstrates the most basic usage of ``sprockets.mixins.amqp``
                web.url(r'/', RequestHandler),
            ], **settings)
 
-       amqp.install(application)
+       amqp_settings = {
+           "reconnect_delay": 5,
+       }
+
+       amqp.install(application, **amqp_settings)
        return application
 
 
-   class RequestHandler(amqp.PublishingMixin, web.RequestHandler):
+   class RequestHandler(amqp.PublishingMixin,
+                        correlation.HandlerMixin,
+                        web.RequestHandler):
 
        @gen.coroutine
        def get(self, *args, **kwargs):
            body = {'request': self.request.path, 'args': args, 'kwargs': kwargs}
-           yield self.amqp_publish('exchange', 'routing.key', json.dumps(body),
-                                   {'content_type': 'application/json'})
-
-Settings
-^^^^^^^^
-
-:url: The AMQP url
-:timeout: The connect timeout, in seconds, if the connection when you try to publish.
-:connection_attempts: The maximum number of retry attempts in case of connection errors.
+           yield self.amqp_publish(
+               'exchange',
+               'routing.key',
+               json.dumps(body),
+               {'content_type': 'application/json'}
+           )
+
+AMQP Settings
+^^^^^^^^^^^^^
+:url: The AMQP URL to connect to.
+:reconnect_delay: The optional time in seconds to wait before reconnecting on connection failure.
+:timeout: The optional maximum time to wait for a bad state to resolve before treating the failure as persistent.
+:connection_attempts: The optional number of connection attempts to make before giving up.
+:on_ready_callback: The optional callback to call when the connection to the AMQP server has been established and is ready.
+:on_unavailable_callback: The optional callback to call when the connection to the AMQP server becomes unavailable.
+:on_persistent_failure_callback: The optional callback to call when the connection failure does not resolve itself within the timeout.
+:on_message_returned_callback: The optional callback to call when the AMQP server returns a message.
+:ioloop: An optional IOLoop to override the default with.
+
+Environment Variables
+^^^^^^^^^^^^^^^^^^^^^
+Any environment variables set will override the corresponding AMQP settings passed into install()
+
+- AMQP_URL
+- AMQP_TIMEOUT
+- AMQP_RECONNECT_DELAY
+- AMQP_CONNECTION_ATTEMPTS
 
 Source
 ------

requires/testing.txt

@@ -1,4 +1,5 @@
 coverage>=3.7,<4
 nose>=1.3.1,<2.0.0
+mock>=2.0.0,<3
 wheel
 -r installation.txt

setup.py

@@ -1,11 +1,31 @@
 #!/usr/bin/env python
-#
+import os.path
 
 import setuptools
 
+from sprockets.mixins.amqp import __version__
+
+
+def read_requirements(name):
+    requirements = []
+    try:
+        with open(os.path.join('requires', name)) as req_file:
+            for line in req_file:
+                if '#' in line:
+                    line = line[:line.index('#')]
+                line = line.strip()
+                if line.startswith('-r'):
+                    requirements.extend(read_requirements(line[2:].strip()))
+                elif line and not line.startswith('-'):
+                    requirements.append(line)
+    except IOError:
+        pass
+    return requirements
+
+
 setuptools.setup(
     name='sprockets.mixins.amqp',
-    version='1.0.1',
+    version=__version__,
     description='Mixin for publishing events to RabbitMQ',
     long_description=open('README.rst').read(),
     url='https://github.com/sprockets/sprockets.mixins.amqp',
@@ -28,5 +48,5 @@
     ],
     packages=setuptools.find_packages(),
     namespace_packages=['sprockets', 'sprockets.mixins'],
-    install_requires=open('requires/installation.txt').read(),
+    install_requires=read_requirements('installation.txt'),
     zip_safe=True)