Fix best_prefix() to preserve unit family; closes #95

Bit-family instances (Bit, Kib, Mib, kb, Mb, etc.) now always return
a Bit-family result from best_prefix(). Previously the conversion
method name was built with a hardcoded 'B' suffix, so e.g.
Bit(30950093).best_prefix() returned MiB instead of Mib.

Changes:
- Replace 'type(self) is Byte' exact-type check with isinstance(self, Byte),
  removing the pylint unidiomatic-typecheck suppression
- At _index == 0 (below the first prefix threshold), Bit-family inputs
  now return Bit.from_other(self) rather than Byte, preserving family
  consistency down to the floor
- Conversion method name now uses 'b' suffix for Bit-family and 'B'
  suffix for Byte-family inputs
- Updated best_prefix() docstring with revised index-0 rule and a
  versionchanged:: 2.0.0 note
- Updated test_bit_round_up to document the new family-preserving
  behaviour (Bit(16).best_prefix() -> Bit, not Byte)

Author: timlnx

bitmath/__init__.py

@@ -379,7 +379,7 @@ def from_other(cls, item):
     ######################################################################
     # The following implement the Python datamodel customization methods
     #
-    # Reference: http://docs.python.org/2.7/reference/datamodel.html#basic-customization
+    # Reference: https://docs.python.org/3/reference/datamodel.html#basic-customization
 
     def __repr__(self):
         """Representation of this object as you would expect to see in an
@@ -430,7 +430,8 @@ def best_prefix(self, system=None):
 Else, begin by recording the unit system the instance is defined
 by. This determines which steps (NIST_STEPS/SI_STEPS) we iterate over.
 
-If the instance is not already a ``Byte`` instance, convert it to one.
+If the instance is not already a ``Byte`` instance, convert it to one
+for the purpose of the log calculation.
 
 NIST units step up by powers of 1024, SI units step up by powers of
 1000.
@@ -444,18 +445,28 @@ def best_prefix(self, system=None):
 This will return a value >= 0. The following determines the 'best
 prefix unit' for representation:
 
-* result == 0, best represented as a Byte
+* result == 0, best represented as a Byte (or Bit for Bit-family inputs)
 * result >= len(SYSTEM_STEPS), best represented as an Exbi/Exabyte
 * 0 < result < len(SYSTEM_STEPS), best represented as SYSTEM_PREFIXES[result-1]
 
+Unit family is preserved: Bit-family instances (Bit, Kib, Mib, kb,
+Mb, etc.) always return a Bit-family result. Byte-family instances
+always return a Byte-family result.
+
+.. versionchanged:: 2.0.0
+   Bit-family instances now return Bit-family results. Previously,
+   ``best_prefix()`` always returned a Byte-family unit regardless of
+   the input type (e.g. ``Bit(30950093).best_prefix()`` returned
+   ``MiB`` instead of ``Mib``). See GitHub issue #95.
+
         """
 
         # Use absolute value so we don't return Bit's for *everything*
         # less than Byte(1). From github issue #55
         if abs(self) < Byte(1):
             return Bit.from_other(self)
         else:
-            if type(self) is Byte:  # pylint: disable=unidiomatic-typecheck
+            if isinstance(self, Byte):
                 _inst = self
             else:
                 _inst = Byte.from_other(self)
@@ -491,7 +502,10 @@ def best_prefix(self, system=None):
         # in the list.
 
         if _index == 0:
-            # Already a Byte() type, so return it.
+            # Below the first prefix threshold. Bit-family inputs return as
+            # Bit to preserve family; Byte-family inputs return as Byte.
+            if isinstance(self, Bit):
+                return Bit.from_other(self)
             return _inst
         elif _index >= len(_STEPS):
             # This is a really big number. Use the biggest prefix we've got
@@ -500,9 +514,12 @@ def best_prefix(self, system=None):
             # There is an appropriate prefix unit to represent this
             _best_prefix = _STEPS[_index - 1]
 
-        _conversion_method = getattr(
-            self,
-            'to_%sB' % _best_prefix)
+        # Preserve unit family: Bit-family -> 'to_Xib'/'to_Xb',
+        # Byte-family -> 'to_XiB'/'to_XB'.
+        if isinstance(self, Bit):
+            _conversion_method = getattr(self, 'to_%sb' % _best_prefix)
+        else:
+            _conversion_method = getattr(self, 'to_%sB' % _best_prefix)
 
         return _conversion_method()
 

tests/test_best_prefix_BASE.py

@@ -42,11 +42,15 @@ def test_byte_round_down(self):
         self.assertIs(type(half_byte.best_prefix()), bitmath.Bit)
 
     def test_bit_round_up(self):
-        """best_prefix_base: 2 Bytes (as a Bit()) round up into a Byte()"""
+        """best_prefix_base: 2 Bytes (as a Bit()) stays as Bit() — family preserved
+
+Bit(16) is 2 bytes, below the Kib/kb threshold. There is no sub-kibibit
+prefix unit, so best_prefix returns Bit to preserve the Bit family.
+Prior to 2.0.0 this returned Byte(2).
+"""
         # Two bytes is 16 bits
         two_bytes = bitmath.Bit(bytes=2)
-        # Bit(16) should round up into Byte(2)
-        self.assertIs(type(two_bytes.best_prefix()), bitmath.Byte)
+        self.assertIs(type(two_bytes.best_prefix()), bitmath.Bit)
 
     def test_byte_no_rounding(self):
         """best_prefix_base: 1 Byte (as a Byte()) best prefix is still a Byte()"""