Merge pull request #391 from tomato42/docs

Update docs

Author: tomato42

docs/conf.py

@@ -31,6 +31,7 @@
 # ones.
 extensions = [
     'sphinx.ext.autodoc',
+    'sphinx.ext.intersphinx',
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -121,7 +122,7 @@
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = 'alabaster'
+html_theme = 'sphinx_rtd_theme'
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
@@ -338,3 +339,4 @@
 # If true, do not generate a @detailmenu in the "Top" node's menu.
 #
 # texinfo_no_detailmenu = False
+intersphinx_mapping = {'https://docs.python.org/': None}

docs/index.rst

@@ -11,6 +11,8 @@ Contents:
 .. toctree::
    :maxdepth: 2
 
+   modules
+
 Indices and tables
 ==================
 

tlslite/__init__.py

@@ -13,15 +13,13 @@
 To use, do::
 
     from tlslite import TLSConnection, ...
-    
+
 If you want to import the most useful objects, the cleanest way is::
 
     from tlslite.api import *
 
 Then use the L{tlslite.TLSConnection.TLSConnection} class with a socket.
 (Or, use one of the integration classes in L{tlslite.integration}).
-
-@version: 0.8.0-alpha36
 """
 
 from tlslite.api import *

tlslite/extensions.py

@@ -51,8 +51,8 @@ class TLSExtension(object):
     :ivar extType: a 2^16-1 limited integer specifying the type of the
         extension that it contains, e.g. 0 indicates server name extension
 
-    :vartype extData: bytearray
-    :ivar extData: a byte array containing the value of the extension as
+    :vartype ~.extData: bytearray
+    :ivar ~.extData: a byte array containing the value of the extension as
         to be written on the wire
 
     :vartype serverType: boolean
@@ -383,7 +383,7 @@ def parse(self, parser):
         """Deserialise extension from on-the-wire data.
 
         :param tlslite.utils.codec.Parser parser: data
-        :rtype TLSExtension
+        :rtype: TLSExtension
         """
         if not parser.getRemainingLength():
             self._internal_value = None
@@ -669,8 +669,8 @@ class SNIExtension(TLSExtension):
     :vartype extType: int
     :ivar extType: numeric type of SNIExtension, i.e. 0
 
-    :vartype extData: bytearray
-    :ivar extData: raw representation of the extension
+    :vartype ~.extData: bytearray
+    :ivar ~.extData: raw representation of the extension
     """
 
     ServerName = namedtuple('ServerName', 'name_type name')
@@ -853,8 +853,8 @@ class SupportedVersionsExtension(VarSeqListExtension):
     :vartype extType: int
     :ivar extType: numeric type of the Supported Versions extension, i.e. 43
 
-    :vartype extData: bytearray
-    :ivar extData: raw representation of the extension data
+    :vartype ~.extData: bytearray
+    :ivar ~.extData: raw representation of the extension data
 
     :vartype versions: list of tuples
     :ivar versions: list of supported protocol versions; each tuple has two
@@ -878,11 +878,11 @@ class SrvSupportedVersionsExtension(TLSExtension):
     :vartype extType: int
     :ivar extType: numeric type of the Supported Versions extension, i.e. 43
 
-    :vartype extData: bytearray
-    :ivar extData: raw representation of the extension payload
+    :vartype ~.extData: bytearray
+    :ivar ~.extData: raw representation of the extension payload
 
-    :vartype version: tuple
-    :ivar version: version selected by the server
+    :vartype ~.version: tuple
+    :ivar ~.version: version selected by the server
     """
 
     def __init__(self):
@@ -950,8 +950,8 @@ class ClientCertTypeExtension(VarListExtension):
     :vartype extType: int
     :ivar extType: numeric type of Certificate Type extension, i.e. 9
 
-    :vartype extData: bytearray
-    :ivar extData: raw representation of the extension data
+    :vartype ~.extData: bytearray
+    :ivar ~.extData: raw representation of the extension data
 
     :vartype certTypes: list of int
     :ivar certTypes: list of certificate type identifiers (each one byte long)
@@ -977,8 +977,8 @@ class ServerCertTypeExtension(IntExtension):
     :vartype extType: int
     :ivar extType: binary type of Certificate Type extension, i.e. 9
 
-    :vartype extData: bytearray
-    :ivar extData: raw representation of the extension data
+    :vartype ~.extData: bytearray
+    :ivar ~.extData: raw representation of the extension data
 
     :vartype cert_type: int
     :ivar cert_type: the certificate type selected by server
@@ -1014,8 +1014,8 @@ class SRPExtension(TLSExtension):
     :vartype extType: int
     :ivar extType: numeric type of SRPExtension, i.e. 12
 
-    :vartype extData: bytearray
-    :ivar extData: raw representation of extension data
+    :vartype ~.extData: bytearray
+    :ivar ~.extData: raw representation of extension data
 
     :vartype identity: bytearray
     :ivar identity: UTF-8 encoding of user name
@@ -1101,8 +1101,8 @@ class NPNExtension(TLSExtension):
     :vartype extType: int
     :ivar extType: numeric type of NPNExtension, i.e. 13172
 
-    :vartype extData: bytearray
-    :ivar extData: raw representation of extension data
+    :vartype ~.extData: bytearray
+    :ivar ~.extData: raw representation of extension data
     """
 
     def __init__(self):
@@ -1527,8 +1527,8 @@ class ALPNExtension(TLSExtension):
     :vartype extType: int
     :ivar extType: numberic type of ALPNExtension, i.e. 16
 
-    :vartype extData: bytearray
-    :ivar extData: raw encoding of the extension data
+    :vartype ~.extData: bytearray
+    :var ~.extData: raw encoding of the extension data
     """
 
     def __init__(self):
@@ -1796,8 +1796,8 @@ class HeartbeatExtension(IntExtension):
     """
     Heartbeat extension from RFC 6520
 
-    @type mode: int
-    @ivar mode: mode if peer is allowed or nor allowed to send responses
+    :type mode: int
+    :ivar mode: mode if peer is allowed or nor allowed to send responses
     """
     def __init__(self):
         super(HeartbeatExtension, self).__init__(

tlslite/handshakesettings.py

@@ -65,7 +65,7 @@ class Keypair(object):
     :vartype key: RSAKey or ECDSAKey
     :ivar key: private key
 
-    :vartype certificates: list of X509
+    :vartype certificates: list(X509)
     :ivar certificates: the certificates to send to peer if the key is selected
         for use. The first one MUST include the public key of the ``key``
     """
@@ -89,22 +89,22 @@ class VirtualHost(object):
     TODO: support SRP as alternative to certificates
     TODO: support PSK as alternative to certificates
 
-    :vartype keys: list of :ref:`~Keypair`
+    :vartype keys: list(Keypair)
     :ivar keys: List of certificates and keys to be used in this
         virtual host. First keypair able to server ClientHello will be used.
 
-    :vartype hostnames: set of bytes
+    :vartype hostnames: set(bytes)
     :ivar hostnames: all the hostnames that server supports
-        please use :ref:`matches_hostname` to verify if the VirtualHost
+        please use :py:meth:`matches_hostname` to verify if the VirtualHost
         can serve a request to a given hostname as that allows wildcard hosts
         that always reply True.
 
-    :vartype trust_anchors: list of X509
+    :vartype trust_anchors: list(X509)
     :ivar trust_anchors: list of CA certificates supported for client
         certificate authentication, sent in CertificateRequest
 
-    :ivar app_protocols: all the application protocols that the server supports
-        (for ALPN)
+    :ivar list(bytes) app_protocols: all the application protocols that the
+        server supports (for ALPN)
     """
 
     def __init__(self):
@@ -146,7 +146,7 @@ class HandshakeSettings(object):
         parameters larger than this length, an alert will be signalled.
         The default is 8193.
 
-    :vartype cipherNames: list
+    :vartype cipherNames: list(str)
     :ivar cipherNames: The allowed ciphers.
 
         The allowed values in this list are 'chacha20-poly1305', 'aes256gcm',
@@ -160,22 +160,18 @@ class HandshakeSettings(object):
         choose whichever ciphersuite matches the earliest entry in this
         list.
 
-        .. note:: If '3des' is used in this list, but TLS Lite can't find an
-            add-on library that supports 3DES, then '3des' will be silently
-            removed.
-
         The default value is list that excludes 'rc4', 'null' and
         'chacha20-poly1305_draft00'.
 
-    :vartype macNames: list
+    :vartype macNames: list(str)
     :ivar macNames: The allowed MAC algorithms.
 
         The allowed values in this list are 'sha384', 'sha256', 'aead', 'sha'
         and 'md5'.
 
         The default value is list that excludes 'md5'.
 
-    :vartype certificateTypes: list
+    :vartype certificateTypes: list(str)
     :ivar certificateTypes: The allowed certificate types.
 
         The only allowed certificate type is 'x509'.  This list is only used
@@ -219,7 +215,7 @@ class HandshakeSettings(object):
     :vartype sendFallbackSCSV: bool
     :ivar sendFallbackSCSV: Whether to, as a client, send FALLBACK_SCSV.
 
-    :vartype rsaSigHashes: list
+    :vartype rsaSigHashes: list(str)
     :ivar rsaSigHashes: List of hashes supported (and advertised as such) for
         TLS 1.2 signatures over Server Key Exchange or Certificate Verify with
         RSA signature algorithm.
@@ -229,7 +225,7 @@ class HandshakeSettings(object):
         The allowed hashes are: "md5", "sha1", "sha224", "sha256",
         "sha384" and "sha512". The default list does not include md5.
 
-    :vartype ecdsaSigHashes: list
+    :vartype ecdsaSigHashes: list(str)
     :ivar ecdsaSigHashes: List of hashes supported (and advertised as such) for
         TLS 1.2 signatures over Server Key Exchange or Certificate Verify with
         ECDSA signature algorithm.
@@ -239,7 +235,7 @@ class HandshakeSettings(object):
         The allowed hashes are: "sha1", "sha224", "sha256",
         "sha384" and "sha512".
 
-    :vartype eccCurves: list
+    :vartype eccCurves: list(str)
     :ivar eccCurves: List of named curves that are to be supported
 
     :vartype useEncryptThenMAC: bool
@@ -261,21 +257,22 @@ class HandshakeSettings(object):
         first curve for eccCurves and may be distinct from curves from that
         list.
 
-    :vartype keyShares: list
+    :vartype keyShares: list(str)
     :ivar keyShares: list of TLS 1.3 key shares to include in Client Hello
 
     :vartype padding_cb: func
     :ivar padding_cb: Callback to function computing number of padding bytes
         for TLS 1.3. Signature is cb_func(msg_size, content_type, max_size).
 
-    :vartype pskConfigs: list of tuples
+    :vartype pskConfigs: list(tuple(bytearray, bytearray, bytearray))
     :ivar pskConfigs: list of tuples, first element of the tuple is the
         human readable, UTF-8 encoded, "identity" of the associated secret
         (bytearray, can be empty for TLS 1.2 and earlier), second element is
         the binary secret (bytearray), third is an optional parameter
-        specifying the PRF hash to be used in TLS 1.3 ('sha256' or 'sha384')
+        specifying the PRF hash to be used in TLS 1.3 (``sha256`` or
+        ``sha384``)
 
-    :vartype ticketKeys: list of bytearray
+    :vartype ticketKeys: list(bytearray)
     :ivar ticketKeys: keys to be used for encrypting and decrypting session
         tickets. First entry is the encryption key for new tickets and the
         default decryption key, subsequent entries are the fallback keys
@@ -296,7 +293,7 @@ class HandshakeSettings(object):
     :ivar ticketLifetime: maximum allowed lifetime of ticket encryption key,
         in seconds. 1 day by default
 
-    :vartype psk_modes: list
+    :vartype psk_modes: list(str)
     :ivar psk_modes: acceptable modes for the PSK key exchange in TLS 1.3
 
     :ivar int max_early_data: maximum number of bytes acceptable for 0-RTT
@@ -312,8 +309,8 @@ class HandshakeSettings(object):
     :ivar heartbeat_response_callback: Callback to function when Heartbeat
         response is received.
 
-    :vartype record_size_limit: int
-    :ivar record_size_limit: maximum size of records we are willing to process
+    :vartype ~.record_size_limit: int
+    :ivar ~.record_size_limit: maximum size of records we are willing to process
         (value advertised to the other side). It must not be larger than
         2**14+1 (the maximum for TLS 1.3) and will be reduced to 2**14 if TLS
         1.2 or lower is the highest enabled version. Must not be set to values

tlslite/messages.py

@@ -318,14 +318,14 @@ class ClientHello(HelloMessage):
     :vartype srp_username: bytearray
     :ivar srp_username: name of the user in SRP extension (deprecated)
 
-    :vartype supports_npn: boolean
-    :ivar supports_npn: NPN extension presence (deprecated)
+    :vartype ~.supports_npn: boolean
+    :ivar ~.supports_npn: NPN extension presence (deprecated)
 
-    :vartype tack: boolean
-    :ivar tack: TACK extension presence (deprecated)
+    :vartype ~.tack: boolean
+    :ivar ~.tack: TACK extension presence (deprecated)
 
-    :vartype server_name: bytearray
-    :ivar server_name: first host_name (type 0) present in SNI extension
+    :vartype ~.server_name: bytearray
+    :ivar ~.server_name: first host_name (type 0) present in SNI extension
         (deprecated)
 
     :vartype extensions: list of :py:class:`TLSExtension`
@@ -1620,8 +1620,8 @@ class ClientKeyExchange(HandshakeMsg):
 
     :vartype cipherSuite: int
     :ivar cipherSuite: the cipher suite id used for the connection
-    :vartype version: tuple(int, int)
-    :ivar version: TLS protocol version used for the connection
+    :vartype ~.version: tuple(int, int)
+    :ivar ~.version: TLS protocol version used for the connection
     :vartype srp_A: int
     :ivar srp_A: SRP protocol client answer value
     :vartype dh_Yc: int
@@ -2056,7 +2056,7 @@ class SessionTicketPayload(object):
     This is the internal (meant to be encrypted) representation of server
     state that is set to client in the NewSessionTicket message.
 
-    :ivar int version: implementation detail for forward compatibility
+    :ivar int ~.version: implementation detail for forward compatibility
     :ivar bytearray master_secret: master secret for TLS 1.2-, resumption
         master secret for TLS 1.3
 
@@ -2268,14 +2268,14 @@ class Heartbeat(object):
     """
     Handling Heartbeat messages from RFC 6520
 
-    @type message_type: int
-    @ivar message_type: type of message (response or request)
+    :type message_type: int
+    :ivar message_type: type of message (response or request)
 
-    @type payload: bytearray
-    @ivar payload: payload
+    :type payload: bytearray
+    :ivar payload: payload
 
-    @type padding: bytearray
-    @ivar padding: random padding of selected length
+    :type padding: bytearray
+    :ivar padding: random padding of selected length
     """
 
     def __init__(self):
@@ -2335,8 +2335,8 @@ class KeyUpdate(HandshakeMsg):
     """
     Handling KeyUpdate message from RFC 8446
 
-    @type message_type: int
-    @ivar message_type: type of message (update_not_requested or
+    :vartype message_type: int
+    :ivar message_type: type of message (update_not_requested or
                                          update_requested)
     """