openstack/deb-python-cassandra-driver
Code Issues Proposed changes

doc: add cython extensions to installation page

Browse Source
This commit is contained in:
Adam Holmberg
2015-08-19 16:21:02 -05:00
parent aaf06792ec
commit 7ec8d39007
1 changed files with 32 additions and 13 deletions
Download Patch File Download Diff File Expand all files Collapse all files

45
docs/installation.rst
View File

@@ -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 <http://pypy.org>`_ are supported and tested
against.
implementation) and `PyPy <http://pypy.org>`_ 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 <http://software.schmorp.de/pkg/libev.html>`_
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 <http://software.schmorp.de/pkg/libev.html>`_ 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 <http://cython.org/>`_ 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" <spec-or-path>
Alternatively, an environment variable can be used to switch this option regardless of
context::
CASS_DRIVER_NO_CYTHON=1 <your script here>
libev support
^^^^^^^^^^^^^
The driver currently uses Python's ``asyncore`` module for its default