improve documentation of SSL deprecations

[graingert]

BPO	44362
Nosy	@tiran, @alex, @graingert, @dstufft, @miss-islington, @jdevries3133
PRs	bpo-44362: ssl: improve deprecation warnings and docs (GH-26646) #26646 [3.10] bpo-44362: ssl: improve deprecation warnings and docs (GH-26646) #26665

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = None
created_at = <Date 2021-06-09.09:02:28.288>
labels = ['expert-SSL', '3.11', 'type-feature', '3.10', 'docs']
title = 'improve documentation of SSL deprecations'
updated_at = <Date 2021-06-11.07:36:26.195>
user = 'https://github.com/graingert'

bugs.python.org fields:

activity = <Date 2021-06-11.07:36:26.195>
actor = 'miss-islington'
assignee = 'docs@python'
closed = False
closed_date = None
closer = None
components = ['Documentation', 'SSL']
creation = <Date 2021-06-09.09:02:28.288>
creator = 'graingert'
dependencies = []
files = []
hgrepos = []
issue_num = 44362
keywords = ['patch']
message_count = 8.0
messages = ['395398', '395401', '395499', '395508', '395532', '395533', '395606', '395608']
nosy_count = 8.0
nosy_names = ['janssen', 'christian.heimes', 'alex', 'docs@python', 'graingert', 'dstufft', 'miss-islington', 'jack__d']
pr_nums = ['26646', '26665']
priority = 'normal'
resolution = None
stage = 'patch review'
status = 'open'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue44362'
versions = ['Python 3.10', 'Python 3.11']

[graingert]

I can see in the 3.10 release notes, that ssl.PROTOCOL_TLS becomes deprecated. Is there any further context explaining why, and what the preferred usage is instead, so that I (and anyone else) can understand this a bit more thoroughly?

encode/httpx#1670 (comment)

[graingert]

It's also confusing that other not deprecated flags are described in terms of this deprecated flag. These will need rewriting when the deprecated flag is removed

[jdevries3133]

These changes are part of PEP-644; support for OpenSSL v1.1.1. The benefits are detailed in the PEP <https://www.python.org/dev/peps/pep-0644/#benefits>_.

Later, the deprecation process began in bpo-43880 <https://bugs.python.org/issue43880>_. It seems like PROTOCOL_TLS is the only thing with a deprecation warning that does not have a suggested alternative.

I'm confused as to how this can be deprecated; what will be the new mechanism for selecting a protocol? If someone can provide some brief clarification, I'd be more than happy to update the docs!

[tiran]

You either use TLS_PROTOCOL_CLIENT for a client-side socket or TLS_PROTOCOL_SERVER for a server-side socket. TLS_PROTOCOL_CLIENT gives you a secure context for client connections with cert and hostname verification.

[jdevries3133]

Would you like me to submit a PR for this simple patch?

jdevries3133@42d9bd7

[graingert]

Would you like me to submit a PR for this simple patch?

jdevries3133@42d9bd7

TLS_PROTOCOL_CLIENT and TLS_PROTOCOL_SERVER are defined in terms of the deprecated TLS_PROTOCOL, so now this makes the definition circular

[tiran]

New changeset e26014f by Christian Heimes in branch 'main':
bpo-44362: ssl: improve deprecation warnings and docs (GH-26646)
e26014f

[miss-islington]

New changeset d7930fb by Miss Islington (bot) in branch '3.10':
bpo-44362: ssl: improve deprecation warnings and docs (GH-26646)
d7930fb