2.4.1 - Added empty_if function to helpers.common

 - Added `empty_if` to `privex.helpers.common`

 - Added docs for `empty_if`

 - Created three unit tests in `test_bool.py` for testing `empty_if`:

   `test_emptyif_only_empty` `test_emptyif_only_value` and `test_emptyif_with_is_not_empty`

 - Added docs for the new unit tests

Author: Someguy123

docs/source/helpers/common/privex.helpers.common.empty_if.rst

@@ -0,0 +1,6 @@
+empty\_if
+=========
+
+.. currentmodule:: privex.helpers.common
+
+.. autofunction:: empty_if

docs/source/helpers/privex.helpers.common.rst

@@ -14,6 +14,7 @@ privex.helpers.common
       chunked
       dec_round
       empty
+      empty_if
       env_bool
       env_csv
       env_cast

docs/source/helpers/tests/test_bool/testboolhelpers/tests.test_bool.TestBoolHelpers.test_emptyif_only_empty.rst

@@ -0,0 +1,6 @@
+test\_emptyif\_only\_empty
+==========================
+
+.. currentmodule:: tests.test_bool
+
+.. automethod:: TestBoolHelpers.test_emptyif_only_empty

docs/source/helpers/tests/test_bool/testboolhelpers/tests.test_bool.TestBoolHelpers.test_emptyif_only_value.rst

@@ -0,0 +1,6 @@
+test\_emptyif\_only\_value
+==========================
+
+.. currentmodule:: tests.test_bool
+
+.. automethod:: TestBoolHelpers.test_emptyif_only_value

docs/source/helpers/tests/test_bool/testboolhelpers/tests.test_bool.TestBoolHelpers.test_emptyif_with_is_not_empty.rst

@@ -0,0 +1,6 @@
+test\_emptyif\_with\_is\_not\_empty
+===================================
+
+.. currentmodule:: tests.test_bool
+
+.. automethod:: TestBoolHelpers.test_emptyif_with_is_not_empty

docs/source/helpers/tests/test_bool/tests.test_bool.TestBoolHelpers.rst

@@ -4,7 +4,7 @@ TestBoolHelpers
 .. currentmodule:: tests.test_bool
 
 .. autoclass:: TestBoolHelpers
-   :noindex:
+
 
    .. automethod:: __init__
       :noindex:
@@ -22,6 +22,9 @@ Methods
     ~TestBoolHelpers.test_empty_lst
     ~TestBoolHelpers.test_empty_vals
     ~TestBoolHelpers.test_empty_zero
+    ~TestBoolHelpers.test_emptyif_only_empty
+    ~TestBoolHelpers.test_emptyif_only_value
+    ~TestBoolHelpers.test_emptyif_with_is_not_empty
     ~TestBoolHelpers.test_isfalse_falsey
     ~TestBoolHelpers.test_isfalse_truthy
     ~TestBoolHelpers.test_istrue_falsey

privex/helpers/__init__.py

@@ -128,7 +128,7 @@ def _setup_logging(level=logging.WARNING):
 log = _setup_logging()
 name = 'helpers'
 
-VERSION = '2.4.0'
+VERSION = '2.4.1'
 
 
 

privex/helpers/common.py

@@ -47,7 +47,7 @@
 from collections import namedtuple
 from decimal import Decimal, getcontext
 from os import getenv as env
-from typing import Sequence, List, Union, Tuple, Type, Dict
+from typing import Sequence, List, Union, Tuple, Type, Dict, TypeVar, Any
 
 log = logging.getLogger(__name__)
 
@@ -123,6 +123,53 @@ def empty(v, zero: bool = False, itr: bool = False) -> bool:
     return False
 
 
+T = TypeVar('T')
+K = TypeVar('K')
+V = TypeVar('V')
+
+USE_ORIG_VAR = type('UseOrigVar', (), {})
+
+
+def empty_if(v: V, is_empty: K = None, not_empty: T = USE_ORIG_VAR, **kwargs) -> Union[T, K, V]:
+    """
+    Syntactic sugar for ``x if empty(y) else z``. If ``not_empty`` isn't specified, then the original value ``v``
+    will be returned if it's not empty.
+    
+    **Example 1**::
+    
+        >>> def some_func(name=None):
+        ...     name = empty_if(name, 'John Doe')
+        ...     return name
+        >>> some_func("")
+        John Doe
+        >>> some_func("Dave")
+        Dave
+    
+    **Example 2**::
+    
+        >>> empty_if(None, 'is empty', 'is not empty')
+        is empty
+        >>> empty_if(12345, 'is empty', 'is not empty')
+        is not empty
+    
+    
+    :param Any v:     The value to test for emptiness
+    :param is_empty:  The value to return if ``v`` is empty (defaults to ``None``)
+    :param not_empty: The value to return if ``v`` is not empty (defaults to the original value ``v``)
+    :param kwargs:    Any additional kwargs to pass to :func:`.empty`
+    
+    :key zero: if ``zero=True``, then v is empty if it's int ``0`` or str ``'0'``
+    :key itr:  if ``itr=True``,  then v is empty if it's ``[]``, ``{}``, or is an iterable and has 0 length
+    
+    :return V orig_var:  The original value ``v`` is returned if ``not_empty`` isn't specified.
+    :return K is_empty:  The value specified as ``is_empty`` is returned if ``v`` is empty
+    :return T not_empty: The value specified as ``not_empty`` is returned if ``v`` is not empty
+                         (and not_empty was specified)
+    """
+    not_empty = v if not_empty == USE_ORIG_VAR else not_empty
+    return is_empty if empty(v, **kwargs) else not_empty
+
+
 def is_true(v) -> bool:
     """
     Check if a given bool/str/int value is some form of ``True``:

tests/test_bool.py

@@ -95,3 +95,30 @@ def test_notempty(self):
         self.assertFalse(helpers.empty(['world'], itr=True))
         self.assertFalse(helpers.empty(('world',), itr=True))
         self.assertFalse(helpers.empty({'hello': 'world'}, itr=True))
+    
+    def test_emptyif_with_is_not_empty(self):
+        self.assertEqual(helpers.empty_if("", "empty", "not empty"), "empty")
+        self.assertEqual(helpers.empty_if(None, "empty", "not empty"), "empty")
+        self.assertEqual(helpers.empty_if(0, "empty", "not empty", zero=True), "empty")
+
+        self.assertEqual(helpers.empty_if("hello", "empty", "not empty"), "not empty")
+        self.assertEqual(helpers.empty_if(1234, "empty", "not empty"), "not empty")
+        self.assertEqual(helpers.empty_if([1, 2, 3], "empty", "not empty"), "not empty")
+
+    def test_emptyif_only_empty(self):
+        self.assertEqual(helpers.empty_if("", "empty"), "empty")
+        self.assertEqual(helpers.empty_if(None, "empty"), "empty")
+        self.assertEqual(helpers.empty_if(0, "empty", zero=True), "empty")
+    
+        self.assertEqual(helpers.empty_if("hello", "empty"), "hello")
+        self.assertEqual(helpers.empty_if(1234, "empty"), 1234)
+        self.assertListEqual(helpers.empty_if([1, 2, 3], "empty"), [1, 2, 3])
+
+    def test_emptyif_only_value(self):
+        self.assertIsNone(helpers.empty_if(""))
+        self.assertIsNone(helpers.empty_if(None))
+        self.assertIsNone(helpers.empty_if(0, zero=True))
+    
+        self.assertEqual(helpers.empty_if("hello"), "hello")
+        self.assertEqual(helpers.empty_if(1234), 1234)
+        self.assertListEqual(helpers.empty_if([1, 2, 3]), [1, 2, 3])