Skip to content

Commit f06267a

Browse files
aholmbergaholmberg
committed
ProtocolVersion 'enum'
1 parent 2e28fc2 commit f06267a

8 files changed

Lines changed: 81 additions & 62 deletions

File tree

‎cassandra/__init__.py‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -125,6 +125,56 @@ def consistency_value_to_name(value):
125125
return ConsistencyLevel.value_to_name[value] if value is not None else "Not Set"
126126

127127

128+
class ProtocolVersion(object):
129+
"""
130+
Defines native protocol versions supported by this driver.
131+
"""
132+
V1 = 1
133+
"""
134+
v1, supported in Cassandra 1.2-->2.2
135+
"""
136+
137+
V2 = 2
138+
"""
139+
v2, supported in Cassandra 2.0-->2.2;
140+
added support for lightweight transactions, batch operations, and automatic query paging.
141+
"""
142+
143+
V3 = 3
144+
"""
145+
v3, supported in Cassandra 2.1-->3.x+;
146+
added support for protocol-level client-side timestamps (see :attr:`.Session.use_client_timestamp`),
147+
serial consistency levels for :class:`~.BatchStatement`, and an improved connection pool.
148+
"""
149+
150+
V4 = 4
151+
"""
152+
v4, supported in Cassandra 2.2-->3.x+;
153+
added a number of new types, server warnings, new failure messages, and custom payloads. Details in the
154+
`project docs <https://github.com/apache/cassandra/blob/trunk/doc/native_protocol_v4.spec>`_
155+
"""
156+
157+
V5 = 5
158+
"""
159+
v5, in beta from 3.x+
160+
"""
161+
162+
SUPPORTED_VERSIONS = (V5, V4, V3, V2, V1)
163+
"""
164+
A tuple of all supported protocol versions
165+
"""
166+
167+
MIN_SUPPORTED = min(SUPPORTED_VERSIONS)
168+
"""
169+
Minimum protocol version supported by this driver.
170+
"""
171+
172+
MAX_SUPPORTED = max(SUPPORTED_VERSIONS)
173+
"""
174+
Maximum protocol versioni supported by this driver.
175+
"""
176+
177+
128178
class SchemaChangeType(object):
129179
DROPPED = 'DROPPED'
130180
CREATED = 'CREATED'

‎cassandra/cluster.py‎

Lines changed: 13 additions & 42 deletions
Original file line numberDiff line numberDiff line change
@@ -42,7 +42,7 @@
4242

4343
from cassandra import (ConsistencyLevel, AuthenticationFailed,
4444
OperationTimedOut, UnsupportedOperation,
45-
SchemaTargetType, DriverException)
45+
SchemaTargetType, DriverException, ProtocolVersion)
4646
from cassandra.connection import (ConnectionException, ConnectionShutdown,
4747
ConnectionHeartbeat, ProtocolVersionUnsupported)
4848
from cassandra.cqltypes import UserType
@@ -57,8 +57,7 @@
5757
IsBootstrappingErrorMessage,
5858
BatchMessage, RESULT_KIND_PREPARED,
5959
RESULT_KIND_SET_KEYSPACE, RESULT_KIND_ROWS,
60-
RESULT_KIND_SCHEMA_CHANGE, MIN_SUPPORTED_VERSION,
61-
ProtocolHandler)
60+
RESULT_KIND_SCHEMA_CHANGE, ProtocolHandler)
6261
from cassandra.metadata import Metadata, protect_name, murmur3
6362
from cassandra.policies import (TokenAwarePolicy, DCAwareRoundRobinPolicy, SimpleConvictionPolicy,
6463
ExponentialReconnectionPolicy, HostDistance,
@@ -355,45 +354,18 @@ class Cluster(object):
355354
server will be automatically used.
356355
"""
357356

358-
protocol_version = 4
357+
protocol_version = ProtocolVersion.V4
359358
"""
360359
The maximum version of the native protocol to use.
361360
361+
See :class:`.ProtocolVersion` for more information about versions.
362+
362363
If not set in the constructor, the driver will automatically downgrade
363364
version based on a negotiation with the server, but it is most efficient
364365
to set this to the maximum supported by your version of Cassandra.
365366
Setting this will also prevent conflicting versions negotiated if your
366367
cluster is upgraded.
367368
368-
Version 2 of the native protocol adds support for lightweight transactions,
369-
batch operations, and automatic query paging. The v2 protocol is
370-
supported by Cassandra 2.0+.
371-
372-
Version 3 of the native protocol adds support for protocol-level
373-
client-side timestamps (see :attr:`.Session.use_client_timestamp`),
374-
serial consistency levels for :class:`~.BatchStatement`, and an
375-
improved connection pool.
376-
377-
Version 4 of the native protocol adds a number of new types, server warnings,
378-
new failure messages, and custom payloads. Details in the
379-
`project docs <https://github.com/apache/cassandra/blob/trunk/doc/native_protocol_v4.spec>`_
380-
381-
The following table describes the native protocol versions that
382-
are supported by each version of Cassandra:
383-
384-
+-------------------+-------------------+
385-
| Cassandra Version | Protocol Versions |
386-
+===================+===================+
387-
| 1.2 | 1 |
388-
+-------------------+-------------------+
389-
| 2.0 | 1, 2 |
390-
+-------------------+-------------------+
391-
| 2.1 | 1, 2, 3 |
392-
+-------------------+-------------------+
393-
| 2.2 | 1, 2, 3, 4 |
394-
+-------------------+-------------------+
395-
| 3.x | 3, 4 |
396-
+-------------------+-------------------+
397369
"""
398370

399371
allow_beta_protocol_version = False
@@ -1141,15 +1113,14 @@ def protocol_downgrade(self, host_addr, previous_version):
11411113
if self._protocol_version_explicit:
11421114
raise DriverException("ProtocolError returned from server while using explicitly set client protocol_version %d" % (previous_version,))
11431115

1144-
new_version = previous_version - 1
1145-
if new_version < self.protocol_version:
1146-
if new_version >= MIN_SUPPORTED_VERSION:
1147-
log.warning("Downgrading core protocol version from %d to %d for %s. "
1148-
"To avoid this, it is best practice to explicitly set Cluster(protocol_version) to the version supported by your cluster. "
1149-
"http://datastax.github.io/python-driver/api/cassandra/cluster.html#cassandra.cluster.Cluster.protocol_version", self.protocol_version, new_version, host_addr)
1150-
self.protocol_version = new_version
1151-
else:
1152-
raise DriverException("Cannot downgrade protocol version (%d) below minimum supported version: %d" % (new_version, MIN_SUPPORTED_VERSION))
1116+
try:
1117+
new_version = next(v for v in sorted(ProtocolVersion.SUPPORTED_VERSIONS, reversed=True) if v < previous_version)
1118+
log.warning("Downgrading core protocol version from %d to %d for %s. "
1119+
"To avoid this, it is best practice to explicitly set Cluster(protocol_version) to the version supported by your cluster. "
1120+
"http://datastax.github.io/python-driver/api/cassandra/cluster.html#cassandra.cluster.Cluster.protocol_version", self.protocol_version, new_version, host_addr)
1121+
self.protocol_version = new_version
1122+
except StopIteration:
1123+
raise DriverException("Cannot downgrade protocol version below minimum supported version: %d" % (ProtocolVersion.MIN_SUPPORTED,))
11531124

11541125
def connect(self, keyspace=None, wait_for_all_pools=False):
11551126
"""

‎cassandra/connection.py‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -37,15 +37,15 @@
3737
else:
3838
from six.moves.queue import Queue, Empty # noqa
3939

40-
from cassandra import ConsistencyLevel, AuthenticationFailed, OperationTimedOut
40+
from cassandra import ConsistencyLevel, AuthenticationFailed, OperationTimedOut, ProtocolVersion
4141
from cassandra.marshal import int32_pack
4242
from cassandra.protocol import (ReadyMessage, AuthenticateMessage, OptionsMessage,
4343
StartupMessage, ErrorMessage, CredentialsMessage,
4444
QueryMessage, ResultMessage, ProtocolHandler,
4545
InvalidRequestException, SupportedMessage,
4646
AuthResponseMessage, AuthChallengeMessage,
4747
AuthSuccessMessage, ProtocolException,
48-
MAX_SUPPORTED_VERSION, RegisterMessage)
48+
RegisterMessage)
4949
from cassandra.util import OrderedDict
5050

5151

@@ -197,7 +197,7 @@ class Connection(object):
197197
out_buffer_size = 4096
198198

199199
cql_version = None
200-
protocol_version = MAX_SUPPORTED_VERSION
200+
protocol_version = ProtocolVersion.MAX_SUPPORTED
201201

202202
keyspace = None
203203
compression = True
@@ -252,7 +252,7 @@ class Connection(object):
252252

253253
def __init__(self, host='127.0.0.1', port=9042, authenticator=None,
254254
ssl_options=None, sockopts=None, compression=True,
255-
cql_version=None, protocol_version=MAX_SUPPORTED_VERSION, is_control_connection=False,
255+
cql_version=None, protocol_version=ProtocolVersion.MAX_SUPPORTED, is_control_connection=False,
256256
user_type_map=None, connect_timeout=None, allow_beta_protocol_version=False):
257257
self.host = host
258258
self.port = port
@@ -541,7 +541,7 @@ def _read_frame_header(self):
541541
pos = len(buf)
542542
if pos:
543543
version = int_from_buf_item(buf[0]) & PROTOCOL_VERSION_MASK
544-
if version > MAX_SUPPORTED_VERSION:
544+
if version > ProtocolVersion.MAX_SUPPORTED:
545545
raise ProtocolError("This version of the driver does not support protocol version %d" % version)
546546
frame_header = frame_header_v3 if version >= 3 else frame_header_v1_v2
547547
# this frame header struct is everything after the version byte

‎cassandra/protocol.py‎

Lines changed: 0 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -55,9 +55,6 @@ class InternalError(Exception):
5555

5656
ColumnMetadata = namedtuple("ColumnMetadata", ['keyspace_name', 'table_name', 'name', 'type'])
5757

58-
MIN_SUPPORTED_VERSION = 1
59-
MAX_SUPPORTED_VERSION = 5
60-
6158
HEADER_DIRECTION_TO_CLIENT = 0x80
6259
HEADER_DIRECTION_MASK = 0x80
6360

‎docs/api/cassandra.rst‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,9 @@
1414
.. autoclass:: ConsistencyLevel
1515
:members:
1616

17+
.. autoclass:: ProtocolVersion
18+
:members:
19+
1720
.. autoclass:: UserFunctionDescriptor
1821
:members:
1922
:inherited-members:

‎tests/integration/long/test_failure_types.py‎

Lines changed: 3 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -14,9 +14,8 @@
1414

1515
import sys,logging, traceback, time
1616

17-
from cassandra import ConsistencyLevel, OperationTimedOut, ReadTimeout, WriteTimeout, ReadFailure, WriteFailure,\
18-
FunctionFailure
19-
from cassandra.protocol import MAX_SUPPORTED_VERSION
17+
from cassandra import (ConsistencyLevel, OperationTimedOut, ReadTimeout, WriteTimeout, ReadFailure, WriteFailure,
18+
FunctionFailure, ProtocolVersion)
2019
from cassandra.cluster import Cluster, NoHostAvailable
2120
from cassandra.concurrent import execute_concurrent_with_args
2221
from cassandra.query import SimpleStatement
@@ -70,7 +69,7 @@ def setUp(self):
7069
"Native protocol 4,0+ is required for custom payloads, currently using %r"
7170
% (PROTOCOL_VERSION,))
7271
try:
73-
self.cluster = Cluster(protocol_version=MAX_SUPPORTED_VERSION, allow_beta_protocol_version=True)
72+
self.cluster = Cluster(protocol_version=ProtocolVersion.MAX_SUPPORTED, allow_beta_protocol_version=True)
7473
self.session = self.cluster.connect()
7574
except NoHostAvailable:
7675
log.info("Protocol Version 5 not supported,")

‎tests/integration/standard/test_cluster.py‎

Lines changed: 4 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -30,7 +30,6 @@
3030
from cassandra.policies import (RoundRobinPolicy, ExponentialReconnectionPolicy,
3131
RetryPolicy, SimpleConvictionPolicy, HostDistance,
3232
WhiteListRoundRobinPolicy, AddressTranslator)
33-
from cassandra.protocol import MAX_SUPPORTED_VERSION
3433
from cassandra.query import SimpleStatement, TraceUnavailable, tuple_factory
3534

3635
from tests.integration import use_singledc, PROTOCOL_VERSION, get_server_versions, CASSANDRA_VERSION, execute_until_pass, execute_with_long_wait_retry, get_node,\
@@ -188,7 +187,7 @@ def test_protocol_negotiation(self):
188187
"""
189188

190189
cluster = Cluster()
191-
self.assertLessEqual(cluster.protocol_version, MAX_SUPPORTED_VERSION)
190+
self.assertLessEqual(cluster.protocol_version, cassandra.ProtocolVersion.MAX_SUPPORTED)
192191
session = cluster.connect()
193192
updated_protocol_version = session._protocol_version
194193
updated_cluster_version = cluster.protocol_version
@@ -1107,7 +1106,7 @@ def test_invalid_protocol_version_beta_option(self):
11071106
@test_category connection
11081107
"""
11091108

1110-
cluster = Cluster(protocol_version=MAX_SUPPORTED_VERSION, allow_beta_protocol_version=False)
1109+
cluster = Cluster(protocol_version=cassandra.ProtocolVersion.MAX_SUPPORTED, allow_beta_protocol_version=False)
11111110
try:
11121111
with self.assertRaises(NoHostAvailable):
11131112
cluster.connect()
@@ -1126,9 +1125,9 @@ def test_valid_protocol_version_beta_options_connect(self):
11261125
11271126
@test_category connection
11281127
"""
1129-
cluster = Cluster(protocol_version=MAX_SUPPORTED_VERSION, allow_beta_protocol_version=True)
1128+
cluster = Cluster(protocol_version=cassandra.ProtocolVersion.MAX_SUPPORTED, allow_beta_protocol_version=True)
11301129
session = cluster.connect()
1131-
self.assertEqual(cluster.protocol_version, MAX_SUPPORTED_VERSION)
1130+
self.assertEqual(cluster.protocol_version, cassandra.ProtocolVersion.MAX_SUPPORTED)
11321131
self.assertTrue(session.execute("select release_version from system.local")[0])
11331132

11341133

‎tests/unit/test_marshalling.py‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -13,8 +13,8 @@
1313
# limitations under the License.
1414
import sys
1515

16+
from cassandra import ProtocolVersion
1617
from cassandra.marshal import bitlength
17-
from cassandra.protocol import MAX_SUPPORTED_VERSION
1818

1919
try:
2020
import unittest2 as unittest
@@ -153,10 +153,10 @@ def test_decimal(self):
153153
# Just verifying expected exception here
154154
f = converted_types[-1]
155155
self.assertIsInstance(f, float)
156-
self.assertRaises(TypeError, DecimalType.to_binary, f, MAX_SUPPORTED_VERSION)
156+
self.assertRaises(TypeError, DecimalType.to_binary, f, ProtocolVersion.MAX_SUPPORTED)
157157
converted_types = converted_types[:-1]
158158

159-
for proto_ver in range(1, MAX_SUPPORTED_VERSION + 1):
159+
for proto_ver in range(1, ProtocolVersion.MAX_SUPPORTED + 1):
160160
for n in converted_types:
161161
expected = Decimal(n)
162162
self.assertEqual(DecimalType.from_binary(DecimalType.to_binary(n, proto_ver), proto_ver), expected)

0 commit comments

Comments
 (0)