Skip to content

Commit aa24bfb

Browse files
mambocabmambocab
authored
Merge pull request apache#937 from datastax/document-long-compile
Document long compile
2 parents 8aaa4c8 + 7fbaa36 commit aa24bfb

13 files changed

Lines changed: 312 additions & 264 deletions

File tree

‎CHANGELOG.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,7 @@ Other
1414
* Refactor CASSANDRA_VERSION to a some kind of version object (PYTHON-915)
1515
* Warn users when using the deprecated Session.default_consistency_level (PYTHON-953)
1616
* Add DSE smoke test to OSS driver tests (PYTHON-894)
17+
* Document long compilation times and workarounds (PYTHON-868)
1718

1819
3.13.0
1920
======

‎cassandra/cluster.py‎

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -230,10 +230,10 @@ class ExecutionProfile(object):
230230
231231
Some example implementations:
232232
233-
- :func:`cassandra.query.tuple_factory` - return a result row as a tuple
234-
- :func:`cassandra.query.named_tuple_factory` - return a result row as a named tuple
235-
- :func:`cassandra.query.dict_factory` - return a result row as a dict
236-
- :func:`cassandra.query.ordered_dict_factory` - return a result row as an OrderedDict
233+
- :func:`cassandra.query.tuple_factory` - return a result row as a tuple
234+
- :func:`cassandra.query.named_tuple_factory` - return a result row as a named tuple
235+
- :func:`cassandra.query.dict_factory` - return a result row as a dict
236+
- :func:`cassandra.query.ordered_dict_factory` - return a result row as an OrderedDict
237237
"""
238238

239239
speculative_execution_policy = None
@@ -1897,10 +1897,10 @@ def row_factory(self):
18971897
returned row will be a named tuple. You can alternatively
18981898
use any of the following:
18991899
1900-
- :func:`cassandra.query.tuple_factory` - return a result row as a tuple
1901-
- :func:`cassandra.query.named_tuple_factory` - return a result row as a named tuple
1902-
- :func:`cassandra.query.dict_factory` - return a result row as a dict
1903-
- :func:`cassandra.query.ordered_dict_factory` - return a result row as an OrderedDict
1900+
- :func:`cassandra.query.tuple_factory` - return a result row as a tuple
1901+
- :func:`cassandra.query.named_tuple_factory` - return a result row as a named tuple
1902+
- :func:`cassandra.query.dict_factory` - return a result row as a dict
1903+
- :func:`cassandra.query.ordered_dict_factory` - return a result row as an OrderedDict
19041904
19051905
"""
19061906
return self._row_factory

‎cassandra/concurrent.py‎

Lines changed: 6 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -49,13 +49,12 @@ def execute_concurrent(session, statements_and_parameters, concurrency=100, rais
4949
5050
`results_generator` controls how the results are returned.
5151
52-
If :const:`False`, the results are returned only after all requests have completed.
53-
54-
If :const:`True`, a generator expression is returned. Using a generator results in a constrained
55-
memory footprint when the results set will be large -- results are yielded
56-
as they return instead of materializing the entire list at once. The trade for lower memory
57-
footprint is marginal CPU overhead (more thread coordination and sorting out-of-order results
58-
on-the-fly).
52+
* If :const:`False`, the results are returned only after all requests have completed.
53+
* If :const:`True`, a generator expression is returned. Using a generator results in a constrained
54+
memory footprint when the results set will be large -- results are yielded
55+
as they return instead of materializing the entire list at once. The trade for lower memory
56+
footprint is marginal CPU overhead (more thread coordination and sorting out-of-order results
57+
on-the-fly).
5958
6059
A sequence of ``ExecutionResult(success, result_or_exc)`` namedtuples is returned
6160
in the same order that the statements were passed in. If ``success`` is :const:`False`,

‎cassandra/metrics.py‎

Lines changed: 11 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -37,17 +37,17 @@ class Metrics(object):
3737
A :class:`greplin.scales.PmfStat` timer for requests. This is a dict-like
3838
object with the following keys:
3939
40-
* count - number of requests that have been timed
41-
* min - min latency
42-
* max - max latency
43-
* mean - mean latency
44-
* stddev - standard deviation for latencies
45-
* median - median latency
46-
* 75percentile - 75th percentile latencies
47-
* 95percentile - 95th percentile latencies
48-
* 98percentile - 98th percentile latencies
49-
* 99percentile - 99th percentile latencies
50-
* 999percentile - 99.9th percentile latencies
40+
* count - number of requests that have been timed
41+
* min - min latency
42+
* max - max latency
43+
* mean - mean latency
44+
* stddev - standard deviation for latencies
45+
* median - median latency
46+
* 75percentile - 75th percentile latencies
47+
* 95percentile - 95th percentile latencies
48+
* 98percentile - 98th percentile latencies
49+
* 99percentile - 99th percentile latencies
50+
* 999percentile - 99.9th percentile latencies
5151
"""
5252

5353
connection_errors = None

‎cassandra/util.py‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -883,9 +883,9 @@ def __init__(self, value):
883883
"""
884884
Initializer value can be:
885885
886-
- integer_type: absolute nanoseconds in the day
887-
- datetime.time: built-in time
888-
- string_type: a string time of the form "HH:MM:SS[.mmmuuunnn]"
886+
- integer_type: absolute nanoseconds in the day
887+
- datetime.time: built-in time
888+
- string_type: a string time of the form "HH:MM:SS[.mmmuuunnn]"
889889
"""
890890
if isinstance(value, six.integer_types):
891891
self._from_timestamp(value)
@@ -1012,9 +1012,9 @@ def __init__(self, value):
10121012
"""
10131013
Initializer value can be:
10141014
1015-
- integer_type: absolute days from epoch (1970, 1, 1). Can be negative.
1016-
- datetime.date: built-in date
1017-
- string_type: a string time of the form "yyyy-mm-dd"
1015+
- integer_type: absolute days from epoch (1970, 1, 1). Can be negative.
1016+
- datetime.date: built-in date
1017+
- string_type: a string time of the form "yyyy-mm-dd"
10181018
"""
10191019
if isinstance(value, six.integer_types):
10201020
self.days_from_epoch = value

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

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -6,12 +6,12 @@
66
Columns
77
-------
88

9-
Columns in your models map to columns in your CQL table. You define CQL columns by defining column attributes on your model classes.
10-
For a model to be valid it needs at least one primary key column and one non-primary key column.
9+
Columns in your models map to columns in your CQL table. You define CQL columns by defining column attributes on your model classes.
10+
For a model to be valid it needs at least one primary key column and one non-primary key column.
1111

12-
Just as in CQL, the order you define your columns in is important, and is the same order they are defined in on a model's corresponding table.
12+
Just as in CQL, the order you define your columns in is important, and is the same order they are defined in on a model's corresponding table.
1313

14-
Each column on your model definitions needs to be an instance of a Column class.
14+
Each column on your model definitions needs to be an instance of a Column class.
1515

1616
.. autoclass:: Column(**kwargs)
1717

‎docs/api/cassandra/protocol.rst‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -45,11 +45,11 @@ and ``NumpyProtocolHandler``. They can be used as follows:
4545
4646
These protocol handlers comprise different parsers, and return results as described below:
4747

48-
- ProtocolHandler: this default implementation is a drop-in replacement for the pure-Python version.
49-
The rows are all parsed upfront, before results are returned.
48+
- ProtocolHandler: this default implementation is a drop-in replacement for the pure-Python version.
49+
The rows are all parsed upfront, before results are returned.
5050

51-
- LazyProtocolHandler: near drop-in replacement for the above, except that it returns an iterator over rows,
52-
lazily decoded into the default row format (this is more efficient since all decoded results are not materialized at once)
51+
- LazyProtocolHandler: near drop-in replacement for the above, except that it returns an iterator over rows,
52+
lazily decoded into the default row format (this is more efficient since all decoded results are not materialized at once)
5353

54-
- NumpyProtocolHander: deserializes results directly into NumPy arrays. This facilitates efficient integration with
55-
analysis toolkits such as Pandas.
54+
- NumpyProtocolHander: deserializes results directly into NumPy arrays. This facilitates efficient integration with
55+
analysis toolkits such as Pandas.

‎docs/cqlengine/batches.rst‎

Lines changed: 63 additions & 63 deletions
Original file line numberDiff line numberDiff line change
@@ -8,101 +8,101 @@ cqlengine supports batch queries using the BatchQuery class. Batch queries can b
88
Batch Query General Use Pattern
99
===============================
1010

11-
You can only create, update, and delete rows with a batch query, attempting to read rows out of the database with a batch query will fail.
11+
You can only create, update, and delete rows with a batch query, attempting to read rows out of the database with a batch query will fail.
1212

13-
.. code-block:: python
13+
.. code-block:: python
1414
15-
from cassandra.cqlengine.query import BatchQuery
15+
from cassandra.cqlengine.query import BatchQuery
1616
17-
#using a context manager
18-
with BatchQuery() as b:
19-
now = datetime.now()
20-
em1 = ExampleModel.batch(b).create(example_type=0, description="1", created_at=now)
21-
em2 = ExampleModel.batch(b).create(example_type=0, description="2", created_at=now)
22-
em3 = ExampleModel.batch(b).create(example_type=0, description="3", created_at=now)
23-
24-
# -- or --
25-
26-
#manually
27-
b = BatchQuery()
17+
#using a context manager
18+
with BatchQuery() as b:
2819
now = datetime.now()
2920
em1 = ExampleModel.batch(b).create(example_type=0, description="1", created_at=now)
3021
em2 = ExampleModel.batch(b).create(example_type=0, description="2", created_at=now)
3122
em3 = ExampleModel.batch(b).create(example_type=0, description="3", created_at=now)
32-
b.execute()
3323
34-
# updating in a batch
24+
# -- or --
25+
26+
#manually
27+
b = BatchQuery()
28+
now = datetime.now()
29+
em1 = ExampleModel.batch(b).create(example_type=0, description="1", created_at=now)
30+
em2 = ExampleModel.batch(b).create(example_type=0, description="2", created_at=now)
31+
em3 = ExampleModel.batch(b).create(example_type=0, description="3", created_at=now)
32+
b.execute()
33+
34+
# updating in a batch
3535
36-
b = BatchQuery()
37-
em1.description = "new description"
38-
em1.batch(b).save()
39-
em2.description = "another new description"
40-
em2.batch(b).save()
41-
b.execute()
36+
b = BatchQuery()
37+
em1.description = "new description"
38+
em1.batch(b).save()
39+
em2.description = "another new description"
40+
em2.batch(b).save()
41+
b.execute()
4242
43-
# deleting in a batch
44-
b = BatchQuery()
45-
ExampleModel.objects(id=some_id).batch(b).delete()
46-
ExampleModel.objects(id=some_id2).batch(b).delete()
47-
b.execute()
43+
# deleting in a batch
44+
b = BatchQuery()
45+
ExampleModel.objects(id=some_id).batch(b).delete()
46+
ExampleModel.objects(id=some_id2).batch(b).delete()
47+
b.execute()
4848
4949
50-
Typically you will not want the block to execute if an exception occurs inside the `with` block. However, in the case that this is desirable, it's achievable by using the following syntax:
50+
Typically you will not want the block to execute if an exception occurs inside the `with` block. However, in the case that this is desirable, it's achievable by using the following syntax:
5151

52-
.. code-block:: python
52+
.. code-block:: python
5353
54-
with BatchQuery(execute_on_exception=True) as b:
55-
LogEntry.batch(b).create(k=1, v=1)
56-
mystery_function() # exception thrown in here
57-
LogEntry.batch(b).create(k=1, v=2) # this code is never reached due to the exception, but anything leading up to here will execute in the batch.
54+
with BatchQuery(execute_on_exception=True) as b:
55+
LogEntry.batch(b).create(k=1, v=1)
56+
mystery_function() # exception thrown in here
57+
LogEntry.batch(b).create(k=1, v=2) # this code is never reached due to the exception, but anything leading up to here will execute in the batch.
5858
59-
If an exception is thrown somewhere in the block, any statements that have been added to the batch will still be executed. This is useful for some logging situations.
59+
If an exception is thrown somewhere in the block, any statements that have been added to the batch will still be executed. This is useful for some logging situations.
6060

6161
Batch Query Execution Callbacks
6262
===============================
6363

64-
In order to allow secondary tasks to be chained to the end of batch, BatchQuery instances allow callbacks to be
65-
registered with the batch, to be executed immediately after the batch executes.
64+
In order to allow secondary tasks to be chained to the end of batch, BatchQuery instances allow callbacks to be
65+
registered with the batch, to be executed immediately after the batch executes.
6666

67-
Multiple callbacks can be attached to same BatchQuery instance, they are executed in the same order that they
68-
are added to the batch.
67+
Multiple callbacks can be attached to same BatchQuery instance, they are executed in the same order that they
68+
are added to the batch.
6969

70-
The callbacks attached to a given batch instance are executed only if the batch executes. If the batch is used as a
71-
context manager and an exception is raised, the queued up callbacks will not be run.
70+
The callbacks attached to a given batch instance are executed only if the batch executes. If the batch is used as a
71+
context manager and an exception is raised, the queued up callbacks will not be run.
7272

73-
.. code-block:: python
73+
.. code-block:: python
7474
75-
def my_callback(*args, **kwargs):
76-
pass
75+
def my_callback(*args, **kwargs):
76+
pass
7777
78-
batch = BatchQuery()
78+
batch = BatchQuery()
7979
80-
batch.add_callback(my_callback)
81-
batch.add_callback(my_callback, 'positional arg', named_arg='named arg value')
80+
batch.add_callback(my_callback)
81+
batch.add_callback(my_callback, 'positional arg', named_arg='named arg value')
8282
83-
# if you need reference to the batch within the callback,
84-
# just trap it in the arguments to be passed to the callback:
85-
batch.add_callback(my_callback, cqlengine_batch=batch)
83+
# if you need reference to the batch within the callback,
84+
# just trap it in the arguments to be passed to the callback:
85+
batch.add_callback(my_callback, cqlengine_batch=batch)
8686
87-
# once the batch executes...
88-
batch.execute()
87+
# once the batch executes...
88+
batch.execute()
8989
90-
# the effect of the above scheduled callbacks will be similar to
91-
my_callback()
92-
my_callback('positional arg', named_arg='named arg value')
93-
my_callback(cqlengine_batch=batch)
90+
# the effect of the above scheduled callbacks will be similar to
91+
my_callback()
92+
my_callback('positional arg', named_arg='named arg value')
93+
my_callback(cqlengine_batch=batch)
9494
95-
Failure in any of the callbacks does not affect the batch's execution, as the callbacks are started after the execution
96-
of the batch is complete.
95+
Failure in any of the callbacks does not affect the batch's execution, as the callbacks are started after the execution
96+
of the batch is complete.
9797

9898
Logged vs Unlogged Batches
9999
---------------------------
100-
By default, queries in cqlengine are LOGGED, which carries additional overhead from UNLOGGED. To explicitly state which batch type to use, simply:
100+
By default, queries in cqlengine are LOGGED, which carries additional overhead from UNLOGGED. To explicitly state which batch type to use, simply:
101101

102102

103-
.. code-block:: python
103+
.. code-block:: python
104104
105-
from cassandra.cqlengine.query import BatchType
106-
with BatchQuery(batch_type=BatchType.Unlogged) as b:
107-
LogEntry.batch(b).create(k=1, v=1)
108-
LogEntry.batch(b).create(k=1, v=2)
105+
from cassandra.cqlengine.query import BatchType
106+
with BatchQuery(batch_type=BatchType.Unlogged) as b:
107+
LogEntry.batch(b).create(k=1, v=1)
108+
LogEntry.batch(b).create(k=1, v=2)

0 commit comments

Comments
 (0)