[master 1/1] Document the fact that StorageDevice.format is always a DeviceFormat.

dwlehman installerbot-noreply at redhat.com
Thu Jun 18 15:54:10 UTC 2015


From: David Lehman <dlehman at redhat.com>

StorageDevice.format should never be anything other than an instance
of DeviceFormat or one of its subclasses. All block devices contain data
that is arranged according to some format. The case of empty or
uninitialized or unrecognized formatting is represented by the base class
DeviceFormat.
---
 blivet/devices/storage.py | 32 ++++++++++++++++++++++++++++++--
 1 file changed, 30 insertions(+), 2 deletions(-)

diff --git a/blivet/devices/storage.py b/blivet/devices/storage.py
index cf590cf..2eb2a9a 100644
--- a/blivet/devices/storage.py
+++ b/blivet/devices/storage.py
@@ -29,7 +29,7 @@
 from ..flags import flags
 from ..storage_log import log_method_call
 from .. import udev
-from ..formats import getFormat
+from ..formats import getFormat, DeviceFormat
 from ..size import Size
 
 import logging
@@ -592,9 +592,29 @@ def status(self):
         return os.access(self.path, os.W_OK)
 
     def _setFormat(self, fmt):
-        """ Set the Device's format. """
+        """ Set the Device's format.
+
+            :param fmt: the new format or None
+            :type fmt: :class:`~.formats.DeviceFormat` or NoneType
+
+            A value of None will effectively mark the device as unformatted,
+            but this is accomplished by setting it to an instance of the base
+            :class:`~.formats.DeviceFormat` class.
+
+            .. note::
+                :attr:`format` should always be an instance of
+                :class:`~.formats.DeviceFormat`. To ensure this continues to be
+                the case, all subclasses that define their own :attr:`format`
+                getter should call :meth:`StorageDevice._setFormat` from their
+                getter.
+
+        """
         if not fmt:
             fmt = getFormat(None, device=self.path, exists=self.exists)
+
+        if not isinstance(fmt, DeviceFormat):
+            raise ValueError("format must be a DeviceFormat instance")
+
         log_method_call(self, self.name, type=fmt.type,
                         current=getattr(self._format, "type", None))
         if self._format and self._format.status:
@@ -623,6 +643,14 @@ def _updateNetDevMountOption(self):
             self._format.options = ",".join(option_list)
 
     def _getFormat(self):
+        """ Get the device's format instance.
+
+            .. note::
+                :attr:`format` should always be an instance of
+                :class:`~.formats.DeviceFormat`. Under no circumstances should
+                a programmer directly set :attr:`_format` to any other type.
+
+        """
         return self._format
 
     format = property(lambda d: d._getFormat(),


-- 
To view this commit on github, visit https://github.com/rhinstaller/blivet/commit/1b23b4eb071a1c4d19c5919020480cfa3fd0d00a


More information about the anaconda-patches mailing list