4. Instances

4.1. Instance Attributes

bitmath objects have several instance attributes:

BitMathInstance.base

The mathematical base of the unit of the instance (this will be 2 or 10)

>>> print(bitmath.Byte(1337).base)
2
>>> print(bitmath.kB(1337).base)
10
BitMathInstance.binary

The Python binary representation of the instance’s value (in bits)

>>> b = bitmath.Byte(1337)
>>> print(b.binary)
0b10100111001000
BitMathInstance.bin

This is an alias for binary

BitMathInstance.bits

The number of bits in the object, as a floating-point value.

>>> b = bitmath.Byte(1337)
>>> print(b.bits)
10696.0

Note

Bit values are always floating-point. A whole-number input like Byte(1337) produces an exact float (10696.0), but inputs involving division or fractional bytes will produce fractional bit counts. Use int(instance.bits) or math.floor() to obtain an integer when needed. See Rules for Math for the design rationale behind floating-point values.

BitMathInstance.bytes

The number of bytes in the object, as a floating-point value.

>>> b = bitmath.Byte(1337)
>>> print(b.bytes)
1337.0
BitMathInstance.power

The mathematical power the base of the unit of the instance is raised to

>>> b = bitmath.Byte(1337)
>>> print(b.power)
0
BitMathInstance.system

The system of units used to measure this instance (NIST or SI)

>>> b = bitmath.Byte(1337)
>>> print(b.system)
NIST
BitMathInstance.value

The value of the instance in prefix units1

>>> b = bitmath.Byte(1337)
>>> print(b.value)
1337.0
BitMathInstance.unit

The string representation of this prefix unit (such as MiB or kb)

>>> b = bitmath.Byte(1337)
>>> print(b.unit)
B
BitMathInstance.unit_plural

The pluralized string representation of this prefix unit.

>>> b = bitmath.Byte(1337)
>>> print(b.unit_plural)
B
BitMathInstance.unit_singular

The singular string representation of this prefix unit (such as MiB or kb)

>>> b = bitmath.Byte(1337)
>>> print(b.unit_singular)
B

Notes:

  1. Given an instance k, where k = KiB(1.3), then k.value is 1.3

The following is an example of how to access some of these attributes and what you can expect their printed representation to look like:

 1>>> dvd_capacity = GB(4.7)
 2>>> print("Capacity in bits: %s\nbytes: %s\n" % \
 3             (dvd_capacity.bits, dvd_capacity.bytes))
 4
 5Capacity in bits: 37600000000.0
 6bytes: 4700000000.0
 7
 8>>> dvd_capacity.value
 94.7
10
11>>> dvd_capacity.bin
12'0b100011000001001000100111100000000000'
13
14>>> dvd_capacity.binary
15'0b100011000001001000100111100000000000'

4.2. Instance Methods

bitmath objects come with a few basic methods: to_THING(), format(), and best_prefix().

4.2.1. to_THING()

Like the available classes, there are 32 to_THING() methods available. THING is any of the bitmath classes. You can even to_THING() an instance into itself again:

 1>>> from bitmath import *
 2>>> one_mib = MiB(1)
 3>>> one_mib_in_kb = one_mib.to_kb()
 4>>> one_mib == one_mib_in_kb
 5True
 6
 7>>> another_mib = one_mib.to_MiB()
 8>>> print(one_mib, one_mib_in_kb, another_mib)
 91.0 MiB 8388.608 kb 1.0 MiB
10
11>>> six_TB = TB(6)
12>>> six_TB_in_bits = six_TB.to_Bit()
13>>> print(six_TB, six_TB_in_bits)
146.0 TB 4.8e+13 b
15
16>>> six_TB == six_TB_in_bits
17True

4.2.2. best_prefix()

best_prefix([system=None])

Return an equivalent instance which uses the best human-readable prefix-unit to represent it.

Parameters:

system (int) – one of bitmath.NIST or bitmath.SI

Returns:

An equivalent bitmath instance

Return type:

bitmath

Raises:

ValueError – if an invalid unit system is given for system

The best_prefix() method returns the result of converting a bitmath instance into an equivalent instance using a prefix unit that better represents the original value. Another way to think of this is automatic discovery of the most sane, or human readable, unit to represent a given size. This functionality is especially important in the domain of interactive applications which need to report file sizes or transfer rates to users.

As an analog, consider you have 923,874,434¢ in your bank account. You probably wouldn’t want to read your bank statement and find your balance in pennies. Most likely, your bank statement would read a balance of $9,238,744.34. In this example, the input prefix is the cent: ¢. The best prefix for this is the dollar: $.

Let’s, for example, say we are reporting a transfer rate in an interactive application. It’s important to present this information in an easily consumable format. The library we’re using to calculate the rate of transfer reports the rate in bytes per second from a tx_rate() function.

We’ll use this example twice. In the first occurrence, we will print out the transfer rate in a more easily digestible format than pure bytes/second. In the second occurrence we’ll take it a step further, and use the format method to make the output even easier to read.

>>> for _rate in tx_rate():
...    print("Rate: %s/second" % Bit(_rate))
...    time.sleep(1)

Rate: 100.0 b/sec
Rate: 24000.0 b/sec
Rate: 1024.0 b/sec
Rate: 60151.0 b/sec
Rate: 33.0 b/sec
Rate: 9999.0 b/sec
Rate: 9238742.0 b/sec
Rate: 2.09895849555e+13 b/sec
Rate: 934098021.0 b/sec
Rate: 934894.0 b/sec

And now using a custom formatting definition:

>>> for _rate in tx_rate():
...    print(Bit(_rate).best_prefix().format("Rate: {value:.3f} {unit}/sec"))
...    time.sleep(1)

Rate: 12.500 B/sec
Rate: 2.930 KiB/sec
Rate: 128.000 B/sec
Rate: 7.343 KiB/sec
Rate: 4.125 B/sec
Rate: 1.221 KiB/sec
Rate: 1.101 MiB/sec
Rate: 2.386 TiB/sec
Rate: 111.353 MiB/sec
Rate: 114.123 KiB/sec

4.2.3. format()

BitMathInstance.format(fmt_spec)

Return a custom-formatted string to represent this instance.

Parameters:

fmt_spec (str) – A valid formatting mini-language string

Returns:

The custom formatted representation

Return type:

string

bitmath instances come with a verbose built-in string representation:

>>> leet_bits = Bit(1337)
>>> print(leet_bits)
1337.0 b

However, for instances which aren’t whole numbers (as in MiB(1/3.0) == 0.333333333333 MiB, etc), their representation can be undesirable.

The format() method gives you complete control over the instance’s representation. All of the instances attributes are available to use when choosing a representation.

The following sections describe some common use cases of the format() method as well as provide a brief tutorial of the greater Python formatting meta-language.

4.2.3.1. Setting Decimal Precision

By default, bitmath instances will print to a fairly long precision for values which are not whole multiples of their prefix unit. In most use cases, simply printing out the first 2 or 3 digits of precision is acceptable.

The following examples will show us how to print out a bitmath instance in a more human readable way, by limiting the decimal precision to 2 digits.

First, for reference, the default formatting:

>>> ugly_number = MB(50).to_MiB() / 8.0
>>> print(ugly_number)
5.96046447754 MiB

Now, let’s use the format() method to limit that to two digits of precision:

>>> print(ugly_number.format("{value:.2f}{unit}"))
5.96 MiB

By changing the 2 character, you increase or decrease the precision. Set it to 0 ({value:.0f}) and you have what effectively looks like an integer.

4.2.3.2. Format All the Instance Attributes

The following example prints out every instance attribute. Take note of how an attribute may be referenced multiple times.

 1>>> longer_format = """Formatting attributes for %s
 2   ...: This instances prefix unit is {unit}, which is a {system} type unit
 3   ...: The unit value is {value}
 4   ...: This value can be truncated to just 1 digit of precision: {value:.1f}
 5   ...: In binary this looks like: {binary}
 6   ...: The prefix unit is derived from a base of {base}
 7   ...: Which is raised to the power {power}
 8   ...: There are {bytes} bytes in this instance
 9   ...: The instance is {bits} bits large
10   ...: bytes/bits without trailing decimals: {bytes:.0f}/{bits:.0f}""" % str(ugly_number)
11
12>>> print(ugly_number.format(longer_format))
13Formatting attributes for 5.96046447754 MiB
14This instances prefix unit is MiB, which is a NIST type unit
15The unit value is 5.96046447754
16This value can be truncated to just 1 digit of precision: 6.0
17In binary this looks like: 0b10111110101111000010000000
18The prefix unit is derived from a base of 2
19Which is raised to the power 20
20There are 6250000.0 bytes in this instance
21The instance is 50000000.0 bits large
22bytes/bits without trailing decimals: 6250000/50000000

Note

On line 4 we print with 1 digit of precision, on line 16 we see the value has been rounded to 6.0

4.2.4. Python Format Protocol (f-strings and format())

BitMathInstance.__format__(fmt_spec)

Support Python’s standard string formatting protocol (PEP 3101), enabling bitmath instances to be used directly in f-strings and format() calls.

When fmt_spec is empty, returns str(self) — the same as the default string representation:

>>> size = bitmath.MiB(2.847598437)
>>> f'{size}'
'2.847598437 MiB'

When fmt_spec is a numeric format spec, it is applied to self.value only, returning the formatted number without a unit suffix. The caller controls the surrounding string:

>>> size = bitmath.MiB(2.847598437)
>>> f'{size:.1f} {size.unit}'
'2.8 MiB'

This makes it straightforward to build columnar output with consistent alignment across mixed unit types:

>>> disk_usage = [
...     ("home", bitmath.GiB(127.3)),
...     ("tmp",  bitmath.MiB(843.7)),
...     ("var",  bitmath.GiB(2.1)),
... ]
>>> for mount, size in disk_usage:
...     print(f"{mount:<8} {size:>10.2f} {size.unit}")
home        127.30 GiB
tmp         843.70 MiB
var           2.10 GiB

Any standard Python numeric format spec works: :.2f, :.3e, :.0f, >10.2f, and so on.

Note

The format spec applies to self.value — the numeric quantity in the instance’s current prefix unit. To render a different unit, convert first: size.to_GiB(), then format.

Added in version 2.0.0.

Credit

The original concept and implementation for this feature was contributed by Jonathan Eunice in pull request #76.

4.2.5. Rounding and Integer Conversion

bitmath instances support Python’s standard rounding protocol. math.floor(), math.ceil(), and the built-in round() all return a new bitmath instance of the same type with the prefix value rounded accordingly.

>>> import math, bitmath

>>> math.floor(bitmath.MiB(1.75))
MiB(1)

>>> math.ceil(bitmath.MiB(1.25))
MiB(2)

>>> round(bitmath.GiB(3.7))
GiB(4)

>>> round(bitmath.KiB(1.555), 2)
KiB(1.56)

These methods round the prefix value. To obtain the nearest whole byte count, convert first:

>>> int(bitmath.KiB(1/3).bytes)
341

To obtain the nearest whole bit count:

>>> int(bitmath.KiB(1/3).bits)
2730

Warning

Rounding intermediate results is lossy. math.floor(GiB(10) / 3) * 3 yields GiB(9), not GiB(10). Only round at the final output step, not during calculation.

See also

Rules for Math — design rationale for floating-point values and guidance on when rounding is appropriate.

4.3. Instance Properties

4.3.1. THING Properties

Like the available classes, there are 32 THING properties available. THING is any of the bitmath classes. Under the covers these properties call to_THING.

 1>>> from bitmath import *
 2>>> one_mib = MiB(1)
 3>>> one_mib == one_mib.kb
 4True
 5
 6>>> print(one_mib, one_mib.kb, one_mib.MiB)
 71.0 MiB 8388.608 kb 1.0 MiB
 8
 9>>> six_TB = TB(6)
10>>> print(six_TB, six_TB.Bit)
116.0 TB 4.8e+13 b
12
13>>> six_TB == six_TB.Bit
14True

4.4. The Formatting Mini-Language

That is all you begin printing numbers with custom precision. If you want to learn a little bit more about using the formatting mini-language, read on.

You may be asking yourself where these {value:.2f} and {unit} strings came from. These are part of the Format Specification Mini-Language which is part of the Python standard library. To be explicitly clear about what’s going on here, let’s break the first specifier ({value:.2f}) down into it’s component parts:

{value:.2f}
   |  |||
   |  |||\---- The "f" says to format this as a floating point type
   |  ||\----- The 2 indicates we want 2 digits of precision (default is 6)
   |  |\------ The '.' character must precede the precision specifier for floats
   |  \------- The : separates the attribute name from the formatting specification
   \---------- The name of the attribute to print

The second specifier ({unit}) says to format the unit attribute as a string (string is the default type when no type is given).

See also

Python String Format Cookbook

Marcus Kazmierczak’s excellent introduction to string formatting