From 7ec8d390074826377d2c4d5aa34ce0ba09c84c51 Mon Sep 17 00:00:00 2001 From: Adam Holmberg Date: Wed, 19 Aug 2015 16:21:02 -0500 Subject: [PATCH] doc: add cython extensions to installation page --- docs/installation.rst | 45 ++++++++++++++++++++++++++++++------------- 1 file changed, 32 insertions(+), 13 deletions(-) diff --git a/docs/installation.rst b/docs/installation.rst index d5da6c9f..33ad869b 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -4,8 +4,7 @@ Installation Supported Platforms ------------------- Python 2.6, 2.7, 3.3, and 3.4 are supported. Both CPython (the standard Python -implementation) and `PyPy `_ are supported and tested -against. +implementation) and `PyPy `_ are supported and tested. Linux, OSX, and Windows are supported. @@ -65,7 +64,7 @@ To check if the installation was successful, you can run:: python -c 'import cassandra; print cassandra.__version__' -It should print something like "2.0.0". +It should print something like "2.7.0". (*Optional*) Compression Support -------------------------------- @@ -94,30 +93,33 @@ support this:: pip install scales -(*Optional*) Sorted Sets ------------------------- +(*Optional*) blist for Sorted Sets +---------------------------------- Cassandra can store entire collections within a column. One of those collection types is a set. Cassandra's sets are actually ordered -sets. By default, the driver will use unordered sets to represent -these collections. If you would like to maintain the ordering, +sets. By default, the driver will use a pure Python ordered sets to represent +these collections. If you would like to use an optimized implementation, install the ``blist`` library:: pip install blist +* Note: blist performance is not necessarily better for simply querying sets. +The only benefit may come with doing set logic in results processing. + (*Optional*) Non-python Dependencies ------------------------------------ The driver has several **optional** features that have non-Python dependencies. C Extensions ^^^^^^^^^^^^ -By default, two C extensions are compiled: one that adds support -for token-aware routing with the ``Murmur3Partitioner``, and one that -allows you to use `libev `_ -for the event loop, which improves performance. +By default, a number of extensions are complect, providing faster hashing +for token-aware routing with the ``Murmur3Partitioner``, +`libev `_ event loop integration, +and Cython optimized extensions. When installing manually through setup.py, you can disable both with -the ``--no-extensions`` option, or selectively disable one or the other -with ``--no-murmur3`` and ``--no-libev``. +the ``--no-extensions`` option, or selectively disable them with +with ``--no-murmur3``, ``--no-libev``, or ``--no-cython``. To compile the extensions, ensure that GCC and the Python headers are available. @@ -133,6 +135,23 @@ On OS X, homebrew installations of Python should provide the necessary headers. See :ref:`windows_build` for notes on configuring the build environment on Windows. +Cython-based Extensions +~~~~~~~~~~~~~~~~~~~~~~~ +By default, this package uses `Cython `_ to optimize core modules and build custom extensions. +This is not a hard requirement, but is engaged by default to build extensions offering better performance than the +pure Python implementation. + +This build phase can be avoided using the build switch, or an environment variable:: + + python setup.py install --no-cython + -or- + pip install --install-option="--no-cython" + +Alternatively, an environment variable can be used to switch this option regardless of +context:: + + CASS_DRIVER_NO_CYTHON=1 + libev support ^^^^^^^^^^^^^ The driver currently uses Python's ``asyncore`` module for its default