Permalink
Browse files

REAMDE and tutorial improvements.

  • Loading branch information...
thobbs committed Dec 5, 2010
1 parent 6772a15 commit c6960b839453e1a27236acb1487749ad4b42a942
Showing with 34 additions and 39 deletions.
  1. +13 −19 README.mkd
  2. +21 −20 doc/tutorial.rst
View
@@ -1,21 +1,23 @@
Note
====
-If you are using the 0.6.x series of Cassandra then get pycassa 0.3 from the
-Downloads section and read the documentation contained within. This README
-applies to the current state of pycassa which tracks Cassandra's development
-(work in-progress toward Cassandra 0.7).
+If you are using the Cassandra 0.6, then get pycassa 0.3 from the
+[Downloads](https://github.com/pycassa/pycassa/downloads) section and read the
+documentation contained within. This README applies to the current state of
+pycassa, which tracks Cassandra 0.7.
+
+See [the wiki](https://github.com/pycassa/pycassa/wiki/Pycassa-%2B-Cassandra-Compatibility)
+for more compatibility notes.
pycassa
=======
pycassa is a python client library for Apache Cassandra with the following features:
-1. Auto-failover single or thread-local connections
+1. Auto-failover for normal or thread-local connections
2. Connection pooling
3. A batch interface
-4. Simplified version of the Thrift interface
-5. A method to map an existing class to a Cassandra column family
+4. A method to map an existing class to a Cassandra column family
Documentation
-------------
@@ -42,16 +44,6 @@ Mailing List:
* User list: [http://groups.google.com/group/pycassa-discuss](http://groups.google.com/group/pycassa-discuss)
* Developer list: [http://groups.google.com/group/pycassa-devel](http://groups.google.com/group/pycassa-devel)
-Requirements
-------------
-
- thrift: http://incubator.apache.org/thrift/
- Cassandra: http://cassandra.apache.org
-
-To install thrift's python bindings:
-
- easy_install thrift05
-
Installation
------------
@@ -60,8 +52,10 @@ If easy_install is available, you can use:
easy_install pycassa
The simplest way to install manually is to copy the pycassa directories to
-your program. If you want to install, run setup.py as a superuser.
+your program. If you want to install, make sure you have thrift installed,
+and run setup.py as a superuser.
+ easy_install thrift05
python setup.py install
Connecting
@@ -78,7 +72,7 @@ To get a connection pool, pass a Keyspace and an optional list of servers:
>>> pool = pycassa.connect('Keyspace1') # Defaults to connecting to the server at 'localhost:9160'
>>> pool = pycassa.connect('Keyspace1', ['192.168.2.10:9160'])
-See the [tutorial](http://pycassa.github.com/pycassa/tutorial.html#making-a-connection) for more details.
+See the [tutorial](http://pycassa.github.com/pycassa/tutorial.html#connecting-to-cassandra) for more details.
Basic Usage
-----------
View
@@ -69,13 +69,7 @@ are included in the default schema file:
>>> col_fam = pycassa.ColumnFamily(pool, 'Standard1')
If you get an error about the keyspace or column family not
-existing, make sure you imported the yaml file. This can
-be done using Cassandra's :file:`bin/schematool`:
-
-.. code-block:: bash
-
- cd $CASSANDRA_HOME
- bin/schematool localhost 8080 import
+existing, make sure you imported the schema with :file:`bin/schematool`.
Inserting Data
--------------
@@ -125,9 +119,9 @@ specify them using a `columns` argument:
>>> col_fam.get('row_key', columns=['name1', 'name2'])
{'name1': 'foo', 'name2': 'bar'}
-We may also get a slice (or subrange) or the columns in a row. To do this,
+We may also get a slice (or subrange) of the columns in a row. To do this,
use the `column_start` and `column_finish` parameters. One or both of these may
-be left empty to allow the slice to extend to one or both ends the.
+be left empty to allow the slice to extend to one or both ends.
Note that `column_finish` is inclusive. Assuming we've inserted several
columns with names '1' through '9', we can do the following:
@@ -177,8 +171,10 @@ with keys 'row_key1' through 'row_key9', we can do this:
'row_key6' => {'name':'val'}
'row_key7' => {'name':'val'}
-.. note:: You must use an OrderPreservingPartitioner to be able to
- get a meaningful range of rows.
+.. note:: Cassandra must be using an OrderPreservingPartitioner for you to be
+ able to get a meaningful range of rows; the default, RandomPartitioner,
+ stores rows in the order of the MD5 hash of their keys. See
+ http://www.riptano.com/docs/0.6/operations/clustering#partitioners.
The last way to get multiple rows at a time is to take advantage of
secondary indexes by using :meth:`~pycassa.columnfamily.ColumnFamily.get_indexed_slices()`,
@@ -373,13 +369,17 @@ the following:
.. code-block:: python
>>> import pycassa
- >>> pool = pycassa.ConnectionPool('Keyspace1')
- >>> col_fam = pycassa.ColumnFamily(pool, 'Indexed1')
- >>> index_exp = pycassa.create_index_expression('birthdate', 1984)
- >>> index_clause = pycassa.create_index_clause([index_exp])
- >>> result = col_fam.get_indexed_slices(index_clause)
- >>> list(result)
- {'winston smith': {'birthdate': 1984}}
+ >>> from pycassa.index import *
+ >>> pool = pycassa.connect('Keyspace1')
+ >>> users = pycassa.ColumnFamily(pool, 'Users')
+ >>> state_expr = create_index_expression('state', 'Utah')
+ >>> bday_expr = create_index_expression('birthdate', 1970, GT)
+ >>> clause = create_index_clause([state_expr, bday_expr], count=20)
+ >>> for key, user in users.get_indexed_slices(clause):
+ ... print user['name'] + ",", user['state'], user['birthdate']
+ John Smith, Utah 1971
+ Mike Scott, Utah 1980
+ Jeff Bird, Utah 1973
Although at least one
:class:`~pycassa.cassandra.ttypes.IndexExpression` in the clause
@@ -513,5 +513,6 @@ and dropped using :class:`pycassa.system_manager.SystemManager`. Additionally,
indexes may be created and dropped using this class as well.
Although most of SystemManager's methods may be used in a program,
-it is recommended use this manually using a tool like :ref:`pycassa-shell`. There
-is a :ref:`provided example <pycassa-shell-sys-man>` of this usage.
+it is recommended that they be used manually with a tool like
+:ref:`pycassa-shell`. There is a
+:ref:`provided example <pycassa-shell-sys-man>` of this usage.

0 comments on commit c6960b8

Please sign in to comment.