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

Imported Upstream version 2.1.7

parent 82f8f6f6
*.pyc
*.c
build
dist
conf
*.egg-info
*.so
*.pyd
*.dll
setup.cfg
\ No newline at end of file
docs/source/api/generated
docs/gh-pages
setup.cfg
......@@ -3,19 +3,25 @@ include README.rst
include setup.cfg.template
include setup.py
include setupegg.py
include zmqversion.py
include buildutils.py
graft docs
prune docs/build
prune docs/gh-pages
recursive-include docs *
recursive-exclude docs _build
# graft docs
graft examples
graft zmq
graft perf
exclude setup.cfg
exclude zmq/libzmq*
# exclude docs/_static
# exclude docs/_templates
global-exclude *.so
global-exclude *.pyd
global-exclude *.pyc
global-exclude .git*
global-exclude .DS_Store
==============================
PyZMQ: Python bindings for 0MQ
PyZMQ: Python bindings for ØMQ
==============================
This package contains Python bindings for `0QM <http://www.zeromq.org>`_.
0MQ is a lightweight and fast messaging implementation.
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
===========
......@@ -20,17 +45,54 @@ 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 this Python package, you will first need to build and
install the latest development version of 0MQ itself. After you have done
this, follow these steps:
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:
First, copy the ``setup.cfg.template`` file in this directory to ``setup.cfg``
and edit the `include_dirs` and `library_dirs` fields of the ``setup.cfg``
file to point to the directories that contain the library and header file for
your 0MQ installation.
$ 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::
......@@ -43,20 +105,30 @@ on GitHub.
Windows
-------
Generally you'll need to add the location of ``libzmq.dll`` to your ``$PATH``.
Here's Microsoft's docs:
http://msdn.microsoft.com/en-us/library/7d83bc18(VS.80).aspx on this topic.
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.
It is best to compile both ØMQ and PyØMQ with Microsoft Visual Studio 2008 or
above. You should not need to use mingw.
Linux
-----
On Linux, you will need to do one of the following:
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 0MQ.
* Build the extension using the ``-rpath`` flag::
* 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
......@@ -90,7 +162,7 @@ How to release PyZMQ
Currently, we are using the following steps to release PyZMQ:
* Change the version number in ``setup.py`` and ``version.pyx``.
* Check the version number in ``version.pyx``.
* Remove old ``MANIFEST`` and ``egg-info`` files and ``dist`` and ``build``
directories.
* Check ``MANIFEST.in``.
......@@ -105,13 +177,13 @@ Currently, we are using the following steps to release PyZMQ:
* Upload the tarball and ``.zip`` file to github.
* Branch the release::
git co -b 2.0.8 master
git push origin 2.0.8
git checkout -b 2.1.7 master
git push origin 2.1.7
* Tag the release::
git tag -a -m “Tagging release 2.0.8” 2.0.8
git push origin tags
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.
......@@ -138,3 +210,5 @@ The following people have contributed to the project:
* 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)
"""Detect zmq version"""
#
# 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
#
# 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,
# 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
# along with this program. If not, see <http://www.gnu.org/licenses/>.
import shutil
import sys
import os
import logging
import pickle
from distutils import ccompiler
from subprocess import Popen, PIPE
try:
from configparser import ConfigParser
except:
from ConfigParser import ConfigParser
pjoin = os.path.join
#-----------------------------------------------------------------------------
# Logging (adapted from h5py: http://h5py.googlecode.com)
#-----------------------------------------------------------------------------
logger = logging.getLogger()
logger.addHandler(logging.StreamHandler(sys.stderr))
def debug(what):
pass
def fatal(instring, code=1):
logger.error("Fatal: "+instring)
exit(code)
def warn(instring):
logger.error("Warning: "+instring)
#-----------------------------------------------------------------------------
# Utility functions (adapted from h5py: http://h5py.googlecode.com)
#-----------------------------------------------------------------------------
def detect_zmq(basedir, **compiler_attrs):
"""Compile, link & execute a test program, in empty directory `basedir`.
The C compiler will be updated with any keywords given via setattr.
Parameters
----------
basedir : path
The location where the test program will be compiled and run
**compiler_attrs : dict
Any extra compiler attributes, which will be set via ``setattr(cc)``.
Returns
-------
A dict of properties for zmq compilation, with the following two keys:
vers : tuple
The ZMQ version as a tuple of ints, e.g. (2,2,0)
options : dict
The compiler options used to compile the test function, e.g. `include_dirs`,
`library_dirs`, `libs`, etc.
"""
cc = ccompiler.new_compiler()
for name, val in compiler_attrs.items():
setattr(cc, name, val)
cfile = pjoin(basedir, 'vers.c')
efile = pjoin(basedir, 'vers')
f = open(cfile, 'w')
try:
f.write(
r"""
#include <stdio.h>
#include "zmq.h"
int main(){
unsigned int major, minor, patch;
zmq_version(&major, &minor, &patch);
fprintf(stdout, "vers: %d.%d.%d\n", major, minor, patch);
return 0;
}
""")
finally:
f.close()
if sys.platform == 'darwin':
# allow for missing UB arch, since it will still work:
preargs = ['-undefined', 'dynamic_lookup']
else:
preargs = None
objs = cc.compile([cfile])
cc.link_executable(objs, efile, extra_preargs=preargs)
result = Popen(efile, stdout=PIPE, stderr=PIPE)
so, se = result.communicate()
# for py3k:
so = so.decode()
se = se.decode()
if result.returncode:
msg = "Error running version detection script:\n%s\n%s" % (so,se)
logging.error(msg)
raise IOError(msg)
handlers = {'vers': lambda val: tuple(int(v) for v in val.split('.'))}
props = {}
for line in (x for x in so.split('\n') if x):
key, val = line.split(':')
props[key] = handlers[key](val)
props['options'] = compiler_attrs
return props
def localpath(*args):
plist = [os.path.dirname(__file__)]+list(args)
return os.path.abspath(pjoin(*plist))
def loadpickle(name):
""" Load object from pickle file, or None if it can't be opened """
name = pjoin('conf', name)
try:
f = open(name,'rb')
except IOError:
# raise
return None
try:
return pickle.load(f)
except Exception:
# raise
return None
finally:
f.close()
def savepickle(name, data):
""" Save to pickle file, exiting if it can't be written """
if not os.path.exists('conf'):
os.mkdir('conf')
name = pjoin('conf', name)
try:
f = open(name, 'wb')
except IOError:
fatal("Can't open pickle file \"%s\" for writing" % name)
try:
pickle.dump(data, f, 0)
finally:
f.close()
def v_str(v_tuple):
"""turn (2,0,1) into '2.0.1'."""
return ".".join(str(x) for x in v_tuple)
def get_eargs():
""" Look for options in environment vars """
settings = {}
zmq = os.environ.get("ZMQ_DIR", '')
if zmq != '':
debug("Found environ var ZMQ_DIR=%s" % zmq)
settings['zmq'] = zmq
return settings
def get_cfg_args():
""" Look for options in setup.cfg """
settings = {}
zmq = ''
if not os.path.exists('setup.cfg'):
return settings
cfg = ConfigParser()
cfg.read('setup.cfg')
if 'build_ext' in cfg.sections() and \
cfg.has_option('build_ext', 'include_dirs'):
includes = cfg.get('build_ext', 'include_dirs')
include = includes.split(os.pathsep)[0]
if include.endswith('include') and os.path.isdir(include):
zmq = include[:-8]
if zmq != '':
debug("Found ZMQ=%s in setup.cfg" % zmq)
settings['zmq'] = zmq
return settings
def get_cargs():
""" Look for global options in the command line """
settings = loadpickle('buildconf.pickle')
if settings is None: settings = {}
for arg in sys.argv[:]:
if arg.find('--zmq=') == 0:
zmq = arg.split('=')[-1]
if zmq.lower() == 'default':
settings.pop('zmq', None)
else:
settings['zmq'] = zmq
sys.argv.remove(arg)
savepickle('buildconf.pickle', settings)
return settings
def discover_settings():
""" Discover custom settings for ZMQ path"""
settings = get_cfg_args() # lowest priority
settings.update(get_eargs())
settings.update(get_cargs()) # highest priority
return settings.get('zmq')
def copy_and_patch_libzmq(ZMQ, libzmq):
"""copy libzmq into source dir, and patch it if necessary.
This command is necessary prior to running a bdist on Linux or OS X.
"""
if sys.platform.startswith('win'):
return
# copy libzmq into zmq for bdist
local = localpath('zmq',libzmq)
if ZMQ is None and not os.path.exists(local):
fatal("Please specify zmq prefix via `setup.py configure --zmq=/path/to/zmq` "
"or copy libzmq into zmq/ manually prior to running bdist.")
try:
lib = pjoin(ZMQ, 'lib', libzmq)
print ("copying %s -> %s"%(lib, local))
shutil.copy(lib, local)
except Exception:
if not os.path.exists(local):
fatal("Could not copy libzmq into zmq/, which is necessary for bdist. "
"Please specify zmq prefix via `setup.py configure --zmq=/path/to/zmq` "
"or copy libzmq into zmq/ manually.")
finally:
# link libzmq.dylib -> libzmq.1.dylib
link = localpath('zmq',libzmq.replace('.1',''))
if not os.path.exists(link):
os.symlink(libzmq, link)
if sys.platform == 'darwin':
# patch install_name on darwin, instead of using rpath
cmd = ['install_name_tool', '-id', '@loader_path/../%s'%libzmq, local]
try:
p = Popen(cmd, stdout=PIPE,stderr=PIPE)
except OSError:
fatal("install_name_tool not found, cannot patch libzmq for bundling.")
out,err = p.communicate()
if p.returncode:
fatal("Could not patch bundled libzmq install_name: %s"%err, p.returncode)
......@@ -5,15 +5,18 @@
SPHINXOPTS =
SPHINXBUILD = sphinx-build
PAPER =
BUILDDIR = _build
BUILDDIR = build
SRCDIR = source
# Internal variables.
PAPEROPT_a4 = -D latex_paper_size=a4
PAPEROPT_letter = -D latex_paper_size=letter
ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) $(SRCDIR)
.PHONY: help clean html dirhtml pickle json htmlhelp qthelp latex changes linkcheck doctest
default: html
help:
@echo "Please use \`make <target>' where <target> is one of"
@echo " html to make standalone HTML files"
......@@ -29,8 +32,29 @@ help:
clean:
-rm -rf $(BUILDDIR)/*
-rm -rf $(SRCDIR)/api/generated/*
-rm -rf dist
-rm -rf gh-pages
api: $(SRCDIR)/api/generated/gen.rst
$(SRCDIR)/api/generated/gen.rst:
python autogen_api.py
@echo "Build API docs finished."
dist: all
mkdir -p dist
rm -rf dist/*
ln $(BUILDDIR)/latex/PyZMQ.pdf dist/
cp -a $(BUILDDIR)/html dist/
@echo "Build finished. Final docs are in dist/"
html:
pdf: latex
cd $(BUILDDIR)/latex && make all-pdf
all: html pdf
html: api
$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
@echo
@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
......@@ -65,7 +89,7 @@ qthelp:
@echo "To view the help file:"
@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/PyZMQ.qhc"
latex:
latex: api
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
@echo
@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
......@@ -87,3 +111,7 @@ doctest:
$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
@echo "Testing of doctests in the sources finished, look at the " \
"results in $(BUILDDIR)/doctest/output.txt."
gh-pages: html
sh update_ghpages.sh
#!/usr/bin/env python
"""Script to auto-generate our API docs.
"""
# stdlib imports
import os
import sys
# local imports
sys.path.append(os.path.abspath('sphinxext'))
# import sphinx_cython
from apigen import ApiDocWriter
#*****************************************************************************
if __name__ == '__main__':
pjoin = os.path.join
package = 'zmq'
outdir = pjoin('source','api','generated')
docwriter = ApiDocWriter(package,rst_extension='.rst')
# You have to escape the . here because . is a special char for regexps.
# You must do make clean if you change this!
docwriter.package_skip_patterns += [ r'\.tests$' ]
docwriter.module_skip_patterns += [ r'\.tests',
r'win32_support']
# Now, generate the outputs
docwriter.write_api_docs(outdir)
docwriter.write_index(outdir, 'gen',
relative_to = pjoin('source','api')
)
print '%d files written' % len(docwriter.written_modules)
.. PyZMQ documentation master file, created by
sphinx-quickstart on Sat Feb 20 23:31:19 2010.
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
PyZMQ documentation!
====================
Contents:
.. toctree::
:maxdepth: 2
pyversions.rst
unicode.rst
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
......@@ -505,3 +505,44 @@ ul.search li div.context {
ul.keywordmatches li.goodmatch a {
font-weight: bold;
}
/* from numpy:*/
td.field-body > blockquote {
margin-top: 0.1em;
margin-bottom: 0.5em;
}
/* spacing in see also definition lists */
dl.last > dd {
margin-top: 1px;
margin-bottom: 5px;
margin-left: 30px;
}
.field-list th {
color: rgb(0,102,204);
background: #eee;
}
table.field-list th {
/* border-left: 1px solid #aaa !important;*/
padding-left: 5px;
white-space: nowrap;
}
table.field-list {
border-collapse: separate;
border-spacing: 10px;
}
th.field-name {
/* border-left: 1px solid #aaa !important;*/
padding-left: .5em;
padding-right: .5em;
text-align: right;
}
.rubric {
color: rgb(0,50,150);
background-color: ;
font-style: italic;
}
\ No newline at end of file
......@@ -4,7 +4,7 @@
{% block rootrellink %}
<li><a href="{{ pathto('index') }}">home</a>|&nbsp;</li>
<li><a href="{{ pathto('search') }}">search</a>|&nbsp;</li>
<li><a href="{{ pathto('contents') }}">documentation </a> &raquo;</li>
<li><a href="{{ pathto('api/index') }}">API</a> &raquo;</li>
{% endblock %}
......
.. _api-index:
###################
The PyZMQ API
###################
.. htmlonly::
:Release: |release|
:Date: |today|
.. include:: generated/gen.rst
......@@ -12,11 +12,15 @@
# serve to show the default.
import sys, os
import string
# 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.append(os.path.abspath('sphinxext'))
sys.path.insert(0,os.path.abspath('../sphinxext'))
# patch autodoc to work with Cython Sources
import sphinx_cython
# -- General configuration -----------------------------------------------------
......@@ -27,8 +31,10 @@ extensions = ['matplotlib.sphinxext.mathmpl',
'matplotlib.sphinxext.plot_directive',
'sphinx.ext.autodoc',
'sphinx.ext.doctest',
'sphinx.ext.intersphinx',
'ipython_console_highlighting',
'inheritance_diagram',
'sphinxtogithub',
'numpydoc']
# Add any paths that contain templates here, relative to this directory.
......@@ -38,23 +44,36 @@ templates_path = ['_templates']
source_suffix = '.rst'
# The encoding of source files.
#source_encoding = 'utf-8'
source_encoding = 'utf-8'
# The master toctree document.
master_doc = 'index'
# General information about the project.
project = u'PyZMQ'
copyright = u'2010, Brian E. Granger'
copyright = u"""2010, Brian E. Granger.
ØMQ logo © iMatix Corportation, used under the Creative Commons Attribution-Share Alike 3.0 License.
Python logo ™ of the Python Software Foundation, used by Min RK with permission from the Foundation"""
intersphinx_mapping = {'python': ('http://docs.python.org/', None)}
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
# built documents.
#
def extract_version():
"""extract pyzmq version from core/version.pyx, so it's not multiply defined"""
with open(os.path.join('..', '..', 'zmq', 'core', 'version.pyx')) as f:
line = f.readline()
while not line.startswith("__version__"):
line = f.readline()
exec(line)
return __version__
vs = extract_version()
# The short X.Y version.
version = '2.0.10.1'
version = vs.rstrip(string.letters)
# The full version, including alpha/beta/rc tags.