Skip to main content

Python client for Riak

Project description

======================
Python Client for Riak
======================

Documentation
=============

`Documentation for the Riak Python Client Library
<http://basho.github.io/riak-python-client/index.html>`_ is available
here. The documentation source is found in `docs/ subdirectory
<https://github.com/basho/riak-python-client/tree/master/docs>`_ and
can be built with `Sphinx <http://sphinx.pocoo.org/>`_.

Documentation for Riak is available at http://docs.basho.com/riak/latest

Install
=======

The recommended versions of Python for use with this client are Python
`2.7.x`, `3.3.x`, `3.4.x` and `3.5.x`. The latest version from each series
should be preferred.

Riak TS (Timeseries)
===================

You must use version `2.7.11`, `3.4.4` or `3.5.1` (or greater within a version series).
Otherwise you will be affected by `this Python bug <https://bugs.python.org/issue23517>`_.


From Source
-----------

.. code-block:: console

python setup.py install

There are additional dependencies on Python packages `setuptools` and `protobuf`.

From PyPI
---------

Official packages are signed and published to `PyPI
<https://pypi.python.org/pypi/riak>`_.

To install from `PyPI <https://pypi.python.org/pypi/riak>`_ directly you can use
`pip`.

.. code-block:: console

pip install riak


Testing
=======

To setup the default test configuration build a test Riak node (from
a ``riak`` directory)

.. code-block:: console

make rel

See `Basic Cluster Setup
<http://docs.basho.com/riak/2.0.0/ops/building/basic-cluster-setup/>`_
for more details.

For all of the simple default values, set the ``RIAK_DIR`` environment
variable to the root of your Riak installation. Then from the
``riak-python-client`` directory

.. code-block:: console

make -C buildbot preconfigure

Start your Riak node with ``riak start`` from the the Riak directory, then

.. code-block:: console

make -C buildbot configure
make -C buildbot test

That will run the test suite twice: once with security enabled and once
without.

Testing Options
---------------

If you wish to change the default options you can run the setup by hand.
First configure the test node by adjusting the ``riak.conf``
settings, where ``RIAK_DIR`` is the path to the top your
Riak installation

.. code-block:: console

python setup.py preconfigure --riak-conf=$RIAK_DIR/etc/riak.conf

Optionally the hostname and port numbers can be changed, too, via these
arguments:

- ``--host=`` IP of host running Riak (default is ``localhost``)
- ``--pb-port=`` protocol buffers port number (default is ``8087``)
- ``--http-port=`` http port number (default is ``8098``)
- ``--https-port=`` https port number (default is ``8099``)

You may alternately add these lines to ``setup.cfg``

.. code-block:: ini

[preconfigure]
riak-conf=/Users/sean/dev/riak/rel/riak/etc/riak.conf
host=localhost
pb-port=8087
http-port=8098
https-port=8099

Next start the test node. Once it is running, a test configuration is
installed which includes security test users and bucket types

.. code-block:: console

python setup.py configure --riak-admin=$RIAK_DIR/bin/riak-admin

Optionally these configuration settings can be changed, too:

- ``--username=`` test user account (default is ``testuser``)
- ``--password=`` password for test user account (default is
``testpassword``)
- ``--certuser=`` secruity test user account (default is ``certuser``)
- ``--certpass=`` password for security test user account (default is
``certpass``)

Similarly ``setup.cfg`` may be modified instead. To run the tests against a
Riak server (with configured TCP port configuration) on localhost, execute

.. code-block:: console

python setup.py test

Connections to Riak in Tests
----------------------------

If your Riak server isn't running on localhost or you have built a
Riak devrel from source, use the environment variables
``RIAK_TEST_HOST``, ``RIAK_TEST_HTTP_PORT`` and
``RIAK_TEST_PB_PORT`` to specify where to find the Riak server.
``RIAK_TEST_PROTOCOL`` to specify which protocol to test. Can be
either ``pbc`` or ``http``.

Some of the connection tests need port numbers that are NOT in use. If
ports 1023 and 1022 are in use on your test system, set the
environment variables ``DUMMY_HTTP_PORT`` and ``DUMMY_PB_PORT`` to
unused port numbers.

Testing Search
--------------

If you don't have `Riak Search
<http://docs.basho.com/riak/latest/dev/using/search/>`_ enabled, you
can set the ``RUN_SEARCH`` environment variable to 0 skip those
tests.

If you don't have `Search 2.0 <https://github.com/basho/yokozuna>`_
enabled, you can set the ``RUN_YZ`` environment variable to 0 to skip
those tests.

Testing Bucket Types (Riak 2+)
------------------------------

To test bucket-types, you must run the ``create_bucket_types`` setup
command, which will create the bucket-types used in testing, or create
them manually yourself. It can be run like so (substituting ``$RIAK``
with the root of your Riak install)

.. code-block:: console

./setup.py create_bucket_types --riak-admin=$RIAK/bin/riak-admin

You may alternately add these lines to `setup.cfg`

.. code-block:: ini

[create_bucket_types]
riak-admin=/Users/sean/dev/riak/rel/riak/bin/riak-admin

To skip the bucket-type tests, set the ``RUN_BTYPES`` environment
variable to ``0``.

Testing Data Types (Riak 2+)
----------------------------

To test data types, you must set up bucket types (see above.)

To skip the data type tests, set the ``RUN_DATATYPES`` environment
variable to ``0``.

Testing Timeseries (Riak 2.1+)
------------------------------

To test timeseries data, you must run the ``setup_timeseries`` command,
which will create the bucket-types used in testing, or create them
manually yourself. It can be run like so (substituting ``$RIAK`` with
the root of your Riak install)

.. code-block:: console

./setup.py setup_timeseries --riak-admin=$RIAK/bin/riak-admin

You may alternately add these lines to `setup.cfg`

.. code-block:: ini

[setup_timeseries]
riak-admin=/Users/sean/dev/riak/rel/riak/bin/riak-admin

To enable the timeseries tests, set the ``RUN_TIMESERIES`` environment
variable to ``1``.

Testing Secondary Indexes
-------------------------

To test
`Secondary Indexes <http://docs.basho.com/riak/2.0.0/dev/using/2i/>`_,
the ``RUN_INDEXES`` environment variable must be set to 1 (or 0 to skip them.)

Testing Security (Riak 2+)
--------------------------

By default
`Security <http://docs.basho.com/riak/2.0.0beta1/ops/running/authz/>`_ is not
enabled on Riak. Once ``security = on`` is configured in the ``riak.conf``
file it can be enabled with ``riak-admin``.

If you have set up the test environment outlined in the `Testing`_ section
you can go ahead and use this command to enable security

.. code-block:: console

python setup.py enable_security --riak-admin=$RIAK_DIR/bin/riak-admin

Once you are done testing security you can also

.. code-block:: console

python setup.py disable_security --riak-admin=$RIAK_DIR/bin/riak-admin

To run the tests, then simply

.. code-block:: console

RUN_SECURITY=1 RIAK_TEST_HTTP_PORT=18098 python setup.py test

Contributors
--------------------------
- Andrew Thompson
- Andy Gross <andy@basho.com>
- Armon Dadgar
- Brett Hazen
- Brett Hoerner
- Brian Roach
- Bryan Fink
- Daniel Lindsley
- Daniel Néri
- Daniel Reverri
- David Koblas
- Dmitry Rozhkov
- Eric Florenzano
- Eric Moritz
- Filip de Waard
- Gilles Devaux
- Greg Nelson
- Greg Stein
- Gregory Burd
- Ian Plosker
- Jayson Baird <jay@mochimedia.com>
- Jeffrey Massung
- Jon Meredith <jmeredith@basho.com>
- Josip Lisec
- Justin Sheehy <justin@basho.com>
- Kevin Smith
- `Luke Bakken <https://github.com/lukebakken>`_
- Mark Erdmann
- Mark Phillips
- Mathias Meyer
- Matt Heitzenroder
- Mikhail Sobolev
- Reid Draper
- Russell Brown
- Rusty Klophaus
- Rusty Klophaus <rusty@basho.com>
- Scott Lystig Fritchie
- Sean Cribbs
- Shuhao Wu
- Silas Sewell
- Socrates Lee
- Soren Hansen
- Sreejith Kesavan
- Timothée Peignier
- William Kral

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

riak-2.4.1.tar.gz (182.1 kB view hashes)

Uploaded Source

Built Distributions

riak-2.4.1-py3.5.egg (431.2 kB view hashes)

Uploaded Source

riak-2.4.1-py3.4.egg (432.1 kB view hashes)

Uploaded Source

riak-2.4.1-py3.3.egg (438.3 kB view hashes)

Uploaded Source

riak-2.4.1-py2.7.egg (421.0 kB view hashes)

Uploaded Source

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page