Merge pull request #65 from DhruvDuseja/format_solute_utility

Add utility method to format dictionary

CHANGELOG.md

@@ -5,6 +5,12 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+### Added
+
+- `format_solutes_dict()` method added into the utils module to help format solutes dictionaries with a unit.
+
 ## [0.9.0] - 2023-10-17
 
 ### Added

src/pyEQL/utils.py

@@ -32,6 +32,28 @@ def standardize_formula(formula: str):
     return Ion.from_formula(formula).reduced_formula
 
 
+def format_solutes_dict(solute_dict: dict, units: str):
+    """
+    Formats a dictionary of solutes by converting the amount to a string with the provided units suitable for passing to
+    use with the Solution class. Note that all solutes must be given in the same units.
+
+    Args:
+        solute_dict: The dictionary to format. This must be of the form dict{str: Number}
+            e.g. {"Na+": 0.5, "Cl-": 0.9}
+        units: The units to use for the solute. e.g. "mol/kg"
+
+    Returns:
+        A formatted solute dictionary.
+
+    Raises:
+        TypeError if `solute_dict` is not a dictionary.
+    """
+    if not isinstance(solute_dict, dict):
+        raise TypeError("solute_dict must be a dictionary. Refer to the doc for proper formatting.")
+
+    return {key: f"{value!s} {units}" for key, value in solute_dict.items()}
+
+
 class FormulaDict(UserDict):
     """
     Automatically converts keys on get/set using pymatgen.core.Ion.from_formula(key).reduced_formula.

tests/test_utils.py

@@ -2,8 +2,9 @@
 Tests of pyEQL.utils module
 
 """
+from pytest import raises
 
-from pyEQL.utils import FormulaDict, standardize_formula
+from pyEQL.utils import FormulaDict, format_solutes_dict, standardize_formula
 
 
 def test_standardize_formula():
@@ -35,3 +36,17 @@ def test_formula_dict():
     assert d.get("Na+") == 0.5
     d.update({"Br-": 2})
     assert d["Br[-]"] == 2
+
+
+def test_format_solute():
+    """
+    Test formatting solute dictionaries
+    """
+    test = {"Na+": 0.5, "Cl-": 0.5}
+    base = {"Na+": "0.5 mol/kg", "Cl-": "0.5 mol/kg"}
+    assert format_solutes_dict(test, units="mol/kg") == base
+
+    bad_test = [["Na+", 0.5], ["Cl-", 0.5]]
+    error_msg = "solute_dict must be a dictionary. Refer to the doc for proper formatting."
+    with raises(TypeError, match=error_msg):
+        format_solutes_dict(bad_test, units="mol/kg")