From f69ccc93df916d273bea61ca30128c21d68ce1a7 Mon Sep 17 00:00:00 2001 From: tim Date: Mon, 17 Oct 2016 15:00:38 +0200 Subject: [PATCH 1/4] Add doc strings for Block cls --- bigchaindb/models.py | 86 +++++++++++++++++++++++++++++++++++++++----- 1 file changed, 78 insertions(+), 8 deletions(-) diff --git a/bigchaindb/models.py b/bigchaindb/models.py index 6471b075..6d2ff053 100644 --- a/bigchaindb/models.py +++ b/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. - Else it raises an appropriate exception describing - the reason of invalidity. + :class:`~.Block`: If valid, returns a `Block` object. Else an + appropriate exception describing the reason of invalidity is + 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') From b42eec93c7b05df09191e0afac9676c65f7f6fcc Mon Sep 17 00:00:00 2001 From: tim Date: Mon, 14 Nov 2016 13:53:49 +0100 Subject: [PATCH 2/4] Fix indentation for model docs --- bigchaindb/models.py | 80 ++++++++++++++++++++++---------------------- 1 file changed, 40 insertions(+), 40 deletions(-) diff --git a/bigchaindb/models.py b/bigchaindb/models.py index 6d2ff053..afda5ca9 100644 --- a/bigchaindb/models.py +++ b/bigchaindb/models.py @@ -120,7 +120,24 @@ class Transaction(Transaction): class Block(object): """A Block bundles up to 1000 Transactions. Nodes vote on its validity. - Attributes: + 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 @@ -130,23 +147,6 @@ class Block(object): 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') @@ -214,12 +214,12 @@ class Block(object): 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`. + Args: + signing_key (str): A signing key corresponding to + `self.node_pubkey`. - Returns: - :class:`~.Block` + Returns: + :class:`~.Block` """ block_body = self.to_dict() block_serialized = serialize(block_body['block']) @@ -230,8 +230,8 @@ class Block(object): def is_signature_valid(self): """Checks the validity of a Block's signature. - Returns: - bool: Stating the validity of the Block's signature. + Returns: + bool: Stating the validity of the Block's signature. """ block = self.to_dict()['block'] # cc only accepts bytestring messages @@ -248,20 +248,20 @@ class Block(object): def from_dict(cls, block_body): """Transforms a Python dictionary to a Block object. - Note: - Throws errors if passed signature or id is incorrect. + Note: + Throws errors if passed signature or id is incorrect. - Args: - block_body (dict): A block dictionary to be transformed. + Args: + block_body (dict): A block dictionary to be transformed. - Returns: - :class:`~Block` + 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`. + 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'] @@ -301,11 +301,11 @@ class Block(object): def to_dict(self): """Transforms the object to a Python dictionary. - Returns: - dict: The Block as an alternative serialization format. + Returns: + dict: The Block as an alternative serialization format. - Raises: - OperationError: If a Block doesn't contain any transactions. + Raises: + OperationError: If a Block doesn't contain any transactions. """ if len(self.transactions) == 0: raise OperationError('Empty block creation is not allowed') From 37cf057b99e14ae49bdb9410372d106801fa6a66 Mon Sep 17 00:00:00 2001 From: tim Date: Mon, 14 Nov 2016 13:56:05 +0100 Subject: [PATCH 3/4] PR Feedback for docs --- bigchaindb/models.py | 9 +++------ 1 file changed, 3 insertions(+), 6 deletions(-) diff --git a/bigchaindb/models.py b/bigchaindb/models.py index afda5ca9..a6a2ecdb 100644 --- a/bigchaindb/models.py +++ b/bigchaindb/models.py @@ -248,9 +248,6 @@ class Block(object): 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. @@ -299,13 +296,13 @@ class Block(object): return self.to_dict()['id'] def to_dict(self): - """Transforms the object to a Python dictionary. + """Transforms the Block to a Python dictionary. Returns: - dict: The Block as an alternative serialization format. + dict: The Block as a dict. Raises: - OperationError: If a Block doesn't contain any transactions. + OperationError: If the Block doesn't contain any transactions. """ if len(self.transactions) == 0: raise OperationError('Empty block creation is not allowed') From 74e1f9c30330058ab5fd7fe25d5742fe4d66626e Mon Sep 17 00:00:00 2001 From: tim Date: Mon, 14 Nov 2016 14:59:09 +0100 Subject: [PATCH 4/4] Fix tense in docs --- bigchaindb/models.py | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/bigchaindb/models.py b/bigchaindb/models.py index a6a2ecdb..57d64272 100644 --- a/bigchaindb/models.py +++ b/bigchaindb/models.py @@ -118,7 +118,7 @@ class Transaction(Transaction): class Block(object): - """A Block bundles up to 1000 Transactions. Nodes vote on its validity. + """Bundle a list of Transactions in a Block. Nodes vote on its validity. Attributes: transaction (:obj:`list` of :class:`~.Transaction`): @@ -129,7 +129,7 @@ class Block(object): 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. + integrity and validity of the creator of a Block. """ def __init__(self, transactions=None, node_pubkey=None, timestamp=None, @@ -146,7 +146,7 @@ class Block(object): 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. + integrity and validity of the creator of a Block. """ if transactions is not None and not isinstance(transactions, list): raise TypeError('`transactions` must be a list instance or None') @@ -174,14 +174,14 @@ class Block(object): return self.to_dict() == other def validate(self, bigchain): - """Validates the Block. + """Validate the Block. Args: bigchain (:class:`~bigchaindb.Bigchain`): An instantiated Bigchain object. Returns: - :class:`~.Block`: If valid, returns a `Block` object. Else an + :class:`~.Block`: If valid, return a `Block` object. Else an appropriate exception describing the reason of invalidity is raised. @@ -212,7 +212,7 @@ class Block(object): return self def sign(self, signing_key): - """Creates a signature for the Block and overwrites `self.signature`. + """Create a signature for the Block and overwrite `self.signature`. Args: signing_key (str): A signing key corresponding to @@ -228,7 +228,7 @@ class Block(object): return self def is_signature_valid(self): - """Checks the validity of a Block's signature. + """Check the validity of a Block's signature. Returns: bool: Stating the validity of the Block's signature. @@ -246,7 +246,7 @@ class Block(object): @classmethod def from_dict(cls, block_body): - """Transforms a Python dictionary to a Block object. + """Transform a Python dictionary to a Block object. Args: block_body (dict): A block dictionary to be transformed. @@ -296,7 +296,7 @@ class Block(object): return self.to_dict()['id'] def to_dict(self): - """Transforms the Block to a Python dictionary. + """Transform the Block to a Python dictionary. Returns: dict: The Block as a dict.