Reorganize TLS options: implement PREFERRED/REQUIRED SSL mode behavior

[Copilot]

PyMySQL had no way to emulate MySQL's ssl_mode=REQUIRED, and ssl_disabled was effectively a no-op. This reorganizes TLS behavior around a clear priority order without adding new options.

Behavior

Evaluated in order:

1. ssl_disabled=True → prohibit SSL
2. Any explicit SSL option set (ssl, ssl_ca, ssl_cert, ssl_key, ssl_key_password, ssl_verify_cert, ssl_verify_identity) → REQUIRED: raises OperationalError(CR_SSL_CONNECTION_ERROR) if the server doesn't advertise CLIENT.SSL
3. No SSL options → PREFERRED: attempt SSL if the server supports it, fall back to plain connection otherwise

# Now raises OperationalError if server doesn't support SSL
conn = pymysql.connect(host=..., ssl_ca="/path/to/ca.pem")

# Silently falls back to plaintext if server has no SSL — no config needed
conn = pymysql.connect(host=...)

# Explicitly opt out
conn = pymysql.connect(host=..., ssl_disabled=True)

Changes

• connections.py

  • Added self._ssl_required to distinguish REQUIRED vs PREFERRED at connect time
  • PREFERRED mode: creates a default no-verify SSLContext via _create_ssl_ctx({}) when no SSL options are given and the ssl module is available
  • _request_authentication: refactored into a client_flags/_do_ssl pattern — CLIENT.SSL is added to the handshake flags only when the SSL upgrade actually happens (needed for PREFERRED, already set for REQUIRED); raises on REQUIRED + no server SSL; falls back silently for PREFERRED

• tests/test_connection.py: new tests covering PREFERRED setup, REQUIRED error path (with CA context assertion), and PREFERRED fallback

• CHANGELOG.md: documents the behavior change