[blivet:master] Upgrade the comments in raid.py to be compatible with sphinx.

mulhern amulhern at redhat.com
Tue Dec 17 23:21:40 UTC 2013


Because doing documentation reminded me that RAID was an initialism
changed some exception messages to use RAID instead of raid and changed
some tests to match.

Signed-off-by: mulhern <amulhern at redhat.com>
---
 blivet/devicelibs/raid.py          | 121 +++++++++++++++++++++++++++----------
 tests/devicefactory_test.py        |   6 +-
 tests/devicelibs_test/raid_test.py |   6 +-
 tests/devices_test.py              |  12 ++--
 4 files changed, 102 insertions(+), 43 deletions(-)

diff --git a/blivet/devicelibs/raid.py b/blivet/devicelibs/raid.py
index b55804c..941f02d 100644
--- a/blivet/devicelibs/raid.py
+++ b/blivet/devicelibs/raid.py
@@ -26,33 +26,44 @@ import abc
 from ..errors import RaidError
 
 def div_up(a,b):
-    """Rounds up integer division."""
-    return (a + (b - 1))/b
+    """Rounds up integer division.  For example, div_up(3, 2) is 2.
 
-class RAIDLevel(object):
+       :param int a: the dividend
+       :param int b: the divisor
+    """
+    return (a + (b - 1))//b
 
-    __metaclass__ = abc.ABCMeta
+class RAIDLevel(object):
 
     """An abstract class which is the parent of classes which represent a
        RAID level. A better word would be classification, since 'level'
        implies an ordering, but level is the canonical word.
 
        The abstract properties of the class are:
-         level --- A string containing the number that designates this level
-         min_members --- The minimum number of members required for this
+
+       - level: A string containing the number that designates this level
+
+       - min_members: The minimum number of members required for this
            level to be sensibly used.
-         nick --- A single nickname for this level, may be None
+
+       - nick: A single nickname for this level, may be None
 
         All methods in this class fall into these categories:
+
         1) May not be overrridden in any subclass.
+
         2) Are private abstract methods.
+
         3) Are special Python methods, e.g., __str__
 
+
         Note that each subclass in this file is instantiated immediately after
         it is defined and using the same name, effectively yielding a
         singleton object of the class.
     """
 
+    __metaclass__ = abc.ABCMeta
+
     # ABSTRACT PROPERTIES
     level = abc.abstractproperty(lambda s: None,
        doc="A code representing the level")
@@ -79,8 +90,13 @@ class RAIDLevel(object):
 
     # METHODS
     def get_max_spares(self, member_count):
-        """Return the maximum number of spares for this level given
-           member_count participating members.
+        """The maximum number of spares for this level.
+
+           :param int member_count: the number of members belonging to the array
+           :rtype: int
+
+           Raiess a RaidError if member_count is fewer than the minimum
+           number of members required for this level.
         """
         if member_count < self.min_members:
             raise RaidError("%s requires at least %d disks" % (self.name, self.min_members))
@@ -92,15 +108,18 @@ class RAIDLevel(object):
         raise NotImplementedError()
 
     def get_base_member_size(self, size, member_count):
-        """Return the required size for each member of the array for
+        """The required size for each member of the array for
            storing only data.
-           :param size: size of data to be stored
-           :type size: natural number
 
-           :param member_count: number of members in this array
-           :param member_count: int
+           :param int size: size of data to be stored
+           :param int member_count: number of members in this array
+           :rtype: int
 
            The return value has the same units as the size parameter.
+
+           Raises a RaidError if member_count is fewer than the minimum
+           number of members required for this array or if size is less
+           than 0.
         """
         if member_count < self.min_members:
             raise RaidError("%s requires at least %d disks" % (self.name, self.min_members))
@@ -114,16 +133,20 @@ class RAIDLevel(object):
         raise NotImplementedError()
 
     def get_raw_array_size(self, member_count, smallest_member_size):
-        """Calculate the raw arraysize, i.e., the number of MB available.
+        """Return the raw arraysize.
 
-           :param member_count: the number of members in the array
-           :param type: int
-           :param smallest_member_size: the size (MB) of the smallest
+           :param int member_count: the number of members in the array
+           :param int smallest_member_size: the size of the smallest
              member of this array
-           :param type: int
+           :rtype: int
 
            The return value has the same units as the smallest_member_size
            parameter.
+
+           Raises a RaidError if member_count is fewer than the minimum
+           number of members required for this array or if size is less
+           than 0.
+
         """
         if member_count < self.min_members:
             raise RaidError("%s requires at least %d disks" % (self.name, self.min_members))
@@ -137,6 +160,13 @@ class RAIDLevel(object):
         raise NotImplementedError()
 
     def get_size(self, member_count, smallest_member_size, chunk_size):
+        """
+           :param int member_count: the number of members in the array
+           :param int smallest_member_size: the size of the smallest
+             member of this array
+           :param int chunk_size: the smallest size this array allows
+           :rtype: int
+        """
         size = self.get_raw_array_size(member_count, smallest_member_size)
         return self._get_size(size, chunk_size)
 
@@ -146,8 +176,15 @@ class RAIDLevel(object):
         raise NotImplementedError()
 
     def get_recommended_stride(self, member_count):
-        """Get a recommended stride size in blocks. Returns None if there
-           is no recommended size.
+        """Return a recommended stride size in blocks.
+
+           Returns None if there is no recommended size.
+
+           :param int member_count: the number of members in the array
+           :rtype: int or None
+
+           Raises a RaidError if member_count is fewer than the
+           minimum number of members required for this level
         """
         if member_count < self.min_members:
             raise RaidError("%s requires at least %d disks" % (self.name, self.min_members))
@@ -171,6 +208,10 @@ class RAIDLevels(object):
 
     def __init__(self, levels=True):
         """Add the specified standard levels to the levels in this object.
+
+           :param levels: the standard levels to be added to this object
+           :type levels: bool or a list of valid RAID level descriptors
+
            If levels is True, add all standard levels. Else, levels
            must be a list of valid level descriptors of standard levels.
            Duplicate descriptors are ignored.
@@ -186,7 +227,7 @@ class RAIDLevels(object):
                 for level in levels:
                     matches = [l for l in self.standard_levels if level in l.names]
                     if len(matches) != 1:
-                        raise RaidError("invalid standard raid level descriptor %s" % level)
+                        raise RaidError("invalid standard RAID level descriptor %s" % level)
                     else:
                         self.addRaidLevel(matches[0])
             except TypeError:
@@ -196,18 +237,20 @@ class RAIDLevels(object):
     _standard_levels = []
 
     standard_levels = property(lambda s: s._standard_levels,
-       doc="any standard raid level classes defined in this package.")
+       doc="any standard RAID level classes defined in this package.")
 
     @classmethod
     def isRaidLevel(cls, level):
         """Return False if level does not satisfy minimum requirements for
-           a RAID level.
+           a RAID level, otherwise return True.
+
+           :param object level: an object representing a RAID level
 
            There must be at least one element in the names list, or the level
            will be impossible to look up by any string.
 
-           The name must be defined; it should be one of the elements in the
-           names list.
+           The name property must be defined; it should be one of the
+           elements in the names list.
 
            All RAID objects in standard_levels are guaranteed to pass these
            minimum requirements.
@@ -227,8 +270,15 @@ class RAIDLevels(object):
 
     @classmethod
     def addRAIDLevelToStandardLevels(cls, level):
-        """Adds this raid level to the internal list of standard raid levels
+        """Adds this RAID level to the internal list of standard RAID levels
            defined in this package.
+
+           :param level: an object representing a RAID level
+           :type level: object
+
+           Raises a RaidError if level is not a valid RAID level.
+
+           Does not allow duplicate level objects.
         """
         if not cls.isRaidLevel(level):
             raise RaidError('level is not a valid RAID level')
@@ -236,17 +286,26 @@ class RAIDLevels(object):
             cls._standard_levels.append(level)
 
     def raidLevel(self, descriptor):
-        """Return raid object corresponding to descriptor. Raises RaidError
-           if no raid object can be found for this descriptor.
+        """Return raid object corresponding to descriptor.
+
+           :param any descriptor: a RAID level descriptor
+
+           Raises a RaidError if no raid object can be found for this
+           descriptor.
         """
         for level in self._raid_levels:
             if descriptor in level.names:
                 return level
-        raise RaidError("invalid raid level descriptor %s" % descriptor)
+        raise RaidError("invalid RAID level descriptor %s" % descriptor)
 
     def addRaidLevel(self, level):
         """Adds level to the list of levels if it is not already there.
-           Raises a RaidError if it is not a valid level.
+
+           :param object level: an object representing a RAID level
+
+           Raises a RaidError if level is not valid.
+
+           Does not allow duplicate level objects.
         """
         if not self.isRaidLevel(level):
             raise RaidError("level is not a valid RAID level")
diff --git a/tests/devicefactory_test.py b/tests/devicefactory_test.py
index 081a48d..dd878ce 100644
--- a/tests/devicefactory_test.py
+++ b/tests/devicefactory_test.py
@@ -28,11 +28,11 @@ class MDFactoryTestCase(unittest.TestCase):
 
     def testMDFactory(self):
         self.assertRaisesRegexp(mdraid.MDRaidError,
-           "invalid raid level",
+           "invalid RAID level",
            self.factory1._get_device_space)
 
         self.assertRaisesRegexp(mdraid.MDRaidError,
-           "invalid raid level",
+           "invalid RAID level",
            self.factory1._set_raid_level)
 
         self.assertEqual(self.factory1.container_list, [])
@@ -40,7 +40,7 @@ class MDFactoryTestCase(unittest.TestCase):
         self.assertIsNone(self.factory1.get_container())
 
         self.assertRaisesRegexp(mdraid.MDRaidError,
-           "invalid raid level",
+           "invalid RAID level",
            self.factory1._get_new_device,
            parents=[])
 
diff --git a/tests/devicelibs_test/raid_test.py b/tests/devicelibs_test/raid_test.py
index 84bf94a..424e5f2 100644
--- a/tests/devicelibs_test/raid_test.py
+++ b/tests/devicelibs_test/raid_test.py
@@ -109,15 +109,15 @@ class RaidTestCase(unittest.TestCase):
         ## __init__
         ##
         self.assertRaisesRegexp(errors.RaidError,
-                                "invalid raid level",
+                                "invalid RAID level",
                                 self.levels_none.raidLevel, 10)
 
         self.assertRaisesRegexp(errors.RaidError,
-                                "invalid raid level",
+                                "invalid RAID level",
                                 self.levels_some.raidLevel, 10)
 
         self.assertRaisesRegexp(errors.RaidError,
-                                "invalid standard raid level descriptor",
+                                "invalid standard RAID level descriptor",
                                 raid.RAIDLevels, ["raid3.1415"])
 
 def suite():
diff --git a/tests/devices_test.py b/tests/devices_test.py
index 8507e81..ccd1228 100644
--- a/tests/devices_test.py
+++ b/tests/devices_test.py
@@ -352,18 +352,18 @@ class MDRaidArrayDeviceTestCase(DeviceStateTestCase):
                         totalDevices=lambda x, m: self.assertEqual(x, 5, m))
 
         self.assertRaisesRegexp(mdraid.MDRaidError,
-                                "invalid raid level",
+                                "invalid RAID level",
                                 MDRaidArrayDevice,
                                 "dev")
 
         self.assertRaisesRegexp(mdraid.MDRaidError,
-                                "invalid raid level",
+                                "invalid RAID level",
                                 MDRaidArrayDevice,
                                 "dev",
                                 level="raid2")
 
         self.assertRaisesRegexp(mdraid.MDRaidError,
-                                "invalid raid level",
+                                "invalid RAID level",
                                 MDRaidArrayDevice,
                                 "dev",
                                 parents=[Device("parent")])
@@ -376,7 +376,7 @@ class MDRaidArrayDeviceTestCase(DeviceStateTestCase):
                                 parents=[Device("parent")])
 
         self.assertRaisesRegexp(mdraid.MDRaidError,
-                                "invalid raid level descriptor junk",
+                                "invalid RAID level descriptor junk",
                                 MDRaidArrayDevice,
                                 "dev",
                                 level="junk")
@@ -391,10 +391,10 @@ class MDRaidArrayDeviceTestCase(DeviceStateTestCase):
 
     def testMDRaidArrayDeviceMethods(self, *args, **kwargs):
         """Test for method calls on initialized MDRaidDevices."""
-        with self.assertRaisesRegexp(mdraid.MDRaidError, "invalid raid level" ):
+        with self.assertRaisesRegexp(mdraid.MDRaidError, "invalid RAID level" ):
             self.dev7.level = "junk"
 
-        with self.assertRaisesRegexp(mdraid.MDRaidError, "invalid raid level" ):
+        with self.assertRaisesRegexp(mdraid.MDRaidError, "invalid RAID level" ):
             self.dev7.level = None
 
 class BTRFSDeviceTestCase(DeviceStateTestCase):
-- 
1.8.3.1



More information about the anaconda-patches mailing list