Metadata-Version: 2.4
Name: philiprehberger-filesize
Version: 0.4.0
Summary: Convert bytes to human-readable file sizes and back.
Project-URL: Homepage, https://github.com/philiprehberger/py-filesize#readme
Project-URL: Repository, https://github.com/philiprehberger/py-filesize
Project-URL: Issues, https://github.com/philiprehberger/py-filesize/issues
Project-URL: Changelog, https://github.com/philiprehberger/py-filesize/blob/main/CHANGELOG.md
Author: Philip Rehberger
License-Expression: MIT
License-File: LICENSE
Keywords: bytes,filesize,format,human-readable,size
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# philiprehberger-filesize

[![Tests](https://github.com/philiprehberger/py-filesize/actions/workflows/publish.yml/badge.svg)](https://github.com/philiprehberger/py-filesize/actions/workflows/publish.yml)
[![PyPI version](https://img.shields.io/pypi/v/philiprehberger-filesize.svg)](https://pypi.org/project/philiprehberger-filesize/)
[![Last updated](https://img.shields.io/github/last-commit/philiprehberger/py-filesize)](https://github.com/philiprehberger/py-filesize/commits/main)

![philiprehberger-filesize](https://raw.githubusercontent.com/philiprehberger/py-filesize/main/package-card.webp)

Convert bytes to human-readable file sizes and back.

## Installation

```bash
pip install philiprehberger-filesize
```

## Usage

```python
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.

```python
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.

```python
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:

```python
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.

```python
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

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

## Support

If you find this project useful:

⭐ [Star the repo](https://github.com/philiprehberger/py-filesize)

🐛 [Report issues](https://github.com/philiprehberger/py-filesize/issues?q=is%3Aissue+is%3Aopen+label%3Abug)

💡 [Suggest features](https://github.com/philiprehberger/py-filesize/issues?q=is%3Aissue+is%3Aopen+label%3Aenhancement)

❤️ [Sponsor development](https://github.com/sponsors/philiprehberger)

🌐 [All Open Source Projects](https://philiprehberger.com/open-source-packages)

💻 [GitHub Profile](https://github.com/philiprehberger)

🔗 [LinkedIn Profile](https://www.linkedin.com/in/philiprehberger)

## License

[MIT](LICENSE)
