Prune redundant :rtype: from SSL module (#1315)

The `SSL` module now has full type annotations, which are correctly
extracted to the docs, so using `:rtype:` in the docstring is redundant.

We also update the contributor guidelines to require type hints in new
code.

Author: jlaine

CONTRIBUTING.rst

@@ -39,20 +39,19 @@ Documentation
 
 When introducing new functionality, please remember to write documentation.
 
-- New functions and methods should have a docstring describing what they do, what parameters they takes, what types those parameters are, and what they return.
+- New functions and methods should have a docstring describing what they do, what parameters they takes, and what they return. They should also come with `type hints`_.
 
   .. code-block:: python
 
-     def dump_publickey(type, pkey):
+     def dump_publickey(type: int, pkey: PKey) -> bytes:
          """
          Dump a public key to a buffer.
 
          :param type: The file type (one of :data:`FILETYPE_PEM` or
              :data:`FILETYPE_ASN1`).
-         :param PKey pkey: The PKey to dump.
+         :param pkey: The PKey to dump.
 
          :return: The buffer with the dumped key in it.
-         :rtype: bytes
          """
 
 
@@ -110,6 +109,7 @@ Feel free to cross-check this information with Keybase_.
 .. _Keybase: https://keybase.io/hynek
 .. _pyca/pyopenssl: https://github.com/pyca/pyopenssl
 .. _PEP 8: https://www.python.org/dev/peps/pep-0008/
+.. _`type hints`: https://docs.python.org/3/library/typing.html
 .. _cryptography code review process: https://cryptography.io/en/latest/development/reviewing-patches/
 .. _freenode: https://freenode.net
 .. _mailing list: https://mail.python.org/mailman/listinfo/cryptography-dev

src/OpenSSL/SSL.py

@@ -2221,7 +2221,6 @@ def renegotiate(self) -> bool:
         Renegotiate the session.
 
         :return: True if the renegotiation can be started, False otherwise
-        :rtype: bool
         """
         if not self.renegotiate_pending():
             _openssl_assert(_lib.SSL_renegotiate(self._ssl) == 1)
@@ -2245,7 +2244,6 @@ def renegotiate_pending(self) -> bool:
         a renegotiation is finished.
 
         :return: Whether there's a renegotiation in progress
-        :rtype: bool
         """
         return _lib.SSL_renegotiate_pending(self._ssl) == 1
 
@@ -2254,7 +2252,6 @@ def total_renegotiations(self) -> int:
         Find out the total number of renegotiations.
 
         :return: The number of renegotiations.
-        :rtype: int
         """
         return _lib.SSL_total_renegotiations(self._ssl)
 
@@ -2483,7 +2480,6 @@ def get_state_string(self) -> bytes:
         Retrieve a verbose string detailing the state of the Connection.
 
         :return: A string representing the state
-        :rtype: bytes
         """
         return _ffi.string(_lib.SSL_state_string_long(self._ssl))
 
@@ -2724,7 +2720,6 @@ def _get_finished_message(self, function) -> Optional[bytes]:
 
         :return: :data:`None` if the desired message has not yet been
             received, otherwise the contents of the message.
-        :rtype: :class:`bytes` or :class:`NoneType`
         """
         # The OpenSSL documentation says nothing about what might happen if the
         # count argument given is zero.  Specifically, it doesn't say whether
@@ -2754,7 +2749,6 @@ def get_finished(self) -> Optional[bytes]:
 
         :return: The contents of the message or :obj:`None` if the TLS
             handshake has not yet completed.
-        :rtype: :class:`bytes` or :class:`NoneType`
 
         .. versionadded:: 0.15
         """
@@ -2766,7 +2760,6 @@ def get_peer_finished(self) -> Optional[bytes]:
 
         :return: The contents of the message or :obj:`None` if the TLS
             handshake has not yet completed.
-        :rtype: :class:`bytes` or :class:`NoneType`
 
         .. versionadded:: 0.15
         """
@@ -2778,7 +2771,6 @@ def get_cipher_name(self) -> Optional[str]:
 
         :returns: The name of the currently used cipher or :obj:`None`
             if no connection has been established.
-        :rtype: :class:`str` or :class:`NoneType`
 
         .. versionadded:: 0.15
         """
@@ -2795,7 +2787,6 @@ def get_cipher_bits(self) -> Optional[int]:
 
         :returns: The number of secret bits of the currently used cipher
             or :obj:`None` if no connection has been established.
-        :rtype: :class:`int` or :class:`NoneType`
 
         .. versionadded:: 0.15
         """
@@ -2811,7 +2802,6 @@ def get_cipher_version(self) -> Optional[str]:
 
         :returns: The protocol name of the currently used cipher
             or :obj:`None` if no connection has been established.
-        :rtype: :class:`str` or :class:`NoneType`
 
         .. versionadded:: 0.15
         """
@@ -2829,7 +2819,6 @@ def get_protocol_version_name(self) -> str:
         :returns: The TLS version of the current connection, for example
             the value for TLS 1.2 would be ``TLSv1.2``or ``Unknown``
             for connections that were not successfully established.
-        :rtype: :class:`str`
         """
         version = _ffi.string(_lib.SSL_get_version(self._ssl))
         return version.decode("utf-8")
@@ -2840,7 +2829,6 @@ def get_protocol_version(self) -> int:
 
         :returns: The TLS version of the current connection.  For example,
             it will return ``0x769`` for connections made over TLS version 1.
-        :rtype: :class:`int`
         """
         version = _lib.SSL_version(self._ssl)
         return version