added more helpers

Author: Daniel15568

README.md

@@ -12,45 +12,66 @@ Stop typing `(part / whole) * 100` and worrying about division by zero.
 
 ## ✨ What It Does
 
-Percentify gives you a single function:
+A tiny, zero-dependency Python toolkit for all things percentages:
 
-- Calculates what percentage one number is of another.
-- Handles divide-by-zero safely (returns 0.0 instead of crashing).
-- Lets you choose how many decimal places to round to.
-- Has zero dependencies — just pure Python.
+- **`percent`** — what percentage is `part` of `whole`?
+- **`percent_change`** — how much did a value increase or decrease?
+- **`percent_diff`** — how far apart are two values?
+- **`percent_distribute`** — split a total into weighted shares.
+- **`percent_format`** — turn any number into a clean `"25.0%"` string.
+
+All functions handle edge cases (division by zero, negative values) safely and let you control decimal precision.
 
 ## 📦 Installation
 ```
 pip install percentify
 ```
 
-### Usage
-```
+## Usage
+
+### `percent` — Part of a Whole
+```python
 from percentify import percent
 
-# Basic usage
 percent(50, 200)          # → 25.0
-
-# Handles fractions
 percent(1, 3)             # → 33.33
+percent(5, 0)             # → 0.0  (safe division by zero)
+percent(7, 9, 4)          # → 77.7778  (custom decimals)
+```
 
-# Safe when dividing by zero
-percent(5, 0)             # → 0.0
+### `percent_change` — Increase or Decrease
+```python
+from percentify import percent_change
 
-# Custom decimals
-percent(7, 9, 4)          # → 77.7778
+percent_change(100, 150)  # → 50.0   (50% increase)
+percent_change(200, 150)  # → -25.0  (25% decrease)
+percent_change(0, 100)    # → 0.0    (safe when old is zero)
 ```
 
-### 🛠️ How It Works
+### `percent_diff` — Difference Between Two Values
+```python
+from percentify import percent_diff
 
-The library is intentionally simple;
+percent_diff(10, 20)      # → 66.67
+percent_diff(50, 50)      # → 0.0
 ```
-def percent(part: float, whole: float, decimals: int = 2) -> float:
-    if whole == 0:
-        return 0.0
-    return round((part / whole) * 100, decimals)
+
+### `percent_distribute` — Split a Total by Weights
+```python
+from percentify import percent_distribute
+
+percent_distribute(200, [1, 3])       # → [50.0, 150.0]
+percent_distribute(100, [1, 1, 1])    # → [33.33, 33.33, 33.33]
+```
+
+### `percent_format` — Format as a String
+```python
+from percentify import percent_format
+
+percent_format(25.0)                  # → "25.0%"
+percent_format(33.3333, 1)            # → "33.3%"
+percent_format(50, suffix=" percent") # → "50.0 percent"
 ```
-That’s it. Clean, safe, and ready to use anywhere you need percentages in your code.
 
 # 🤝 Contributing
 

percentify/__init__.py

@@ -1,4 +1,4 @@
-from .core import percent
+from .core import percent, percent_change, percent_diff, percent_distribute, percent_format
 
-__all__ = ["percent"]
-__version__ = "0.1.3"
+__all__ = ["percent", "percent_change", "percent_diff", "percent_distribute", "percent_format"]
+__version__ = "0.2.0"

percentify/core.py

@@ -1,4 +1,13 @@
-from typing import SupportsFloat, Optional
+from typing import List, SupportsFloat, Optional
+
+
+def _round_value(value: float, decimals: Optional[int]) -> float:
+    if decimals is None:
+        return value
+    if decimals < 0:
+        raise ValueError("`decimals` must be non-negative or None.")
+    return round(value, decimals)
+
 
 def percent(part: SupportsFloat, whole: SupportsFloat, decimals: Optional[int] = 2) -> float:
     """
@@ -18,11 +27,97 @@ def percent(part: SupportsFloat, whole: SupportsFloat, decimals: Optional[int] =
         return 0.0
 
     value = float(part) / whole * 100.0
+    return _round_value(value, decimals)
 
-    if decimals is None:
-        return value
 
-    if decimals < 0:
-        raise ValueError("`decimals` must be non-negative or None.")
+def percent_change(old: SupportsFloat, new: SupportsFloat, decimals: Optional[int] = 2) -> float:
+    """
+    Calculate the percentage change from `old` to `new`.
 
-    return round(value, decimals)
+    Args:
+        old: The original value.
+        new: The new value.
+        decimals: Number of decimal places to round to.
+            If None, the raw percentage (unrounded float) is returned.
+
+    Returns:
+        float: Percentage change. Positive means increase, negative means decrease.
+            If `old` is 0, returns 0.0.
+    """
+    old = float(old)
+    if old == 0:
+        return 0.0
+
+    value = (float(new) - old) / abs(old) * 100.0
+    return _round_value(value, decimals)
+
+
+def percent_diff(a: SupportsFloat, b: SupportsFloat, decimals: Optional[int] = 2) -> float:
+    """
+    Calculate the percentage difference between two values.
+
+    Uses the average of the two values as the denominator.
+
+    Args:
+        a: First value.
+        b: Second value.
+        decimals: Number of decimal places to round to.
+            If None, the raw percentage (unrounded float) is returned.
+
+    Returns:
+        float: Percentage difference (always non-negative).
+            If both values are 0, returns 0.0.
+    """
+    a, b = float(a), float(b)
+    avg = (abs(a) + abs(b)) / 2.0
+    if avg == 0:
+        return 0.0
+
+    value = abs(a - b) / avg * 100.0
+    return _round_value(value, decimals)
+
+
+def percent_distribute(total: SupportsFloat, weights: List[SupportsFloat], decimals: Optional[int] = 2) -> List[float]:
+    """
+    Distribute a total into percentage-based shares according to weights.
+
+    Args:
+        total: The total value to distribute.
+        weights: A list of weights determining each share's proportion.
+        decimals: Number of decimal places to round to.
+            If None, the raw values (unrounded floats) are returned.
+
+    Returns:
+        list[float]: Each weight's share of the total.
+
+    Raises:
+        ValueError: If weights is empty or all weights are zero.
+    """
+    if not weights:
+        raise ValueError("`weights` must not be empty.")
+
+    float_weights = [float(w) for w in weights]
+    weight_sum = sum(float_weights)
+
+    if weight_sum == 0:
+        raise ValueError("Sum of `weights` must not be zero.")
+
+    total = float(total)
+    return [_round_value(w / weight_sum * total, decimals) for w in float_weights]
+
+
+def percent_format(value: SupportsFloat, decimals: Optional[int] = 2, suffix: str = "%") -> str:
+    """
+    Format a numeric value as a percentage string.
+
+    Args:
+        value: The percentage value to format.
+        decimals: Number of decimal places to round to.
+            If None, the raw float is used without rounding.
+        suffix: The suffix to append (default: "%").
+
+    Returns:
+        str: Formatted percentage string, e.g. "25.0%".
+    """
+    rounded = _round_value(float(value), decimals)
+    return f"{rounded}{suffix}"

pyproject.toml

@@ -4,12 +4,13 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "percentify"
-version = "0.1.4"
-description = "A micro-library to easily calculate percentage between two numbers."
+version = "0.2.0"
+description = "A tiny, zero-dependency Python toolkit for percentages — calculate, compare, format, and distribute."
 authors = [{ name = "Daniel Emakporuena", email = "danielemakporuena1@gmail.com" }]
 readme = "README.md"
 license = { text = "Apache-2.0" }
 requires-python = ">=3.7"
+keywords = ["percentage", "percent", "math", "utility", "statistics", "format"]
 classifiers = [
     "Programming Language :: Python :: 3",
     "License :: OSI Approved :: Apache Software License",

tests/test_core.py

@@ -1,4 +1,8 @@
-from percentify import percent
+import pytest
+from percentify import percent, percent_change, percent_diff, percent_distribute, percent_format
+
+
+# --- percent ---
 
 def test_percent_normal():
     assert percent(50, 200) == 25.0
@@ -8,3 +12,95 @@ def test_percent_fraction():
 
 def test_percent_zero_division():
     assert percent(5, 0) == 0.0
+
+def test_percent_no_rounding():
+    assert percent(1, 3, None) == pytest.approx(33.33333333333333)
+
+def test_percent_custom_decimals():
+    assert percent(7, 9, 4) == 77.7778
+
+def test_percent_negative_decimals():
+    with pytest.raises(ValueError):
+        percent(1, 3, -1)
+
+
+# --- percent_change ---
+
+def test_percent_change_increase():
+    assert percent_change(100, 150) == 50.0
+
+def test_percent_change_decrease():
+    assert percent_change(200, 150) == -25.0
+
+def test_percent_change_no_change():
+    assert percent_change(100, 100) == 0.0
+
+def test_percent_change_zero_old():
+    assert percent_change(0, 100) == 0.0
+
+def test_percent_change_negative_old():
+    assert percent_change(-100, -50) == 50.0
+
+def test_percent_change_custom_decimals():
+    assert percent_change(3, 7, 4) == 133.3333
+
+
+# --- percent_diff ---
+
+def test_percent_diff_basic():
+    assert percent_diff(10, 20) == 66.67
+
+def test_percent_diff_same():
+    assert percent_diff(50, 50) == 0.0
+
+def test_percent_diff_both_zero():
+    assert percent_diff(0, 0) == 0.0
+
+def test_percent_diff_order_independent():
+    assert percent_diff(10, 20) == percent_diff(20, 10)
+
+def test_percent_diff_custom_decimals():
+    assert percent_diff(3, 7, 4) == 80.0
+
+
+# --- percent_distribute ---
+
+def test_distribute_equal():
+    assert percent_distribute(100, [1, 1, 1]) == [pytest.approx(33.33), pytest.approx(33.33), pytest.approx(33.33)]
+
+def test_distribute_weighted():
+    assert percent_distribute(200, [1, 3]) == [50.0, 150.0]
+
+def test_distribute_single():
+    assert percent_distribute(100, [5]) == [100.0]
+
+def test_distribute_empty():
+    with pytest.raises(ValueError):
+        percent_distribute(100, [])
+
+def test_distribute_zero_weights():
+    with pytest.raises(ValueError):
+        percent_distribute(100, [0, 0])
+
+def test_distribute_custom_decimals():
+    result = percent_distribute(100, [1, 1, 1], 4)
+    assert result == [pytest.approx(33.3333), pytest.approx(33.3333), pytest.approx(33.3333)]
+
+
+# --- percent_format ---
+
+def test_format_basic():
+    assert percent_format(25.0) == "25.0%"
+
+def test_format_custom_decimals():
+    assert percent_format(33.3333, 1) == "33.3%"
+
+def test_format_custom_suffix():
+    assert percent_format(50, suffix=" percent") == "50.0 percent"
+
+def test_format_no_rounding():
+    result = percent_format(33.3333, None)
+    assert result == "33.3333%"
+
+def test_format_zero():
+    assert percent_format(0) == "0.0%"