docs(SSL): restore socket-derived attributes on Connection page (#1465)#1502
Open
LeSingh1 wants to merge 1 commit into
Open
docs(SSL): restore socket-derived attributes on Connection page (#1465)#1502LeSingh1 wants to merge 1 commit into
LeSingh1 wants to merge 1 commit into
Conversation
…#1465) The Connection API page lost every `socket.socket`-derived method (`bind`, `listen`, `fileno`, `getsockname`, `getpeername`, `setsockopt`, etc.) when the doc migrated to `autoclass`. Those methods are not defined on `OpenSSL.SSL.Connection`; they are delegated at runtime through `__getattr__` to the wrapped socket, so Sphinx's autoclass introspection cannot see them. `bind()` in particular has been in use on `Connection` since Cheroot 2006 and was documented through v17.5.0, but https://www.pyopenssl.org/en/26.2.0/api/ssl.html now lists none of them — exactly the gap @webknjaz tracked to commit 737e89a. Add an explicit listing of the most-used forwarded methods under the `autoclass` block, with one-line descriptions and `:py:meth:` links back to the `socket.socket` reference docs. Also note that any other socket attribute is reachable the same way, and that new server-side code should generally bind the underlying socket directly rather than go through the Connection proxy (per the issue's second action item). Docs build with `-W` (warnings-as-errors) is clean; the rendered `api/ssl.html` now contains `Connection.bind`, `Connection.listen`, `Connection.fileno`, and the other forwarded entries. No code change; behavior is unaffected.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Fixes #1465.
The
ConnectionAPI page lost everysocket.socket-derived method (bind,listen,fileno,getsockname,getpeername,setsockopt, etc.) when the docs migrated toautoclass. Those methods are not defined onOpenSSL.SSL.Connection; they are delegated at runtime via__getattr__to the wrapped socket, so Sphinx's autoclass introspection cannot see them.bind()on aConnectionhas been in use since Cheroot 2006 and was documented through v17.5.0, but the current API page lists none of them — exactly the regression @webknjaz tracked to #737 in the issue.Fix
Add an explicit listing of the most-frequently-used forwarded methods under the
autoclassblock with one-line descriptions and:py:meth:links back to thesocket.socketreference. Closes the doc gap without touching runtime behavior. The trailing paragraph also notes the issue's second action item — new server-side code should generally bind the underlying socket directly rather than go through theConnectionproxy.Verification
The rendered
api/ssl.htmlnow containsConnection.bind,Connection.listen,Connection.fileno,Connection.getsockname,Connection.getpeername,Connection.setsockopt,Connection.getsockopt, and the timeout/blocking accessors.No code change; behavior is unaffected. Docs-only.