Add doc strings for Block cls

bigchaindb/models.py

@@ -118,8 +118,36 @@ class Transaction(Transaction):
 
 
 class Block(object):
+    """A Block bundles up to 1000 Transactions. Nodes vote on its validity.
+
+        Attributes:
+            transaction (:obj:`list` of :class:`~.Transaction`):
+                Transactions to be included in the Block.
+            node_pubkey (str): The public key of the node creating the
+                Block.
+            timestamp (str): The Unix time a Block was created.
+            voters (:obj:`list` of :obj:`str`): A list of a federation
+                nodes' public keys supposed to vote on the Block.
+            signature (str): A cryptographic signature ensuring the
+                integrity and creatorship of a Block.
+    """
+
     def __init__(self, transactions=None, node_pubkey=None, timestamp=None,
                  voters=None, signature=None):
+        """The Block model is mainly used for (de)serialization and integrity
+        checking.
+
+            Args:
+                transaction (:obj:`list` of :class:`~.Transaction`):
+                    Transactions to be included in the Block.
+                node_pubkey (str): The public key of the node creating the
+                    Block.
+                timestamp (str): The Unix time a Block was created.
+                voters (:obj:`list` of :obj:`str`): A list of a federation
+                    nodes' public keys supposed to vote on the Block.
+                signature (str): A cryptographic signature ensuring the
+                    integrity and creatorship of a Block.
+        """
         if transactions is not None and not isinstance(transactions, list):
             raise TypeError('`transactions` must be a list instance or None')
         else:
@@ -146,18 +174,20 @@ class Block(object):
         return self.to_dict() == other
 
     def validate(self, bigchain):
-        """Validate a block.
+        """Validates the Block.
 
         Args:
-            bigchain (Bigchain): an instantiated bigchaindb.Bigchain object.
+            bigchain (:class:`~bigchaindb.Bigchain`): An instantiated Bigchain
+                object.
 
         Returns:
-            block (Block): The block as a `Block` object if it is valid.
+            :class:`~.Block`: If valid, returns a `Block` object. Else an
-                           Else it raises an appropriate exception describing
+            appropriate exception describing the reason of invalidity is
-                           the reason of invalidity.
+            raised.
 
         Raises:
-            OperationError: if a non-federation node signed the block.
+            OperationError: If a non-federation node signed the Block.
+            InvalidSignature: If a Block's signature is invalid.
         """
 
         # First, make sure this node hasn't already voted on this block
@@ -182,6 +212,15 @@ class Block(object):
         return self
 
     def sign(self, signing_key):
+        """Creates a signature for the Block and overwrites `self.signature`.
+
+            Args:
+                signing_key (str): A signing key corresponding to
+                    `self.node_pubkey`.
+
+            Returns:
+                :class:`~.Block`
+        """
         block_body = self.to_dict()
         block_serialized = serialize(block_body['block'])
         signing_key = SigningKey(signing_key)
@@ -189,8 +228,13 @@ class Block(object):
         return self
 
     def is_signature_valid(self):
+        """Checks the validity of a Block's signature.
+
+            Returns:
+                bool: Stating the validity of the Block's signature.
+        """
         block = self.to_dict()['block']
-        # cc only accepts bytesting messages
+        # cc only accepts bytestring messages
         block_serialized = serialize(block).encode()
         verifying_key = VerifyingKey(block['node_pubkey'])
         try:
@@ -202,6 +246,24 @@ class Block(object):
 
     @classmethod
     def from_dict(cls, block_body):
+        """Transforms a Python dictionary to a Block object.
+
+            Note:
+                Throws errors if passed signature or id is incorrect.
+
+            Args:
+                block_body (dict): A block dictionary to be transformed.
+
+            Returns:
+                :class:`~Block`
+
+            Raises:
+                InvalidHash: If the block's id is not corresponding to its
+                    data.
+                InvalidSignature: If the block's signature is not corresponding
+                    to it's data or `node_pubkey`.
+        """
+        # TODO: Reuse `is_signature_valid` method here.
         block = block_body['block']
         block_serialized = serialize(block)
         block_id = hash_data(block_serialized)
@@ -220,7 +282,7 @@ class Block(object):
             #       https://github.com/bigchaindb/cryptoconditions/issues/27
             try:
                 signature_valid = verifying_key\
-                        .verify(block_serialized.encode(), signature)
+                    .verify(block_serialized.encode(), signature)
             except ValueError:
                 signature_valid = False
             if signature_valid is False:
@@ -237,6 +299,14 @@ class Block(object):
         return self.to_dict()['id']
 
     def to_dict(self):
+        """Transforms the object to a Python dictionary.
+
+            Returns:
+                dict: The Block as an alternative serialization format.
+
+            Raises:
+                OperationError: If a Block doesn't contain any transactions.
+        """
         if len(self.transactions) == 0:
             raise OperationError('Empty block creation is not allowed')