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

Context

We're refactoring a two decade-old codebase (Cheroot of CherryPy) with a bunch of bizzare structural flaws. So I started looking into the docs and found out that there's no OpenSSL.SSL.Connection.bind() method in there, that's been in use since 2006 (https://github.com/cherrypy/cherrypy/commit/b0dd93d83a56f6913784e3b69b0c49691259913f#diff-4da30a13bec1efb85a2b8a6dae158ee03967fbb2bb5b829b267b4e3e2edaae1bR571-R572).

pyOpenSSL's docs don't have any examples of using it for server-side sockets so I scanned the web for some — all of them call bind() on the connection object, not the underlying raw socket:

• https://web.archive.org/web/20231129211622/http://code.activestate.com/recipes/442473/
• https://github.com/msabramo/pyOpenSSL/blob/master/examples/simple/server.py
• https://grep.app/search?f.lang=Python&regexp=true&q=.*\n.*SSL\.Connection.*\n.*bind

I tracked its disappearance from the docs to v18.0.0 but the change log does not deprecate it at any point: https://www.pyopenssl.org/en/18.0.0/changelog.html. The previous release documents the bind() method @ https://www.pyopenssl.org/en/17.5.0/api/ssl.html#OpenSSL.SSL.Connection.bind.

Looking deeper, I've found that migrating to .. autoclass:: was what broke the doc: https://github.com/pyca/pyopenssl/pull/737/files#diff-5a8fffa321fa2f49bfc55606c2eae6bf1fd132f970644b616c3978dcc123d812L532-R240. In fact, this ain't the first time I'm noticing the problem with OpenSSL.SSL.Connection: #1012.

The reason why this broke is revealed by looking into the source code and discovering that no explicit OpenSSL.SSL.Connection.bind() is defined. Instead, it's a same-called method of the underlying socket — OpenSSL.SSL.Connection._socket.bind() exposed via __getattr__(): https://github.com/pyca/pyopenssl/blob/68acb78d1594bd3b8aac152de0fef95c4dd80d03/src/OpenSSL/SSL.py#L1572. That that's what prevent's Sphinx from traversing the dynamically looked up methods that are present conditionally.

Action items

• resurrect the socket.socket-inherited method list in the API doc
• think of showcasing an authoritative example of using bind() — I think it should encourage people to bind() the underlying socket instead of the connection object

Start with src/OpenSSL/SSL.py, especially OpenSSL.SSL.Connection.getattr, and the API documentation entry that migrated to .. autoclass::. Restore the socket.socket-derived methods in the generated API documentation and determine whether to add an authoritative bind() example; verify the rendered docs include bind() and clarify which socket should be bound.