Deprecate ssl_options in favor of ssl_context

[dkropachev]

Decision

Keep the deprecated ssl_options parameter and public attribute available as migration aids, but do not use them to configure TLS. Any non-None value, including an empty dictionary, must raise a clear ValueError explaining how to migrate to ssl_context.

This intentionally replaces the earlier warning-only proposal. The option remains discoverable so existing applications fail with actionable guidance instead of an unknown-keyword error.

Required behavior

• Cluster(ssl_options=...) raises immediately.
• Assigning cluster.ssl_options = ... raises immediately.
• The error maps legacy settings to ssl.SSLContext APIs.
• Internal cloud/SNI routing metadata remains private and is not exposed through Cluster.ssl_options.
• ssl_options=None remains accepted.

Migration

import ssl
from cassandra.cluster import Cluster

context = ssl.create_default_context(cafile="/path/to/ca.pem")
context.load_cert_chain("/path/to/client.crt", "/path/to/client.key")
context.check_hostname = True

cluster = Cluster(ssl_context=context)

Legacy mappings:

• ca_certs -> SSLContext.load_verify_locations()
• certfile / keyfile -> SSLContext.load_cert_chain()
• cert_reqs -> SSLContext.verify_mode
• check_hostname -> SSLContext.check_hostname
• ciphers -> SSLContext.set_ciphers()

Related

Replacement for #938. Implemented by #957.

[dkropachev]

Decision for the replacement of #938: do not continue expanding the legacy ssl_options compatibility layer across reactors. Reject caller-supplied ssl_options with a clear migration error directing users to configure and pass ssl_context instead. This intentionally replaces the warning-only compatibility approach described above.