Bytesize is a module for handling parsing, display, and computation with sizes expressed in bytes. Its principle feature is a Size class from which can be constructed Size objects which represent a precise, whole quantity of bytes. Size object can be displayed in a locale-specific manner. Various arithmetic operations are defined for Size objects.
When computing with bytes, the numeric value can be viewed as a logical, rather than a physical, quantity. That is, unlike, e.g., mass or length, which are quantities which must be measured with a measuring instrument which has some built-in imprecision, the number of bytes of memory in RAM, or on a disk, is a quantity that is not measured, but is known precisely. Consequently, computations such as addition of two Sizes, and conversion between different magnitudes of bytes, i.e., from MiB to GiB, must be done precisely. The underlying implementation must therefore use a precise representation of the number of bytes. Floating point numbers, which are frequently the preferred type for the representation of physical quantities, are disallowed by this requirement.
This module does not accomodate multi-dimensionality of byte quantities. Consequently, multiplying one Size object by another Size object will cause an error to be raised, since bytes^2 is not representable by the module. For most uses, and for all uses in blivet from which this module originates, any operation which would yield a multi-dimensional quantity of bytes is not useful. There are no plans to adapt this package so that it can accomodate multi-dimensionality of bytes.
Numerous computations with bytes are nonsensical. For example, 2 raised to a power which is some number of bytes, is a meaningless computation. All such operations cause an error to be raised.
It is not possible to use floating point numbers in computations with Sizes. Where a fractional quantity is desired, use Decimal objects instead of floats. Thus, Size(0) * 1.2 raises an exception, but Size(0) * Decimal(“1.2”) is acceptable.
Sizes are displayed using binary rather than SI prefixes or names, regardless of the value. For example, 1000 bytes is not displayed as 1KB (1 kilobyte), but as some number of bytes or KiB (kibibytes). The precise form in which a Size is displayed is configurable.
The size module supplies a set of named prefixes for both SI and binary units, for all non-fractional prefixes. Fractional prefixes are not defined, since fractional bytes are not of interest.
New Size objects can be constructed from Size objects, numeric values, e.g., int or Decimal, or strings which represent such numeric values. strings may be used to represent fractional quantities, e.g., “1.2”, but floats are disallowed.
The constructor takes an optional units specifier, which defaults to bytes for all numeric values, and to None for Size objects. The type of the unit specifier is a named prefix supplied by the size module. Fractional quantities are rounded down to whole numbers of bytes.
All errors raised by bytesize operations are subtypes of the SizeError class.
If you are interested in computing in Python with physical, rather than logical, quantities, you should consult the pint package: http://pint.readthedocs.org.