bitmath

Common errors

• ValueError: Input cannot be parsed into a bitmath object.

  cause Attempting to parse a string that does not match a recognized SI or NIST unit format (e.g., '100 MB' or '100 MiB') or providing a non-string input to `bitmath.parse_string()` will raise a ValueError.
  fix Ensure input strings for `bitmath.parse_string()` use standard unit suffixes (e.g., 'GB', 'GiB'). For parsing more flexible or unconventional formats, use `bitmath.parse_string_unsafe()`.

• Installation fails or reports 'pip installs need pip >= 1.1.'

  cause Historical versions of `bitmath` documentation noted a requirement for `pip` version 1.1 or newer. While modern `pip` versions far exceed this, users in very old or constrained Python environments might still encounter issues.
  fix Upgrade your `pip` installation to the latest version using `pip install --upgrade pip`. If a very old `pip` is unavoidable, a workaround historically suggested was to download the `bitmath` tarball from PyPI and install it manually: `pip install bitmath-x.y.z.tar.gz`.

Warnings

• gotcha The `bitmath.format()` context manager is not thread-safe. Using it in a threaded environment may lead to unexpected results or errors. The suggested workaround is to apply formatting to each object instance directly using its `.format()` method.
  Fix: Avoid `bitmath.format()` in multi-threaded contexts; instead, use `instance.format()` directly on `bitmath` objects.
• gotcha `bitmath.parse_string()` is strict and will raise a `ValueError` for non-standard units (e.g., '4.7 G' instead of '4.7 GiB' or '4.7 GB') or non-string inputs. For more lenient parsing of non-standard units, `bitmath.parse_string_unsafe()` is available, but its usage requires careful consideration of potential ambiguities.
  Fix: Ensure input strings conform to standard SI or NIST unit notations (e.g., '100 MiB', '5 GB') when using `bitmath.parse_string()`. If parsing unknown formats, consider `bitmath.parse_string_unsafe()` and review its documentation.
• gotcha `bitmath.query_device_capacity()` requires superuser (root/admin) privileges to make system calls for reading device capacity. It is also only verified to work on Linux and macOS platforms.
  Fix: Run your application with appropriate administrative privileges when using `query_device_capacity()` on Linux/macOS. Be aware of platform limitations.
• gotcha When performing arithmetic operations between `bitmath` types and standard Python number types (integers or floats), the resulting type and behavior can sometimes be unexpected, particularly with bitwise operations. Results may not always align with intuitive unit conversions.
  Fix: Explicitly convert numbers to `bitmath` types before performing operations, or carefully review the documentation for mixed-type operation behaviors.

Install

• pip install bitmath Install stable release

Imports

• MiB

  from bitmath import MiB

• KiB

  from bitmath import KiB

• * (all units)

  from bitmath import *

• parse_string

  import bitmath
  bitmath.parse_string(...)

• getsize

  import bitmath
  bitmath.getsize(...)

Quickstart

Demonstrates how to instantiate bitmath objects, convert between units, perform basic arithmetic, and parse string representations of file sizes.

import bitmath

# Instantiate some bitmath objects
file_size_mib = bitmath.MiB(100) # 100 Mebibytes
network_speed_mb = bitmath.MB(500) # 500 Megabytes

# Convert units
file_size_kib = file_size_mib.to_KiB() # Convert to Kibibytes
print(f"100 MiB is {file_size_kib}")

# Perform arithmetic
total_data = file_size_mib + bitmath.GiB(2)
print(f"100 MiB + 2 GiB = {total_data.best_prefix()}")

# Parse a string
parsed_size = bitmath.parse_string("1.5 TiB")
print(f"Parsed size: {parsed_size}")