Add docstrings

cic/attachment.py

@@ -9,7 +9,13 @@ logg = logging.getLogger(__name__)
 
 
 class Attachment(Data):
+    """Processes, serialized and publishes all attachments found in the "attachments" subdirectory of the settings directory.
 
+    :param path: Path to settings directory
+    :type path: str
+    :param writer: Writer interface receiving the output of the processor
+    :type writer: cic.output.OutputWriter
+    """
     def __init__(self, path='.', writer=None):
         super(Attachment, self).__init__()
         self.contents = {}
@@ -19,6 +25,8 @@ class Attachment(Data):
 
 
     def load(self):
+        """Loads attachment data from settings.
+        """
         for s in os.listdir(self.attachment_path):
             fp = os.path.realpath(os.path.join(self.attachment_path, s))
             f = open(fp, 'rb')
@@ -32,19 +40,32 @@ class Attachment(Data):
 
 
     def start(self):
+        """Initialize attachment settings from template.
+        """
         super(Attachment, self).start()
         os.makedirs(self.attachment_path)
 
 
     def get(self, k):
+        """Get a single attachment by the sha256 hash of the content.
+
+        :param k: Content hash
+        :type k: str (hex)
+        """
         return self.contents[k]
 
 
     def asdict(self):
+        """Output attachment state to dict
+        """
         return self.contents
 
 
     def process(self, token_address=None, token_symbol=None, writer=None):
+        """Serialize and publish attachments.
+
+        See cic.processor.Processor.process 
+        """
         if writer == None:
             writer = self.writer
 

cic/meta.py

@@ -20,7 +20,15 @@ logg = logging.getLogger(__name__)
 
 
 class Meta(Data):
+    """Serialize and publish metadata for token.
 
+    The token metadata is any mutable data that is not part of the initial token proof, but published simultaneously as the token nonetheless.
+
+    :param path: Path to settings directory
+    :type path: str
+    :param writer: Writer interface receiving the output of the processor
+    :type writer: cic.output.OutputWriter
+    """
     def __init__(self, path='.', writer=None):
         super(Meta, self).__init__()
         self.name = None
@@ -31,6 +39,8 @@ class Meta(Data):
 
 
     def load(self):
+        """Load metadata from settings.
+        """
         super(Meta, self).load()
 
         f = open(self.meta_path, 'r')
@@ -44,6 +54,8 @@ class Meta(Data):
 
 
     def start(self):
+        """Initialize metadata settings from template.
+        """
         super(Meta, self).start()
 
         meta_template_file_path = os.path.join(data_dir, 'meta_template_v{}.json'.format(self.version()))
@@ -58,11 +70,15 @@ class Meta(Data):
 
 
     def reference(self, token_address):
+        """Calculate the mutable reference for the token metadata.
+        """
         token_address_bytes = bytes.fromhex(strip_0x(token_address))
         return generate_metadata_pointer(token_address_bytes, MetadataPointer.TOKEN_META)
 
 
     def asdict(self):
+        """Output proof state to dict.
+        """
         return {
             'name': self.name,
             'contact': self.contact,
@@ -70,6 +86,10 @@ class Meta(Data):
 
     
     def process(self, token_address=None, token_symbol=None, writer=None):
+        """Serialize and publish metadata.
+
+        See cic.processor.Processor.process 
+        """
         if writer == None:
             writer = self.writer
 
@@ -98,6 +118,12 @@ class Meta(Data):
 
 
 class MetadataWriter(OutputWriter):
+    """Custom writer for publishing data under immutable content-addressed pointers in the cic-meta storage backend.
+
+    Data that is not utf-8 will be converted to base64 before publishing.
+
+    Implements cic.output.OutputWriter
+    """
 
     def write(self, k, v):
         rq = MetadataRequestsHandler(MetadataPointer.NONE, bytes.fromhex(k))

cic/processor.py

@@ -5,7 +5,19 @@ logg = logging.getLogger(__name__)
 
 
 class Processor:
+    """Drives the serialization and publishing of contracts, proofs and metadata for the token.
 
+    :param proof: Proof object to publish
+    :type proof: cic.proof.Proof
+    :param attachment: Attachment object to publish
+    :type attachment: cic.attachment.Attachment
+    :param metadata: Metadata object to publish
+    :type metadata: cic.meta.Meta
+    :param writer: Writer interface receiving the output of the processor
+    :type writer: cic.output.OutputWriter
+    :param extensions: Extension contexts to publish to
+    :type extensions: list of cic.extension.Extension
+    """
     def __init__(self, proof=None, attachment=None, metadata=None, outputs_writer=None, extensions=[]):
         self.token_address = None
         self.extensions = extensions
@@ -19,10 +31,22 @@ class Processor:
 
 
     def writer(self):
+        """Return the writer instance that the process is using.
+
+        :rtype: cic.output.OutputWriter
+        :return: Writer
+        """
         return self.__outputs_writer
 
 
     def get_outputs(self):
+        """Return all written outputs.
+
+        This will return nothing unless the process method has been executed.
+
+        :rtype: bytes
+        :return: Outputs
+        """
         outputs = []
         for ext in self.extensions:
             outputs += ext.outputs
@@ -31,6 +55,15 @@ class Processor:
 
 
     def process(self, writer=None):
+        """Serializes and publishes all token data.
+
+        Calls the process method on each extension. For each extension, the process method on attachment, proof and metadata, in that order, for any of them that have provided at processor object instantiation.
+
+        All output written to the publish writer will also be cached so that it subsequently be recalled using the get_outputs method.
+
+        :param writer: Writer to use for publishing.
+        :type writer: cic.output.OutputWriter
+        """
 
         tasks = [
             'attachment',

cic/proof.py

@@ -19,6 +19,19 @@ logg = logging.getLogger(__name__)
 
 
 class Proof(Data):
+    """Proof handles the immutable token proof data mapped to the initial token deployment.
+
+    It processes inputs from the proof.json file in the session directory.
+
+    Optionally, attachment objects can be added to the proof. If added, the resulting proof digest will consists of the attachment digests added to the root digest. These are then are deterministically ordered, regardless of which order attachments were given to the constructor.
+
+    :param path: Path to settings directory
+    :type path: str
+    :param attachments: List of attachment objects to include in the proof
+    :type attachments: cic.attachment.Attachment
+    :param writer: Writer interface receiving the output of the processor
+    :type writer: cic.output.OutputWriter
+    """
 
     def __init__(self, path='.', attachments=None, writer=None):
         super(Proof, self).__init__()
@@ -34,6 +47,8 @@ class Proof(Data):
                 
 
     def load(self):
+        """Load proof data from settings.
+        """
         super(Proof, self).load()
 
         f = open(self.proof_path, 'r')
@@ -58,6 +73,8 @@ class Proof(Data):
 
 
     def start(self):
+        """Initialize proof settings from template.
+        """
         super(Proof, self).start()
 
         proof_template_file_path = os.path.join(data_dir, 'proof_template_v{}.json'.format(self.version()))
@@ -72,6 +89,8 @@ class Proof(Data):
 
 
     def asdict(self):
+        """Output proof state to dict.
+        """
         return {
             'version': self.version(),
             'namespace': self.namespace,
@@ -81,6 +100,7 @@ class Proof(Data):
                 }
 
 
+    # TODO: the efficiency of this method could probably be improved.
     def __get_ordered_hashes(self):
         ks = list(self.attachments.keys())
         ks.sort()
@@ -95,6 +115,8 @@ class Proof(Data):
 
 
     def root(self):
+        """Calculate the root digest from the serialized proof object.
+        """
         v = self.asdict() 
         #b = cbor2.dumps(v)
         b = json.dumps(v)
@@ -109,6 +131,10 @@ class Proof(Data):
 
 
     def process(self, token_address=None, token_symbol=None, writer=None):
+        """Serialize and publish proof.
+
+        See cic.processor.Processor.process 
+        """
         if writer == None:
             writer = self.writer