Type ssl_context for stdlib and pyOpenSSL reactors

[dkropachev]

Summary

Expose a useful public type for Cluster.ssl_context and related connection APIs. The accepted context depends on the selected reactor:

• Asyncore, asyncio, gevent, and libev use ssl.SSLContext.
• Twisted and Eventlet use OpenSSL.SSL.Context.

Today ssl_context is unannotated and its documentation describes only ssl.SSLContext, so editors and type checkers cannot guide users migrating away from ssl_options.

Proposed approach

• Define a public TLS-context type alias representing ssl.SSLContext | OpenSSL.SSL.Context.
• Import the pyOpenSSL type only under typing.TYPE_CHECKING or expose it through a stub so pyOpenSSL remains optional at runtime.
• Annotate the Cluster constructor, Cluster.ssl_context, Connection, and relevant reactor helpers.
• Document that the context type must match connection_class; a simple union can describe accepted values even if the dependency between both arguments cannot be expressed precisely.
• Add a PEP 561 py.typed marker or public stubs. Without one, annotations in the installed package are not reliably exposed to downstream type checkers.

Example API

TLSContext = Union[ssl.SSLContext, "OpenSSL.SSL.Context"]

class Cluster:
    def __init__(
        self,
        ...,
        ssl_context: Optional[TLSContext] = None,
        ...,
    ) -> None: ...

The concrete implementation should remain compatible with the minimum supported Python version and must not make pyOpenSSL a required dependency.

Acceptance criteria

• Installed-package users receive ssl_context completion and type checking.
• A stdlib ssl.SSLContext is accepted for stdlib-backed reactors.
• OpenSSL.SSL.Context is accepted for Twisted and Eventlet.
• Importing the driver without pyOpenSSL still succeeds.
• Documentation and type-checking tests cover both context families and explain the reactor constraint.

Related

Follow-up to #940 and #957.