| Name | pybytesize JSON |
| Version |
0.8.0
JSON |
| download |
| home_page | None |
| Summary | Smart, Pythonic, and dynamic: automatic unit selection and conversions made intuitive. |
| upload_time | 2025-02-15 22:00:15 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.10 |
| license | None |
| keywords |
bytesize
pixi
python
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# ByteSize: A Simple Library for Byte Size Operations
ByteSize takes the pain out of data-size conversions—efficiently handle metric/binary units, block alignment, and more, all from a single, Pythonic interface.
[](https://github.com/prefix-dev/pixi)
[](https://github.com/astral-sh/ruff)
[](https://github.com/squidfunk/mkdocs-material)
[](https://codecov.io/github/jjjermiah/ByteSize)
<!--  -->
`ByteSize` is a Python library that simplifies operations with file sizes, offering dynamic unit conversions, string parsing, formatting, and more.
## Features
- Parse human-readable size strings (e.g., `"10MB"`, `"1.5GiB"`) into raw bytes.
- Convert between metric (e.g., `MB`) and binary units (e.g., `MiB`).
- Arithmetic operations while preserving byte units.
- Block-aligned size calculations.
- User-friendly formatting with customizable precision.
- No dependencies, lightweight, and easy to use.
## Installation
Clone the repository and install the package:
```bash
pip install pybytesize
```
## Quickstart Guide
### Creating a `ByteSize` Object
Create a `ByteSize` object from integers or human-readable strings.
By default, string representation will find the most suitable (binary) unit.
```python
>>> from bytesize import ByteSize
>>> size = ByteSize(1_048_576) # From an integer bytes
>>> print(size)
1.00 MiB
>>> size = ByteSize("1_073_741_824MB") # From a string
>>> print(size)
1.00 PiB
```
### Unit Conversion
Access size in different units dynamically.
```python
>>> size1 = ByteSize(1_073_741_824)
>>> print(size1.MB) # Metric:
1.073741824
>>> print(size1.MiB) # Binary
1.00
```
## Advanced Usage
### Block Alignment
Calculate the apparent size with block alignment.
```python
>>> size = ByteSize(123_456_789)
>>> aligned_size = size.apparent_size(4096)
>>> print(aligned_size.bytes)
123457536
```
### Arithmetic with Sizes
Perform addition, subtraction, multiplication, and division.
```python
>>> size3 = ByteSize("1GB") + ByteSize("512MB")
>>> print(size3) # '1.50 GiB'
1.50 GiB
>>> size4 = ByteSize("1TB") - ByteSize("500GB")
>>> print(size4) # '0.50 TiB'
0.50 TiB
```
### Formatting Sizes
Customize formatting for specific units or precision.
```python
>>> size = ByteSize(123_456_789)
>>> print(f"{size:.2f:MB}") # '123.46 MB'
123.46 MB
>>> print(f"{size:.2f:GiB}") # '0.11 GiB'
0.11 GiB
```
Raw data
{
"_id": null,
"home_page": null,
"name": "pybytesize",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": "Jermiah Joseph <jermiahjoseph98@gmail.com>",
"keywords": "bytesize, pixi, python",
"author": null,
"author_email": "Jermiah Joseph <jermiahjoseph98@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/d2/60/e94f13014715ff0ee6e87e8dc600615c9ec6da3a803113378d0c98d7be5b/pybytesize-0.8.0.tar.gz",
"platform": null,
"description": "# ByteSize: A Simple Library for Byte Size Operations\n\nByteSize takes the pain out of data-size conversions\u2014efficiently handle metric/binary units, block alignment, and more, all from a single, Pythonic interface.\n\n[](https://github.com/prefix-dev/pixi)\n[](https://github.com/astral-sh/ruff)\n[](https://github.com/squidfunk/mkdocs-material)\n[](https://codecov.io/github/jjjermiah/ByteSize)\n\n<!--  -->\n\n\n\n\n\n\n\n\n\n\n\n`ByteSize` is a Python library that simplifies operations with file sizes, offering dynamic unit conversions, string parsing, formatting, and more.\n\n## Features\n\n- Parse human-readable size strings (e.g., `\"10MB\"`, `\"1.5GiB\"`) into raw bytes.\n- Convert between metric (e.g., `MB`) and binary units (e.g., `MiB`).\n- Arithmetic operations while preserving byte units.\n- Block-aligned size calculations.\n- User-friendly formatting with customizable precision.\n- No dependencies, lightweight, and easy to use.\n\n## Installation\n\nClone the repository and install the package:\n\n```bash\npip install pybytesize\n```\n\n## Quickstart Guide\n\n### Creating a `ByteSize` Object\n\nCreate a `ByteSize` object from integers or human-readable strings.\n\nBy default, string representation will find the most suitable (binary) unit.\n\n```python\n>>> from bytesize import ByteSize\n\n>>> size = ByteSize(1_048_576) # From an integer bytes \n>>> print(size)\n1.00 MiB\n\n>>> size = ByteSize(\"1_073_741_824MB\") # From a string\n>>> print(size)\n1.00 PiB\n```\n\n### Unit Conversion\n\nAccess size in different units dynamically.\n\n```python\n>>> size1 = ByteSize(1_073_741_824)\n>>> print(size1.MB) # Metric:\n1.073741824\n>>> print(size1.MiB) # Binary\n1.00\n```\n\n## Advanced Usage\n\n### Block Alignment\n\nCalculate the apparent size with block alignment.\n\n```python\n>>> size = ByteSize(123_456_789)\n>>> aligned_size = size.apparent_size(4096)\n>>> print(aligned_size.bytes) \n123457536\n```\n\n### Arithmetic with Sizes\n\nPerform addition, subtraction, multiplication, and division.\n\n```python\n>>> size3 = ByteSize(\"1GB\") + ByteSize(\"512MB\")\n>>> print(size3) # '1.50 GiB'\n1.50 GiB\n\n>>> size4 = ByteSize(\"1TB\") - ByteSize(\"500GB\")\n>>> print(size4) # '0.50 TiB'\n0.50 TiB\n```\n\n### Formatting Sizes\n\nCustomize formatting for specific units or precision.\n\n```python\n>>> size = ByteSize(123_456_789)\n>>> print(f\"{size:.2f:MB}\") # '123.46 MB'\n123.46 MB\n>>> print(f\"{size:.2f:GiB}\") # '0.11 GiB'\n0.11 GiB\n```\n",
"bugtrack_url": null,
"license": null,
"summary": "Smart, Pythonic, and dynamic: automatic unit selection and conversions made intuitive.",
"version": "0.8.0",
"project_urls": {
"changelog": "https://github.com/jjjermiah/ByteSize/blob/main/docs/CHANGELOG.md",
"documentation": "https://jjjermiah.github.io/PyByteSize/",
"homepage": "https://github.com/jjjermiah/ByteSize",
"issues": "https://github.com/jjjermiah/ByteSize/issues",
"repository": "https://github.com/jjjermiah/ByteSize"
},
"split_keywords": [
"bytesize",
" pixi",
" python"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "a0a80ad9658bda17bf09e46e163d2aa47db8163e176f0da81d883aef1b4b4b8c",
"md5": "4eb221a900eb98682e061d353977ae37",
"sha256": "beb7f7fbf6121b4d33326f61faaa084bf44bda8c604a8dbaccf0549daed73982"
},
"downloads": -1,
"filename": "pybytesize-0.8.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "4eb221a900eb98682e061d353977ae37",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 9840,
"upload_time": "2025-02-15T22:00:14",
"upload_time_iso_8601": "2025-02-15T22:00:14.316268Z",
"url": "https://files.pythonhosted.org/packages/a0/a8/0ad9658bda17bf09e46e163d2aa47db8163e176f0da81d883aef1b4b4b8c/pybytesize-0.8.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "d260e94f13014715ff0ee6e87e8dc600615c9ec6da3a803113378d0c98d7be5b",
"md5": "21ae2972d15b1c265eea4da3c3b8e7f3",
"sha256": "230a661b8876394bbfe50cc23c75b7ca370caf0ae6146225fe6ad77cd2866262"
},
"downloads": -1,
"filename": "pybytesize-0.8.0.tar.gz",
"has_sig": false,
"md5_digest": "21ae2972d15b1c265eea4da3c3b8e7f3",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 10204,
"upload_time": "2025-02-15T22:00:15",
"upload_time_iso_8601": "2025-02-15T22:00:15.698674Z",
"url": "https://files.pythonhosted.org/packages/d2/60/e94f13014715ff0ee6e87e8dc600615c9ec6da3a803113378d0c98d7be5b/pybytesize-0.8.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-02-15 22:00:15",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "jjjermiah",
"github_project": "ByteSize",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "pybytesize"
}
