[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