mirror of https://github.com/zeromq/pyzmq.git
215 lines
6.8 KiB
ReStructuredText
215 lines
6.8 KiB
ReStructuredText
==============================
|
|
PyZMQ: Python bindings for ØMQ
|
|
==============================
|
|
|
|
This package contains Python bindings for `ØMQ <http://www.zeromq.org>`_.
|
|
ØMQ is a lightweight and fast messaging implementation.
|
|
|
|
Versioning
|
|
==========
|
|
|
|
Current release of pyzmq is 2.1.7, and targets libzmq-2.1.7. For libzmq
|
|
2.0.x, use pyzmq release 2.0.10.1 or the 2.0.x development branch.
|
|
|
|
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
|
|
*not* be newer than your libzmq. This is a strict restriction for pyzmq <= 2.1.0, but we
|
|
intend to support libzmq >= 2.1.0 for pyzmq 2.1.x.
|
|
|
|
ØMQ 3.0
|
|
-------
|
|
|
|
As of 2.1.7, we have experimental support for the 3.0 API of libzmq,
|
|
developed at https://github.com/zeromq/libzmq. No code to change, no flags to pass, just
|
|
build against libzmq 3 and it should work. The pyzmq API has not changed.
|
|
|
|
|
|
Documentation
|
|
=============
|
|
|
|
See PyZMQ's Sphinx `generated documentation <http://zeromq.github.com/pyzmq>`_ on GitHub for API
|
|
details, and some notes on Python and Cython development.
|
|
|
|
Downloading
|
|
===========
|
|
|
|
Unless you specifically want to develop PyZMQ, we recommend downloading the
|
|
PyZMQ source code from our github download page here:
|
|
|
|
https://github.com/zeromq/pyzmq/downloads
|
|
|
|
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
|
|
=========================
|
|
|
|
Eggs
|
|
----
|
|
|
|
We have binary installers for various Pythons on OSX and (32b) Windows, so you should be able to
|
|
just ``easy_install pyzmq`` in many situations. These eggs *include libzmq-2.1.7*, so they should
|
|
be the only thing you need to start using pyzmq, but we simply don't have the experience to know
|
|
when and where these installers will not work.
|
|
|
|
If a binary installer fails for you, please `tell us <https://github.com/zeromq/pyzmq/issues>`_
|
|
about your system and the failure, so that we can try to fix it in later releases, and fall back
|
|
on building from source.
|
|
|
|
Eggs are on PyPI, and we have them for 'current' Pythons, which are for OSX 10.6:
|
|
|
|
* Python 2.6, 2.7, 3.2 (32b and 64b intel)
|
|
|
|
and win32:
|
|
|
|
* Python 2.7, 3.2
|
|
|
|
We also have MSI installer packages in our `downloads
|
|
<http://github.com/zeromq/pyzmq/downloads>`_ section on GitHub.
|
|
|
|
Our build scripts are much improved as of 2.1.4, so if you would like to contribute 64b Windows
|
|
installers, or have any improvements on existing releases, they would be much appreciated.
|
|
Simply ``python setup.py bdist_msi`` or ``python setupegg.py bdist_egg`` *should* work, once you
|
|
have a 64b libzmq and Python. We simply don't have the VMs or time in which to do this
|
|
ourselves.
|
|
|
|
General
|
|
-------
|
|
|
|
To build and install pyzmq from source, you will first need to build libzmq.
|
|
After you have done this, follow these steps:
|
|
|
|
Tell pyzmq where libzmq is via the configure subcommand:
|
|
|
|
$ python setup.py configure --zmq=/path/to/zeromq2
|
|
|
|
or the zmq install directory on OSX/Linux:
|
|
|
|
$ python setup.py configure --zmq=/usr/local
|
|
|
|
The argument should be a directory containing a ``lib`` and a ``include`` directory, containing
|
|
``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:
|
|
|
|
$ python setup.py configure --zmq=../zeromq-2.1.7
|
|
|
|
Second, run this command::
|
|
|
|
$ python setup.py install
|
|
|
|
Cython is not required to build pyzmq from a release package, but it is
|
|
required if you want to develop pyzmq, or build directly from our repository
|
|
on GitHub.
|
|
|
|
Windows
|
|
-------
|
|
|
|
On Windows, libzmq.dll will be copied into the zmq directory, and installed along with pyzmq,
|
|
so you shouldn't need to edit your ``PATH``.
|
|
|
|
It is best to compile both ØMQ and PyØMQ with Microsoft Visual Studio 2008. You
|
|
should not need to use mingw. If you build libzmq with MSVS 2010, then there
|
|
will be issues in error handling, because there will be a mismatch between error
|
|
numbers.
|
|
|
|
Current testing indicates that running
|
|
|
|
$ python setup.py bdist_msi
|
|
|
|
successfully builds a working MSI installer, but we don't have enough Windows deployment
|
|
experience to know where that may fail.
|
|
|
|
|
|
Linux
|
|
-----
|
|
|
|
If you install libzmq to a location other than the default (``/usr/local``) on Linux,
|
|
you may need to do one of the following:
|
|
|
|
* Set ``LD_LIBRARY_PATH`` to point to the ``lib`` directory of ØMQ.
|
|
* Build the extension using the ``--rpath`` flag::
|
|
|
|
$ python setup.py build_ext --rpath=/opt/zeromq-dev/lib --inplace
|
|
|
|
Development
|
|
-----------
|
|
|
|
To develop PyZMQ, you will need to install Cython, version 0.13 or greater.
|
|
After installing Cython, instead of doing ``python setup.py install`` do::
|
|
|
|
$ python setup.py build_ext --inplace
|
|
$ python setupegg.py develop
|
|
|
|
This will build the C extension inplace and then put this directory on your
|
|
``sys.path``. With this configuration you only have to run::
|
|
|
|
$ python setup.py build_ext --inplace
|
|
|
|
each time you change the ``.pyx`` files. To clean the sources, you can do::
|
|
|
|
$ python setup.py clean
|
|
|
|
Testing
|
|
-------
|
|
|
|
To run the test suite after installing, just do::
|
|
|
|
$ python setup.py test
|
|
|
|
How to release PyZMQ
|
|
--------------------
|
|
|
|
Currently, we are using the following steps to release PyZMQ:
|
|
|
|
* Check the version number in ``version.pyx``.
|
|
* Remove old ``MANIFEST`` and ``egg-info`` files and ``dist`` and ``build``
|
|
directories.
|
|
* Check ``MANIFEST.in``.
|
|
* Register the release with pypi::
|
|
|
|
python setup.py register
|
|
|
|
* Build source distributions and upload::
|
|
|
|
python setup.py sdist --formats=zip,gztar upload
|
|
|
|
* Upload the tarball and ``.zip`` file to github.
|
|
* Branch the release::
|
|
|
|
git checkout -b 2.1.7 master
|
|
git push origin 2.1.7
|
|
|
|
* Tag the release::
|
|
|
|
git tag -a -m "Tagging release 2.1.7" v2.1.7
|
|
git push origin --tags
|
|
|
|
* Make sure the ``README.rst`` has an updated list of contributors.
|
|
* Announce on list.
|
|
|
|
Authors
|
|
=======
|
|
|
|
This project was started by and continues to be led by Brian E. Granger
|
|
(ellisonbg AT gmail DOT com).
|
|
|
|
The following people have contributed to the project:
|
|
|
|
* Carlos Rocha (carlos DOT rocha AT gmail DOT com)
|
|
* Andrew Gwozdziewycz (git AT apgwoz DOT com)
|
|
* Fernando Perez (fernando DOT perez AT berkeley DOT edu)
|
|
* Nicholas Piel (nicholas AT nichol DOT as)
|
|
* Eugene Chernyshov (chernyshov DOT eugene AT gmail DOT com)
|
|
* Justin Riley (justin DOT t DOT riley AT gmail DOT com)
|
|
* Ivo Danihelka (ivo AT denihelka DOT net)
|
|
* Thomas Supra (tomspur AT fedoraproject DOT org)
|
|
* Douglas Creager (dcreager AT dcreager DOT net)
|
|
* Erick Tryzelaar (erick DOT tryzelaar AT gmail DOT com)
|
|
* Min Ragan-Kelley (benjaminrk AT gmail DOT com)
|
|
* Scott Sadler (github AT mashi DOT org)
|
|
* spez (steve AT hipmunk DOT com)
|
|
* Thomas Kluyver (takowl AT gmail DOT com)
|
|
* Baptiste Lepilleur (baptiste DOT lepilleur AT gmail DOT com)
|
|
* Daniel Truemper (truemped AT googlemail DOT com)
|