ByteSize (jjjermiah/bytesize)

ByteSize

https://github.com/jjjermiah/bytesize
Admin
ByteSize is a Python library that simplifies byte size operations with dynamic unit conversions,...

Tokens:4,493
Snippets:37
Trust Score:7.3
Update:2 months ago
Show doc for...
Context Summary (auto-generated)
Raw
# ByteSize

ByteSize is a Python library that simplifies file size operations, providing dynamic unit conversions between metric (KB, MB, GB) and binary (KiB, MiB, GiB) units, human-readable string parsing, and arithmetic operations on byte sizes. It enables developers to easily parse size strings like "10MB" or "1.5GiB" into raw bytes, convert between different unit systems, and format sizes for display with customizable precision.

The library is lightweight with zero dependencies and extends Python's built-in `int` type, making ByteSize objects fully compatible with standard numeric operations while preserving byte-aware behavior. It supports block-aligned size calculations for filesystem operations, provides intelligent best-fit unit selection for human-readable output, and includes comprehensive error handling with helpful suggestions for unrecognized unit strings.

## Creating ByteSize Objects

Create a ByteSize object from integers (raw bytes) or human-readable strings. The library automatically parses unit suffixes and converts values to bytes internally, while providing best-fit binary unit representation by default.

```python
from bytesize import ByteSize

# Create from integer (raw bytes)
size = ByteSize(1_048_576)
print(size)  # Output: 1.00 MiB

# Create from string with metric unit
size = ByteSize("500MB")
print(size)  # Output: 476.84 MiB
print(size.bytes)  # Output: 500000000

# Create from string with binary unit
size = ByteSize("1.5GiB")
print(size)  # Output: 1.50 GiB
print(size.bytes)  # Output: 1610612736

# Parse large numbers from strings
size = ByteSize("1_073_741_824MB")
print(size)  # Output: 1.00 PiB

# Whitespace is handled automatically
size = ByteSize("   1024B   ")
print(size.bytes)  # Output: 1024
```

## Unit Conversion via Attributes

Access size values in any supported unit using dynamic attribute access. The library supports both abbreviated forms (MB, GiB) and full names (megabytes, gibibytes) for all metric and binary units.

```python
from bytesize import ByteSize

size = ByteSize(1_073_741_824)  # 1 GiB in bytes

# Metric unit conversions
print(size.KB)   # Output: 1073741.824
print(size.MB)   # Output: 1073.741824
print(size.GB)   # Output: 1.073741824
print(size.TB)   # Output: 0.001073741824

# Binary unit conversions
print(size.KiB)  # Output: 1048576.0
print(size.MiB)  # Output: 1024.0
print(size.GiB)  # Output: 1.0
print(size.TiB)  # Output: 0.0009765625

# Full name variants work too
print(size.megabytes)  # Output: 1073.741824
print(size.gibibytes)  # Output: 1.0
print(size.mebibytes)  # Output: 1024.0
```

## Best-Fit Unit Selection

Get the most appropriate metric or binary unit representation for a byte size. The library automatically selects the largest unit that keeps the value below the base threshold (1000 for metric, 1024 for binary).

```python
from bytesize import ByteSize

size = ByteSize(1_234_567)

# Get best-fit metric representation (base-1000)
unit, value = size.readable_metric
print(f"{value:.2f} {unit}")  # Output: 1.23 MB

# Get best-fit binary representation (base-1024)
unit, value = size.readable_binary
print(f"{value:.2f} {unit}")  # Output: 1.18 MiB

# Works across all size ranges
small = ByteSize(500)
print(small.readable_binary)  # Output: ('B', 500.0)

large = ByteSize(1_099_511_627_776)  # 1 TiB
print(large.readable_binary)  # Output: ('TiB', 1.0)
print(large.readable_metric)  # Output: ('TB', 1.099511627776)
```

## String Formatting

Customize output formatting using Python's format specification syntax. Supports precision control, unit selection, and combined format strings for flexible display options.

```python
from bytesize import ByteSize

size = ByteSize(123_456_789)

# Format with precision and specific unit
print(f"{size:.2f:MB}")   # Output: 123.46 MB
print(f"{size:.2f:MiB}")  # Output: 117.74 MiB
print(f"{size:.2f:GiB}")  # Output: 0.11 GiB

# Format with unit only (uses default 2 decimal precision)
print(f"{size:GB}")       # Output: 0.12 GB
print(f"{size:B}")        # Output: 123456789 B

# Format with precision only (auto-selects best binary unit)
print(f"{size:.2f}")      # Output: 117.74 MiB
print(f"{size:.4f}")      # Output: 117.7376 MiB

# Works with format() function too
print(format(size, ".2f:KB"))  # Output: 123456.79 KB

# Default string representation uses .2f with binary units
size = ByteSize(1_000_000)
print(str(size))  # Output: 976.56 KiB
```

## Arithmetic Operations

Perform mathematical operations on ByteSize objects. All arithmetic operations return new ByteSize instances, preserving the byte-aware behavior throughout calculations.

```python
from bytesize import ByteSize

# Addition
size1 = ByteSize("1GB")
size2 = ByteSize("512MB")
total = size1 + size2
print(total)  # Output: 1.41 GiB
print(total.bytes)  # Output: 1512000000

# Subtraction
large = ByteSize("1TB")
small = ByteSize("500GB")
diff = large - small
print(diff)  # Output: 465.66 GiB

# Multiplication
size = ByteSize("100MB")
doubled = size * 2
print(doubled)  # Output: 190.73 MiB
print(doubled.bytes)  # Output: 200000000

# Division
size = ByteSize("1GiB")
half = size / 2
print(half)  # Output: 512.00 MiB

# Floor division
size = ByteSize(2_000_000)
result = size // 3
print(result.bytes)  # Output: 666666

# Chain operations
total_storage = ByteSize("500GB") * 4 + ByteSize("1TB")
print(total_storage)  # Output: 2.73 TiB
```

## Block-Aligned Size Calculation

Calculate the apparent (block-aligned) size for filesystem operations. This rounds up the byte size to the nearest block boundary, which is essential for accurate disk space calculations.

```python
from bytesize import ByteSize

size = ByteSize(123_456_789)

# Align to 4096-byte blocks (common filesystem block size)
aligned = size.apparent_size(4096)
print(aligned.bytes)  # Output: 123457536
print(aligned)  # Output: 117.74 MiB

# Different block sizes
size = ByteSize(1_000_000)
print(size.apparent_size(512).bytes)   # Output: 1000448
print(size.apparent_size(1024).bytes)  # Output: 1000448
print(size.apparent_size(2048).bytes)  # Output: 1001472
print(size.apparent_size(4096).bytes)  # Output: 1003520

# Calculate wasted space due to block alignment
original = ByteSize(1_000_000)
aligned = original.apparent_size(4096)
wasted = aligned - original
print(f"Wasted: {wasted.bytes} bytes")  # Output: Wasted: 3520 bytes
```

## ByteUnit Enum

Access byte unit definitions directly via the ByteUnit enum for low-level unit operations. Each unit has a `factor` attribute representing its multiplier from bytes.

```python
from bytesize import ByteUnit, METRIC_UNITS, BINARY_UNITS

# Access unit factors directly
print(ByteUnit.KB.factor)   # Output: 1000
print(ByteUnit.KiB.factor)  # Output: 1024
print(ByteUnit.MB.factor)   # Output: 1000000
print(ByteUnit.MiB.factor)  # Output: 1048576
print(ByteUnit.GB.factor)   # Output: 1000000000
print(ByteUnit.GiB.factor)  # Output: 1073741824

# Convert string representation
print(str(ByteUnit.MB))   # Output: MB
print(str(ByteUnit.GiB))  # Output: GiB

# Available metric units (base-1000)
for unit in METRIC_UNITS:
    print(f"{unit}: {unit.factor}")
# Output: B: 1, KB: 1000, MB: 1000000, GB: 1000000000, ...

# Available binary units (base-1024)
for unit in BINARY_UNITS:
    print(f"{unit}: {unit.factor}")
# Output: B: 1, KiB: 1024, MiB: 1048576, GiB: 1073741824, ...
```

## Unit Lookup and Suggestions

Look up ByteUnit members by string name and get helpful suggestions for typos. The library provides fuzzy matching to help identify intended units.

```python
from bytesize import lookup_unit, find_closest_match, UnknownUnitError

# Look up units by various names
unit = lookup_unit("MB")
print(unit.factor)  # Output: 1000000

unit = lookup_unit("megabytes")
print(unit.factor)  # Output: 1000000

unit = lookup_unit("GiB")
print(unit.factor)  # Output: 1073741824

unit = lookup_unit("gibibytes")
print(unit.factor)  # Output: 1073741824

# Find closest matches for typos
print(find_closest_match("megabites"))  # Output: megabytes
print(find_closest_match("gibibyte"))   # Output: gibibytes
print(find_closest_match("kilobyte"))   # Output: kilobytes
print(find_closest_match("PIB"))        # Output: PiB

# Handle unknown units gracefully
try:
    lookup_unit("invalid_unit")
except UnknownUnitError as e:
    print(f"Error: {e}")  # Output: Error: No matching byte unit for 'invalid_unit'
```

## Error Handling

The library provides specific exception types for different error conditions, enabling precise error handling in applications.

```python
from bytesize import (
    ByteSize,
    ByteSizeError,
    NegativeByteSizeError,
    UnrecognizedSizeStringError,
    InvalidNumericValueError,
    UnknownUnitError,
)

# Handle negative values
try:
    size = ByteSize(-1000)
except NegativeByteSizeError as e:
    print(f"Error: {e}")  # Output: Error: Byte size cannot be negative: -1000

# Handle unparseable strings
try:
    size = ByteSize("not_a_size")
except UnrecognizedSizeStringError as e:
    print("Could not parse size string")

# Handle unknown units with suggestions
try:
    size = ByteSize("100XX")
except UnknownUnitError as e:
    print(f"Error: {e}")  # Output includes suggestions

# Catch all ByteSize errors with base class
try:
    size = ByteSize("-50MB")
except ByteSizeError as e:
    print(f"ByteSize error: {e}")

# Handle invalid block size
try:
    size = ByteSize(1000)
    aligned = size.apparent_size(0)
except ValueError as e:
    print(f"Error: {e}")  # Output: Error: Block size must be > 0.
```

## Summary

ByteSize is ideal for applications that need to work with file sizes, storage quotas, network bandwidth, or any scenario involving data size calculations. Common use cases include building file managers and storage monitoring tools, implementing upload/download progress displays, calculating disk space requirements with block alignment, parsing user-provided size inputs in configuration files or command-line interfaces, and generating human-readable size reports for logging and analytics.

The library integrates seamlessly with Python's numeric types since ByteSize extends `int`, making it compatible with any code that works with integers while adding size-aware formatting and conversion capabilities. The comprehensive error handling with helpful suggestions makes it user-friendly for applications that accept size input from end users. The zero-dependency design ensures easy deployment and minimal footprint, while the LRU-cached unit lookups provide efficient performance for repeated conversions in high-throughput scenarios.