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 (cherrypy/cherrypy@b0dd93d#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:
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__():
|
def __getattr__(self, name): |
. That that's what prevent's Sphinx from traversing the dynamically looked up methods that are present conditionally.
Action items
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 (cherrypy/cherrypy@b0dd93d#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: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 withOpenSSL.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__():pyopenssl/src/OpenSSL/SSL.py
Line 1572 in 68acb78
Action items
socket.socket-inherited method list in the API docbind()— I think it should encourage people tobind()the underlying socket instead of the connection object