[jlaine]

The type annotations provided in types-OpenSSL are at best incomplete, and are bound to fall out of sync with PyOpenSSL. This PR brings type annotations to all public APIs in the SSL module.

It also changes references from unicode to str in the docstrings.

NOTE: I was not sure how to type the first argument of recv_into.

[alex]

If you rebase on main, CI should be green.

[mhils]

Strong +1 on inlining the annotations from types-pyopenssl, thank you for doing this @jlaine! 🍰

LGTM % @alex's comment.

[jlaine]

I have rebased on top of main, let's see if CI is happy.

I also added int annotations to our constants, like types-OpenSSL does.

Some questions:

• Do we only support passing a socket.socket to Connection, or is something that quacks like a socket OK too?
• Related to the above : Connection.connect and Connection.sock_shutdown say they return "what the socket returns". If the socket is garanteed to be a socket.socket, that would be None, and there is no need to return anything. But as we might be supporting weird socket-like things, I'd rather not touch it.
• Guidance on typing the first argument of Connection.recv_into would be welcome!
• Do we want to ship a py.typed marker so that our typings take precedence over types-OpenSSL? => YES

As a stretch goal I was wondering whether we can get a clean mypy run on SSL.py. A couple of aspects of the code make this moderately hard:

• _ffi.string returns bytes but mypy does know this. Do we want to add: _ffi_string: Callable[[Any], bytes] = _ffi.string ?
• _raise_ssl_error is sometimes used in context where we know it will raise .. and sometimes not. This results in mypy complaining there is no return statement on some codepaths.
• A number of functions are just thin wrapper around return _lib.SSL_SOMETHING(..), and mypy rightly complains.

[jlaine]

I can't remember what your preferred policy is, do you want me to squash the changes down or would you rather do it?

[reaperhulk]

We’re happy to squash ourselves.

[alex]

We're fine to squash ourselves. Thanks.

If you want a side-quest, the next milestone would be to get mypy running over our tests directory (see tox.ini) :-)