Merge pull request #1 from data-centt/main

Update

Author: dave3214

README.md

@@ -1,56 +1,87 @@
 #                                              % Percentify %
-[![PyPI Downloads](https://static.pepy.tech/personalized-badge/percentify?period=total&units=INTERNATIONAL_SYSTEM&left_color=BLACK&right_color=GREEN&left_text=downloads)](https://pepy.tech/projects/percentify)
 [![PyPI version](https://img.shields.io/pypi/v/percentify.svg?style=flat&color=blue)](https://pypi.org/project/percentify/)
 [![Python Versions](https://img.shields.io/pypi/pyversions/percentify.svg?style=flat&color=green)](https://pypi.org/project/percentify/)
 [![License](https://img.shields.io/pypi/l/percentify.svg?style=flat&color=orange)](LICENSE)
 [![Build Status](https://github.com/data-centt/percentify/actions/workflows/python-app.yml/badge.svg)](https://github.com/data-centt/percentify/actions/workflows/python-app.yml)
+![GitHub Stars](https://img.shields.io/github/stars/data-centt/percentify?style=flat&color=white)
 
-**Percentify** — a tiny Python helper that turns *"part of a whole"* into a clean percentage.  
+**Percentify** is a Python package that turns *"part of a whole"* into a clean percentage.  
 Stop typing `(part / whole) * 100` and worrying about division by zero.
 
 ---
 
 ## ✨ What It Does
 
-Percentify gives you a single function:
+A zero-dependency Python toolkit for all things percentages:
+
+
+- **`percent`** — what percentage is `part` of `whole`?
+- **`change`** — how much did a value increase or decrease?
+- **`difference`** — how far apart are two values?
+- **`split`** — split a total into weighted shares.
+- **`display`** — 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.
 
-- 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.
 
 ## 📦 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
+### `change` — Increase or Decrease
+```python
+from percentify import change
 
-# Custom decimals
-percent(7, 9, 4)          # → 77.7778
+change(100, 150)  # → 50.0   (50% increase)
+change(200, 150)  # → -25.0  (25% decrease)
+change(0, 100)    # → 0.0    (safe when old is zero)
 ```
 
-### 🛠️ How It Works
+### `difference` — Difference Between Two Values
+```python
+from percentify import difference
 
-The library is intentionally simple — just one function:
+difference(10, 20)      # → 66.67
+difference(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)
+
+### `split` — Split a Total by Weights
+```python
+from percentify import split
+
+split(200, [1, 3])       # → [50.0, 150.0]
+split(100, [1, 1, 1])    # → [33.33, 33.33, 33.33]
+```
+
+### `display` — Format as a String
+```python
+from percentify import display
+
+display(25.0)                         # → "25.0%"
+display(33.3333, 1)                   # → "33.3%"
+display(50, suffix=" percent")        # → "50.0 percent"
+display(0.45, multiply=True)          # → "45.0%"
+```
+
+### Composing Functions
+```python
+from percentify import change, display
+
+display(change(100, 20))  # → "-80.0%"
 ```
-That’s it. Clean, safe, and ready to use anywhere you need percentages in your code.
 
 # 🤝 Contributing
 
@@ -61,4 +92,4 @@ Contributions are welcome!
 - Commit your changes
 - Open a pull request
 
-I try to keep it tiny on purpose, to discuss big new features first.
+I try to keep it within scope, to discuss big new features first.

percentify/__init__.py

@@ -1,4 +1,4 @@
-from .core import percent
+from .core import percent, change, difference, split, display
 
-__all__ = ["percent"]
-__version__ = "0.1.3"
+__all__ = ["percent", "change", "difference", "split", "display"]
+__version__ = "0.3.1"

percentify/core.py

@@ -1,8 +1,17 @@
-from typing import SupportsFloat
+from typing import List, SupportsFloat, Optional
 
-def percent(part: SupportsFloat, whole: SupportsFloat, decimals: int | None = 2) -> float:
+
+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:
     """
-    Calculate what percentage `part` is of the `whole`.
+    Calculate what percentage as `part` is of the `whole`.
 
     Args:
         part: The numerator.
@@ -18,11 +27,102 @@ def percent(part: SupportsFloat, whole: SupportsFloat, decimals: int | None = 2)
         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 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 difference(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 split(total: SupportsFloat, weights: List[SupportsFloat], decimals: Optional[int] = 2) -> List[float]:
+    """
+    split 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 display(value: SupportsFloat, decimals: Optional[int] = 2, suffix: str = "%", multiply:bool = False) -> str:
+    """
+    display takes 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: "%").
+        multiply: bool defaulted to False, if True multiplies the value by 100 turning it to percentage of 100.
+
+
+    Returns:
+        str: Formatted percentage string, e.g. "25.0%".
+    """
+    v = float(value)
+    if multiply:
+        v *= 100
+    rounded = _round_value(float(v), decimals)
+    return f"{rounded}{suffix}"

pyproject.toml

@@ -4,12 +4,13 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "percentify"
-version = "0.1.3"
-description = "A micro-library to easily calculate percentage between two numbers."
+version = "0.3.1"
+description = "A 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, change, difference, split, display
+
+
+# --- percent ---
 
 def test_percent_normal():
     assert percent(50, 200) == 25.0
@@ -8,3 +12,104 @@ 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)
+
+
+# --- change ---
+
+def test_change_increase():
+    assert change(100, 150) == 50.0
+
+def test_change_decrease():
+    assert change(200, 150) == -25.0
+
+def test_change_no_change():
+    assert change(100, 100) == 0.0
+
+def test_change_zero_old():
+    assert change(0, 100) == 0.0
+
+def test_change_negative_old():
+    assert change(-100, -50) == 50.0
+
+def test_change_custom_decimals():
+    assert change(3, 7, 4) == 133.3333
+
+
+# --- difference ---
+
+def test_difference_basic():
+    assert difference(10, 20) == 66.67
+
+def test_difference_same():
+    assert difference(50, 50) == 0.0
+
+def test_difference_both_zero():
+    assert difference(0, 0) == 0.0
+
+def test_difference_order_independent():
+    assert difference(10, 20) == difference(20, 10)
+
+def test_difference_custom_decimals():
+    assert difference(3, 7, 4) == 80.0
+
+
+# --- split ---
+
+def test_split_equal():
+    assert split(100, [1, 1, 1]) == [pytest.approx(33.33), pytest.approx(33.33), pytest.approx(33.33)]
+
+def test_split_weighted():
+    assert split(200, [1, 3]) == [50.0, 150.0]
+
+def test_split_single():
+    assert split(100, [5]) == [100.0]
+
+def test_split_empty():
+    with pytest.raises(ValueError):
+        split(100, [])
+
+def test_split_zero_weights():
+    with pytest.raises(ValueError):
+        split(100, [0, 0])
+
+def test_split_custom_decimals():
+    result = split(100, [1, 1, 1], 4)
+    assert result == [pytest.approx(33.3333), pytest.approx(33.3333), pytest.approx(33.3333)]
+
+
+# --- display ---
+
+def test_display_basic():
+    assert display(25.0) == "25.0%"
+
+def test_display_custom_decimals():
+    assert display(33.3333, 1) == "33.3%"
+
+def test_display_custom_suffix():
+    assert display(50, suffix=" percent") == "50.0 percent"
+
+def test_display_no_rounding():
+    result = display(33.3333, None)
+    assert result == "33.3333%"
+
+def test_display_zero():
+    assert display(0) == "0.0%"
+
+def test_display_multiply():
+    assert display(0.45, multiply=True) == "45.0%"
+
+def test_display_multiply_small():
+    assert display(0.0725, multiply=True) == "7.25%"
+
+def test_display_multiply_false():
+    assert display(0.45) == "0.45%"