Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

Doc cleanup

  • Loading branch information...
commit ec9a5debbf96915a474379716b7d8dc85ffb0b00 1 parent 9d287ce
@thobbs thobbs authored
View
8 doc/api/index.rst
@@ -17,11 +17,3 @@ Pycassa Modules
pycassa/util
pycassa/connection
pycassa/logging/pycassa_logger
-
-Thrift Generated Modules
-------------------------
-
-.. toctree::
- :maxdepth: 3
-
- pycassa/cassandra/ttypes
View
5 doc/api/pycassa/cassandra/ttypes.rst
@@ -1,5 +0,0 @@
-:mod:`pycassa.cassandra.ttypes` -- Thrift Object Types
-======================================================
-
-.. automodule:: pycassa.cassandra.ttypes
- :members:
View
10 doc/installation.rst
@@ -3,13 +3,13 @@
Installing
==========
-easy_install
-------------
-If you have :file:`easy_install` installed, you can simply do:
+Installing from PyPi
+--------------------
+If you have :file:`pip` installed, you can simply do:
.. code-block:: bash
- $ easy_install pycassa
+ $ pip install pycassa
This will also install the Thrift python bindings automatically.
@@ -19,7 +19,7 @@ Make sure that you have Thrift's python bindings installed:
.. code-block:: bash
- $ easy_install thrift05
+ $ pip install thrift
You can download a release from
`github <http://github.com/pycassa/pycassa/downloads>`_
View
105 doc/tutorial.rst
@@ -19,9 +19,9 @@ should run without raising an exception:
This tutorial also assumes that a Cassandra instance is running on the
default host and port. Read the `instructions for getting started
-with Cassandra <http://www.datastax.com/docs/0.7/getting_started/index>`_ ,
-making sure that you choose a `version that is compatible with
-pycassa <http://wiki.github.com/pycassa/pycassa/pycassa-cassandra-compatibility>`_.
+with Cassandra <http://www.datastax.com/docs/0.7/getting_started/index>`_ if
+you need help with this.
+
You can start Cassandra like so:
.. code-block:: bash
@@ -67,6 +67,9 @@ for this tutorial:
This connects to a local instance of Cassandra and creates a keyspace
named 'Keyspace1' with a column family named 'ColumnFamily1'.
+You can find further `documentation for the CLI online
+<http://www.datastax.com/docs/1.0/dml/using_cli>`_.
+
Using pycassaShell
^^^^^^^^^^^^^^^^^^
:ref:`pycassa-shell` is an interactive Python shell that is included
@@ -77,7 +80,7 @@ environment to work with.
Here's how to create the keyspace and column family:
-.. code-block:: bash
+.. code-block:: none
user@~ $ pycassaShell
----------------------------------
@@ -246,7 +249,7 @@ with keys 'row_key1' through 'row_key9', we can do this:
.. 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.7/operations/clustering#partitioners.
+ http://www.datastax.com/docs/1.0/cluster_architecture/partitioning.
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()`,
@@ -299,40 +302,21 @@ You can also do this in parallel for multiple rows using
Typed Column Names and Values
-----------------------------
-In Cassandra 0.7, you can specify a comparator type for column names
-and a validator type for column values.
-
-The types available are:
-
-* BytesType - no type
-* IntegerType - 32 bit integer
-* LongType - 64 bit integer
-* AsciiType - ASCII string
-* UTF8Type - UTF8 encoded string
-* TimeUUIDType - version 1 UUID (timestamp based)
-* LexicalUUID - non-version 1 UUID
-
-The column name comparator types affect how columns are sorted within
-a row. You can use these with standard column families as well as with
-super column families; with super column families, the subcolumns may
-even have a different comparator type. Here's an example ``cassandra.yaml``:
-
-::
-
- - name: StandardInt
- column_type: Standard
- compare_with: IntegerType
+Within a column family, column names have a specified `comparator type`
+which controls how they are sorted. Column values and row keys may also
+have a `validation class`, which validates that inserted values are
+the correct type.
- - name: SuperLongSubAscii
- column_type: Super
- compare_with: LongType
- compare_subcolumns_with: AsciiType
+The different types available include ASCII strings, integers, dates,
+UTF8, raw bytes, UUIDs, and more. See :mod:`pycassa.types` for a full
+list.
-Cassandra still requires you to pack these types into a format it can
+Cassandra requires you to pack column names and values into a format it can
understand by using something like :meth:`struct.pack()`. Fortunately,
-when **pycassa** sees that a column family uses these types, it knows
-to pack and unpack these data types automatically for you. So, if we want to
-write to the StandardInt column family, we can do the following:
+when **pycassa** sees that a column family has a particular comparator type
+or validation class, it knows to pack and unpack these data types automatically
+for you. So, if we want to write to the StandardInt column family, which has
+an IntegerType comparator, we can do the following:
.. code-block:: python
@@ -344,49 +328,24 @@ write to the StandardInt column family, we can do the following:
Notice that 42 is an integer here, not a string.
-As mentioned above, Cassandra also offers validators on column values with
-the same set of types. Validators can be set for an entire column family,
-for individual columns, or both. Here's another example ``cassandra.yaml``:
-
-::
-
- - name: AllLongs
- column_type: Standard
- default_validation_class: LongType
-
- - name: OneUUID
- column_type: Standard
- column_metadata:
- - name: uuid
- validator_class: TimeUUIDType
-
- - name: LongsExceptUUID
- column_type: Standard
- default_validation_class: LongType
- column_metadata:
- - name: uuid
- validator_class: TimeUUIDType
-
-**pycassa** knows to pack these column values automatically too:
+As mentioned above, Cassandra also offers validators on column values and keys
+with the same set of types. Column value validators can be set for an entire
+column family, for individual columns, or both. **pycassa** knows to pack these
+column values automatically too. Suppose we have a `Users` column family with
+two columns, ``name`` and ``age``, with types UTF8Type and IntegerType:
.. code-block:: python
- >>> import uuid
- >>> col_fam = pycassa.ColumnFamily(pool, 'LongsExceptUUID')
- >>> col_fam.insert('row_key', {'foo': 123456789, 'uuid': uuid.uuid1()})
+ >>> col_fam = pycassa.ColumnFamily(pool, 'Users')
+ >>> col_fam.insert('thobbs', {'name': 'Tyler', 'age': 24})
1354491238782746
- >>> col_fam.get('row_key')
- {'foo': 123456789, 'uuid': UUID('5880c4b8-bd1a-11df-bbe1-00234d21610a')}
+ >>> col_fam.get('thobbs')
+ {'name': 'Tyler', 'age': 24}
Of course, if **pycassa**'s automatic behavior isn't working for you, you
-can turn it off when you create the
-:class:`~pycassa.columnfamily.ColumnFamily`:
-
-.. code-block:: python
-
- >>> col_fam = pycassa.ColumnFamily(pool, 'Standard1',
- ... autopack_names=False,
- ... autopack_values=False)
+can turn it off or change it using :attr:`~.ColumnFamily.autopack_names`,
+:attr:`~.ColumnFamily.autopack_values`, :attr:`~.ColumnFamily.column_name_class`,
+:attr:`~.ColumnFamily.default_validation_class`, and so on.
Connection Pooling
------------------
View
22 pycassa/columnfamily.py
@@ -63,8 +63,9 @@ class ColumnFamily(object):
buffer_size = 1024
""" When calling :meth:`get_range()` or :meth:`get_indexed_slices()`,
the intermediate results need to be buffered if we are fetching many
- rows, otherwise the Cassandra server will overallocate memory and fail.
- This is the size of that buffer in number of rows. The default is 1024. """
+ rows, otherwise performance may suffer and the Cassandra server may
+ overallocate memory and fail. This is the size of that buffer in number
+ of rows. The default is 1024. """
read_consistency_level = ConsistencyLevel.ONE
""" The default consistency level for every read operation, such as
@@ -87,7 +88,8 @@ class ColumnFamily(object):
""" Results are returned as dictionaries. By default, python 2.7's
:class:`collections.OrderedDict` is used if available, otherwise
:class:`~pycassa.util.OrderedDict` is used so that order is maintained.
- A different class, such as :class:`dict` may be used setting this. """
+ A different class, such as :class:`dict`, may be instead by used setting
+ this. """
autopack_names = True
""" Controls whether column names are automatically converted to or from
@@ -130,7 +132,8 @@ def _get_column_name_class(self):
This is set automatically by inspecting the column family's
``comparator_type``, but it may also be set manually if you want
autopacking behavior without setting a ``comparator_type``. Options
- include anything in :mod:`~pycassa.system_manager`, such as "LongType". """
+ include an instance of any class in :mod:`pycassa.types`, such as ``LongType()``.
+ """
def _set_super_column_name_class(self, t):
if isinstance(t, types.CassandraType):
@@ -195,7 +198,8 @@ def _get_default_validation_class(self):
This is set automatically by inspecting the column family's
``default_validation_class``, but it may also be set manually if you want
autopacking behavior without setting a ``default_validation_class``. Options
- include anything in :mod:`~pycassa.system_manager`, such as "LongType". """
+ include an instance of any class in :mod:`pycassa.types`, such as ``LongType()``.
+ """
def _set_column_validators(self, other_dict):
self._column_validators = ColumnValidatorDict(other_dict)
@@ -229,8 +233,9 @@ def _get_key_validation_class(self):
``key_validation_class`` (which only exists in Cassandra 0.8 or greater),
but may be set manually if you want the autopacking behavior without
setting a ``key_validation_class`` or if you are using Cassandra 0.7.
- Options include anything in :mod:`~pycassa.system_manager`, such as
- "LongType"."""
+ Options include an instance of any class in :mod:`pycassa.types`,
+ such as ``LongType()``.
+ """
def __init__(self, pool, column_family, **kwargs):
"""
@@ -926,8 +931,7 @@ def remove(self, key, columns=None, super_column=None,
If `columns` and `super_column` are both ``None``, the entire row is
removed.
- The timestamp used for remove is returned.
-
+ The timestamp used for the mutation is returned.
"""
if timestamp is None:
View
6 pycassa/columnfamilymap.py
@@ -3,8 +3,8 @@
.. seealso:: :mod:`pycassa.types`
-In addition to the default :class:`~pycassa.types.Column` classes,
-you may also define your own types for the mapper. For example, the
+In addition to the default classes in :class:`~pycassa.types`,
+you may also define your own types for the mapper. For example,
IntString may be defined as:
.. code-block:: python
@@ -45,7 +45,7 @@ def __init__(self, cls, pool, column_family, columns=None, raw_columns=False, **
:meth:`get_range()` and :meth:`get_indexed_slices()`.
`pool` is a :class:`~pycassa.pool.ConnectionPool` that will be used
- in the same way a :class:ColumnFamily uses one.
+ in the same way a :class:`~.ColumnFamily` uses one.
`column_family` is the name of a column family to tie to `cls`.
Please sign in to comment.
Something went wrong with that request. Please try again.