philiprehberger-filesize 0.4.0

Convert bytes to human-readable file sizes and back.

philiprehberger-filesize

Convert bytes to human-readable file sizes and back.

Installation

pip install philiprehberger-filesize

Usage

from philiprehberger_filesize import humanize, parse, is_larger_than

humanize(1536)                  # "1.5 KB"
humanize(1073741824)            # "1.0 GB"
humanize(1024, binary=True)     # "1.0 KiB"

parse("1.5 GB")                 # 1500000000
parse("1 KiB")                  # 1024

is_larger_than(5000000, "1 MB") # True

Convert to a specific unit

to_unit(size, unit) returns a float in the requested unit. Useful for arithmetic when a formatted string would not do.

from philiprehberger_filesize import to_unit

to_unit(1500, "KB")         # 1.5
to_unit(1024 ** 2, "MiB")   # 1.0
to_unit(2_500_000, "MB")    # 2.5

Convert from a unit to bytes

from_unit(value, unit) is the inverse of to_unit: it converts a numeric value in a named unit to bytes.

from philiprehberger_filesize import from_unit

from_unit(1.5, "MB")        # 1_500_000
from_unit(2, "KiB")         # 2048
from_unit(1, "GB")          # 1_000_000_000

Size constants

Exported integer constants for use as multipliers in code:

from philiprehberger_filesize import KB, MB, GB, MIB, GIB, humanize

threshold = 5 * MB
humanize(threshold)             # "5.0 MB"
humanize(2 * GIB, binary=True)  # "2.0 GiB"

Available: BYTES, KB, MB, GB, TB, KIB, MIB, GIB, TIB.

Summing and comparing sizes

total(*sizes) accepts any mix of integer byte counts and human-readable strings, parses the strings via parse(), and returns the sum. compare(a, b) returns -1, 0, or 1 after parsing each operand — useful for sorting mixed int/str size values.

from philiprehberger_filesize import total, compare

total(1024, "1 KB", "2 MB")     # 2_001_024
total()                         # 0

compare(100, 200)               # -1
compare("1 KiB", 1024)          # 0
compare("1 MB", "1 KB")         # 1

sizes = ["10 KB", "1 MB", 500]
sorted(sizes, key=lambda s: compare(s, 0))
# [500, '10 KB', '1 MB']

API

Function / Class	Description
humanize(size, binary=False, precision=1)	Bytes to human string
format_bytes(size, binary=False, precision=2)	Alias with precision=2
parse(text)	Human string to bytes
to_unit(size, unit)	Convert bytes to a specific unit, returning a float
from_unit(value, unit)	Convert a value in a named unit to bytes (inverse of to_unit)
is_larger_than(size, threshold)	Compare size to human string
total(*sizes)	Sum mixed int/string sizes into bytes
compare(a, b)	Return -1/0/1 after parsing both operands
BYTES, KB, MB, GB, TB	SI multiplier constants (1000-based)
KIB, MIB, GIB, TIB	Binary multiplier constants (1024-based)

Development

pip install -e .
python -m pytest tests/ -v

Support

If you find this project useful:

⭐ Star the repo

🐛 Report issues

💡 Suggest features

❤️ Sponsor development

🌐 All Open Source Projects

💻 GitHub Profile

🔗 LinkedIn Profile

License

MIT