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

Further reorg of cqlengine documentation

Browse Source
This commit is contained in:
Adam Holmberg
2015-02-09 14:31:39 -06:00
parent 5a22c2d7e4
commit d7a5f0a3f5
17 changed files with 86 additions and 415 deletions
Download Patch File Download Diff File Expand all files Collapse all files

18
cassandra/cqlengine/connection.py
View File

@@ -30,18 +30,14 @@ def setup(
retry_connect=False,
**kwargs):
"""
Records the hosts and connects to one of them
Setup a the driver connection used by the mapper
:param hosts: list of hosts, see http://datastax.github.io/python-driver/api/cassandra/cluster.html
:type hosts: list
:param default_keyspace: The default keyspace to use
:type default_keyspace: str
:param consistency: The global consistency level
:type consistency: int
:param lazy_connect: True if should not connect until first use
:type lazy_connect: bool
:param retry_connect: bool
:param retry_connect: True if we should retry to connect even if there was a connection failure initially
:param list hosts: list of hosts, see http://datastax.github.io/python-driver/api/cassandra/cluster.html
:param str default_keyspace: The default keyspace to use
:param int consistency: The global default :class:`~.ConsistencyLevel`
:param bool lazy_connect: True if should not connect until first use
:param bool retry_connect: True if we should retry to connect even if there was a connection failure initially
:param \*\*kwargs: Pass-through keyword arguments for :class:`cassandra.cluster.Cluster`
"""
global cluster, session, default_consistency_level, lazy_connect_args

50
cassandra/cqlengine/management.py
View File

@@ -19,13 +19,21 @@ schema_columnfamilies = NamedTable('system', 'schema_columnfamilies')
def create_keyspace(name, strategy_class, replication_factor, durable_writes=True, **replication_values):
"""
creates a keyspace
*Deprecated - this will likely be repaced with something specialized per replication strategy.*
Creates a keyspace
:param name: name of keyspace to create
:param strategy_class: keyspace replication strategy class
:param replication_factor: keyspace replication factor
:param durable_writes: 1.2 only, write log is bypassed if set to False
:param **replication_values: 1.2 only, additional values to ad to the replication data map
If the keyspace already exists, it will not be modified.
**This function should be used with caution, especially in production environments.
Take care to execute schema modifications in a single context (i.e. not concurrently with other clients).**
*There are plans to guard schema-modifying functions with an environment-driven conditional.*
:param str name: name of keyspace to create
:param str strategy_class: keyspace replication strategy class (:attr:`~.SimpleStrategy` or :attr:`~.NetworkTopologyStrategy`
:param int replication_factor: keyspace replication factor, used with :attr:`~.SimpleStrategy`
:param bool durable_writes: Write log is bypassed if set to False
:param \*\*replication_values: Additional values to ad to the replication options map
"""
cluster = get_cluster()
@@ -54,19 +62,31 @@ def create_keyspace(name, strategy_class, replication_factor, durable_writes=Tru
def delete_keyspace(name):
"""
*There are plans to guard schema-modifying functions with an environment-driven conditional.*
**This function should be used with caution, especially in production environments.
Take care to execute schema modifications in a single context (i.e. not concurrently with other clients).**
Drops a keyspace, if it exists.
:param str name: name of keyspace to delete
"""
cluster = get_cluster()
if name in cluster.metadata.keyspaces:
execute("DROP KEYSPACE {}".format(name))
def create_table(model):
raise CQLEngineException("create_table is deprecated, please use sync_table")
def sync_table(model):
"""
Inspects the model and creates / updates the corresponding table and columns.
Note that the attributes removed from the model are not deleted on the database.
They become effectively ignored by (will not show up on) the model.
**This function should be used with caution, especially in production environments.
Take care to execute schema modifications in a single context (i.e. not concurrently with other clients).**
*There are plans to guard schema-modifying functions with an environment-driven conditional.*
"""
if not issubclass(model, Model):
@@ -298,11 +318,15 @@ def update_compaction(model):
return False
def delete_table(model):
raise CQLEngineException("delete_table has been deprecated in favor of drop_table()")
def drop_table(model):
"""
Drops the table indicated by the model, if it exists.
**This function should be used with caution, especially in production environments.
Take care to execute schema modifications in a single context (i.e. not concurrently with other clients).**
*There are plans to guard schema-modifying functions with an environment-driven conditional.*
"""
# don't try to delete non existant tables
meta = get_cluster().metadata

7
docs/api/cassandra/cqlengine/connection.rst Normal file
View File

@@ -0,0 +1,7 @@
``cassandra.cqlengine.connection`` - Connection management for cqlengine
========================================================================
.. module:: cassandra.cqlengine.connection
.. autofunction:: setup

15
docs/api/cassandra/cqlengine/management.rst Normal file
View File

@@ -0,0 +1,15 @@
``cassandra.cqlengine.management`` - Schema management for cqlengine
========================================================================
.. module:: cassandra.cqlengine.management
A collection of functions for managing keyspace and table schema.
.. autofunction:: create_keyspace
.. autofunction:: delete_keyspace
.. autofunction:: sync_table
.. autofunction:: drop_table

1
docs/api/cassandra/cqlengine/models.rst
View File

@@ -10,6 +10,7 @@ Model
The initializer creates an instance of the model. Pass in keyword arguments for columns you've defined on the model.
.. code-block:: python
class Person(Model):
id = columns.UUID(primary_key=True)
first_name = columns.Text()

4
docs/api/index.rst
View File

@@ -25,6 +25,8 @@ Core Driver
cassandra/io/geventreactor
cassandra/io/twistedreactor
.. _om_api:
Object Mapper
-------------
.. toctree::
@@ -33,3 +35,5 @@ Object Mapper
cassandra/cqlengine/models
cassandra/cqlengine/columns
cassandra/cqlengine/query
cassandra/cqlengine/connection
cassandra/cqlengine/management

2
docs/conf.py
View File

@@ -125,7 +125,7 @@ html_theme_path = ['./themes']
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['_static']
html_static_path = []
# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
# using the given strftime format.

206
docs/cqlengine/columns.rst
View File

@@ -1,206 +0,0 @@
=======
Columns
=======
.. module:: cqlengine.columns
.. class:: Bytes()
Stores arbitrary bytes (no validation), expressed as hexadecimal ::
columns.Bytes()
.. class:: Ascii()
Stores a US-ASCII character string ::
columns.Ascii()
.. class:: Text()
Stores a UTF-8 encoded string ::
columns.Text()
**options**
:attr:`~columns.Text.min_length`
Sets the minimum length of this string. If this field is not set , and the column is not a required field, it defaults to 0, otherwise 1.
:attr:`~columns.Text.max_length`
Sets the maximum length of this string. Defaults to None
.. class:: Integer()
Stores a 32-bit signed integer value ::
columns.Integer()
.. class:: BigInt()
Stores a 64-bit signed long value ::
columns.BigInt()
.. class:: VarInt()
Stores an arbitrary-precision integer ::
columns.VarInt()
.. class:: DateTime()
Stores a datetime value.
columns.DateTime()
.. class:: UUID()
Stores a type 1 or type 4 UUID.
columns.UUID()
.. class:: TimeUUID()
Stores a UUID value as the cql type 'timeuuid' ::
columns.TimeUUID()
.. classmethod:: from_datetime(dt)
generates a TimeUUID for the given datetime
:param dt: the datetime to create a time uuid from
:type dt: datetime.datetime
:returns: a time uuid created from the given datetime
:rtype: uuid1
.. class:: Boolean()
Stores a boolean True or False value ::
columns.Boolean()
.. class:: Float()
Stores a floating point value ::
columns.Float()
**options**
:attr:`~columns.Float.double_precision`
If True, stores a double precision float value, otherwise single precision. Defaults to True.
.. class:: Decimal()
Stores a variable precision decimal value ::
columns.Decimal()
.. class:: Counter()
Counters can be incremented and decremented ::
columns.Counter()
Collection Type Columns
----------------------------
CQLEngine also supports container column types. Each container column requires a column class argument to specify what type of objects it will hold. The Map column requires 2, one for the key, and the other for the value
*Example*
.. code-block:: python
class Person(Model):
id = columns.UUID(primary_key=True, default=uuid.uuid4)
first_name = columns.Text()
last_name = columns.Text()
friends = columns.Set(columns.Text)
enemies = columns.Set(columns.Text)
todo_list = columns.List(columns.Text)
birthdays = columns.Map(columns.Text, columns.DateTime)
.. class:: Set()
Stores a set of unordered, unique values. Available only with Cassandra 1.2 and above ::
columns.Set(value_type)
**options**
:attr:`~columns.Set.value_type`
The type of objects the set will contain
:attr:`~columns.Set.strict`
If True, adding this column will raise an exception during save if the value is not a python `set` instance. If False, it will attempt to coerce the value to a set. Defaults to True.
.. class:: List()
Stores a list of ordered values. Available only with Cassandra 1.2 and above ::
columns.List(value_type)
**options**
:attr:`~columns.List.value_type`
The type of objects the set will contain
.. class:: Map()
Stores a map (dictionary) collection, available only with Cassandra 1.2 and above ::
columns.Map(key_type, value_type)
**options**
:attr:`~columns.Map.key_type`
The type of the map keys
:attr:`~columns.Map.value_type`
The type of the map values
Column Options
==============
Each column can be defined with optional arguments to modify the way they behave. While some column types may define additional column options, these are the options that are available on all columns:
.. attribute:: BaseColumn.primary_key
If True, this column is created as a primary key field. A model can have multiple primary keys. Defaults to False.
*In CQL, there are 2 types of primary keys: partition keys and clustering keys. As with CQL, the first primary key is the partition key, and all others are clustering keys, unless partition keys are specified manually using* :attr:`BaseColumn.partition_key`
.. attribute:: BaseColumn.partition_key
If True, this column is created as partition primary key. There may be many partition keys defined, forming a *composite partition key*
.. attribute:: BaseColumn.index
If True, an index will be created for this column. Defaults to False.
*Note: Indexes can only be created on models with one primary key*
.. attribute:: BaseColumn.db_field
Explicitly sets the name of the column in the database table. If this is left blank, the column name will be the same as the name of the column attribute. Defaults to None.
.. attribute:: BaseColumn.default
The default value for this column. If a model instance is saved without a value for this column having been defined, the default value will be used. This can be either a value or a callable object (ie: datetime.now is a valid default argument).
.. attribute:: BaseColumn.required
If True, this model cannot be saved without a value defined for this column. Defaults to False. Primary key fields cannot have their required fields set to False.
.. attribute:: BaseColumn.clustering_order
Defines CLUSTERING ORDER for this column (valid choices are "asc" (default) or "desc"). It may be specified only for clustering primary keys - more: http://www.datastax.com/docs/1.2/cql_cli/cql/CREATE_TABLE#using-clustering-order

27
docs/cqlengine/connection.rst
View File

@@ -1,27 +0,0 @@
==========
Connection
==========
.. module:: cqlengine.connection
The setup function in `cqlengine.connection` records the Cassandra servers to connect to.
If there is a problem with one of the servers, cqlengine will try to connect to each of the other connections before failing.
.. function:: setup(hosts)
:param hosts: list of hosts, strings in the <hostname>:<port>, or just <hostname>
:type hosts: list
:param default_keyspace: keyspace to default to
:type default_keyspace: str
:param consistency: the consistency level of the connection, defaults to 'ONE'
:type consistency: int
# see http://datastax.github.io/python-driver/api/cassandra.html#cassandra.ConsistencyLevel
Records the hosts and connects to one of them
See the example at :ref:`getting-started`

47
docs/cqlengine/development.rst
View File

@@ -1,47 +0,0 @@
==================
Development
==================
Travis CI
================
Tests are run using Travis CI using a Matrix to test different Cassandra and Python versions. It is located here: https://travis-ci.org/cqlengine/cqlengine
Python versions:
- 2.7
- 3.4
Cassandra vesions:
- 1.2 (protocol_version 1)
- 2.0 (protocol_version 2)
- 2.1 (upcoming, protocol_version 3)
Pull Requests
===============
Only Pull Requests that have passed the entire matrix will be considered for merge into the main codebase.
Please see the contributing guidelines: https://github.com/cqlengine/cqlengine/blob/master/CONTRIBUTING.md
Testing Locally
=================
Before testing, you'll need to set an environment variable to the version of Cassandra that's being tested. The version cooresponds to the <Major><Minor> release, so for example if you're testing against Cassandra 2.1, you'd set the following:
.. code-block:: bash
export CASSANDRA_VERSION=20
At the command line, execute:
.. code-block:: bash
bin/test.py
This is a wrapper for nose that also sets up the database connection.

22
docs/cqlengine/external_resources.rst
View File

@@ -1,22 +0,0 @@
============================
External Resources
============================
Video Tutorials
================
Introduction to CQLEngine: https://www.youtube.com/watch?v=zrbQcPNMbB0
TimeUUID and Table Polymorphism: https://www.youtube.com/watch?v=clXN9pnakvI
Blog Posts
===========
Blake Eggleston on Table Polymorphism in the .8 release: http://blakeeggleston.com/cqlengine-08-released.html

2
docs/cqlengine/faq.rst
View File

@@ -3,7 +3,7 @@ Frequently Asked Questions
==========================
Q: Why don't updates work correctly on models instantiated as Model(field=blah, field2=blah2)?
-------------------------------------------------------------------
----------------------------------------------------------------------------------------------
A: The recommended way to create new rows is with the models .create method. The values passed into a model's init method are interpreted by the model as the values as they were read from a row. This allows the model to "know" which rows have changed since the row was read out of cassandra, and create suitable update statements.

47
docs/cqlengine/manage_schemas.rst
View File

@@ -1,47 +0,0 @@
================
Managing Schemas
================
**Users of versions < 0.4, please read this post before upgrading:** `Breaking Changes`_
.. _Breaking Changes: https://groups.google.com/forum/?fromgroups#!topic/cqlengine-users/erkSNe1JwuU
.. module:: cqlengine.connection
.. module:: cqlengine.management
Once a connection has been made to Cassandra, you can use the functions in ``cqlengine.management`` to create and delete keyspaces, as well as create and delete tables for defined models
.. function:: create_keyspace(name)
:param name: the keyspace name to create
:type name: string
creates a keyspace with the given name
.. function:: delete_keyspace(name)
:param name: the keyspace name to delete
:type name: string
deletes the keyspace with the given name
.. function:: sync_table(model)
:param model: the :class:`~cqlengine.model.Model` class to make a table with
:type model: :class:`~cqlengine.model.Model`
syncs a python model to cassandra (creates & alters)
.. function:: drop_table(model)
:param model: the :class:`~cqlengine.model.Model` class to delete a column family for
:type model: :class:`~cqlengine.model.Model`
deletes the CQL table for the given model
See the example at :ref:`getting-started`

6
docs/cqlengine/models.rst
View File

@@ -20,8 +20,8 @@ This example defines a ``Person`` table, with the columns ``first_name`` and ``l
.. code-block:: python
from cassandra.cqlengine import columns
from cassandra.cqlengine.models import Model
from cassandra.cqlengine import columns
from cassandra.cqlengine.models import Model
class Person(Model):
id = columns.UUID(primary_key=True)
@@ -72,7 +72,7 @@ To sync the models to the database, you may do the following*:
sync_table(Comment)
\*Note: synchronizing models causes schema changes, and should be done with caution.
Please see the discussion in :doc:`manage_schemas` for considerations.
Please see the discussion in :doc:`/api/cassandra/cqlengine/management` for considerations.
For examples on manipulating data and creating queries, see :doc:`queryset`

2
docs/cqlengine/queryset.rst
View File

@@ -222,7 +222,7 @@ Token Function
next_page = list(query.filter(pk__token__gt=cqlengine.Token(last.pk)))
QuerySets are immutable
======================
=======================
When calling any method that changes a queryset, the method does not actually change the queryset object it's called on, but returns a new queryset object with the attributes of the original queryset, plus the attributes added in the method call.

22
docs/cqlengine/related_projects.rst
View File

@@ -1,22 +0,0 @@
==================================
Related Projects
==================================
Cassandra Native Driver
=========================
- Docs: http://datastax.github.io/python-driver/api/index.html
- Github: https://github.com/datastax/python-driver
- Pypi: https://pypi.python.org/pypi/cassandra-driver/2.1.0
Sphinx Contrib Module
=========================
- Github https://github.com/dokai/sphinxcontrib-cqlengine
Django Integration
=========================
- Github https://cqlengine.readthedocs.org

23
docs/object_mapper.rst
View File

@@ -3,31 +3,24 @@ Object Mapper
cqlengine is the Cassandra CQL 3 Object Mapper packaged with this driver
:ref:`getting-started`
:ref:`Jump to Getting Started <getting-started>`
Contents
--------
:doc:`cqlengine/models`
Mapping objects to tables
Examples defining models, and mapping them to tables
:doc:`cqlengine/queryset`
Query sets, filtering
Overview of query sets and filtering
:doc:`cqlengine/batches`
Batch mutations
Working with batch mutations
:doc:`cqlengine/connection`
Managing connections
:doc:`cqlengine/manage_schemas`
:doc:`cqlengine/external_resources`
:doc:`cqlengine/related_projects`
:ref:`API Documentation <om_api>`
Index of API documentation
:doc:`cqlengine/third_party`
:doc:`cqlengine/development`
High-level examples in Celery and uWSGI
:doc:`cqlengine/faq`
@@ -37,6 +30,8 @@ Contents
cqlengine/models
cqlengine/queryset
cqlengine/batches
cqlengine/third_party
cqlengine/faq
.. _getting-started: