Skip to content

docs(SSL): restore socket-derived attributes on Connection page (#1465)#1502

Open
LeSingh1 wants to merge 1 commit into
pyca:mainfrom
LeSingh1:docs/1465-restore-connection-socket-members
Open

docs(SSL): restore socket-derived attributes on Connection page (#1465)#1502
LeSingh1 wants to merge 1 commit into
pyca:mainfrom
LeSingh1:docs/1465-restore-connection-socket-members

Conversation

@LeSingh1
Copy link
Copy Markdown

Fixes #1465.

The Connection API page lost every socket.socket-derived method (bind, listen, fileno, getsockname, getpeername, setsockopt, etc.) when the docs migrated to autoclass. Those methods are not defined on OpenSSL.SSL.Connection; they are delegated at runtime via __getattr__ to the wrapped socket, so Sphinx's autoclass introspection cannot see them.

bind() on a Connection has 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 autoclass block with one-line descriptions and :py:meth: links back to the socket.socket reference. 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 the Connection proxy.

Verification

$ sphinx-build -W -b html doc doc/_build/html
... build succeeded.

$ grep -c 'Connection.bind\|Connection.listen\|Connection.fileno' doc/_build/html/api/ssl.html
12

The rendered api/ssl.html now contains Connection.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.

…#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.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Development

Successfully merging this pull request may close these issues.

[docs regression in v18.0.0] The API document lost all socket.socket-derived attributes

1 participant