Merge pull request #184 from NeuralEnsemble/feat/document-writers

docs(writers): document classes and methods

Author: sanjayankur31

neuroml/nml/helper_methods.py

@@ -2931,7 +2931,14 @@ def __str__(self):
         source='''\
 
     def exportHdf5(self, h5file, h5Group):
-        """Export to HDF5 file.  """
+        """Export to HDF5 file.
+
+        :param h5file: HDF5 file handler
+        :type h5file: file object
+        :param h5Group: the tables Group object to write
+        :type h5Group: tables.Group
+
+        """
         #print("Exporting %s: "+str(self.id)+" as HDF5")
         %s
     '''

neuroml/nml/nml.py

@@ -2,8 +2,8 @@
 # -*- coding: utf-8 -*-
 
 #
-# Generated Wed Sep 20 19:12:47 2023 by generateDS.py version 2.43.1.
-# Python 3.10.6 (main, Nov 14 2022, 16:10:14) [GCC 11.3.0]
+# Generated Tue Dec  5 10:44:41 2023 by generateDS.py version 2.43.3.
+# Python 3.11.6 (main, Oct  3 2023, 00:00:00) [GCC 13.2.1 20230918 (Red Hat 13.2.1-3)]
 #
 # Command line options:
 #   ('-o', 'nml.py')
@@ -16,7 +16,7 @@
 #   NeuroML_v2.3.xsd
 #
 # Command line:
-#   /usr/local/bin/generateDS -o "nml.py" --use-getter-setter="none" --user-methods="helper_methods.py" --export="write validate" --custom-imports-template="gds_imports-template.py" NeuroML_v2.3.xsd
+#   /home/asinha/.local/share/virtualenvs/neuroml-311-dev/bin/generateDS -o "nml.py" --use-getter-setter="none" --user-methods="helper_methods.py" --export="write validate" --custom-imports-template="gds_imports-template.py" NeuroML_v2.3.xsd
 #
 # Current working directory (os.getcwd()):
 #   nml
@@ -7370,7 +7370,14 @@ def _buildChildren(
         super(InputList, self)._buildChildren(child_, node, nodeName_, True)
 
     def exportHdf5(self, h5file, h5Group):
-        """Export to HDF5 file."""
+        """Export to HDF5 file.
+
+        :param h5file: HDF5 file handler
+        :type h5file: file object
+        :param h5Group: the tables Group object to write
+        :type h5Group: tables.Group
+
+        """
         # print("Exporting InputList: "+str(self.id)+" as HDF5")
 
         ilGroup = h5file.create_group(h5Group, "inputList_" + self.id)
@@ -10840,7 +10847,14 @@ def _buildChildren(
         super(Population, self)._buildChildren(child_, node, nodeName_, True)
 
     def exportHdf5(self, h5file, h5Group):
-        """Export to HDF5 file."""
+        """Export to HDF5 file.
+
+        :param h5file: HDF5 file handler
+        :type h5file: file object
+        :param h5Group: the tables Group object to write
+        :type h5Group: tables.Group
+
+        """
         # print("Exporting Population: "+str(self.id)+" as HDF5")
 
         popGroup = h5file.create_group(h5Group, "population_" + self.id)
@@ -12504,7 +12518,14 @@ def __str__(self):
         )
 
     def exportHdf5(self, h5file, h5Group):
-        """Export to HDF5 file."""
+        """Export to HDF5 file.
+
+        :param h5file: HDF5 file handler
+        :type h5file: file object
+        :param h5Group: the tables Group object to write
+        :type h5Group: tables.Group
+
+        """
         # print("Exporting Network: "+str(self.id)+" as HDF5")
 
         netGroup = h5file.create_group(h5Group, "network")
@@ -44993,7 +45014,14 @@ def _buildChildren(
         super(ContinuousProjection, self)._buildChildren(child_, node, nodeName_, True)
 
     def exportHdf5(self, h5file, h5Group):
-        """Export to HDF5 file."""
+        """Export to HDF5 file.
+
+        :param h5file: HDF5 file handler
+        :type h5file: file object
+        :param h5Group: the tables Group object to write
+        :type h5Group: tables.Group
+
+        """
         # print("Exporting ContinuousProjection: "+str(self.id)+" as HDF5")
 
         projGroup = h5file.create_group(h5Group, "projection_" + self.id)
@@ -45401,7 +45429,14 @@ def _buildChildren(
         super(ElectricalProjection, self)._buildChildren(child_, node, nodeName_, True)
 
     def exportHdf5(self, h5file, h5Group):
-        """Export to HDF5 file."""
+        """Export to HDF5 file.
+
+        :param h5file: HDF5 file handler
+        :type h5file: file object
+        :param h5Group: the tables Group object to write
+        :type h5Group: tables.Group
+
+        """
         # print("Exporting ElectricalProjection: "+str(self.id)+" as HDF5")
 
         projGroup = h5file.create_group(h5Group, "projection_" + self.id)
@@ -46678,7 +46713,14 @@ def _buildChildren(
         super(Projection, self)._buildChildren(child_, node, nodeName_, True)
 
     def exportHdf5(self, h5file, h5Group):
-        """Export to HDF5 file."""
+        """Export to HDF5 file.
+
+        :param h5file: HDF5 file handler
+        :type h5file: file object
+        :param h5Group: the tables Group object to write
+        :type h5Group: tables.Group
+
+        """
         # print("Exporting Projection: "+str(self.id)+" as HDF5")
 
         projGroup = h5file.create_group(h5Group, "projection_" + self.id)

neuroml/writers.py

@@ -2,13 +2,25 @@
 from six import string_types
 
 
+"""Classes to write NeuroML to various formats."""
+
+
 class NeuroMLWriter(object):
+    """Writes from NeuroMLDocument to nml file.
+
+    In future can implement from other types via chain of responsibility pattern.
+    """
     @classmethod
     def write(cls, nmldoc, file, close=True):
-        """
-        Writes from NeuroMLDocument to nml file
-        in future can implement from other types
-        via chain of responsibility pattern.
+        """Write a NeuroMLDocument to file.
+
+        :param nmldoc: NeuroML document object to write
+        :type nmldoc: neuroml.NeuroMLDocument
+        :param file: file name to write to
+        :type file: str
+        :param close: toggle whether file should be closed
+        :type close: bool
+        :raises AttributeError: if export fails
         """
 
         if isinstance(file, string_types):
@@ -36,8 +48,21 @@ def write(cls, nmldoc, file, close=True):
 
 
 class NeuroMLHdf5Writer(object):
+    """Exports NeuroML documents to HDF5 format."""
     @classmethod
     def write(cls, nml_doc, h5_file_name, embed_xml=True, compress=True):
+        """Write a NeuroMLDocument to HDF5 file
+
+        :param nmldoc: NeuroML document object to write
+        :type nmldoc: neuroml.NeuroMLDocument
+        :param h5_file_name: file name to write to
+        :type h5_file_name: str
+        :param embed_xml: toggle whether XML serialization should be embedded
+        :type embed_xml: bool
+        :param compress: toggle compression
+        :type compress: bool
+        """
+
         import tables
 
         FILTERS = (
@@ -67,17 +92,13 @@ def write(cls, nml_doc, h5_file_name, embed_xml=True, compress=True):
 
             try:
                 import StringIO
-
                 sf = StringIO.StringIO()
-            except:
+            except ImportError:
                 import io
-
                 sf = io.StringIO()
 
             NeuroMLWriter.write(nml_doc, sf, close=False)
-
             nml2 = sf.getvalue()
-
             rootGroup._f_setattr("neuroml_top_level", nml2)
 
             # Put back into previous form...
@@ -89,20 +110,20 @@ def write(cls, nml_doc, h5_file_name, embed_xml=True, compress=True):
     """
     @classmethod
     def write_xml_and_hdf5(cls,nml_doc0,xml_file_name,h5_file_name):
-        
+
         nml_doc_hdf5 = neuroml.NeuroMLDocument(nml_doc0.id)
-        
+
         for n in nml_doc0.networks:
             nml_doc_hdf5.networks.append(n)
-            
+
         nml_doc0.networks = []
-        
-        nml_doc0.includes.append(neuroml.IncludeType(h5_file_name)) 
-        
+
+        nml_doc0.includes.append(neuroml.IncludeType(h5_file_name))
+
         NeuroMLWriter.write(nml_doc0,xml_file_name)
-        
+
         NeuroMLHdf5Writer.write(nml_doc_hdf5,h5_file_name,embed_xml=False)
-        
+
         # Put back into previous form...
         for n in nml_doc_hdf5.networks:
             nml_doc0.networks.append(n)
@@ -113,11 +134,22 @@ def write_xml_and_hdf5(cls,nml_doc0,xml_file_name,h5_file_name):
 
 class ArrayMorphWriter(object):
     """
+    Write morphology to ArrayMorph format.
+
     For now just testing a simple method which can write a morphology, not a NeuroMLDocument.
     """
 
     @classmethod
     def __write_single_cell(cls, array_morph, fileh, cell_id=None):
+        """Write a array morphology to a file handler.
+
+        :param array_morph: a array morph object containing a morphology
+        :type array_morph: neuroml.arraymorph.ArrayMorphology
+        :param fileh: file handler of file to write to
+        :type fileh: file object
+        :param cell_id: id of cell
+        :type cell_id: str
+        """
         vertices = array_morph.vertices
         connectivity = array_morph.connectivity
         physical_mask = array_morph.physical_mask
@@ -128,12 +160,12 @@ def __write_single_cell(cls, array_morph, fileh, cell_id=None):
         # Create the groups:
         # can use morphology name in future?
 
-        if array_morph.id == None:
+        if array_morph.id is None:
             morphology_name = "Morphology"
         else:
             morphology_name = array_morph.id
 
-        if cell_id == None:
+        if cell_id is None:
             morphology_group = fileh.create_group(root, morphology_name)
             hierarchy_prefix = "/" + morphology_name
         else:
@@ -151,26 +183,39 @@ def __write_single_cell(cls, array_morph, fileh, cell_id=None):
 
     @classmethod
     def __write_neuroml_document(cls, document, fileh):
-        document_id = document.id
+        """Write a NeuroMLDocument containing morphology to a file handler
 
+        :param document: a NeuroML document object containing a morphology
+        :type document: neuroml.NeuroMLDocument
+        :param fileh: file handler of file to write to
+        :type fileh: file object
+        """
         for default_id, cell in enumerate(document.cells):
             morphology = cell.morphology
 
-            if morphology.id == None:
+            if morphology.id is None:
                 morphology.id = "Morphology" + str(default_id)
-            if cell.id == None:
+            if cell.id is None:
                 cell.id = "Cell" + str(default_id)
 
             cls.__write_single_cell(morphology, fileh, cell_id=cell.id)
 
         for default_id, morphology in enumerate(document.morphology):
-            if morphology.id == None:
+            if morphology.id is None:
                 morphology.id = "Morphology" + str(default_id)
 
             cls.__write_single_cell(morphology, fileh, cell_id=cell.id)
 
     @classmethod
     def write(cls, data, filepath):
+        """Write morphology to file in ArrayMorph format.
+
+        :param data: data to write
+        :type data: neuroml.arraymorph.ArrayMorphology or neuroml.NeuroMLDocument
+        :param filepath: path of file to write to
+        :type filepath: str
+
+        """
         import tables
 
         fileh = tables.open_file(filepath, mode="w")