diff --git a/README.rst b/README.rst index 4a58a81f..85acae25 100644 --- a/README.rst +++ b/README.rst @@ -83,6 +83,11 @@ The HPACK tools require the following package: * jansson >= 2.5 +The Python bindings require the following packages: + +* cython >= 0.19 +* python >= 2.7 + If you are using Ubuntu 12.04, you need the following packages installed: @@ -723,3 +728,37 @@ With ``-d`` option, the extra ``headerTable`` key is added and its associated value contains the state of dyanmic header table after the corresponding header set was processed. The format is the same as ``deflatehd``. + +Python bindings +--------------- + +This ``python`` directory contains nghttp2 Python bindings. The +bindings currently only provide HPACK compressor and decompressor +classes. + +The extension module is called ``nghttp2``. + +``make`` will build the bindings and target Python version is +determined by configure script. If the detected Python version is not +what you expect, specify a path to Python executable in ``PYTHON`` +variable as an argument to configure script (e.g., ``./configure +PYTHON=/usr/bin/python3.3``). + +Example ++++++++ + +The following example code illustrates basic usage of HPACK compressor +and decompressor in Python:: + + import binascii + import nghttp2 + + deflater = nghttp2.HDDeflater(nghttp2.HD_SIDE_REQUEST) + inflater = nghttp2.HDInflater(nghttp2.HD_SIDE_REQUEST) + + data = deflater.deflate([(b'foo', b'bar'), + (b'baz', b'buz')]) + print(binascii.b2a_hex(data)) + + hdrs = inflater.inflate(data) + print(hdrs) diff --git a/configure.ac b/configure.ac index 31db7222..ce30ccf3 100644 --- a/configure.ac +++ b/configure.ac @@ -68,6 +68,11 @@ AC_ARG_ENABLE([examples], [Build examples [default=check]])], [request_examples=$enableval], [request_examples=check]) +AC_ARG_ENABLE([python-bindings], + [AS_HELP_STRING([--enable-python-bindings], + [Build Python bindings [default=check]])], + [request_python_bindings=$enableval], [request_python_bindings=check]) + AC_ARG_ENABLE([failmalloc], [AS_HELP_STRING([--enable-failmalloc], [Build failmalloc test program [default=no]])], @@ -78,6 +83,11 @@ AC_ARG_WITH([libxml2], [Use libxml2 [default=check]])], [request_libxml2=$withval], [request_libxml2=check]) +AC_ARG_WITH([cython], + [AS_HELP_STRING([--with-cython=PATH], + [Use cython in given PATH])], + [cython_path=$withval], []) + dnl Define variables AC_ARG_VAR([CYTHON], [the Cython executable]) @@ -89,8 +99,15 @@ AC_PROG_LN_S AC_PROG_MAKE_SET AM_PROG_CC_C_O PKG_PROG_PKG_CONFIG([0.20]) -AM_PATH_PYTHON([2.6],, [:]) -AC_CHECK_PROGS([CYTHON], [cython.py cython]) +AM_PATH_PYTHON([2.7],, [:]) +AX_PYTHON_DEVEL([>= '2.7']) + +if test "x${cython_path}" = "x"; then + AC_CHECK_PROGS([CYTHON], [cython.py cython]) +else + CYTHON=${cython_path} + AC_SUBST([CYTHON]) +fi AX_CXX_COMPILE_STDCXX_11([noext], [optional]) @@ -280,6 +297,22 @@ fi AM_CONDITIONAL([ENABLE_EXAMPLES], [ test "x${enable_examples}" = "xyes" ]) +# Python bindings +enable_python_bindings=no +if test "x${request_python_bindings}" != "xno" && + test "x${CYTHON}" != "x" && + test "x${PYTHON}" != ":"; then + enable_python_bindings=yes +fi + +if test "x${request_python_bindings}" = "xyes" && + test "x${enable_python_bindings}" != "xyes"; then + AC_MSG_ERROR([python bindings were requested (--enable-python-bindings) but dependencies are not met.]) +fi + +AM_CONDITIONAL([ENABLE_PYTHON_BINDINGS], + [test "x${enable_python_bindings}" = "xyes"]) + # failmalloc tests AM_CONDITIONAL([ENABLE_FAILMALLOC], [ test "x${enable_failmalloc}" = "xyes" ]) @@ -379,7 +412,11 @@ AC_MSG_NOTICE([summary of build options: CXXFLAGS: ${CXXFLAGS} CXXCPP: ${CXXCPP} Library types: Shared=${enable_shared}, Static=${enable_static} - Python: ${PYTHON} ${PYTHON_VERSION} + Python: ${PYTHON} + PYTHON_VERSION: ${PYTHON_VERSION} + pyexecdir: ${pyexecdir} + PYTHON_CPPFLAGS:${PYTHON_CPPFLAGS} + PYTHON_LDFLAGS: ${PYTHON_LDFLAGS} Cython: ${CYTHON} CUnit: ${have_cunit} OpenSSL: ${have_openssl} @@ -390,5 +427,6 @@ AC_MSG_NOTICE([summary of build options: Applications: ${enable_app} HPACK tools: ${enable_hpack_tools} Examples: ${enable_examples} + Python bindings:${enable_python_bindings} Failmalloc: ${request_failmalloc} ]) diff --git a/m4/ax_python_devel.m4 b/m4/ax_python_devel.m4 new file mode 100644 index 00000000..cf2163c9 --- /dev/null +++ b/m4/ax_python_devel.m4 @@ -0,0 +1,324 @@ +# =========================================================================== +# http://www.gnu.org/software/autoconf-archive/ax_python_devel.html +# =========================================================================== +# +# SYNOPSIS +# +# AX_PYTHON_DEVEL([version]) +# +# DESCRIPTION +# +# Note: Defines as a precious variable "PYTHON_VERSION". Don't override it +# in your configure.ac. +# +# This macro checks for Python and tries to get the include path to +# 'Python.h'. It provides the $(PYTHON_CPPFLAGS) and $(PYTHON_LDFLAGS) +# output variables. It also exports $(PYTHON_EXTRA_LIBS) and +# $(PYTHON_EXTRA_LDFLAGS) for embedding Python in your code. +# +# You can search for some particular version of Python by passing a +# parameter to this macro, for example ">= '2.3.1'", or "== '2.4'". Please +# note that you *have* to pass also an operator along with the version to +# match, and pay special attention to the single quotes surrounding the +# version number. Don't use "PYTHON_VERSION" for this: that environment +# variable is declared as precious and thus reserved for the end-user. +# +# This macro should work for all versions of Python >= 2.1.0. As an end +# user, you can disable the check for the python version by setting the +# PYTHON_NOVERSIONCHECK environment variable to something else than the +# empty string. +# +# If you need to use this macro for an older Python version, please +# contact the authors. We're always open for feedback. +# +# LICENSE +# +# Copyright (c) 2009 Sebastian Huber +# Copyright (c) 2009 Alan W. Irwin +# Copyright (c) 2009 Rafael Laboissiere +# Copyright (c) 2009 Andrew Collier +# Copyright (c) 2009 Matteo Settenvini +# Copyright (c) 2009 Horst Knorr +# Copyright (c) 2013 Daniel Mullner +# +# This program is free software: you can redistribute it and/or modify it +# under the terms of the GNU General Public License as published by the +# Free Software Foundation, either version 3 of the License, or (at your +# option) any later version. +# +# This program 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 GNU General +# Public License for more details. +# +# You should have received a copy of the GNU General Public License along +# with this program. If not, see . +# +# As a special exception, the respective Autoconf Macro's copyright owner +# gives unlimited permission to copy, distribute and modify the configure +# scripts that are the output of Autoconf when processing the Macro. You +# need not follow the terms of the GNU General Public License when using +# or distributing such scripts, even though portions of the text of the +# Macro appear in them. The GNU General Public License (GPL) does govern +# all other use of the material that constitutes the Autoconf Macro. +# +# This special exception to the GPL applies to versions of the Autoconf +# Macro released by the Autoconf Archive. When you make and distribute a +# modified version of the Autoconf Macro, you may extend this special +# exception to the GPL to apply to your modified version as well. + +#serial 16 + +AU_ALIAS([AC_PYTHON_DEVEL], [AX_PYTHON_DEVEL]) +AC_DEFUN([AX_PYTHON_DEVEL],[ + # + # Allow the use of a (user set) custom python version + # + AC_ARG_VAR([PYTHON_VERSION],[The installed Python + version to use, for example '2.3'. This string + will be appended to the Python interpreter + canonical name.]) + + AC_PATH_PROG([PYTHON],[python[$PYTHON_VERSION]]) + if test -z "$PYTHON"; then + AC_MSG_ERROR([Cannot find python$PYTHON_VERSION in your system path]) + PYTHON_VERSION="" + fi + + # + # Check for a version of Python >= 2.1.0 + # + AC_MSG_CHECKING([for a version of Python >= '2.1.0']) + ac_supports_python_ver=`$PYTHON -c "import sys; \ + ver = sys.version.split ()[[0]]; \ + print (ver >= '2.1.0')"` + if test "$ac_supports_python_ver" != "True"; then + if test -z "$PYTHON_NOVERSIONCHECK"; then + AC_MSG_RESULT([no]) + AC_MSG_FAILURE([ +This version of the AC@&t@_PYTHON_DEVEL macro +doesn't work properly with versions of Python before +2.1.0. You may need to re-run configure, setting the +variables PYTHON_CPPFLAGS, PYTHON_LDFLAGS, PYTHON_SITE_PKG, +PYTHON_EXTRA_LIBS and PYTHON_EXTRA_LDFLAGS by hand. +Moreover, to disable this check, set PYTHON_NOVERSIONCHECK +to something else than an empty string. +]) + else + AC_MSG_RESULT([skip at user request]) + fi + else + AC_MSG_RESULT([yes]) + fi + + # + # if the macro parameter ``version'' is set, honour it + # + if test -n "$1"; then + AC_MSG_CHECKING([for a version of Python $1]) + ac_supports_python_ver=`$PYTHON -c "import sys; \ + ver = sys.version.split ()[[0]]; \ + print (ver $1)"` + if test "$ac_supports_python_ver" = "True"; then + AC_MSG_RESULT([yes]) + else + AC_MSG_RESULT([no]) + AC_MSG_ERROR([this package requires Python $1. +If you have it installed, but it isn't the default Python +interpreter in your system path, please pass the PYTHON_VERSION +variable to configure. See ``configure --help'' for reference. +]) + PYTHON_VERSION="" + fi + fi + + # + # Check if you have distutils, else fail + # + AC_MSG_CHECKING([for the distutils Python package]) + ac_distutils_result=`$PYTHON -c "import distutils" 2>&1` + if test -z "$ac_distutils_result"; then + AC_MSG_RESULT([yes]) + else + AC_MSG_RESULT([no]) + AC_MSG_ERROR([cannot import Python module "distutils". +Please check your Python installation. The error was: +$ac_distutils_result]) + PYTHON_VERSION="" + fi + + # + # Check for Python include path + # + AC_MSG_CHECKING([for Python include path]) + if test -z "$PYTHON_CPPFLAGS"; then + python_path=`$PYTHON -c "import distutils.sysconfig; \ + print (distutils.sysconfig.get_python_inc ());"` + plat_python_path=`$PYTHON -c "import distutils.sysconfig; \ + print (distutils.sysconfig.get_python_inc (plat_specific=1));"` + if test -n "${python_path}"; then + if test "${plat_python_path}" != "${python_path}"; then + python_path="-I$python_path -I$plat_python_path" + else + python_path="-I$python_path" + fi + fi + PYTHON_CPPFLAGS=$python_path + fi + AC_MSG_RESULT([$PYTHON_CPPFLAGS]) + AC_SUBST([PYTHON_CPPFLAGS]) + + # + # Check for Python library path + # + AC_MSG_CHECKING([for Python library path]) + if test -z "$PYTHON_LDFLAGS"; then + # (makes two attempts to ensure we've got a version number + # from the interpreter) + ac_python_version=`cat<]], + [[Py_Initialize();]]) + ],[pythonexists=yes],[pythonexists=no]) + AC_LANG_POP([C]) + # turn back to default flags + CPPFLAGS="$ac_save_CPPFLAGS" + LIBS="$ac_save_LIBS" + + AC_MSG_RESULT([$pythonexists]) + + if test ! "x$pythonexists" = "xyes"; then + AC_MSG_FAILURE([ + Could not link test program to Python. Maybe the main Python library has been + installed in some non-standard library path. If so, pass it to configure, + via the LDFLAGS environment variable. + Example: ./configure LDFLAGS="-L/usr/non-standard-path/python/lib" + ============================================================================ + ERROR! + You probably have to install the development version of the Python package + for your distribution. The exact name of this package varies among them. + ============================================================================ + ]) + PYTHON_VERSION="" + fi + + # + # all done! + # +]) diff --git a/python/Makefile.am b/python/Makefile.am index 5593bce0..7ae672c1 100644 --- a/python/Makefile.am +++ b/python/Makefile.am @@ -21,20 +21,26 @@ # OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION # WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. -EXTRA_DIST = README.rst cnghttp2.pxd nghttp2.pyx setup.py +EXTRA_DIST = cnghttp2.pxd setup.py -PYSETUP_INCLUDE_DIRS=$(top_srcdir)/lib/includes:$(top_srcdir)/lib -PYSETUP_LIBDIRS=$(top_builddir)/lib/.libs +if ENABLE_PYTHON_BINDINGS -.PHONY: help build_ext +distclean-local: + -rm -f nghttp2.c -help: - @echo "Please use \`make \` where is one of" - @echo " build_ext to build Python @PYTHON_VERSION@ nghttp2 extension" +.pyx.c: + $(CYTHON) -o $@ $< -nghttp2.c: nghttp2.pyx cnghttp2.pxd - $(CYTHON) nghttp2.pyx +pyexec_LTLIBRARIES = nghttp2.la +nghttp2_la_SOURCES = nghttp2.pyx +nghttp2_la_CPPFLAGS = \ + $(PYTHON_CPPFLAGS) \ + -I$(top_srcdir)/lib/includes \ + -I$(build_srcdir)/lib/includes \ + -I$(top_srcdir)/lib +nghttp2_la_LDFLAGS = \ + $(PYTHON_LDFLAGS) \ + -avoid-version -module +nghttp2_la_LIBADD = $(top_builddir)/lib/libnghttp2.la -build_ext: nghttp2.c - $(PYTHON) setup.py build_ext --include-dirs=$(PYSETUP_INCLUDE_DIRS) \ - --library-dirs=$(PYSETUP_LIBDIRS) +endif # ENABLE_PYTHON_BINDINGS diff --git a/python/README.rst b/python/README.rst deleted file mode 100644 index dbb1fb21..00000000 --- a/python/README.rst +++ /dev/null @@ -1,42 +0,0 @@ -nghttp2 Python C extension module -================================= - -This directory contains nghttp2 Python C extension module. Currently, -header compressor and decompressor are implemented in extension using -cython. - -This is experimental and adds some dependencies which is a bit hard to -check, so this extension module does not built with usual ``make`` in -the top directory. Instead, a user has to run ``make build_ext`` in -this directory. - -The build extension module is called ``nghttp2``. - -The module refers to the libnghttp2.so. If nghttp2 is installed using -``make install``, then importing nghttp2 module should work. If a -user does not want to install nghttp2, then use ``LD_LIBRARY_PATH`` -pointing to the location of libnghttp2.so, which is usually in -``lib/.libs``. If a user also does not want to install nghttp2 module, -use PYTHONPATH to point the location of extension module. This depends -on the architecture and Python version. For example, x86_64 -architecture and Python 2.7 series, a module will be located at -``build/lib.linux-x86_64-2.7``. - -Header compression ------------------- - -The following example code illustrates basic usage of compressor and -decompressor:: - - import binascii - import nghttp2 - - deflater = nghttp2.HDDeflater(nghttp2.HD_SIDE_REQUEST) - inflater = nghttp2.HDInflater(nghttp2.HD_SIDE_REQUEST) - - data = deflater.deflate([(b'foo', b'bar'), - (b'baz', b'buz')]) - print(binascii.b2a_hex(data)) - - hdrs = inflater.inflate(data) - print(hdrs)