Skip to content

Commit d7a5f0a

Browse files
aholmbergaholmberg
committed
Further reorg of cqlengine documentation
1 parent 5a22c2d commit d7a5f0a

17 files changed

Lines changed: 86 additions & 415 deletions

‎cassandra/cqlengine/connection.py‎

Lines changed: 8 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -30,18 +30,14 @@ def setup(
3030
retry_connect=False,
3131
**kwargs):
3232
"""
33-
Records the hosts and connects to one of them
34-
35-
:param hosts: list of hosts, see http://datastax.github.io/python-driver/api/cassandra/cluster.html
36-
:type hosts: list
37-
:param default_keyspace: The default keyspace to use
38-
:type default_keyspace: str
39-
:param consistency: The global consistency level
40-
:type consistency: int
41-
:param lazy_connect: True if should not connect until first use
42-
:type lazy_connect: bool
43-
:param retry_connect: bool
44-
:param retry_connect: True if we should retry to connect even if there was a connection failure initially
33+
Setup a the driver connection used by the mapper
34+
35+
:param list hosts: list of hosts, see http://datastax.github.io/python-driver/api/cassandra/cluster.html
36+
:param str default_keyspace: The default keyspace to use
37+
:param int consistency: The global default :class:`~.ConsistencyLevel`
38+
:param bool lazy_connect: True if should not connect until first use
39+
:param bool retry_connect: True if we should retry to connect even if there was a connection failure initially
40+
:param \*\*kwargs: Pass-through keyword arguments for :class:`cassandra.cluster.Cluster`
4541
"""
4642
global cluster, session, default_consistency_level, lazy_connect_args
4743

‎cassandra/cqlengine/management.py‎

Lines changed: 36 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -19,13 +19,21 @@
1919

2020
def create_keyspace(name, strategy_class, replication_factor, durable_writes=True, **replication_values):
2121
"""
22-
creates a keyspace
22+
*Deprecated - this will likely be repaced with something specialized per replication strategy.*
23+
Creates a keyspace
2324
24-
:param name: name of keyspace to create
25-
:param strategy_class: keyspace replication strategy class
26-
:param replication_factor: keyspace replication factor
27-
:param durable_writes: 1.2 only, write log is bypassed if set to False
28-
:param **replication_values: 1.2 only, additional values to ad to the replication data map
25+
If the keyspace already exists, it will not be modified.
26+
27+
**This function should be used with caution, especially in production environments.
28+
Take care to execute schema modifications in a single context (i.e. not concurrently with other clients).**
29+
30+
*There are plans to guard schema-modifying functions with an environment-driven conditional.*
31+
32+
:param str name: name of keyspace to create
33+
:param str strategy_class: keyspace replication strategy class (:attr:`~.SimpleStrategy` or :attr:`~.NetworkTopologyStrategy`
34+
:param int replication_factor: keyspace replication factor, used with :attr:`~.SimpleStrategy`
35+
:param bool durable_writes: Write log is bypassed if set to False
36+
:param \*\*replication_values: Additional values to ad to the replication options map
2937
"""
3038
cluster = get_cluster()
3139

@@ -54,19 +62,31 @@ def create_keyspace(name, strategy_class, replication_factor, durable_writes=Tru
5462

5563

5664
def delete_keyspace(name):
65+
"""
66+
*There are plans to guard schema-modifying functions with an environment-driven conditional.*
67+
68+
**This function should be used with caution, especially in production environments.
69+
Take care to execute schema modifications in a single context (i.e. not concurrently with other clients).**
70+
71+
Drops a keyspace, if it exists.
72+
73+
:param str name: name of keyspace to delete
74+
"""
5775
cluster = get_cluster()
5876
if name in cluster.metadata.keyspaces:
5977
execute("DROP KEYSPACE {}".format(name))
6078

61-
def create_table(model):
62-
raise CQLEngineException("create_table is deprecated, please use sync_table")
63-
6479
def sync_table(model):
6580
"""
6681
Inspects the model and creates / updates the corresponding table and columns.
6782
6883
Note that the attributes removed from the model are not deleted on the database.
6984
They become effectively ignored by (will not show up on) the model.
85+
86+
**This function should be used with caution, especially in production environments.
87+
Take care to execute schema modifications in a single context (i.e. not concurrently with other clients).**
88+
89+
*There are plans to guard schema-modifying functions with an environment-driven conditional.*
7090
"""
7191

7292
if not issubclass(model, Model):
@@ -298,11 +318,15 @@ def update_compaction(model):
298318
return False
299319

300320

301-
def delete_table(model):
302-
raise CQLEngineException("delete_table has been deprecated in favor of drop_table()")
321+
def drop_table(model):
322+
"""
323+
Drops the table indicated by the model, if it exists.
303324
325+
**This function should be used with caution, especially in production environments.
326+
Take care to execute schema modifications in a single context (i.e. not concurrently with other clients).**
304327
305-
def drop_table(model):
328+
*There are plans to guard schema-modifying functions with an environment-driven conditional.*
329+
"""
306330

307331
# don't try to delete non existant tables
308332
meta = get_cluster().metadata

‎docs/api/cassandra/cqlengine/connection.rst‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
``cassandra.cqlengine.connection`` - Connection management for cqlengine
2+
========================================================================
3+
4+
.. module:: cassandra.cqlengine.connection
5+
6+
.. autofunction:: setup
7+

‎docs/api/cassandra/cqlengine/management.rst‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
``cassandra.cqlengine.management`` - Schema management for cqlengine
2+
========================================================================
3+
4+
.. module:: cassandra.cqlengine.management
5+
6+
A collection of functions for managing keyspace and table schema.
7+
8+
.. autofunction:: create_keyspace
9+
10+
.. autofunction:: delete_keyspace
11+
12+
.. autofunction:: sync_table
13+
14+
.. autofunction:: drop_table
15+

‎docs/api/cassandra/cqlengine/models.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,7 @@ Model
1010
The initializer creates an instance of the model. Pass in keyword arguments for columns you've defined on the model.
1111

1212
.. code-block:: python
13+
1314
class Person(Model):
1415
id = columns.UUID(primary_key=True)
1516
first_name = columns.Text()

‎docs/api/index.rst‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,8 @@ Core Driver
2525
cassandra/io/geventreactor
2626
cassandra/io/twistedreactor
2727

28+
.. _om_api:
29+
2830
Object Mapper
2931
-------------
3032
.. toctree::
@@ -33,3 +35,5 @@ Object Mapper
3335
cassandra/cqlengine/models
3436
cassandra/cqlengine/columns
3537
cassandra/cqlengine/query
38+
cassandra/cqlengine/connection
39+
cassandra/cqlengine/management

‎docs/conf.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -125,7 +125,7 @@
125125
# Add any paths that contain custom static files (such as style sheets) here,
126126
# relative to this directory. They are copied after the builtin static files,
127127
# so a file named "default.css" will overwrite the builtin "default.css".
128-
html_static_path = ['_static']
128+
html_static_path = []
129129

130130
# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
131131
# using the given strftime format.

‎docs/cqlengine/columns.rst‎

Lines changed: 0 additions & 206 deletions
This file was deleted.

‎docs/cqlengine/connection.rst‎

Lines changed: 0 additions & 27 deletions
This file was deleted.

0 commit comments

Comments
 (0)