docstring refactoring

Author: JuliaSprenger

neo/test/iotest/common_io_test.py

@@ -1,4 +1,4 @@
-'''
+"""
 Common tests for IOs:
  * check presence of all necessary attr
  * check types
@@ -13,7 +13,7 @@
 gin.g-node.org and upload files at NeuralEnsemble/ephy_testing_data
 data repo.
 
-'''
+"""
 
 __test__ = False
 
@@ -55,21 +55,25 @@
 
 
 class BaseTestIO:
-    '''
+    """
     This class make common tests for all IOs.
 
     Several startegies:
       * for IO able to read write : test_write_then_read
       * for IO able to read write with hash conservation (optional):
         test_read_then_write
-      * for all IOs : test_assert_readed_neo_object_is_compliant
+      * for all IOs : test_assert_read_neo_object_is_compliant
         2 cases:
           * files are at G-node and downloaded:
             download_test_files_if_not_present
           * files are generated by MyIO.write()
 
-    '''
-    # ~ __test__ = False
+    Note: When inheriting this class use it as primary superclass in
+    combination with the unittest.TestCase as a 2nd superclass, e.g.
+    `NewIOTestClass(BaseTestIO, unittest.TestCase):`
+
+    """
+    # __test__ = False
 
     # all IO test need to modify this:
     ioclass = None  # the IOclass to be tested
@@ -214,7 +218,7 @@ def generic_io_object(self, filename=None, return_path=False, clean=False):
 
     def read_file(self, filename=None, return_path=False, clean=False,
                   target=None, readall=False, lazy=False):
-        '''
+        """
         Read from the specified filename.
 
         If filename is None, create a filename (default).
@@ -235,7 +239,7 @@ def read_file(self, filename=None, return_path=False, clean=False,
 
         If readall is True, use the read_all_ method instead of the read_
         method. Default is False.
-        '''
+        """
         ioobj, path = self.generic_io_object(filename=filename,
                                              return_path=True, clean=clean)
         obj = read_generic(ioobj, target=target, lazy=lazy,
@@ -247,7 +251,7 @@ def read_file(self, filename=None, return_path=False, clean=False,
 
     def write_file(self, obj=None, filename=None, return_path=False,
                    clean=False, target=None):
-        '''
+        """
         Write the target object to a file using the given neo io object ioobj.
 
         If filename is None, create a filename (default).
@@ -266,7 +270,7 @@ def write_file(self, obj=None, filename=None, return_path=False,
 
         obj is the object to write.  If obj is None, an object is created
         automatically for the io class.
-        '''
+        """
         ioobj, path = self.generic_io_object(filename=filename,
                                              return_path=True, clean=clean)
         obj = write_generic(ioobj, target=target, return_reader=False)
@@ -276,15 +280,15 @@ def write_file(self, obj=None, filename=None, return_path=False,
         return obj
 
     def iter_io_objects(self, return_path=False, clean=False):
-        '''
+        """
         Return an iterable over the io objects created from files_to_test
 
         If return_path is True, yield the full path of the file along with
         the io object.  yield ioobj, path  Default is False.
 
         If clean is True, try to delete existing versions of the file
         before creating the io object.  Default is False.
-        '''
+        """
         return iter_generic_io_objects(ioclass=self.ioclass,
                                        filenames=self.files_to_test,
                                        directory=self.local_test_dir,
@@ -293,7 +297,7 @@ def iter_io_objects(self, return_path=False, clean=False):
 
     def iter_readers(self, target=None, readall=False,
                      return_path=False, return_ioobj=False, clean=False):
-        '''
+        """
         Return an iterable over readers created from files_to_test.
 
         If return_path is True, return the full path of the file along with
@@ -310,7 +314,7 @@ def iter_readers(self, target=None, readall=False,
 
         If readall is True, use the read_all_ method instead of the
         read_ method. Default is False.
-        '''
+        """
         return iter_generic_readers(ioclass=self.ioclass,
                                     filenames=self.files_to_test,
                                     directory=self.local_test_dir,
@@ -323,7 +327,7 @@ def iter_readers(self, target=None, readall=False,
     def iter_objects(self, target=None, return_path=False, return_ioobj=False,
                      return_reader=False, clean=False, readall=False,
                      lazy=False):
-        '''
+        """
         Iterate over objects read from the list of filenames in files_to_test.
 
         If target is None, use the first supported_objects from ioobj
@@ -351,7 +355,7 @@ def iter_objects(self, target=None, return_path=False, return_ioobj=False,
 
         If readall is True, use the read_all_ method instead of the read_
         method. Default is False.
-        '''
+        """
         return iter_read_objects(ioclass=self.ioclass,
                                  filenames=self.files_to_test,
                                  directory=self.local_test_dir,
@@ -427,26 +431,26 @@ def test_write_then_read(self):
         close_object_safe(ioobj2)
 
     def test_read_then_write(self):
-        '''
+        """
         Test for IO that are able to read and write, here %s:
          1 - Read a file
          2 Write object set in another file
          3 Compare the 2 files hash
 
         NOTE: TODO: Not implemented yet
-        ''' % self.ioclass.__name__
+        """ % self.ioclass.__name__
 
         if not self.able_to_write_or_read(readwrite=True):
             return
             # assert_file_contents_equal(a, b)
 
-    def test_assert_readed_neo_object_is_compliant(self):
-        '''
+    def test_assert_read_neo_object_is_compliant(self):
+        """
         Reading %s files in `files_to_test` produces compliant objects.
 
         Compliance test: neo.test.tools.assert_neo_object_is_compliant for
         lazy mode.
-        ''' % self.ioclass.__name__
+        """ % self.ioclass.__name__
         for obj, path in self.iter_objects(lazy=False, return_path=True):
             try:
                 # Check compliance of the block
@@ -456,14 +460,14 @@ def test_assert_readed_neo_object_is_compliant(self):
                 exc.args += ('from %s' % os.path.basename(path), )
                 raise
 
-    def test_readed_with_lazy_is_compliant(self):
-        '''
+    def test_read_with_lazy_is_compliant(self):
+        """
         Reading %s files in `files_to_test` with `lazy` is compliant.
 
         Test the reader with lazy = True.
         The schema must contain proxy objects.
 
-        ''' % self.ioclass.__name__
+        """ % self.ioclass.__name__
         # This is for files presents at G-Node or generated
         if self.ioclass.support_lazy:
             for obj, path in self.iter_objects(lazy=True, return_path=True):