sizelib 0.1.0__tar.gz

sizelib-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Saptarshi Roy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

sizelib-0.1.0/PKG-INFO

@@ -0,0 +1,113 @@
+Metadata-Version: 2.4
+Name: sizelib
+Version: 0.1.0
+Summary: A simple, pythonic library for working with and humanizing file sizes.
+Author: Saptarshi Roy
+License-Expression: MIT
+Project-URL: Repository, https://github.com/saptarshiroy39/sizelib
+Project-URL: Homepage, https://pypi.org/project/sizelib
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+<h1 align="center">
+  <img src="./public/sizelib.svg" alt="📄" width="128">
+  <br>
+  <b>sizelib</b>
+</h1>
+
+<p align="center">
+  <a href="https://pypi.org/project/sizelib"><b>sizelib</b></a> is a lightweight, type-safe Python Library for working with and humanizing file sizes. It offers clean, type-preserving size helpers (supporting both `int` and `float`) and loop-based human readable string conversions.
+</p>
+
+<p align="center">
+  <a href="https://pypi.org/project/sizelib"><b>🔗 <code>PyPI Package</code></b></a>
+  &nbsp;|&nbsp;
+  🆔 <code>pip install sizelib</code> or <code>uv add sizelib</code>
+</p>
+
+---
+
+## 🐍 _SDK_
+
+`Installation`
+
+```bash
+pip install sizelib
+# or
+uv add sizelib
+```
+
+`Size Helper Functions`
+
+```python
+from sizelib import size
+
+# Define constraints using binary (base 2 / 1024) or decimal (base 10 / 1000) helper methods
+MAX_UPLOAD_SIZE = size.mib(10)   # 10 MiB (10485760 bytes)
+CACHE_LIMIT = size.gib(2)        # 2 GiB (2147483648 bytes)
+USER_QUOTA = size.gb(50)         # 50 GB (50000000000 bytes)
+
+print(MAX_UPLOAD_SIZE)           # Output: 10485760
+print(type(MAX_UPLOAD_SIZE))     # Output: <class 'int'>
+```
+
+`Humanize Byte Sizes`
+
+```python
+from sizelib import humanize
+
+# Default binary formatting (base 2 / 1024)
+print(humanize(MAX_UPLOAD_SIZE))  # Output: 10 MiB
+print(humanize(CACHE_LIMIT))      # Output: 2 GiB
+
+# Decimal values are formatted up to 2 decimal places
+TOTAL = CACHE_LIMIT + size.mib(500)
+print(humanize(TOTAL))            # Output: 2.49 GiB
+
+# Decimal formatting (base 10 / 1000)
+print(humanize(USER_QUOTA, base=10))  # Output: 50 GB
+```
+
+`Exception Handling`
+
+```python
+from sizelib import FileTooLarge, size, humanize
+
+file_size = size.mib(12)
+
+try:
+    if file_size > MAX_UPLOAD_SIZE:
+        raise FileTooLarge(f"File size exceeds limit of {humanize(MAX_UPLOAD_SIZE)}")
+except FileTooLarge as e:
+    print(e)
+    # Output: File size exceeds limit of 10 MiB
+```
+
+---
+
+## ✨ _Features_
+
+| FEATURE                  | DESCRIPTION                                                                                         |
+| ------------------------ | --------------------------------------------------------------------------------------------------- |
+| 📏 **Unit Helpers**      | Standardized functions for all major divisions (`kb`, `mb`, `gb`, `tb`, `kib`, `mib`, `gib`, `tib`) |
+| 🧪 **Type Preservation** | Dynamically maintains input types (returns int/floats accordingly)                                 |
+| ⚙️ **Custom Bases**      | Support for both binary (`base=2` / 1024) and decimal (`base=10` / 1000) formats                    |
+| 🛡️ **Structured Errors** | Exposes custom `SizeLibError` and `FileTooLarge` exceptions for validation                          |
+| ⚡ **Ultra Minimalism**  | Zero external dependencies with an optimized, lightweight iteration algorithm                       |
+
+---
+
+## 🏗️ _System Architecture_
+
+| #   | COMPONENT          | DESCRIPTION                                                     | STACK        |
+| --- | ------------------ | --------------------------------------------------------------- | ------------ |
+| 1️⃣  | **Sizelib Size**   | The math factor constants and unit calculation helper functions | **_Python_** |
+| 2️⃣  | **Sizelib Format** | The humanization formatting module for readable string units    | **_Python_** |
+
+---
+
+<p align="center">
+  Made with 📄 by <a href="https://hirishi.in">Saptarshi Roy</a>
+</p>

sizelib-0.1.0/README.md

@@ -0,0 +1,100 @@
+<h1 align="center">
+  <img src="./public/sizelib.svg" alt="📄" width="128">
+  <br>
+  <b>sizelib</b>
+</h1>
+
+<p align="center">
+  <a href="https://pypi.org/project/sizelib"><b>sizelib</b></a> is a lightweight, type-safe Python Library for working with and humanizing file sizes. It offers clean, type-preserving size helpers (supporting both `int` and `float`) and loop-based human readable string conversions.
+</p>
+
+<p align="center">
+  <a href="https://pypi.org/project/sizelib"><b>🔗 <code>PyPI Package</code></b></a>
+  &nbsp;|&nbsp;
+  🆔 <code>pip install sizelib</code> or <code>uv add sizelib</code>
+</p>
+
+---
+
+## 🐍 _SDK_
+
+`Installation`
+
+```bash
+pip install sizelib
+# or
+uv add sizelib
+```
+
+`Size Helper Functions`
+
+```python
+from sizelib import size
+
+# Define constraints using binary (base 2 / 1024) or decimal (base 10 / 1000) helper methods
+MAX_UPLOAD_SIZE = size.mib(10)   # 10 MiB (10485760 bytes)
+CACHE_LIMIT = size.gib(2)        # 2 GiB (2147483648 bytes)
+USER_QUOTA = size.gb(50)         # 50 GB (50000000000 bytes)
+
+print(MAX_UPLOAD_SIZE)           # Output: 10485760
+print(type(MAX_UPLOAD_SIZE))     # Output: <class 'int'>
+```
+
+`Humanize Byte Sizes`
+
+```python
+from sizelib import humanize
+
+# Default binary formatting (base 2 / 1024)
+print(humanize(MAX_UPLOAD_SIZE))  # Output: 10 MiB
+print(humanize(CACHE_LIMIT))      # Output: 2 GiB
+
+# Decimal values are formatted up to 2 decimal places
+TOTAL = CACHE_LIMIT + size.mib(500)
+print(humanize(TOTAL))            # Output: 2.49 GiB
+
+# Decimal formatting (base 10 / 1000)
+print(humanize(USER_QUOTA, base=10))  # Output: 50 GB
+```
+
+`Exception Handling`
+
+```python
+from sizelib import FileTooLarge, size, humanize
+
+file_size = size.mib(12)
+
+try:
+    if file_size > MAX_UPLOAD_SIZE:
+        raise FileTooLarge(f"File size exceeds limit of {humanize(MAX_UPLOAD_SIZE)}")
+except FileTooLarge as e:
+    print(e)
+    # Output: File size exceeds limit of 10 MiB
+```
+
+---
+
+## ✨ _Features_
+
+| FEATURE                  | DESCRIPTION                                                                                         |
+| ------------------------ | --------------------------------------------------------------------------------------------------- |
+| 📏 **Unit Helpers**      | Standardized functions for all major divisions (`kb`, `mb`, `gb`, `tb`, `kib`, `mib`, `gib`, `tib`) |
+| 🧪 **Type Preservation** | Dynamically maintains input types (returns int/floats accordingly)                                 |
+| ⚙️ **Custom Bases**      | Support for both binary (`base=2` / 1024) and decimal (`base=10` / 1000) formats                    |
+| 🛡️ **Structured Errors** | Exposes custom `SizeLibError` and `FileTooLarge` exceptions for validation                          |
+| ⚡ **Ultra Minimalism**  | Zero external dependencies with an optimized, lightweight iteration algorithm                       |
+
+---
+
+## 🏗️ _System Architecture_
+
+| #   | COMPONENT          | DESCRIPTION                                                     | STACK        |
+| --- | ------------------ | --------------------------------------------------------------- | ------------ |
+| 1️⃣  | **Sizelib Size**   | The math factor constants and unit calculation helper functions | **_Python_** |
+| 2️⃣  | **Sizelib Format** | The humanization formatting module for readable string units    | **_Python_** |
+
+---
+
+<p align="center">
+  Made with 📄 by <a href="https://hirishi.in">Saptarshi Roy</a>
+</p>

sizelib-0.1.0/pyproject.toml

@@ -0,0 +1,22 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "sizelib"
+version = "0.1.0"
+description = "A simple, pythonic library for working with and humanizing file sizes."
+authors = [{name = "Saptarshi Roy"}]
+license = "MIT"
+readme = "README.md"
+
+requires-python = ">=3.8"
+dependencies = []
+
+[project.urls]
+Repository = "https://github.com/saptarshiroy39/sizelib"
+Homepage = "https://pypi.org/project/sizelib"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+packages = ["sizelib"]

sizelib-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

sizelib-0.1.0/src/sizelib/__init__.py

@@ -0,0 +1,5 @@
+from . import size
+from .exceptions import FileTooLarge, SizeLibError
+from .humanize import humanize
+
+__all__ = ["size", "humanize", "SizeLibError", "FileTooLarge"]

sizelib-0.1.0/src/sizelib/config.py

@@ -0,0 +1,11 @@
+BYTE = 1
+
+KB = 1000
+MB = 1000**2
+GB = 1000**3
+TB = 1000**4
+
+KIB = 1024
+MIB = 1024**2
+GIB = 1024**3
+TIB = 1024**4

sizelib-0.1.0/src/sizelib/exceptions.py

@@ -0,0 +1,6 @@
+class SizeLibError(Exception):
+    pass
+
+
+class FileTooLarge(SizeLibError):
+    pass

sizelib-0.1.0/src/sizelib/humanize.py

@@ -0,0 +1,23 @@
+def humanize(size_bytes: int | float, base: int = 2) -> str:
+    if size_bytes < 0:
+        raise ValueError("Size cannot be negative")
+    if size_bytes == 0:
+        return "0 B"
+
+    if base == 2:
+        divisor = 1024
+        units = ["B", "KiB", "MiB", "GiB", "TiB", "PiB", "EiB", "ZiB", "YiB"]
+    elif base == 10:
+        divisor = 1000
+        units = ["B", "KB", "MB", "GB", "TB", "PB", "EB", "ZB", "YB"]
+    else:
+        raise ValueError("base must be 2 or 10")
+
+    for unit in units:
+        if size_bytes < divisor:
+            break
+        size_bytes /= divisor
+
+    if size_bytes == int(size_bytes):
+        return f"{int(size_bytes)} {unit}"
+    return f"{size_bytes:.2f} {unit}"

sizelib-0.1.0/src/sizelib/size.py

@@ -0,0 +1,37 @@
+from .config import BYTE, GB, GIB, KB, KIB, MB, MIB, TB, TIB
+
+
+def b(value: int | float) -> int | float:
+    return value * BYTE
+
+
+def kb(value: int | float) -> int | float:
+    return value * KB
+
+
+def mb(value: int | float) -> int | float:
+    return value * MB
+
+
+def gb(value: int | float) -> int | float:
+    return value * GB
+
+
+def tb(value: int | float) -> int | float:
+    return value * TB
+
+
+def kib(value: int | float) -> int | float:
+    return value * KIB
+
+
+def mib(value: int | float) -> int | float:
+    return value * MIB
+
+
+def gib(value: int | float) -> int | float:
+    return value * GIB
+
+
+def tib(value: int | float) -> int | float:
+    return value * TIB

sizelib-0.1.0/src/sizelib.egg-info/PKG-INFO

@@ -0,0 +1,113 @@
+Metadata-Version: 2.4
+Name: sizelib
+Version: 0.1.0
+Summary: A simple, pythonic library for working with and humanizing file sizes.
+Author: Saptarshi Roy
+License-Expression: MIT
+Project-URL: Repository, https://github.com/saptarshiroy39/sizelib
+Project-URL: Homepage, https://pypi.org/project/sizelib
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+<h1 align="center">
+  <img src="./public/sizelib.svg" alt="📄" width="128">
+  <br>
+  <b>sizelib</b>
+</h1>
+
+<p align="center">
+  <a href="https://pypi.org/project/sizelib"><b>sizelib</b></a> is a lightweight, type-safe Python Library for working with and humanizing file sizes. It offers clean, type-preserving size helpers (supporting both `int` and `float`) and loop-based human readable string conversions.
+</p>
+
+<p align="center">
+  <a href="https://pypi.org/project/sizelib"><b>🔗 <code>PyPI Package</code></b></a>
+  &nbsp;|&nbsp;
+  🆔 <code>pip install sizelib</code> or <code>uv add sizelib</code>
+</p>
+
+---
+
+## 🐍 _SDK_
+
+`Installation`
+
+```bash
+pip install sizelib
+# or
+uv add sizelib
+```
+
+`Size Helper Functions`
+
+```python
+from sizelib import size
+
+# Define constraints using binary (base 2 / 1024) or decimal (base 10 / 1000) helper methods
+MAX_UPLOAD_SIZE = size.mib(10)   # 10 MiB (10485760 bytes)
+CACHE_LIMIT = size.gib(2)        # 2 GiB (2147483648 bytes)
+USER_QUOTA = size.gb(50)         # 50 GB (50000000000 bytes)
+
+print(MAX_UPLOAD_SIZE)           # Output: 10485760
+print(type(MAX_UPLOAD_SIZE))     # Output: <class 'int'>
+```
+
+`Humanize Byte Sizes`
+
+```python
+from sizelib import humanize
+
+# Default binary formatting (base 2 / 1024)
+print(humanize(MAX_UPLOAD_SIZE))  # Output: 10 MiB
+print(humanize(CACHE_LIMIT))      # Output: 2 GiB
+
+# Decimal values are formatted up to 2 decimal places
+TOTAL = CACHE_LIMIT + size.mib(500)
+print(humanize(TOTAL))            # Output: 2.49 GiB
+
+# Decimal formatting (base 10 / 1000)
+print(humanize(USER_QUOTA, base=10))  # Output: 50 GB
+```
+
+`Exception Handling`
+
+```python
+from sizelib import FileTooLarge, size, humanize
+
+file_size = size.mib(12)
+
+try:
+    if file_size > MAX_UPLOAD_SIZE:
+        raise FileTooLarge(f"File size exceeds limit of {humanize(MAX_UPLOAD_SIZE)}")
+except FileTooLarge as e:
+    print(e)
+    # Output: File size exceeds limit of 10 MiB
+```
+
+---
+
+## ✨ _Features_
+
+| FEATURE                  | DESCRIPTION                                                                                         |
+| ------------------------ | --------------------------------------------------------------------------------------------------- |
+| 📏 **Unit Helpers**      | Standardized functions for all major divisions (`kb`, `mb`, `gb`, `tb`, `kib`, `mib`, `gib`, `tib`) |
+| 🧪 **Type Preservation** | Dynamically maintains input types (returns int/floats accordingly)                                 |
+| ⚙️ **Custom Bases**      | Support for both binary (`base=2` / 1024) and decimal (`base=10` / 1000) formats                    |
+| 🛡️ **Structured Errors** | Exposes custom `SizeLibError` and `FileTooLarge` exceptions for validation                          |
+| ⚡ **Ultra Minimalism**  | Zero external dependencies with an optimized, lightweight iteration algorithm                       |
+
+---
+
+## 🏗️ _System Architecture_
+
+| #   | COMPONENT          | DESCRIPTION                                                     | STACK        |
+| --- | ------------------ | --------------------------------------------------------------- | ------------ |
+| 1️⃣  | **Sizelib Size**   | The math factor constants and unit calculation helper functions | **_Python_** |
+| 2️⃣  | **Sizelib Format** | The humanization formatting module for readable string units    | **_Python_** |
+
+---
+
+<p align="center">
+  Made with 📄 by <a href="https://hirishi.in">Saptarshi Roy</a>
+</p>

sizelib-0.1.0/src/sizelib.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+LICENSE
+README.md
+pyproject.toml
+src/sizelib/__init__.py
+src/sizelib/config.py
+src/sizelib/exceptions.py
+src/sizelib/humanize.py
+src/sizelib/size.py
+src/sizelib.egg-info/PKG-INFO
+src/sizelib.egg-info/SOURCES.txt
+src/sizelib.egg-info/dependency_links.txt
+src/sizelib.egg-info/top_level.txt

sizelib-0.1.0/src/sizelib.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

sizelib-0.1.0/src/sizelib.egg-info/top_level.txt

@@ -0,0 +1 @@
+sizelib