Update docs for constant enums

Author: minrk

docs/requirements.txt

@@ -1,6 +1,7 @@
 cython>=0.29
+enum-tools[sphinx]>=0.9
 gevent
-pygments==2.4.2
+pygments>=2.6
 sphinx>=3.0.4
 sphinx-rtd-theme==0.5.*
 tornado

docs/source/api/zmq.rst

@@ -88,6 +88,42 @@ Polling
 
 .. autofunction:: zmq.select
 
+Constants
+---------
+
+All libzmq constants are available as top-level attributes
+(``zmq.PUSH``, etc.),
+as well as via enums (``zmq.SocketType.PUSH``, etc.).
+
+.. versionchanged:: 23
+
+    constants for unavailable socket types
+    or draft features will always be defined in pyzmq,
+    whether the features themselves are available or not.
+
+.. versionadded:: 23
+
+    Each category of zmq constant is now available as an IntEnum.
+
+.. autoenum:: SocketType
+
+.. autoenum:: SocketOption
+
+.. autoenum:: Flag
+
+.. autoenum:: PollEvent
+
+.. autoenum:: ContextOption
+
+.. autoenum:: MessageOption
+
+.. autoenum:: Event
+
+.. autoenum:: SecurityMechanism
+
+.. autoenum:: DeviceType
+
+.. autoenum:: Errno
 
 Exceptions
 ----------

docs/source/changelog.rst

@@ -7,6 +7,23 @@ Changes in PyZMQ
 This is a coarse summary of changes in pyzmq versions.
 For a full changelog, consult the `git log <https://github.com/zeromq/pyzmq/commits>`_.
 
+23.0.0
+======
+
+Changes:
+
+- all zmq constants are now available as Python enums
+  (e.g. ``zmq.SocketType.PULL``, ``zmq.SocketOption.IDENTITY``),
+  generated statically from zmq.h instead of at compile-time.
+  This means that checks for the *presence* of a constant (`hasattr(zmq, 'RADIO')`)
+  is not a valid check for the presence of a feature.
+  This practice has never been robust, but it may have worked sometimes.
+  Use direct checks via e.g. :func:`zmq.has` or :func:`zmq.zmq_version_info`.
+
+Compatibility fixes:
+
+- Remove all use of deprecated stdlib distutils
+
 22.3.0
 ======
 

docs/source/conf.py

@@ -14,11 +14,9 @@
 import string
 import sys
 
-# If extensions (or modules to document with autodoc) are in another directory,
-# add these directories to sys.path here. If the directory is relative to the
-# documentation root, use os.path.abspath to make it absolute, like shown here.
-sys.path.insert(0, os.path.abspath('../sphinxext'))
-sys.path.append(os.path.abspath('../..'))
+# add repo root to sys.path
+here = os.path.dirname(__file__)
+sys.path.append(os.path.abspath(os.path.join(here, os.pardir, os.pardir)))
 
 # set target libzmq version
 from buildutils.bundle import bundled_version
@@ -38,6 +36,7 @@
     'sphinx.ext.intersphinx',
     'sphinx.ext.napoleon',
     'sphinx_rtd_theme',
+    'enum_tools.autoenum',
 ]
 
 # Add any paths that contain templates here, relative to this directory.

docs/source/eventloop.rst

@@ -46,7 +46,7 @@ Sockets created by this Context will return Futures from any would-be blocking m
         zmq.asyncio.install()
 
         ctx = zmq.asyncio.Context()
-    
+
     This step is no longer needed in pyzmq 17.
 
 
@@ -67,6 +67,12 @@ with :meth:`~.ZMQStream.on_send`.
 Futures and coroutines
 ----------------------
 
+.. note::
+
+    With recent Python (3.6) and tornado (5),
+    there's no reason to use :mod:`zmq.eventloop.future`
+    instead of the strictly-more-compatible :mod:`zmq.asyncio`.
+
 PyZMQ 15 adds :mod:`zmq.eventloop.future`, containing a Socket subclass
 that returns :class:`~.tornado.concurrent.Future` objects for use in :mod:`tornado` coroutines.
 To use this API, import :class:`zmq.eventloop.future.Context`.
@@ -173,7 +179,7 @@ events off of the queue. You can specify to flush only recv events, only send ev
 any events, and you can specify a limit for how many events to flush in order to prevent
 starvation.
 
-.. _Tornado: https://github.com/facebook/tornado
+.. _Tornado: https://github.com/tornadoweb/tornado
 
 :func:`install()`
 -----------------

docs/source/morethanbindings.rst

@@ -87,6 +87,46 @@ This affects the default options of any *new* sockets created after the assignme
 Socket options that do not apply to a socket (e.g. SUBSCRIBE on non-SUB sockets) will
 simply be ignored.
 
+libzmq constants as Enums
+-------------------------
+
+.. versionadded:: 23
+
+libzmq constants are now available as Python enums,
+making it easier to enumerate socket options, etc.
+
+Context managers
+----------------
+
+.. versionadded:: 14
+    Context/Sockets as context managers
+
+.. versionadded:: 20
+    bind/connect context managers
+
+For more Pythonic resource management,
+contexts and sockets can be used as context managers.
+Just like standard-library socket and file methods,
+entering a context:
+
+.. sourcecode:: python
+
+    import zmq
+    with zmq.Context() as ctx:
+        with ctx.socket(zmq.PUSH) as s:
+            s.connect(url)
+            s.send_multipart([b"message"])
+        # exiting Socket context closes socket
+    # exiting Context context terminates context
+
+In addition, each bind/connect call may be used as a context:
+
+.. sourcecode:: python
+
+    with socket.connect(url):
+        s.send_multipart([b"message"])
+    # exiting connect context calls socket.disconnect(url)
+
 
 Core Extensions
 ---------------
@@ -105,12 +145,12 @@ and any object sent via those methods can be reconstructed with the
 :meth:`~.Socket.recv_json` and :meth:`~.Socket.recv_pyobj` methods. Unicode strings are
 other objects that are not unambiguously sendable over the wire, so we include
 :meth:`~.Socket.send_string` and :meth:`~.Socket.recv_string` that simply send bytes
-after encoding the message ('utf-8' is the default). 
+after encoding the message ('utf-8' is the default).
 
 .. seealso::
 
     * :ref:`Further information <serialization>` on serialization in pyzmq.
-    
+
     * :ref:`Our Unicode discussion <unicode>` for more information on the trials and
       tribulations of working with Unicode in a C extension while supporting Python 2 and 3.
 
@@ -133,7 +173,7 @@ builtin :py:class:`~Queue.Queue` object), instantiating a MessageTracker takes a
 amount of time (10s of µs), so in situations instantiating many small messages, this can
 actually dominate performance. As a result, tracking is optional, via the ``track`` flag,
 which is optionally passed, always defaulting to ``False``, in each of the three places
-where a Frame object (the pyzmq object for wrapping a segment of a message) is 
+where a Frame object (the pyzmq object for wrapping a segment of a message) is
 instantiated: The :class:`.Frame` constructor, and non-copying sends and receives.
 
 A MessageTracker is very simple, and has just one method and one attribute. The property
@@ -156,9 +196,9 @@ included in PyZMQ itself:
 
 * :ref:`zmq.log <logging>` : Logging handlers for hooking Python logging up to the
   network
-* :ref:`zmq.devices <devices>` : Custom devices and objects for running devices in the 
+* :ref:`zmq.devices <devices>` : Custom devices and objects for running devices in the
   background
-* :ref:`zmq.eventloop <eventloop>` : The `Tornado`_ event loop, adapted for use 
+* :ref:`zmq.eventloop <eventloop>` : The `Tornado`_ event loop, adapted for use
   with ØMQ sockets.
 * :ref:`zmq.ssh <ssh>` : Simple tools for tunneling zeromq connections via ssh.
 

docs/source/serialization.rst

@@ -22,7 +22,7 @@ methods can be reconstructed with the :meth:`~.Socket.recv_json` and
 :meth:`~.Socket.recv_pyobj` methods.
 
 
-These methods designed for convenience, not for performance, so developers who do want 
+These methods designed for convenience, not for performance, so developers who want
 to emphasize performance should use their own serialized send/recv methods.
 
 Using your own serialization
@@ -41,15 +41,16 @@ The following will send *compressed* pickles over the wire:
 
 .. sourcecode:: python
 
-    import zlib, cPickle as pickle
+    import pickle
+    import zlib
 
-    def send_zipped_pickle(socket, obj, flags=0, protocol=-1):
+    def send_zipped_pickle(socket, obj, flags=0, protocol=pickle.HIGHEST_PROTOCOL):
         """pickle an object, and zip the pickle before sending it"""
         p = pickle.dumps(obj, protocol)
         z = zlib.compress(p)
         return socket.send(z, flags=flags)
 
-    def recv_zipped_pickle(socket, flags=0, protocol=-1):
+    def recv_zipped_pickle(socket, flags=0):
         """inverse of send_zipped_pickle"""
         z = socket.recv(flags)
         p = zlib.decompress(z)

zmq/constants.py

@@ -8,6 +8,11 @@
 
 
 class Errno(IntEnum):
+    """libzmq error codes
+
+    .. versionadded:: 23
+    """
+
     EAGAIN = errno.EAGAIN
     EFAULT = errno.EFAULT
     EINVAL = errno.EINVAL
@@ -65,7 +70,10 @@ class Errno(IntEnum):
 
 
 class ContextOption(IntEnum):
-    """Options for Context.get/set"""
+    """Options for Context.get/set
+
+    .. versionadded:: 23
+    """
 
     IO_THREADS = 1
     MAX_SOCKETS = 2
@@ -80,7 +88,10 @@ class ContextOption(IntEnum):
 
 
 class SocketType(IntEnum):
-    """zmq socket types"""
+    """zmq socket types
+
+    .. versionadded:: 23
+    """
 
     PAIR = 0
     PUB = 1
@@ -119,7 +130,10 @@ class _OptType(Enum):
 
 
 class SocketOption(IntEnum):
-    """Options for Socket.get/set"""
+    """Options for Socket.get/set
+
+    .. versionadded:: 23
+    """
 
     _opt_type: str
 
@@ -245,22 +259,33 @@ def __new__(cls, value, opt_type=_OptType.int):
 
 
 class MessageOption(IntEnum):
+    """Options on zmq.Frame objects
+
+    .. versionadded:: 23
+    """
+
     MORE = 1
     SHARED = 3
     # Deprecated message options
     SRCFD = 2
 
 
 class Flag(IntFlag):
-    """Send/recv options"""
+    """Send/recv flags
+
+    .. versionadded:: 23
+    """
 
     DONTWAIT = 1
     SNDMORE = 2
     NOBLOCK = DONTWAIT
 
 
 class SecurityMechanism(IntEnum):
-    """Security mechanisms (socket.get(zmq.MECHANISM))"""
+    """Security mechanisms (as returned by ``socket.get(zmq.MECHANISM)``)
+
+    .. versionadded:: 23
+    """
 
     NULL = 0
     PLAIN = 1
@@ -269,7 +294,10 @@ class SecurityMechanism(IntEnum):
 
 
 class Event(IntFlag):
-    """Socket monitoring events"""
+    """Socket monitoring events
+
+    .. versionadded:: 23
+    """
 
     @staticmethod
     def _global_name(name):
@@ -323,17 +351,27 @@ def _global_name(name):
     # DRAFT Socket monitoring events
     PIPES_STATS = 0x10000
     ALL_V1 = ALL
-    ALL_V2 = ALL | PIPES_STATS
+    ALL_V2 = ALL_V1 | PIPES_STATS
 
 
 class PollEvent(IntFlag):
+    """Which events to poll for in poll methods
+
+    .. versionadded: 23
+    """
+
     POLLIN = 1
     POLLOUT = 2
     POLLERR = 4
     POLLPRI = 8
 
 
 class DeviceType(IntEnum):
+    """Device type constants for zmq.device
+
+    .. versionadded: 23
+    """
+
     STREAMER = 1
     FORWARDER = 2
     QUEUE = 3

zmq/utils/jsonapi.py

@@ -1,6 +1,6 @@
 """JSON serialize to/from utf8 bytes
 
-..versionchanged:: 22.2
+.. versionchanged:: 22.2
     Remove optional imports of different JSON implementations.
     Now that we require recent Python, unconditionally use the standard library.
     Custom JSON libraries can be used via custom serialization functions.