Merge pull request #24 from wtolson/modernize

Modernize gnsq for nsq 1.0.0 and python 3.7

.travis.yml

@@ -1,19 +1,18 @@
 # Config file for automatic testing at travis-ci.org
+dist: xenial
 language: python
 
 python:
+  - "3.7"
   - "3.6"
   - "3.5"
   - "3.4"
   - "2.7"
-  - "pypy"
+  - "pypy3.5"
 
 env:
-  - NSQ_VERSION=0.3.5 GO_VERSION=1.4.2
-  - NSQ_VERSION=0.3.6 GO_VERSION=1.5.1
-  - NSQ_VERSION=0.3.7 GO_VERSION=1.6
-  - NSQ_VERSION=0.3.8 GO_VERSION=1.6.2
   - NSQ_VERSION=1.0.0-compat GO_VERSION=1.8
+  - NSQ_VERSION=1.1.0 GO_VERSION=1.10.3
 
 matrix:
   include:

HISTORY.rst

@@ -7,15 +7,34 @@ History
 1.0.0 (TBD)
 ~~~~~~~~~~~
 
-* Drop support for python 2.6 and python 3.3
+* Drop support for python 2.6 and python 3.3, add support for python 3.7
+* Drop support for nsq < 1.0.0
 * Handle changing connections during redistribute ready
+* Add create topic and create channel to LookupdClient
+* Add pause and unpause topic to NsqdHTTPClient
+* Add ability to filter NsqdHTTPClient stats by topic/channel
+* Add text format for NsqdHTTPClient stats
+* Add binary multipublish over http
+* Add queue handler to the contrib package
+* Add Producer class, a high level tcp message writer
+* Fixed detecting if consumer is starved
+* Optimizations to better distribute ready state among the nsqd connections
+* Detect starved consumers when batching messages
+* [DEPRECATED] :class:`~gnsq.Nsqd` is deprecated. Use
+  :class:`~gnsq.NsqdTCPClient` or :class:`~gnsq.NsqdHTTPClient` instead. See
+  :ref:`upgrading-to-100` for more information.
+* [DEPRECATED] :class:`~gnsq.Lookupd` is deprecated. Use
+  :class:`~gnsq.LookupdClient` instead. See :ref:`upgrading-to-100` for more
+  information.
+* [DEPRECATED] :class:`~gnsq.Reader` is deprecated. Use :class:`~gnsq.Consumer`
+  instead.  See :ref:`upgrading-to-100` for more information.
 
 
 0.4.0 (2017-06-13)
 ~~~~~~~~~~~~~~~~~~
 
 * #13 - Allow use with nsq v1.0.0 (thanks @daroot)
-* Add contrib package with utlities.
+* Add contrib package with utilities.
 
 
 0.3.3 (2016-09-25)
@@ -35,7 +54,7 @@ History
 0.3.1 (2015-11-06)
 ~~~~~~~~~~~~~~~~~~
 
-* Fix negative in flight causing not throtteling after backoff.
+* Fix negative in flight causing not throttling after backoff.
 
 
 0.3.0 (2015-06-14)
@@ -66,15 +85,15 @@ History
 
 * Topics and channels are now valid to 64 characters.
 * Ephemeral topics are now valid.
-* Adjustable backoff behaviour.
+* Adjustable backoff behavior.
 
 
 0.2.0 (2014-08-03)
 ~~~~~~~~~~~~~~~~~~
 
 * Warn on connection failure.
 * Add extra requires for snappy.
-* Add support for nsq auth protocal.
+* Add support for nsq auth protocol.
 
 
 0.1.4 (2014-07-24)

README.rst

@@ -43,24 +43,42 @@ Currently there is support for Python 2.7+, Python 3.4+ and PyPy.
 Usage
 -----
 
-First make sure nsq is `installed and running`_. Next create a nsqd connection
-and publish some messages to your topic::
+First make sure nsq is `installed and running`_. Next create a producer and
+publish some messages to your topic::
 
     import gnsq
-    conn = gnsq.Nsqd(address='localhost', http_port=4151)
 
-    conn.publish('topic', 'hello gevent!')
-    conn.publish('topic', 'hello nsq!')
+    producer = gnsq.Producer('localhost:4150')
 
-Then create a Reader to consume messages from your topic::
+    producer.publish('topic', 'hello gevent!')
+    producer.publish('topic', 'hello nsq!')
 
-    reader = gnsq.Reader('topic', 'channel', 'localhost:4150')
+Then create a Consumer to consume messages from your topic::
 
-    @reader.on_message.connect
-    def handler(reader, message):
+    consumer = gnsq.Consumer('topic', 'channel', 'localhost:4150')
+
+    @consumer.on_message.connect
+    def handler(consumer, message):
         print 'got message:', message.body
 
-    reader.start()
+    consumer.start()
+
+Compatibility
+-------------
+
+For **NSQ 1.0** and later, use the major version 1 (``1.x.y``) of gnsq.
+
+For **NSQ 0.3.8** and earlier, use the major version 0 (``0.x.y``) of the
+library.
+
+The recommended way to set your requirements in your `setup.py` or
+`requirements.txt` is::
+
+    # NSQ 1.x.y
+    gnsq>=1.0.0
+
+    # NSQ 0.x.y
+    gnsq<1.0.0
 
 Dependencies
 ------------

docs/conf.py

@@ -77,7 +77,7 @@
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = 'alabaster'
+html_theme = 'sphinx_rtd_theme'
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the

docs/consumer.rst

@@ -0,0 +1,6 @@
+Consumer: high-level message reader
+-----------------------------------
+
+.. autoclass:: gnsq.Consumer
+  :members:
+  :inherited-members:

docs/contrib.rst

@@ -0,0 +1,54 @@
+Contrib modules
+---------------
+
+Patterns and best practices for gnsq made code.
+
+
+Batching messages
+~~~~~~~~~~~~~~~~~
+
+
+.. autoclass:: gnsq.contrib.batch.BatchHandler
+  :members:
+  :inherited-members:
+
+
+Giveup handlers
+~~~~~~~~~~~~~~~
+
+
+.. autoclass:: gnsq.contrib.giveup.LogGiveupHandler
+  :members:
+  :inherited-members:
+
+
+.. autoclass:: gnsq.contrib.giveup.JSONLogGiveupHandler
+  :members:
+  :inherited-members:
+
+
+.. autoclass:: gnsq.contrib.giveup.NsqdGiveupHandler
+  :members:
+  :inherited-members:
+
+
+Concurrency
+~~~~~~~~~~~
+
+
+.. autoclass:: gnsq.contrib.queue.QueueHandler
+  :members:
+  :inherited-members:
+  :exclude-members: copy, put, put_nowait
+
+
+.. autoclass:: gnsq.contrib.queue.ChannelHandler
+
+
+Error logging
+~~~~~~~~~~~~~
+
+
+.. autoclass:: gnsq.contrib.sentry.SentryExceptionHandler
+  :members:
+  :inherited-members:

docs/index.rst

@@ -14,13 +14,16 @@ Contents
 .. toctree::
    :maxdepth: 2
 
-   reader
+   consumer
+   producer
    nsqd
    lookupd
    message
    signals
+   contrib
    contributing
    authors
+   upgrading
    history
 
 Indices and tables

docs/lookupd.rst

@@ -1,6 +1,10 @@
 Nsqlookupd client
 -----------------
 
-.. autoclass:: gnsq.Lookupd
+.. autoclass:: gnsq.LookupdClient
   :members:
   :inherited-members:
+
+
+.. autoclass:: gnsq.Lookupd
+  :members:

docs/nsqd.rst

@@ -1,6 +1,15 @@
-Nsqd client
------------
+Nsqd clients
+------------
 
-.. autoclass:: gnsq.Nsqd
+.. autoclass:: gnsq.NsqdHTTPClient
+  :members:
+  :inherited-members:
+
+
+.. autoclass:: gnsq.NsqdTCPClient
   :members:
   :inherited-members:
+
+
+.. autoclass:: gnsq.Nsqd
+  :members:

docs/producer.rst

@@ -0,0 +1,6 @@
+Producer: high-level message writer
+-----------------------------------
+
+.. autoclass:: gnsq.Producer
+  :members:
+  :inherited-members:

docs/signals.rst

@@ -1,8 +1,8 @@
 Signals
 -------
 
-Both :doc:`Reader <reader>` and :doc:`Nsqd <nsqd>` classes expose various
-signals provided by the `Blinker`_ library.
+Both :doc:`Consumer <consumer>` and :doc:`NsqdTCPClient <nsqd>` classes expose
+various signals provided by the `Blinker`_ library.
 
 Subscribing to signals
 ~~~~~~~~~~~~~~~~~~~~~~
@@ -13,16 +13,16 @@ argument is the function that should be called when the signal is emitted,
 the optional second argument specifies a sender.  To unsubscribe from a
 signal, you can use the :meth:`~blinker.base.Signal.disconnect` method. ::
 
-    def error_handler(reader, error):
+    def error_handler(consumer, error):
         print 'Got an error:', error
 
-    reader.on_error.connect(error_handler)
+    consumer.on_error.connect(error_handler)
 
 You can also easily subscribe to signals by using
 :meth:`~blinker.base.NamedSignal.connect` as a decorator::
 
-    @reader.on_giving_up.connect
-    def handle_giving_up(reader, message):
+    @consumer.on_giving_up.connect
+    def handle_giving_up(consumer, message):
         print 'Giving up on:', message.id
 
 .. _Blinker: https://pypi.python.org/pypi/blinker