classification
Title: improve documentation of SSL deprecations
Type: enhancement Stage: patch review
Components: Documentation, SSL Versions: Python 3.11, Python 3.10
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: docs@python Nosy List: alex, christian.heimes, docs@python, dstufft, graingert, jack__d, janssen, miss-islington
Priority: normal Keywords: patch

Created on 2021-06-09 09:02 by graingert, last changed 2021-06-11 07:36 by miss-islington.

Pull Requests
URL Status Linked Edit
PR 26646 merged christian.heimes, 2021-06-10 18:32
PR 26665 merged miss-islington, 2021-06-11 07:16
Messages (8)
msg395398 - (view) Author: Thomas Grainger (graingert) * Date: 2021-06-09 09:02
> 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?

https://github.com/encode/httpx/issues/1670#issuecomment-857509311
msg395401 - (view) Author: Thomas Grainger (graingert) * Date: 2021-06-09 09:03
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
msg395499 - (view) Author: Jack DeVries (jack__d) * Date: 2021-06-10 02:01
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!
msg395508 - (view) Author: Christian Heimes (christian.heimes) * (Python committer) Date: 2021-06-10 06:36
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.
msg395532 - (view) Author: Jack DeVries (jack__d) * Date: 2021-06-10 13:13
Would you like me to submit a PR for this simple patch?

https://github.com/jdevries3133/cpython/commit/42d9bd7f97f03b49d4fc89780616704998492ac1
msg395533 - (view) Author: Thomas Grainger (graingert) * Date: 2021-06-10 13:16
> Would you like me to submit a PR for this simple patch?
> 
> https://github.com/jdevries3133/cpython/commit/42d9bd7f97f03b49d4fc89780616704998492ac1


TLS_PROTOCOL_CLIENT and TLS_PROTOCOL_SERVER are defined in terms of the deprecated TLS_PROTOCOL, so now this makes the definition circular
msg395606 - (view) Author: Christian Heimes (christian.heimes) * (Python committer) Date: 2021-06-11 07:15
New changeset e26014f1c47d26d6097ff7a0f25384bfbde714a9 by Christian Heimes in branch 'main':
bpo-44362: ssl: improve deprecation warnings and docs (GH-26646)
https://github.com/python/cpython/commit/e26014f1c47d26d6097ff7a0f25384bfbde714a9
msg395608 - (view) Author: miss-islington (miss-islington) Date: 2021-06-11 07:36
New changeset d7930fb720b5e9db2076b116dffcd52b6ca71438 by Miss Islington (bot) in branch '3.10':
bpo-44362: ssl: improve deprecation warnings and docs (GH-26646)
https://github.com/python/cpython/commit/d7930fb720b5e9db2076b116dffcd52b6ca71438
History
Date User Action Args
2021-06-11 07:36:26miss-islingtonsetmessages: + msg395608
2021-06-11 07:16:03miss-islingtonsetnosy: + miss-islington
pull_requests: + pull_request25252
2021-06-11 07:15:58christian.heimessetmessages: + msg395606
2021-06-10 18:32:52christian.heimessetkeywords: + patch
nosy: + christian.heimes

pull_requests: + pull_request25232
stage: patch review
2021-06-10 13:18:02christian.heimessetnosy: - christian.heimes
2021-06-10 13:16:41graingertsetmessages: + msg395533
2021-06-10 13:13:21jack__dsetmessages: + msg395532
2021-06-10 06:36:59christian.heimessetmessages: + msg395508
2021-06-10 02:01:26jack__dsetnosy: + jack__d
messages: + msg395499
2021-06-09 09:10:03christian.heimessetassignee: docs@python

type: enhancement
components: + Documentation, SSL
nosy: + docs@python
2021-06-09 09:03:58graingertsetmessages: + msg395401
2021-06-09 09:02:28graingertcreate