Commit bad794d4 authored by SVN-Git Migration's avatar SVN-Git Migration

Imported Upstream version 2.2.0

parent d2aec125
# Licensing and contributing to PyZMQ
PyZMQ uses different licenses for different parts of the code.
The 'core' of PyZMQ (located in zmq/core) is licensed under LGPLv3. This just
means that if you make any changes to how that code works, you must release
those changes under the LGPL. If you just *use* pyzmq, then you can use any
license you want for your own code.
We don't feel that the restrictions imposed by the LGPL make sense for the
'non-core' functionality in pyzmq (derivative code must *also* be LGPL or GPL),
especially for examples and utility code, so we have relicensed all 'non-core'
code under the more permissive BSD (specifically Modified BSD aka New BSD aka
3-clause BSD), where possible. This means that you can copy this code and build
your own apps without needing to license your own code with the LGPL or GPL.
## Your contributions
When you contribute to PyZMQ, your contributions are made under the same
license as the file you are working on. Any new original code should be BSD
licensed.
Examples are copyright their respective authors, and BSD unless otherwise
specified by the author. You can LGPL (or GPL or MIT or Apache, etc.) your own new
examples if you like, but we strongly encourage using the default BSD license.
## Inherited licenses in pyzmq
Some code outside the core is taken from other open-source projects, and
inherits that project's license.
* zmq/eventloop contains files inherited and adapted from [tornado][], and inherits the Apache license
* zmq/ssh/forward.py is from [paramiko][], and inherits LGPL
* zmq/devices/monitoredqueue.pxd is derived from the zmq_device function in
libzmq, and inherits LGPL
* perf examples are (c) iMatix, and LGPL
[tornado]: http://www.tornadoweb.org
[paramiko]: http://www.lag.net/paramiko
\ No newline at end of file
PyZMQ is licensed under the terms of the Modified BSD License (also known as
New or Revised BSD), as follows:
Copyright (c) 2009-2012, Brian Granger, Min Ragan-Kelley
All rights reserved.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:
Redistributions of source code must retain the above copyright notice, this
list of conditions and the following disclaimer.
Redistributions in binary form must reproduce the above copyright notice, this
list of conditions and the following disclaimer in the documentation and/or
other materials provided with the distribution.
Neither the name of PyZMQ nor the names of its contributors may be used to
endorse or promote products derived from this software without specific prior
written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
include COPYING.BSD
include COPYING.LESSER include COPYING.LESSER
include CONTRIBUTING.md
include MANIFEST.in
include README.rst include README.rst
include setup.cfg.template include setup.cfg.template
include setup.py include setup.py
......
...@@ -8,9 +8,12 @@ This package contains Python bindings for `ØMQ <http://www.zeromq.org>`_. ...@@ -8,9 +8,12 @@ This package contains Python bindings for `ØMQ <http://www.zeromq.org>`_.
Versioning Versioning
========== ==========
Current release of pyzmq is 2.1.11, and targets libzmq-2.1.11. For libzmq Current release of pyzmq is 2.2.0, and targets libzmq-2.2.0. For libzmq
2.0.x, use pyzmq release 2.0.10.1 or the 2.0.x development branch. 2.0.x, use pyzmq release 2.0.10.1 or the 2.0.x development branch.
pyzmq-2.1.11 was the last version of pyzmq to support Python 2.5, and pyzmq 2.2.0 will
require Python 2.6.
PyZMQ versioning follows libzmq versioning. In general, your pyzmq version should be the same PyZMQ versioning follows libzmq versioning. In general, your pyzmq version should be the same
as that of your libzmq, but due to the generally growing API of libzmq, your pyzmq should as that of your libzmq, but due to the generally growing API of libzmq, your pyzmq should
*not* be newer than your libzmq. This is a strict restriction for pyzmq <= 2.1.0, but we *not* be newer than your libzmq. This is a strict restriction for pyzmq <= 2.1.0, but we
...@@ -28,20 +31,22 @@ build pyzmq against libzmq3 and it should work. ...@@ -28,20 +31,22 @@ build pyzmq against libzmq3 and it should work.
Documentation Documentation
============= =============
See PyZMQ's Sphinx `generated documentation <http://zeromq.github.com/pyzmq>`_ on GitHub for API See PyZMQ's Sphinx-generated `documentation <http://zeromq.github.com/pyzmq>`_ on GitHub for API
details, and some notes on Python and Cython development. details, and some notes on Python and Cython development. If you want to learn about
using ØMQ in general, the excellect `ØMQ Guide <http://zguide.zeromq.org>`_ is the place
to start, which has a Python version of every example.
Downloading Downloading
=========== ===========
Unless you specifically want to develop PyZMQ, we recommend downloading the Unless you specifically want to develop PyZMQ, we recommend downloading the
PyZMQ source code from our github download page here: PyZMQ source code or MSI installer from our `GitHub download page <https://github.com/zeromq/pyzmq/downloads>`_,
or an egg from `PyPI <http://pypi.python.org/pypi/pyzmq>`_.
https://github.com/zeromq/pyzmq/downloads You can also get the latest source code from our GitHub repository, but
building from the repository will require that you install Cython version 0.13
or later.
While you can also get the latest source code by forking our github
repository, building from the repository will require that you download and
install Cython version 0.13 or later.
Building and installation Building and installation
========================= =========================
...@@ -105,7 +110,7 @@ The argument should be a directory containing ``lib`` and ``include`` directorie ...@@ -105,7 +110,7 @@ The argument should be a directory containing ``lib`` and ``include`` directorie
``libzmq`` and ``zmq.h`` respectively. For instance (on Windows), if you have downloaded pyzmq ``libzmq`` and ``zmq.h`` respectively. For instance (on Windows), if you have downloaded pyzmq
and current libzmq into the same parent directory, this would be: and current libzmq into the same parent directory, this would be:
$ python setup.py configure --zmq=../zeromq-2.1.11 $ python setup.py configure --zmq=../zeromq-2.2.0
Second, run this command:: Second, run this command::
...@@ -197,7 +202,7 @@ How to release PyZMQ ...@@ -197,7 +202,7 @@ How to release PyZMQ
Currently, we are using the following steps to release PyZMQ: Currently, we are using the following steps to release PyZMQ:
* Check the version number in ``version.pyx``. * Check the version number in ``version.py``.
* Remove old ``MANIFEST`` and ``egg-info`` files and ``dist`` and ``build`` * Remove old ``MANIFEST`` and ``egg-info`` files and ``dist`` and ``build``
directories. directories.
* Check ``MANIFEST.in``. * Check ``MANIFEST.in``.
...@@ -213,7 +218,7 @@ Currently, we are using the following steps to release PyZMQ: ...@@ -213,7 +218,7 @@ Currently, we are using the following steps to release PyZMQ:
git checkout -b 2.1.9 master git checkout -b 2.1.9 master
* commit the changed ``version.pyx`` to the branch:: * commit the changed ``version.py`` to the branch::
git add zmq/core/version.pyx && git commit -m "bump version to 2.1.9" git add zmq/core/version.pyx && git commit -m "bump version to 2.1.9"
...@@ -234,22 +239,21 @@ is the primary developer of pyzmq at this time. ...@@ -234,22 +239,21 @@ is the primary developer of pyzmq at this time.
The following people have contributed to the project: The following people have contributed to the project:
* Eugene Chernyshov (chernyshov DOT eugene AT gmail DOT com)
* Douglas Creager (dcreager AT dcreager DOT net)
* Craig Austin (craig DOT austin AT gmail DOT com)
* Andrew Gwozdziewycz (git AT apgwoz DOT com) * Andrew Gwozdziewycz (git AT apgwoz DOT com)
* Baptiste Lepilleur (baptiste DOT lepilleur AT gmail DOT com) * Baptiste Lepilleur (baptiste DOT lepilleur AT gmail DOT com)
* Brandon Craig Rhodes (brandon AT rhodesmill DOT org) * Brandon Craig Rhodes (brandon AT rhodesmill DOT org)
* Brandyn A. White (bwhite AT dappervision DOT com) * Brandyn A. White (bwhite AT dappervision DOT com)
* Brian Granger (ellisonbg AT gmail DOT com) * Brian E. Granger (ellisonbg AT gmail DOT com)
* Carlos A. Rocha (carlos DOT rocha AT gmail DOT com) * Carlos A. Rocha (carlos DOT rocha AT gmail DOT com)
* Daniel Lundin (dln AT spotify DOT com) * Daniel Lundin (dln AT spotify DOT com)
* Daniel Truemper (truemped AT googlemail DOT com) * Daniel Truemper (truemped AT googlemail DOT com)
* Erick Tryzelaar (erick DOT tryzelaar AT gmail DOT com) * Erick Tryzelaar (erick DOT tryzelaar AT gmail DOT com)
* Erik Tollerud (erik DOT tollerud AT gmail DOT com) * Erik Tollerud (erik DOT tollerud AT gmail DOT com)
* Fernando Perez (Fernando DOT Perez AT berkeley DOT edu) * Fernando Perez (Fernando DOT Perez AT berkeley DOT edu)
* Frank Wiles (frank AT revsys DOT com)
* Ivo Danihelka (ivo AT danihelka DOT net) * Ivo Danihelka (ivo AT danihelka DOT net)
* John Gallagher (johnkgallagher AT gmail DOT com)
* Justin Riley (justin DOT t DOT riley AT gmail DOT com) * Justin Riley (justin DOT t DOT riley AT gmail DOT com)
* Min Ragan-Kelley (benjaminrk AT gmail DOT com) * Min Ragan-Kelley (benjaminrk AT gmail DOT com)
* Nicholas Piël (nicholas AT nichol DOT as) * Nicholas Piël (nicholas AT nichol DOT as)
...@@ -269,3 +273,19 @@ as reported by:: ...@@ -269,3 +273,19 @@ as reported by::
with some adjustments. with some adjustments.
Not in git log
--------------
* Eugene Chernyshov (chernyshov DOT eugene AT gmail DOT com)
* Douglas Creager (dcreager AT dcreager DOT net)
* Craig Austin (craig DOT austin AT gmail DOT com)
gevent_zeromq, now zmq.green
----------------------------
* Travis Cline (travis DOT cline AT gmail DOT com)
* Ryan Kelly (ryan AT rfk DOT id DOT au)
* Zachary Voase (z AT zacharyvoase DOT com)
"""Detect zmq version""" """Detect zmq version"""
#-----------------------------------------------------------------------------
# Copyright (C) 2011 Brian Granger, Min Ragan-Kelley
# #
# Copyright (c) 2011 Min Ragan-Kelley # This file is part of pyzmq, copied and adapted from h5py.
# # h5py source used under the New BSD license
# This file is part of pyzmq, copied and adapted from h5py.
# h5py source used under the New BSD license
#
# h5py: <http://code.google.com/p/h5py/>
# BSD license: <http://www.opensource.org/licenses/bsd-license.php>
#
# pyzmq is free software; you can redistribute it and/or modify it under
# the terms of the Lesser GNU General Public License as published by
# the Free Software Foundation; either version 3 of the License, or
# (at your option) any later version.
# #
# pyzmq is distributed in the hope that it will be useful, # h5py: <http://code.google.com/p/h5py/>
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
# Lesser GNU General Public License for more details.
# #
# You should have received a copy of the Lesser GNU General Public License # Distributed under the terms of the New BSD License. The full license is in
# along with this program. If not, see <http://www.gnu.org/licenses/>. # the file COPYING.BSD, distributed as part of this software.
#-----------------------------------------------------------------------------
import shutil import shutil
import sys import sys
......
...@@ -9,6 +9,77 @@ Changes in PyZMQ ...@@ -9,6 +9,77 @@ Changes in PyZMQ
This is a coarse summary of changes in pyzmq versions. For a real changelog, consult the This is a coarse summary of changes in pyzmq versions. For a real changelog, consult the
`git log <https://github.com/zeromq/pyzmq/commits>`_ `git log <https://github.com/zeromq/pyzmq/commits>`_
2.2.0
=====
Some effort has gone into refining the pyzmq API in this release to make it a model for
other language bindings. This is principally made in a few renames of objects and methods,
all of which leave the old name for backwards compatibility.
.. note::
As of this release, all code outside ``zmq.core`` is BSD licensed (where
possible), to allow more permissive use of less-critical code and utilities.
Name Changes
------------
* The :class:`~.Message` class has been renamed to :class:`~.Frame`, to better match other
zmq bindings. The old Message name remains for backwards-compatibility. Wherever pyzmq
docs say "Message", they should refer to a complete zmq atom of communication (one or
more Frames, connected by ZMQ_SNDMORE). Please report any remaining instances of
Message==MessagePart with an Issue (or better yet a Pull Request).
* All ``foo_unicode`` methods are now called ``foo_string`` (``_unicode`` remains for
backwards compatibility). This is not only for cross-language consistency, but it makes
more sense in Python 3, where native strings are unicode, and the ``_unicode`` suffix
was wedded too much to Python 2.
Other Changes and Removals
--------------------------
* ``prefix`` removed as an unused keyword argument from :meth:`~.Socket.send_multipart`.
* ZMQStream :meth:`~.ZMQStream.send` default has been changed to `copy=True`, so it matches
Socket :meth:`~.Socket.send`.
* ZMQStream :meth:`~.ZMQStream.on_err` is deprecated, because it never did anything.
* Python 2.5 compatibility has been dropped, and some code has been cleaned up to reflect
no-longer-needed hacks.
* Some Cython files in :mod:`zmq.core` have been split, to reduce the amount of
Cython-compiled code. Much of the body of these files were pure Python, and thus did
not benefit from the increased compile time. This change also aims to ease maintaining
feature parity in other projects, such as
`pyzmq-ctypes <https://github.com/svpcom/pyzmq-ctypes>`_.
New Stuff
---------
* :class:`~.Context` objects can now set default options when they create a socket. These
are set and accessed as attributes to the context. Socket options that do not apply to a
socket (e.g. SUBSCRIBE on non-SUB sockets) will simply be ignored.
* :meth:`~.ZMQStream.on_recv_stream` has been added, which adds the stream itself as a
second argument to the callback, making it easier to use a single callback on multiple
streams.
* A :attr:`~Frame.more` boolean attribute has been added to the :class:`~.Frame` (née
Message) class, so that frames can be identified as terminal without extra queires of
:attr:`~.Socket.rcvmore`.
Experimental New Stuff
----------------------
These features are marked 'experimental', which means that their APIs are not
set in stone, and may be removed or changed in incompatible ways in later releases.
* :mod:`zmq.web` added for load-balancing requests in a tornado webapp with zeromq.
2.1.11 2.1.11
====== ======
......
...@@ -26,12 +26,12 @@ processes. We have provided classes for launching devices in a background thread ...@@ -26,12 +26,12 @@ processes. We have provided classes for launching devices in a background thread
:class:`.ThreadDevice` and via multiprocessing with :class:`.ProcessDevice`. For :class:`.ThreadDevice` and via multiprocessing with :class:`.ProcessDevice`. For
threadsafety and running across processes, these methods do not take Socket objects as threadsafety and running across processes, these methods do not take Socket objects as
arguments, but rather socket types, and then the socket creation and configuration happens arguments, but rather socket types, and then the socket creation and configuration happens
via the BackgroundDevice's :meth:`x_in` proxy methods. For each configuration method via the BackgroundDevice's :meth:`foo_in` proxy methods. For each configuration method
(bind/connect/setsockopt), there are proxy methods for calling those methods on the Socket (bind/connect/setsockopt), there are proxy methods for calling those methods on the Socket
objects created in the background thread or process, prefixed with 'in\_' or 'out\_', objects created in the background thread or process, prefixed with 'in\_' or 'out\_',
corresponding to the `in_socket` and `out_socket`:: corresponding to the `in_socket` and `out_socket`::
from zmq.devices.basedevice import ProcessDevice from zmq.devices import ProcessDevice
pd = ProcessDevice(zmq.QUEUE, zmq.REP, zmq.REQ) pd = ProcessDevice(zmq.QUEUE, zmq.REP, zmq.REQ)
pd.bind_in('tcp://*:12345') pd.bind_in('tcp://*:12345')
...@@ -62,7 +62,7 @@ of the message in order to get the right message out the other side. ...@@ -62,7 +62,7 @@ of the message in order to get the right message out the other side.
To invoke a monitored queue is similar to invoking a regular ØMQ device:: To invoke a monitored queue is similar to invoking a regular ØMQ device::
from zmq.devices.monitoredqueue import monitored_queue from zmq.devices import monitored_queue
ins = ctx.socket(zmq.ROUTER) ins = ctx.socket(zmq.ROUTER)
outs = ctx.socket(zmq.DEALER) outs = ctx.socket(zmq.DEALER)
mons = ctx.socket(zmq.PUB) mons = ctx.socket(zmq.PUB)
...@@ -75,8 +75,8 @@ in/out prefix is well suited to the PUB/SUB topic subscription model. All messag ...@@ -75,8 +75,8 @@ in/out prefix is well suited to the PUB/SUB topic subscription model. All messag
`mons` will be multipart, the first part being the prefix corresponding to the socket that `mons` will be multipart, the first part being the prefix corresponding to the socket that
received the message. received the message.
:mod:`.devices.monitoredqueuedevice` contains subclasses of BackgroundDevices for Or for launching an MQ in the background, there are :class:`.ThreadMonitoredQueue` and
launching a monitored queue in the background, which function just like the base :class:`.ProcessMonitoredQueue`, which function just like the base
BackgroundDevice objects, but add `x_mon` methods for configuring the monitor socket. BackgroundDevice objects, but add :meth:`foo_mon` methods for configuring the monitor socket.
...@@ -10,8 +10,8 @@ native sockets. We have included a small part of Tornado (specifically its ...@@ -10,8 +10,8 @@ native sockets. We have included a small part of Tornado (specifically its
:mod:`.ioloop`), and adapted its :class:`IOStream` class into :class:`.ZMQStream` for :mod:`.ioloop`), and adapted its :class:`IOStream` class into :class:`.ZMQStream` for
handling poll events on ØMQ sockets. A ZMQStream object works much like a Socket object, handling poll events on ØMQ sockets. A ZMQStream object works much like a Socket object,
but instead of calling :meth:`~.Socket.recv` directly, you register a callback with but instead of calling :meth:`~.Socket.recv` directly, you register a callback with
:meth:`~.ZMQStream.on_recv`. callbacks can also be registered for send and error events :meth:`~.ZMQStream.on_recv`. callbacks can also be registered for send events
with :meth:`~.ZMQStream.on_send` and :meth:`~.ZMQStream.on_err` respectively. with :meth:`~.ZMQStream.on_send`.
:func:`install()` :func:`install()`
...@@ -77,17 +77,42 @@ even if its length is 1. You can easily use this to build things like an echo so ...@@ -77,17 +77,42 @@ even if its length is 1. You can easily use this to build things like an echo so
s = ctx.socket(zmq.REP) s = ctx.socket(zmq.REP)
s.bind('tcp://localhost:12345') s.bind('tcp://localhost:12345')
loop = ioloop.IOLoop.instance() stream = ZMQStream(s)
stream = ZMQStream(s, loop)
def echo(msg): def echo(msg):
stream.send_multipart(msg) stream.send_multipart(msg)
stream.on_recv(echo) stream.on_recv(echo)
loop.start() ioloop.IOLoop.instance().start()
on_recv can also take a `copy` flag, just like :meth:`.Socket.recv`. If `copy=False`, then on_recv can also take a `copy` flag, just like :meth:`.Socket.recv`. If `copy=False`, then
callbacks registered with on_recv will receive tracked :class:`.Message` objects instead of callbacks registered with on_recv will receive tracked :class:`.Frame` objects instead of
bytes. bytes.
:meth:`on_recv_stream`
----------------------
:meth:`.ZMQStream.on_recv_stream` is just like on_recv above, but the callback will be
passed both the message and the stream, rather than just the message. This is meant to make
it easier to use a single callback with multiple streams.
.. sourcecode:: python
s1 = ctx.socket(zmq.REP)
s1.bind('tcp://localhost:12345')
stream1 = ZMQStream(s1)
s2 = ctx.socket(zmq.REP)
s2.bind('tcp://localhost:54321')
stream2 = ZMQStream(s2)
def echo(msg, stream):
stream.send_multipart(msg)
stream1.on_recv_stream(echo)
stream2.on_recv_stream(echo)
ioloop.IOLoop.instance().start()
:meth:`flush` :meth:`flush`
------------- -------------
......
...@@ -14,11 +14,11 @@ PyZMQ Documentation ...@@ -14,11 +14,11 @@ PyZMQ Documentation
PyZMQ is the Python bindings for ØMQ_, written almost entirely in Cython_. This PyZMQ is the Python bindings for ØMQ_, written almost entirely in Cython_. This
documentation currently contains notes on some important aspects of developing PyZMQ and documentation currently contains notes on some important aspects of developing PyZMQ and
an overview of what the ØMQ API looks like in Python. For information on how to use an overview of what the ØMQ API looks like in Python. For information on how to use
ØMQ in general, see the excellent `ØMQ Guide`_, which has examples translated into many ØMQ in general, see the many examples in the excellent `ØMQ Guide`_, all of which
languages, including Python. have a version in Python.
Please don't hesitate to report pyzmq issues to our tracker_ on GitHub, or send Please don't hesitate to report pyzmq-specific issues to our tracker_ on GitHub.
questions to the ØMQ `mailing list`_ or `IRC Channel`_. General questions about ØMQ are better sent to the ØMQ `mailing list`_ or `IRC Channel`_.
:ref:`Summary of Changes in PyZMQ <changelog>` :ref:`Summary of Changes in PyZMQ <changelog>`
......
...@@ -47,7 +47,7 @@ approach is not recommended. ...@@ -47,7 +47,7 @@ approach is not recommended.
Socket Options as Attributes Socket Options as Attributes
**************************** ----------------------------
.. versionadded:: 2.1.9 .. versionadded:: 2.1.9
...@@ -67,6 +67,26 @@ behave just as you would expect: ...@@ -67,6 +67,26 @@ behave just as you would expect:
s.fd s.fd
# 16 # 16
Default Options on the Context
******************************
.. versionadded:: 2.1.12
Just like setting socket options as attributes on Sockets, you can do the same on Contexts.
This affects the default options of any *new* sockets created after the assignment.
.. sourcecode:: python
ctx = zmq.Context()
ctx.linger = 0
rep = ctx.socket(zmq.REP)
req = ctx.socket(zmq.REQ)
Socket options that do not apply to a socket (e.g. SUBSCRIBE on non-SUB sockets) will
simply be ignored.
Core Extensions Core Extensions
--------------- ---------------
...@@ -83,7 +103,7 @@ object over the wire after serializing with :mod:`json` and :mod:`pickle` respec ...@@ -83,7 +103,7 @@ object over the wire after serializing with :mod:`json` and :mod:`pickle` respec
and any object sent via those methods can be reconstructed with the 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 :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 other objects that are not unambiguously sendable over the wire, so we include
:meth:`~.Socket.send_unicode` and :meth:`~.Socket.recv_unicode` that simply send bytes :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:: .. seealso::
...@@ -112,25 +132,25 @@ builtin :py:class:`~Queue.Queue` object), instantiating a MessageTracker takes a ...@@ -112,25 +132,25 @@ 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 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, 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 which is optionally passed, always defaulting to ``False``, in each of the three places
where a Message is instantiated: The :class:`.Message` constructor, and non-copying sends where a Frame object (the pyzmq object for wrapping a segment of a message) is
and receives. 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 A MessageTracker is very simple, and has just one method and one attribute. The property
:attr:`MessageTracker.done` will be ``True`` when the Message(s) being tracked are no :attr:`MessageTracker.done` will be ``True`` when the Frame(s) being tracked are no
longer in use by ØMQ, and :meth:`.MessageTracker.wait` will block, waiting for the longer in use by ØMQ, and :meth:`.MessageTracker.wait` will block, waiting for the
Message(s) to be released. Frame(s) to be released.
.. Note:: .. Note::
A message cannot be tracked after it has been instantiated without tracking. If a A Frame cannot be tracked after it has been instantiated without tracking. If a
Message is to even have the *option* of tracking, it must be constructed with Frame is to even have the *option* of tracking, it must be constructed with
``track=True``. ``track=True``.
Extensions Extensions
---------- ----------
So far, PyZMQ includes three extensions to core ØMQ that we found basic enough to be So far, PyZMQ includes four extensions to core ØMQ that we found basic enough to be
included in PyZMQ itself: included in PyZMQ itself:
* :ref:`zmq.log <logging>` : Logging handlers for hooking Python logging up to the * :ref:`zmq.log <logging>` : Logging handlers for hooking Python logging up to the
......
...@@ -6,7 +6,7 @@ PyZMQ and Unicode ...@@ -6,7 +6,7 @@ PyZMQ and Unicode
================= =================
PyZMQ is built with an eye towards an easy transition to Python 3, and part of PyZMQ is built with an eye towards an easy transition to Python 3, and part of
that is dealing with unicode objects. This is an overview of some of what we that is dealing with unicode strings. This is an overview of some of what we
found, and what it means for PyZMQ. found, and what it means for PyZMQ.
First, Unicode in Python 2 and 3 First, Unicode in Python 2 and 3
...@@ -93,7 +93,7 @@ bytes, then we are potentially using up enormous amounts of excess memory ...@@ -93,7 +93,7 @@ bytes, then we are potentially using up enormous amounts of excess memory
unnecessarily, due to copying and larger memory footprint of unicode strings. unnecessarily, due to copying and larger memory footprint of unicode strings.
Still, we recognize the fact that users will quite frequently have unicode Still, we recognize the fact that users will quite frequently have unicode
strings that they want to send, so we have added ``socket.<method>_unicode()`` strings that they want to send, so we have added ``socket.<method>_string()``
wrappers. These methods simply wrap their bytes counterpart by encoding wrappers. These methods simply wrap their bytes counterpart by encoding
to/decoding from bytes around them, and they all take an `encoding` keyword to/decoding from bytes around them, and they all take an `encoding` keyword
argument that defaults to utf-8. Since encoding and decoding are necessary to argument that defaults to utf-8. Since encoding and decoding are necessary to
...@@ -104,7 +104,16 @@ actions with these wrappers. ...@@ -104,7 +104,16 @@ actions with these wrappers.
strictly setters and there is not corresponding getter method. As a result, we strictly setters and there is not corresponding getter method. As a result, we
feel that we can safely coerce unicode objects to bytes (always to utf-8) in feel that we can safely coerce unicode objects to bytes (always to utf-8) in
these methods. these methods.
.. note::
For cross-language symmetry (including Python 3), the ``_unicode`` methods
are now ``_string``. Many languages have a notion of native strings, and
the use of ``_unicode`` was wedded too closely to the name of such objects
in Python 2. For the time being, anywhere you see ``_string``, ``_unicode``
also works, and is the only option in pyzmq ≤ 2.1.11.
The Methods The Methods
----------- -----------
...@@ -138,14 +147,14 @@ Overview of the relevant methods: ...@@ -138,14 +147,14 @@ Overview of the relevant methods:
`unicode(message)` decodes `message.buffer` with utf-8 `unicode(message)` decodes `message.buffer` with utf-8
.. py:function:: socket.send_unicode(self, unicode s, flags=0, encoding='utf-8') .. py:function:: socket.send_string(self, unicode s, flags=0, encoding='utf-8')
takes a ``unicode`` string `s`, and sends the ``bytes`` takes a ``unicode`` string `s`, and sends the ``bytes``
after encoding without an extra copy, via: after encoding without an extra copy, via:
`socket.send(s.encode(encoding), flags, copy=False)` `socket.send(s.encode(encoding), flags, copy=False)`
.. py:function:: socket.recv_unicode(self, flags=0, encoding='utf-8') .. py:function:: socket.recv_string(self, flags=0, encoding='utf-8')
always returns ``unicode`` string always returns ``unicode`` string
...@@ -163,14 +172,14 @@ Overview of the relevant methods: ...@@ -163,14 +172,14 @@ Overview of the relevant methods:
returns ``bytes`` (or ``int``), never ``unicode`` returns ``bytes`` (or ``int``), never ``unicode``
.. py:function:: socket.setsockopt_unicode(self, opt, unicode optval, encoding='utf-8') .. py:function:: socket.setsockopt_string(self, opt, unicode optval, encoding='utf-8')
accepts ``unicode`` string for `optval` accepts ``unicode`` string for `optval`
encodes `optval` with `encoding` before passing the ``bytes`` to encodes `optval` with `encoding` before passing the ``bytes`` to
`setsockopt` `setsockopt`
.. py:function:: socket.getsockopt_unicode(self, opt, encoding='utf-8') .. py:function:: socket.getsockopt_string(self, opt, encoding='utf-8')
always returns ``unicode`` string, after decoding with `encoding` always returns ``unicode`` string, after decoding with `encoding`
......
PyZMQ examples are copyright their respective authors, and licensed
under the New BSD License as described in COPYING.BSD unless otherwise
specified in the file.
\ No newline at end of file
"""
Complex example which is a combination of the rr* examples from the zguide.
"""
from gevent import spawn
import zmq.green as zmq
# server
context = zmq.Context()
socket = context.socket(zmq.REP)
socket.connect("tcp://localhost:5560")
def serve(socket):
while True:
message = socket.recv()
print "Received request: ", message