Added utilities function

Author: Moasib-Arif

dpytools/utilities/README.md

@@ -0,0 +1,34 @@
+# Utility Functions
+
+## str_to_bool
+
+The `str_to_bool` function is a utility function that converts a string representation of a boolean to a boolean value.
+
+### Usage
+
+```python
+from utilities import str_to_bool
+
+print(str_to_bool('True'))  # Outputs: True
+print(str_to_bool('false'))  # Outputs: False
+
+```
+
+#### Parameters
+`should_be_bool` (str): A string that should represent a boolean value.
+
+#### Returns
+`bool`: The boolean value represented by the input string.
+
+#### Raises
+`AssertionError`: If the input value is not a string.
+`ValueError`: If the input string does not represent a boolean value.
+
+#### Example
+
+```python
+try:
+    print(str_to_bool('not a boolean'))  # Raises ValueError
+except ValueError as e:
+    print(e)  # Outputs: A str value representing a boolean should be one of 'True', 'true', 'False', 'false'. Got 'not a boolean'
+```

dpytools/utilities/utilities.py

@@ -0,0 +1,24 @@
+def str_to_bool(should_be_bool: str) -> bool:
+    """
+    Take a string that should represent a boolean
+    and convert it to bool.
+
+    Raise if we've an unexpected value.
+    """
+
+    assert isinstance(
+        should_be_bool, str
+    ), f"Function str_to_bool only accepts strings, got {type(should_be_bool)}"
+
+    consistent_should_be_bool = should_be_bool.strip().lower()
+
+    if consistent_should_be_bool == "true":
+        return True
+    elif consistent_should_be_bool == "false":
+        return False
+    else:
+        raise ValueError(
+            f"A str value representing a boolean should be one of 'True', 'true', 'False', 'false'. Got '{should_be_bool}'"
+        )
+
+

tests/test_utilities.py

@@ -0,0 +1,46 @@
+import pytest
+
+from dpytools.utilities.utilities import str_to_bool
+
+
+def test_str_to_bool_valid_values():
+    """
+    Test str_to_bool utility can correctly identify the expected
+    boolean values from strings.
+    """
+
+    assert str_to_bool("True") is True
+    assert str_to_bool("true") is True
+    assert str_to_bool("  True ") is True
+    assert str_to_bool("False") is False
+    assert str_to_bool("false") is False
+    assert str_to_bool("false  ") is False
+
+
+def test_str_to_bool_valid_raises_for_invalid_str_value():
+    """
+    Test str_to_bool utility will raise when given a non
+    expected string value
+    """
+
+    with pytest.raises(ValueError) as err:
+        str_to_bool("foo")
+
+    assert (
+        "A str value representing a boolean should be one of 'True', 'true', 'False', 'false'"
+        in str(err)
+    )
+
+
+def test_str_to_bool_raises_for_not_string_argument():
+    """
+    Test str_to_bool utility will raise when given a non
+    string argument
+    """
+
+    for invalid_type in [1, True, 897.23]:
+
+        with pytest.raises(AssertionError) as err:
+            str_to_bool(invalid_type)
+
+        assert "Function str_to_bool only accepts strings" in str(err)