fix sphinx warnings in doc stings

Author: tomato42

src/ecdsa/ecdh.py

@@ -116,7 +116,7 @@ def generate_private_key(self):
         :raises NoCurveError: Curve must be set before key generation.
 
         :return: public (verifying) key from this private key.
-        :rtype: VerifyingKey object
+        :rtype: VerifyingKey
         """
         if not self.curve:
             raise NoCurveError("Curve must be set prior to key generation.")
@@ -135,7 +135,7 @@ def load_private_key(self, private_key):
         :raises InvalidCurveError: private_key curve not the same as self.curve
 
         :return: public (verifying) key from this private key.
-        :rtype: VerifyingKey object
+        :rtype: VerifyingKey
         """
         if not self.curve:
             self.curve = private_key.curve
@@ -158,7 +158,7 @@ def load_private_key_bytes(self, private_key):
         :raises NoCurveError: Curve must be set before loading.
 
         :return: public (verifying) key from this private key.
-        :rtype: VerifyingKey object
+        :rtype: VerifyingKey
         """
         if not self.curve:
             raise NoCurveError("Curve must be set prior to key load.")
@@ -183,7 +183,7 @@ def load_private_key_der(self, private_key_der):
         :raises InvalidCurveError: private_key curve not the same as self.curve
 
         :return: public (verifying) key from this private key.
-        :rtype: VerifyingKey object
+        :rtype: VerifyingKey
         """
         return self.load_private_key(SigningKey.from_der(private_key_der))
 
@@ -204,7 +204,7 @@ def load_private_key_pem(self, private_key_pem):
         :raises InvalidCurveError: private_key curve not the same as self.curve
 
         :return: public (verifying) key from this private key.
-        :rtype: VerifyingKey object
+        :rtype: VerifyingKey
         """
         return self.load_private_key(SigningKey.from_pem(private_key_pem))
 
@@ -215,7 +215,7 @@ def get_public_key(self):
         Needs to be sent to the remote party.
 
         :return: public (verifying) key from local private key.
-        :rtype: VerifyingKey object
+        :rtype: VerifyingKey
         """
         return self.private_key.get_verifying_key()
 
@@ -310,7 +310,7 @@ def generate_sharedsecret_bytes(self):
         :raises NoKeyError: public_key or private_key is not set
 
         :return: shared secret
-        :rtype: byte string
+        :rtype: bytes
         """
         return number_to_string(
             self.generate_sharedsecret(), self.private_key.curve.curve.p()
@@ -323,9 +323,9 @@ def generate_sharedsecret(self):
         The objects needs to have both private key and received public key
         before generation is allowed.
 
-        It's the same for local and remote party.
-        shared secret(local private key, remote public key ) ==
-                shared secret (local public key, remote private key)
+        It's the same for local and remote party,
+        shared secret(local private key, remote public key) ==
+        shared secret(local public key, remote private key)
 
         :raises InvalidCurveError: public_key curve not the same as self.curve
         :raises NoKeyError: public_key or private_key is not set

src/ecdsa/ecdsa.py

@@ -1,56 +1,64 @@
 #! /usr/bin/env python
 
 """
-Implementation of Elliptic-Curve Digital Signatures.
+Low level implementation of Elliptic-Curve Digital Signatures.
+
+.. note ::
+    You're most likely looking for the :py:class:`~ecdsa.keys` module.
+    This is a low-level implementation of the ECDSA that operates on
+    integers, not byte strings.
 
 Classes and methods for elliptic-curve signatures:
 private keys, public keys, signatures,
-NIST prime-modulus curves with modulus lengths of
-192, 224, 256, 384, and 521 bits.
+and definitions of prime-modulus curves.
 
 Example:
 
-  # (In real-life applications, you would probably want to
-  # protect against defects in SystemRandom.)
-  from random import SystemRandom
-  randrange = SystemRandom().randrange
+.. code-block:: python
 
-  # Generate a public/private key pair using the NIST Curve P-192:
+   # (In real-life applications, you would probably want to
+   # protect against defects in SystemRandom.)
+   from random import SystemRandom
+   randrange = SystemRandom().randrange
 
-  g = generator_192
-  n = g.order()
-  secret = randrange( 1, n )
-  pubkey = Public_key( g, g * secret )
-  privkey = Private_key( pubkey, secret )
+   # Generate a public/private key pair using the NIST Curve P-192:
 
-  # Signing a hash value:
+   g = generator_192
+   n = g.order()
+   secret = randrange( 1, n )
+   pubkey = Public_key( g, g * secret )
+   privkey = Private_key( pubkey, secret )
 
-  hash = randrange( 1, n )
-  signature = privkey.sign( hash, randrange( 1, n ) )
+   # Signing a hash value:
 
-  # Verifying a signature for a hash value:
+   hash = randrange( 1, n )
+   signature = privkey.sign( hash, randrange( 1, n ) )
 
-  if pubkey.verifies( hash, signature ):
-    print_("Demo verification succeeded.")
-  else:
-    print_("*** Demo verification failed.")
+   # Verifying a signature for a hash value:
 
-  # Verification fails if the hash value is modified:
+   if pubkey.verifies( hash, signature ):
+     print_("Demo verification succeeded.")
+   else:
+     print_("*** Demo verification failed.")
 
-  if pubkey.verifies( hash-1, signature ):
-    print_("**** Demo verification failed to reject tampered hash.")
-  else:
-    print_("Demo verification correctly rejected tampered hash.")
+   # Verification fails if the hash value is modified:
 
-Version of 2009.05.16.
+   if pubkey.verifies( hash-1, signature ):
+     print_("**** Demo verification failed to reject tampered hash.")
+   else:
+     print_("Demo verification correctly rejected tampered hash.")
 
 Revision history:
       2005.12.31 - Initial version.
+
       2008.11.25 - Substantial revisions introducing new classes.
+
       2009.05.16 - Warn against using random.randrange in real applications.
+
       2009.05.17 - Use random.SystemRandom by default.
 
-Written in 2005 by Peter Pearson and placed in the public domain.
+Originally written in 2005 by Peter Pearson and placed in the public domain,
+modified as part of the python-ecdsa package.
 """
 
 from six import int2byte, b
@@ -69,16 +77,26 @@ class InvalidPointError(RuntimeError):
 
 
 class Signature(object):
-    """ECDSA signature."""
+    """
+    ECDSA signature.
+
+    :ivar int r: the ``r`` element of the ECDSA signature
+    :ivar int s: the ``s`` element of the ECDSA signature
+    """
 
     def __init__(self, r, s):
         self.r = r
         self.s = s
 
     def recover_public_keys(self, hash, generator):
-        """Returns two public keys for which the signature is valid
-        hash is signed hash
-        generator is the used generator of the signature
+        """
+        Returns two public keys for which the signature is valid
+
+        :param int hash: signed hash
+        :param AbstractPoint generator: is the generator used in creation
+            of the signature
+        :rtype: tuple(Public_key, Public_key)
+        :return: a pair of public keys that can validate the signature
         """
         curve = generator.curve()
         n = generator.order()

src/ecdsa/ellipticcurve.py

@@ -224,7 +224,7 @@ def from_bytes(
         :param data: single point encoding of the public key
         :type data: :term:`bytes-like object`
         :param curve: the curve on which the public key is expected to lay
-        :type curve: ecdsa.ellipticcurve.CurveFp
+        :type curve: ~ecdsa.ellipticcurve.CurveFp
         :param validate_encoding: whether to verify that the encoding of the
             point is self-consistent, defaults to True, has effect only
             on ``hybrid`` encoding
@@ -235,8 +235,8 @@ def from_bytes(
             name). All formats by default (specified with ``None``).
         :type valid_encodings: :term:`set-like object`
 
-        :raises MalformedPointError: if the public point does not lay on the
-            curve or the encoding is invalid
+        :raises `~ecdsa.errors.MalformedPointError`: if the public point does
+            not lay on the curve or the encoding is invalid
 
         :return: x and y coordinates of the encoded point
         :rtype: tuple(int, int)
@@ -391,7 +391,7 @@ def from_bytes(
         :param data: single point encoding of the public key
         :type data: :term:`bytes-like object`
         :param curve: the curve on which the public key is expected to lay
-        :type curve: ecdsa.ellipticcurve.CurveFp
+        :type curve: ~ecdsa.ellipticcurve.CurveFp
         :param validate_encoding: whether to verify that the encoding of the
             point is self-consistent, defaults to True, has effect only
             on ``hybrid`` encoding
@@ -407,8 +407,8 @@ def from_bytes(
             such, it will be commonly used with scalar multiplication. This
             will cause to precompute multiplication table generation for it
 
-        :raises MalformedPointError: if the public point does not lay on the
-            curve or the encoding is invalid
+        :raises `~ecdsa.errors.MalformedPointError`: if the public point does
+            not lay on the curve or the encoding is invalid
 
         :return: Point on curve
         :rtype: PointJacobi
@@ -970,7 +970,7 @@ def from_bytes(
         :param data: single point encoding of the public key
         :type data: :term:`bytes-like object`
         :param curve: the curve on which the public key is expected to lay
-        :type curve: ecdsa.ellipticcurve.CurveFp
+        :type curve: ~ecdsa.ellipticcurve.CurveFp
         :param validate_encoding: whether to verify that the encoding of the
             point is self-consistent, defaults to True, has effect only
             on ``hybrid`` encoding
@@ -983,8 +983,8 @@ def from_bytes(
         :param int order: the point order, must be non zero when using
             generator=True
 
-        :raises MalformedPointError: if the public point does not lay on the
-            curve or the encoding is invalid
+        :raises `~ecdsa.errors.MalformedPointError`: if the public point does
+            not lay on the curve or the encoding is invalid
 
         :return: Point on curve
         :rtype: Point