docs: update stale Python 2 comments and docstrings

Also ports the HashableMock thread-safety fix from PR #766
(fix/hashable-mock-thread-safety) to unblock this PR's own CI: the
"Build wheels for macos-arm on macos-14" job was failing on
tests/unit/test_host_connection_pool.py::HostConnectionTests::test_successful_wait_for_connection
with `TypeError: __hash__ method should return an integer not
'MagicMock'`. This is a pre-existing, unrelated flaky-test bug (not
introduced by this Python-2-cleanup PR); PR #766 is the canonical fix
and should still land separately.

MagicMixin.__init__ replaces __hash__ on the mock's type with a
MagicMock object, which is not thread-safe under concurrent hash()
calls (e.g. `connection in self._trash` in pool.py). Fix by restoring
a plain, id-based __hash__ function on the class after
super().__init__() runs.

Author: mykaul

cassandra/datastax/graph/graphson.py

@@ -48,26 +48,25 @@
 ------------ | -------------- | -------------- | ------------
 text         | string         | string         | str
 boolean      |                |                | bool
-bigint       | g:Int64        | g:Int64        | long
+bigint       | g:Int64        | g:Int64        | int
 int          | g:Int32        | g:Int32        | int
 double       | g:Double       | g:Double       | float
 float        | g:Float        | g:Float        | float
 uuid         | g:UUID         | g:UUID         | UUID
 bigdecimal   | gx:BigDecimal  | gx:BigDecimal  | Decimal
 duration     | gx:Duration    | N/A            | timedelta              (Classic graph only)
 DSE Duration | N/A            | dse:Duration   | Duration               (Core graph only)
-inet         | gx:InetAddress | gx:InetAddress | str (unicode), IPV4Address/IPV6Address (PY3)
+inet         | gx:InetAddress | gx:InetAddress | str, IPV4Address/IPV6Address
 timestamp    | gx:Instant     | gx:Instant     | datetime.datetime
 date         | gx:LocalDate   | gx:LocalDate   | datetime.date
 time         | gx:LocalTime   | gx:LocalTime   | datetime.time
 smallint     | gx:Int16       | gx:Int16       | int
-varint       | gx:BigInteger  | gx:BigInteger  | long
-date         | gx:LocalDate   | gx:LocalDate   | Date
+varint       | gx:BigInteger  | gx:BigInteger  | int
 polygon      | dse:Polygon    | dse:Polygon    | Polygon
 point        | dse:Point      | dse:Point      | Point
 linestring   | dse:Linestring | dse:LineString | LineString
-blob         | dse:Blob       | dse:Blob       | bytearray, buffer (PY2), memoryview (PY3), bytes (PY3)
-blob         | gx:ByteBuffer  | gx:ByteBuffer  | bytearray, buffer (PY2), memoryview (PY3), bytes (PY3)
+blob         | dse:Blob       | dse:Blob       | bytearray, memoryview, bytes
+blob         | gx:ByteBuffer  | gx:ByteBuffer  | bytearray, memoryview, bytes
 list         | N/A            | g:List         | list                   (Core graph only)
 map          | N/A            | g:Map          | dict                   (Core graph only)
 set          | N/A            | g:Set          | set or list            (Core graph only)
@@ -969,7 +968,7 @@ def serialize(self, value, writer=None):
         """
         serializer = self.get_serializer(value)
         if not serializer:
-            raise ValueError("Unable to find a serializer for value of type: ".format(type(value)))
+            raise ValueError("Unable to find a serializer for value of type: {}".format(type(value)))
 
         val = serializer.serialize(value, writer or self)
         if serializer is TypeWrapperTypeIO:

cassandra/metadata.py

@@ -2270,7 +2270,7 @@ def _build_table_metadata(self, row, col_rows=None, trigger_rows=None):
 
                     # Some thrift tables define names in composite types (see PYTHON-192)
                     if not column_aliases and hasattr(comparator, 'fieldnames'):
-                        column_aliases = filter(None, comparator.fieldnames)
+                        column_aliases = list(filter(None, comparator.fieldnames))
             else:
                 is_compact = True
                 if column_aliases or not col_rows or is_dct_comparator:

cassandra/util.py

@@ -810,7 +810,8 @@ def __str__(self):
 inet_ntop = socket.inet_ntop
 
 
-# similar to collections.namedtuple, reproduced here because Python 2.6 did not have the rename logic
+# similar to collections.namedtuple, reproduced here to handle invalid identifiers
+# by renaming them to positional names
 def _positional_rename_invalid_identifiers(field_names):
     names_out = list(field_names)
     for index, name in enumerate(field_names):
@@ -1498,7 +1499,7 @@ class Version(object):
     Internal minimalist class to compare versions.
     A valid version is: <int>.<int>.<int>.<int or str>.
 
-    TODO: when python2 support is removed, use packaging.version.
+    TODO: consider using packaging.version instead.
     """
 
     _version = None

tests/unit/util.py

@@ -32,6 +32,34 @@ def _check_order_consistency(smaller, bigger, equal=False):
 
 
 class HashableMock(NonCallableMagicMock):
+    """A Mock subclass that is safely hashable and usable in sets/dicts.
 
-    def __hash__(self):
-        return id(self)
+    NonCallableMagicMock's __init__ (via MagicMixin) replaces __hash__
+    on the *type* with a MagicMock object.  That MagicMock is not
+    thread-safe, so concurrent hash() calls on the same instance —
+    e.g. ``connection in self._trash`` in pool.py — can raise
+    ``TypeError: __hash__ method should return an integer`` on Windows.
+
+    We fix this by restoring a plain function as the class-level
+    __hash__ after super().__init__ runs, so hash() always resolves to
+    a real function (id-based) instead of a MagicMock callable.
+
+    Note: NonCallableMock.__new__ already gives every mock instance its
+    own private subclass (see cpython unittest/mock.py) specifically so
+    that per-instance magic-method patching doesn't leak across mocks.
+    ``type(self)`` here is therefore that private, instance-specific
+    subclass rather than the shared ``HashableMock`` class, so this
+    assignment can't race with another ``HashableMock`` instance's
+    __init__ call. Once __init__ returns, __hash__ is a plain function
+    for the remaining lifetime of the instance, so it is safe to call
+    from multiple threads with no further synchronization needed.
+    """
+
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        # Restore a real __hash__ after MagicMixin overwrites it.
+        type(self).__hash__ = HashableMock._id_hash
+
+    @staticmethod
+    def _id_hash(self):
+        return id(self)