Factored stompest.async out of the core library.

CHANGES.txt

@@ -4,4 +4,5 @@
 * 2.0a1 - Complete redesign: feature-complete implementation of STOMP 1.0 and 1.1. Broker failover. Decoupled from [stomper](http://code.google.com/p/stomper/).
 * 2.0a2 - Heart-beating.
 * 2.0a3 - Implementation of STOMP 1.2 (except repeated header entries). Support for UTF-8 headers and escaping of header delimiting characters (STOMP 1.1 and 1.2).
-* 2.0a4 - Improved STOMP protocol version. Minor incompatible changes of the low-level API (protocol.session and protocol.commands). Bugfixes headers encoding.
+* 2.0a4 - Improved STOMP protocol version. Minor incompatible changes of the low-level API (protocol.session and protocol.commands). Bugfixes headers encoding.
+* 2.0a5 - Factored out stompest.async into a separate PyPI package to make the stompest library self-consistent.

doc/source/conf.py

@@ -12,13 +12,14 @@
 # serve to show the default.
 
 import os, sys
-sys.path.insert(0, '../..')
+for path in ('async', 'core'):
+    sys.path.insert(0, os.path.join('../../src', path))
 
 import stompest
 import stompest.sync
-import stompest.examples.sync
+import stompest.sync.examples
 import stompest.async
-import stompest.examples.async
+import stompest.async.examples
 import stompest.config
 import stompest.protocol
 import stompest.error
@@ -194,7 +195,7 @@
 # (source start file, target name, title, author, documentclass [howto/manual]).
 latex_documents = [
   ('index', 'stompest.tex', u'stompest Documentation',
-   u'Roger Hoover, Jan Müller', 'manual'),
+   u'Jan Müller, Roger Hoover', 'manual'),
 ]
 
 # The name of an image file (relative to this directory) to place at the top of

doc/source/readme.txt

@@ -1,36 +1 @@
-stomp, stomper, stompest!
-=========================
-
-`stompest <https://github.com/nikipore/stompest/>`_ is a full-featured implementation of the `STOMP <http://stomp.github.com/>`_ protocol (versions `1.0 <http://stomp.github.com//stomp-specification-1.0.html>`_, `1.1 <http://stomp.github.com//stomp-specification-1.1.html>`_, and `1.2 <http://stomp.github.com//stomp-specification-1.2.html>`_) for Python 2.6 (and higher) including both synchronous and asynchronous clients:
-
-* The synchronous client is dead simple. It does not assume anything about your concurrency model (thread vs process) or force you to use it any particular way. It gets out of your way and lets you do what you want.
-* The asynchronous client is based on `Twisted <http://twistedmatrix.com/>`_, a very mature and powerful asynchronous programming framework. It supports destination specific message and error handlers (with default "poison pill" error handling), concurrent message processing, graceful shutdown, and connect, receipt, and disconnect timeouts.
-
-Both clients make use of a generic set of components each of which you may use independently to roll your own STOMP client:
-
-* a wire-level STOMP frame parser and compiler,
-
-* a faithful implementation of the syntax of the STOMP protocol with a simple stateless function API,
-
-* a generic implementation of the STOMP session state semantics, such as protocol version negotiation at connect time, transaction and subscription handling (including a generic subscription replay scheme which may be used to reconstruct the session's subscription state after a forced disconnect),
-
-* and a `failover transport <http://activemq.apache.org/failover-transport-reference.html>`_ URI scheme akin to the one used in ActiveMQ.
-
-This package is thoroughly unit tested and (in version 1.x) production hardened for the functionality used by `Mozes <http://www.mozes.com/>`_ --- persistent queueing on `ActiveMQ <http://activemq.apache.org/>`_. The substantially redesigned stompest 2 is probably even better tested but should be considered (mature) alpha: Some features to come (for instance, `Support for repeated header entries in STOMP 1.2 <https://github.com/nikipore/stompest/issues/8>`_) may still require minor changes of the API.
-
-The package is tested with Python 2.6 and 2.7, Twisted 11.0 and 12.0 (it should work with Twisted 10.1 and higher), and ActiveMQ 5.5.1, 5.6, 5.7, 5.8. The integration tests also pass against `RabbitMQ <http://www.rabbitmq.com/>`_ 3.0.2 and `Apollo <http://activemq.apache.org/apollo/>`_ 1.5. All of these brokers were tested with STOMP protocols 1.0, 1.1, and 1.2 (if applicable). Minor enhancements may be required to use this STOMP adapter with other brokers.
-
-Installation
-============
-
-* If you do not wish to use the asynchronous client (which depends on Twisted), stompest is a single, and fully self-contained, plain Python package.
-* You may install stompest using any of the follwoing commands: ``easy_install stompest``, ``pip install stompest``, or ``python setup.py install``.
-
-Questions or Suggestions?
-=========================
-Feel free to `open an issue <https://github.com/nikipore/stompest/issues/>`_ or post a question on the `forum <http://groups.google.com/group/stompest/>`_.
-
-Acknowledgements
-================
-* Version 1.x of stompest was written by `Roger Hoover <http://github.com/theduderog/>`_ at `Mozes <http://www.mozes.com/>`_ and deployed in their production environment.
-* Kudos to `Oisin Mulvihill <https://github.com/oisinmulvihill/>`_, the developer of `stomper <http://code.google.com/p/stomper/>`_! The idea of an abstract representation of the STOMP protocol lives on in stompest.
+.. include:: ../../src/core/README.txt

Makefile → src/async/Makefile

@@ -23,5 +23,5 @@ check:
 
 clean:
 	$(PYTHON) setup.py clean
-	rm -rf dist/ readme.html stompest.egg-info/
+	rm -rf build/ dist/ readme.html *.egg-info/
 	find . -name '*.pyc' -delete

src/async/README.txt

@@ -0,0 +1,22 @@
+stomp, stomper, stompest!
+=========================
+
+This package provides the asynchronous STOMP client based upon the `stompest <https://pypi.python.org/pypi/stompest/>`_ library. It leverages the power of `Twisted <http://twistedmatrix.com/>`_, a very mature and powerful asynchronous programming framework. The client supports destination specific message and error handlers (with default "poison pill" error handling), concurrent message processing, graceful shutdown, and connect, receipt, and disconnect timeouts.
+
+Installation
+============
+
+You may install this package in any of the following ways: ``easy_install stompest.async``, ``pip install stompest.async``, or ``python setup.py install``.
+
+Questions or Suggestions?
+=========================
+Feel free to `open an issue <https://github.com/nikipore/stompest/issues/>`_ or post a question on the `forum <http://groups.google.com/group/stompest/>`_.
+
+Acknowledgements
+================
+* Version 1.x of stompest was written by `Roger Hoover <http://github.com/theduderog/>`_ at `Mozes <http://www.mozes.com/>`_ and deployed in their production environment.
+* Kudos to `Oisin Mulvihill <https://github.com/oisinmulvihill/>`_, the developer of `stomper <http://code.google.com/p/stomper/>`_! The idea of an abstract representation of the STOMP protocol lives on in stompest.
+
+Documentation & Code Examples
+=============================
+The stompest API is `fully documented here <http://nikipore.github.com/stompest/>`_.

src/async/setup.py

@@ -0,0 +1,48 @@
+import os
+import sys
+
+from setuptools import setup, find_packages
+
+from stompest import FULL_VERSION
+
+def read(filename):
+    return open(os.path.join(os.path.dirname(__file__), filename)).read()
+
+if sys.version_info[:2] < (2, 6):
+    print 'stompest requires Python version 2.6 or later (%s detected).' % '.'.join(sys.version_info[:2])
+    sys.exit(-1)
+if sys.version_info[:2] >= (3, 0):
+    print 'stompest is not yet compatible with Python 3 (%s detected).' % '.'.join(sys.version_info[:2])
+    sys.exit(-1)
+
+setup(
+    name='stompest.async',
+    version=FULL_VERSION,
+    author='Jan Mueller',
+    author_email='nikipore@gmail.com',
+    description='Twisted STOMP client based upon the stompest API.',
+    license='Apache License 2.0',
+    packages=find_packages(),
+    namespace_packages=['stompest'],
+    long_description=read('README.txt'),
+    keywords='stomp twisted activemq rabbitmq apollo',
+    url='https://github.com/nikipore/stompest',
+    include_package_data=True,
+    zip_safe=True,
+    install_requires=[
+        'stompest==%s' % FULL_VERSION
+        , 'twisted>=10.1.0'  # Endpoints API
+    ],
+    tests_require=['mock'],
+    test_suite='stompest.async.tests',
+    classifiers=[
+        'Development Status :: 3 - Alpha',
+        'Framework :: Twisted',
+        'Topic :: System :: Networking',
+        'Operating System :: OS Independent',
+        'License :: OSI Approved :: Apache Software License',
+        'Intended Audience :: Developers',
+        'Programming Language :: Python',
+        'Topic :: Software Development :: Libraries :: Python Modules'
+    ],
+)

src/async/stompest/__init__.py

@@ -0,0 +1,10 @@
+# this is a namespace package
+try:
+    import pkg_resources
+    pkg_resources.declare_namespace(__name__)
+except ImportError:
+    import pkgutil
+    __path__ = pkgutil.extend_path(__path__, __name__)
+
+VERSION = '2.0'
+FULL_VERSION = '2.0a5'

stompest/async/client.py → src/async/stompest/async/client.py

@@ -5,23 +5,23 @@
 Examples
 --------
 
-.. automodule:: stompest.examples
+.. automodule:: stompest.async.examples
     :members:
 
 Producer
 ^^^^^^^^
 
-.. literalinclude:: ../../stompest/examples/async/producer.py
+.. literalinclude:: ../../src/async/stompest/async/examples/producer.py
 
 Transformer
 ^^^^^^^^^^^
 
-.. literalinclude:: ../../stompest/examples/async/transformer.py
+.. literalinclude:: ../../src/async/stompest/async/examples/transformer.py
 
 Consumer
 ^^^^^^^^
 
-.. literalinclude:: ../../stompest/examples/async/consumer.py
+.. literalinclude:: ../../src/async/stompest/async/examples/consumer.py
 
 API
 ---

stompest/tests/async_client_test.py → src/async/stompest/async/tests/async_client_test.py

@@ -9,7 +9,7 @@
 from stompest.config import StompConfig
 from stompest.error import StompCancelledError, StompConnectionError, StompConnectTimeout, StompProtocolError
 
-from stompest.tests.broker_simulator import BlackHoleStompServer, ErrorOnConnectStompServer, ErrorOnSendStompServer, RemoteControlViaFrameStompServer
+from .broker_simulator import BlackHoleStompServer, ErrorOnConnectStompServer, ErrorOnSendStompServer, RemoteControlViaFrameStompServer
 from stompest.protocol.spec import StompSpec
 
 observer = log.PythonLoggingObserver()

src/core/Makefile

@@ -0,0 +1,27 @@
+PYTHON=`which python`
+NAME=`python setup.py --name`
+
+dist:
+	$(PYTHON) setup.py sdist
+
+upload:
+	$(PYTHON) setup.py sdist upload
+
+readme:
+	$(PYTHON) setup.py --long-description | rst2html > readme.html
+
+test:
+	$(PYTHON) setup.py test
+
+check:
+	find . -name \*.py | grep -v "^test_" | xargs pylint --errors-only --reports=n
+	# pep8
+	# pyntch
+	# pyflakes
+	# pychecker
+	# pymetrics
+
+clean:
+	$(PYTHON) setup.py clean
+	rm -rf build/ dist/ readme.html *.egg-info/
+	find . -name '*.pyc' -delete

src/core/README.txt

@@ -0,0 +1,41 @@
+stomp, stomper, stompest!
+=========================
+
+`stompest <https://github.com/nikipore/stompest/>`_ is a full-featured implementation of the `STOMP <http://stomp.github.com/>`_ protocol (versions `1.0 <http://stomp.github.com//stomp-specification-1.0.html>`_, `1.1 <http://stomp.github.com//stomp-specification-1.1.html>`_, and `1.2 <http://stomp.github.com//stomp-specification-1.2.html>`_) for Python 2.6 (and higher).
+
+The STOMP client in this package is dead simple: It does not assume anything about your concurrency model (thread vs process) or force you to use it any particular way. It gets out of your way and lets you do what you want. The package also consists of a generic set of components each of which you may use independently to roll your own STOMP client:
+
+* a wire-level STOMP frame parser and compiler,
+
+* a faithful implementation of the syntax of the STOMP protocol with a simple stateless function API,
+
+* a generic implementation of the STOMP session state semantics, such as protocol version negotiation at connect time, transaction and subscription handling (including a generic subscription replay scheme which may be used to reconstruct the session's subscription state after a forced disconnect),
+
+* and a `failover transport <http://activemq.apache.org/failover-transport-reference.html>`_ URI scheme akin to the one used in ActiveMQ.
+
+This package is thoroughly unit tested and (in version 1.x) production hardened for the functionality used by `Mozes <http://www.mozes.com/>`_ --- persistent queueing on `ActiveMQ <http://activemq.apache.org/>`_. The substantially redesigned stompest 2 is probably even better tested but should be considered (mature) alpha: Some features to come (for instance, `Support for repeated header entries in STOMP 1.2 <https://github.com/nikipore/stompest/issues/8>`_) may still require minor changes of the API.
+
+The package is tested with Python 2.6 and 2.7, Twisted 11.0 and 12.0 (it should work with Twisted 10.1 and higher), and ActiveMQ 5.5.1, 5.6, 5.7, 5.8. The integration tests also pass against `RabbitMQ <http://www.rabbitmq.com/>`_ 3.0.2 and `Apollo <http://activemq.apache.org/apollo/>`_ 1.5. All of these brokers were tested with STOMP protocols 1.0, 1.1, and 1.2 (if applicable). Minor enhancements may be required to use this STOMP adapter with other brokers.
+
+Asynchronous Client
+===================
+
+The asynchronous client is based on `Twisted <http://twistedmatrix.com/>`_, a very mature and powerful asynchronous programming framework. In order to keep the stompest package self-consistent, the asynchronous client is available as a separate package `stompest.async <https://pypi.python.org/pypi/stompest.async/>`_.
+
+Installation
+============
+
+You may install this package in any of the following ways: ``easy_install stompest``, ``pip install stompest``, or ``python setup.py install``.
+
+Questions or Suggestions?
+=========================
+Feel free to `open an issue <https://github.com/nikipore/stompest/issues/>`_ or post a question on the `forum <http://groups.google.com/group/stompest/>`_.
+
+Acknowledgements
+================
+* Version 1.x of stompest was written by `Roger Hoover <http://github.com/theduderog/>`_ at `Mozes <http://www.mozes.com/>`_ and deployed in their production environment.
+* Kudos to `Oisin Mulvihill <https://github.com/oisinmulvihill/>`_, the developer of `stomper <http://code.google.com/p/stomper/>`_! The idea of an abstract representation of the STOMP protocol lives on in stompest.
+
+Documentation & Code Examples
+=============================
+The stompest API is `fully documented here <http://nikipore.github.com/stompest/>`_.

setup.py → src/core/setup.py

@@ -2,10 +2,11 @@
 import sys
 
 from setuptools import setup, find_packages
+
 from stompest import FULL_VERSION
 
-def read(fname):
-    return open(os.path.join(os.path.dirname(__file__), fname)).read()
+def read(filename):
+    return open(os.path.join(os.path.dirname(__file__), filename)).read()
 
 if sys.version_info[:2] < (2, 6):
     print 'stompest requires Python version 2.6 or later (%s detected).' % '.'.join(sys.version_info[:2])
@@ -19,17 +20,16 @@ def read(fname):
     version=FULL_VERSION,
     author='Jan Mueller',
     author_email='nikipore@gmail.com',
-    description='STOMP client library for Python including both synchronous and Twisted clients.',
+    description='STOMP library for Python including a synchronous client.',
     license='Apache License 2.0',
     packages=find_packages(),
+    namespace_packages=['stompest'],
     long_description=read('README.txt'),
-    keywords='stomp twisted activemq rabbitmq apollo',
+    keywords='stomp activemq rabbitmq apollo',
     url='https://github.com/nikipore/stompest',
     include_package_data=True,
     zip_safe=True,
-    install_requires=[
-        'twisted>=10.1.0'  # Endpoints API
-    ],
+    install_requires=[],
     tests_require=['mock'],
     test_suite='stompest.tests',
     classifiers=[

src/core/stompest/__init__.py

@@ -0,0 +1,10 @@
+# this is a namespace package
+try:
+    import pkg_resources
+    pkg_resources.declare_namespace(__name__)
+except ImportError:
+    import pkgutil
+    __path__ = pkgutil.extend_path(__path__, __name__)
+
+VERSION = '2.0'
+FULL_VERSION = '2.0a5'

stompest/sync/client.py → src/core/stompest/sync/client.py

@@ -3,18 +3,18 @@
 Examples
 --------
 
-.. automodule:: stompest.examples
+.. automodule:: stompest.sync.examples
     :members:
 
 Producer
 ^^^^^^^^
 
-.. literalinclude:: ../../stompest/examples/sync/producer.py
+.. literalinclude:: ../../src/core/stompest/sync/examples/producer.py
 
 Consumer
 ^^^^^^^^
 
-.. literalinclude:: ../../stompest/examples/sync/consumer.py
+.. literalinclude:: ../../src/core/stompest/sync/examples/consumer.py
 
 API
 ---

stompest/examples/__init__.py → src/core/stompest/sync/examples/__init__.py

@@ -11,4 +11,4 @@
     import logging
     logging.basicConfig()
     logging.getLogger().setLevel(logging.DEBUG)
-"""
+"""