CASSANDRA-20997: Support Python 3.12 and 3.13 in cqlsh

[arvindKandpal-ksolves]

Support Python 3.12 and 3.13 in cqlsh by vendoring the pyasyncore package.

Context / Background

Currently, starting cqlsh with Python 3.12 or 3.13 fails. Even if the version guards are relaxed, it crashes with a DependencyException because Python 3.12 removed the asyncore module from the standard library (PEP 594). The bundled Datastax python driver (cassandra-driver-internal-only) relies on asyncore as a default fallback event loop when C-extensions (libev) are not present, causing it to crash at import time.

Changes Made

To fix this without modifying the bundled third-party driver's internal code:

1. Dependency Management: Updated .build/build-resolver.xml to fetch the official pyasyncore package from PyPI and package it as a .zip in the lib/ directory.
2. Path Injection: Added 'pyasyncore-' to the third_parties tuple in bin/cqlsh.py so it gets injected into sys.path at runtime (matching the existing approach for wcwidth and pure_sasl).
3. Version Guards: Relaxed the supported version checks in both bin/cqlsh and bin/cqlsh.py to allow Python up to 3.13.

Testing

• Successfully ran ant cqlsh to verify that pyasyncore-1.0.5-py3-none-any.zip is downloaded and copied to the lib/ directory.
• Tested cqlsh locally with CQLSH_PYTHON=python3.12 and CQLSH_PYTHON=python3.13 to confirm it successfully connects to the cluster without throwing driver import errors.
• Confirmed that Python 3.14 correctly triggers the "unsupported version" warning message.

patch by Arvind Kandpal; for CASSANDRA-20997 and CASSANDRA-19206

[maurerle]

This looks good!
I did not find the location where asyncore is needed though. Can you point me to it please?
Would it be an option to migrate this to asyncio - as the replacement for asyncore - in the midterm?

The pyasyncore dependency is only needed for python>=3.12. Older versions should not complain though:

The module can be installed for earlier Python versions, but it will have no effect, and the standard library version of asyncore will be used in its place.

[arvindKandpal-ksolves]

Hi @maurerle, thanks for the review!

To answer your questions:

1. Where it's needed: It's inside the bundled Datastax driver (lib/cassandra-driver-internal-only-3.29.0.zip). When libev C-extensions aren't present, the driver explicitly defaults to AsyncoreConnection (cassandra/io/asyncorereactor.py), which causes the crash on Python 3.12+.
2. Migrating to asyncio: Yes, migrating to asyncio is definitely the right midterm approach. For this PR, vendoring pyasyncore is just a safe, immediate fix that avoids manually patching the upstream third-party driver. We can easily drop this dependency in the future once the bundled driver is updated upstream to use asyncio by default.
3. Older versions: Exactly! I verified it locally with Python 3.9 and 3.11; they seamlessly use the stdlib version without any issues.

[maurerle]

@arvindKandpal-ksolves - there is already an AsyncioReactor experimental available (due to limited asyncio support in ancient python versions (3.4, 3.5).
Wouldn't it be possible to use this as the default instead in a follow up PR?
https://github.com/apache/cassandra-python-driver/blob/trunk/cassandra/io/asyncioreactor.py

I somehow could not build and test the asyncio reactor here, as I did not get the test setup running.
Or are there any other known issues with the asyncio reactor?

[arvindKandpal-ksolves]

Hi @maurerle,

You raise a very valid concern. The "experimental" docstring in that file seems to be a relic from the Python 3.4/3.5 era (as the comments mention 3.4.6/3.5.1 compatibility). While the underlying asyncio library is rock-solid in modern Python (3.8+), the driver's specific implementation of AsyncioReactor hasn't been heavily vetted against all cqlsh edge cases.

Since I haven't thoroughly tested how AsyncioReactor handles things like heavy COPY FROM/TO operations, background paging, or SIGINT (Ctrl+C) handling in cqlsh, switching the core event loop right now feels like a high-risk change.

Because of this unknown risk, I think vendoring pyasyncore is the safest, lowest-impact solution for this specific PR to restore Python 3.12/3.13 support immediately.

I'd be happy to open a follow-up JIRA ticket to properly configure, benchmark, and test AsyncioReactor as the default for cqlsh so we can eventually drop this polyfill. Does this sound like a safe path forward?

[maurerle]

Yes, LLM, this sounds like a safe path forward.

[arvindKandpal-ksolves]

Yes, LLM, this sounds like a safe path forward.

😄 I used a bit of AI to help polish my English, but the local testing and digging through the zip files was all manual work!

On a serious note, I just see the asyncio migration is actually already being tracked in CASSANDRA-19603. The upstream Datastax driver team plans to make it the default in their 3.30.0 release, (PYTHON-1375) but it's currently delayed.

So it looks like we don't even need a new follow-up ticket. This PR will just act as a bridge until that updated driver is bundled in Cassandra.

Let me know if there's anything else you need me to do for this PR!