Documentation for the Riak Python Client Library is available here. The documentation source is found in docs/ subdirectory and can be built with Sphinx.
Documentation for Riak is available at http://docs.basho.com/riak/latest
The recommended version of Python for use with this client is Python 2.7. From the Riak Python Client root directory, execute:
python setup.py install
There is an additional dependency on the Python package setuptools.
Official packages are signed and published to PyPI.
To setup the default test configuration build a test Riak node (from a riak
directory):
make rel
See 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 :
cd buildbot
make preconfigure
Start your Riak node with riak start
from the the Riak directory, then back in buildbot
type:
make configure
make test
That will run the test suite twice: once with security enabled and once without.
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:
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 islocalhost
)--pb-port=
protocol buffers port number (default is8087
)--http-port=
http port number (default is8098
)--https-port=
https port number (default is8099
)
You may alternately add these lines to setup.cfg
:
[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:
python setup.py configure --riak-admin=$RIAK_DIR/bin/riak-admin
Optionally these configuration settings can be changed, too:
--username=
test user account (default istestuser
)--password=
password for test user account (default istestpassword
)--certuser=
secruity test user account (default iscertuser
)--certpass=
password for security test user account (default iscertpass
)
Similarly setup.cfg
may be modified instead. To run the tests against a Riak server (with configured TCP port configuration) on localhost, execute:
python setup.py test
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.
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.
If you don't have Riak Search enabled, you can set the SKIP_SEARCH
environment variable to 1 skip those tests.
If you don't have Search 2.0 enabled, you can set the RUN_YZ
environment variable to 0 to skip those tests.
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):
./setup.py create_bucket_types --riak-admin=$RIAK/bin/riak-admin
You may alternately add these lines to `setup.cfg`:
[create_bucket_types]
riak-admin=/Users/sean/dev/riak/rel/riak/bin/riak-admin
To skip the bucket-type tests, set the SKIP_BTYPES
environment variable to 1
.
To test Secondary Indexes, the SKIP_INDEX
environment variable must be set to 0 (or 1 to skip them.)
By default Security 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:
python setup.py enable_security --riak-admin=$RIAK_DIR/bin/riak-admin
Once you are done testing security you can also:
python setup.py disable_security --riak-admin=$RIAK_DIR/bin/riak-admin
To run the tests, then simply:
RUN_SECURITY=1 RIAK_TEST_HTTP_PORT=18098 python setup.py test