3. Classes

3.1. Available Classes

There are two fundamental classes available, the Bit and the Byte.

There are 24 other classes available, representing all the prefix units from k through e (kilo/kibi through exa/exbi).

Classes with ‘i’ in their names are NIST type classes. They were defined by the National Institute of Standards and Technology (NIST) as the ‘Binary Prefix Units’. They are defined by increasing powers of 2.

Classes without the ‘i’ character are SI type classes. Though not formally defined by any standards organization, they follow the International System of Units (SI) pattern (commonly used to abbreviate base 10 values). You may hear these referred to as the “Decimal” or “SI” prefixes.

Classes ending with lower-case ‘b’ characters are bit based. Classes ending with upper-case ‘B’ characters are byte based. Class inheritance is shown below in parentheses to make this more apparent:

NIST	SI
Eib(Bit)	Eb(Bit)
EiB(Byte)	EB(Byte)
Gib(Bit)	Gb(Bit)
GiB(Byte)	GB(Byte)
Kib(Bit)	kb(Bit)
KiB(Byte)	kB(Byte)
Mib(Bit)	Mb(Bit)
MiB(Byte)	MB(Byte)
Pib(Bit)	Pb(Bit)
PiB(Byte)	PB(Byte)
Tib(Bit)	Tb(Bit)
TiB(Byte)	TB(Byte)

Note

As per SI definition, the kB and kb classes begins with a lower-case k character.

The majority of the functionality of bitmath object comes from their rich implementation of standard Python operations. You can use bitmath objects in almost all of the places you would normally use an integer or a float. See the Table of Supported Operations and Appendix: Rules for Math for more details.

3.2. Initializing

class bitmath.Bit([value=0[, bytes=None[, bits=None]]])

class bitmath.Byte([value=0[, bytes=None[, bits=None]]])

class bitmath.EB([value=0[, bytes=None[, bits=None]]])

class bitmath.Eb([value=0[, bytes=None[, bits=None]]])

class bitmath.EiB([value=0[, bytes=None[, bits=None]]])

class bitmath.Eib([value=0[, bytes=None[, bits=None]]])

class bitmath.GB([value=0[, bytes=None[, bits=None]]])

class bitmath.Gb([value=0[, bytes=None[, bits=None]]])

class bitmath.GiB([value=0[, bytes=None[, bits=None]]])

class bitmath.Gib([value=0[, bytes=None[, bits=None]]])

class bitmath.kB([value=0[, bytes=None[, bits=None]]])

class bitmath.kb([value=0[, bytes=None[, bits=None]]])

class bitmath.KiB([value=0[, bytes=None[, bits=None]]])

class bitmath.Kib([value=0[, bytes=None[, bits=None]]])

class bitmath.MB([value=0[, bytes=None[, bits=None]]])

class bitmath.Mb([value=0[, bytes=None[, bits=None]]])

class bitmath.MiB([value=0[, bytes=None[, bits=None]]])

class bitmath.Mib([value=0[, bytes=None[, bits=None]]])

class bitmath.PB([value=0[, bytes=None[, bits=None]]])

class bitmath.Pb([value=0[, bytes=None[, bits=None]]])

class bitmath.PiB([value=0[, bytes=None[, bits=None]]])

class bitmath.Pib([value=0[, bytes=None[, bits=None]]])

class bitmath.TB([value=0[, bytes=None[, bits=None]]])

class bitmath.Tb([value=0[, bytes=None[, bits=None]]])

class bitmath.TiB([value=0[, bytes=None[, bits=None]]])

class bitmath.Tib([value=0[, bytes=None[, bits=None]]])

class bitmath.YB([value=0[, bytes=None[, bits=None]]])

class bitmath.Yb([value=0[, bytes=None[, bits=None]]])

class bitmath.ZB([value=0[, bytes=None[, bits=None]]])

class bitmath.Zb([value=0[, bytes=None[, bits=None]]])

class bitmath.Bitmath([value=0[, bytes=None[, bits=None]]])

The value, bytes, and bits parameters are mutually exclusive. That is to say, you cannot instantiate a bitmath class using more than one of the parameters. Omitting any keyword argument defaults to behaving as if value was provided.

Parameters:

• value (int) – Default: 0. The value of the instance in prefix units. For example, if we were instantiating a bitmath.KiB object to represent 13.37 KiB, the value parameter would be 13.37. For instance, k = bitmath.KiB(13.37).
• bytes (int) – The value of the instance as measured in bytes.
• bits (int) – The value of the instance as measured in bits.

Raises:

ValueError – if more than one parameter is provided.

The following code block demonstrates the 4 acceptable ways to instantiate a bitmath class.

>>> import bitmath

# Omitting all keyword arguments defaults to 'value' behavior.
>>> a = bitmath.KiB(1)

# This is equivalent to the previous statement
>>> b = bitmath.KiB(value=1)

# We can also specify the initial value in bytes.
# Recall, 1KiB = 1024 bytes
>>> c = bitmath.KiB(bytes=1024)

# Finally, we can specify exact number of bits in the
# instance. Recall, 1024B = 8192b
>>> d = bitmath.KiB(bits=8192)

>>> a == b == c == d
True

3.3. Class Methods

3.3.1. Class Method: from_other()

bitmath class objects have one public class method, BitMathClass.from_other() which provides an alternative way to initialize a bitmath class.

This method may be called on bitmath class objects directly. That is to say: you do not need to call this method on an instance of a bitmath class, however that is a valid use case.

classmethod Byte.from_other(item)

Instantiate any BitMathClass using another instance as reference for it’s initial value.

The from_other() class method has one required parameter: an instance of a bitmath class.

Parameters:item (BitMathInstance) – An instance of a bitmath class. Returns:a bitmath instance of type BitMathClass equivalent in value to item Return type:BitMathClass Raises:TypeError – if item is not a valid bitmath class

In pure Python, this could also be written as:

>>> import bitmath

>>> a_mebibyte = bitmath.MiB(1)

>>> a_mebibyte_sized_kibibyte = bitmath.KiB(bytes=a_mebibyte.bytes)

>>> a_mebibyte == a_mebibyte_sized_kibibyte
True

>>> print a_mebibyte, a_mebibyte_sized_kibibyte
1.0 MiB 1024.0 KiB

Or, using the BitMathClass.from_other() class method:

>>> a_mebibyte = bitmath.MiB(1)

>>> a_big_kibibyte = bitmath.KiB.from_other(a_mebibyte)

>>> a_mebibyte == a_big_kibibyte
True

>>> print a_mebibyte, a_big_kibibyte
1.0 MiB 1024.0 KiB