v1.0.1 - Unit tests, csv parsing functions, fix for empty()

 - New parsing functions added to common.py - useful for parsing environmental variables
    - Added csv_parse for parsing simple one-line CSVs and trimming whitespace
    - Added csv_env for extracting a `list()` from a csv formatted environ var
    - Added keyval_parse for parsing key value pair CSVs i.e. `key:val,key:val`
    - Added keyval_env (same as csv_env, but for key value environ vars)
 - Now with unit tests in `tests.py` :)
    - Created unit tests for is_true, is_false and is_empty to ensure reliable bool checks
    - Created unit tests for csv_parse and keyval_parse to ensure reliable parsing
 - Added informational text to the module docblock for privex.helpers
 - Added string '0' for empty()'s zero check
 - Version bump to 1.0.1

Author: Someguy123

privex/helpers/__init__.py

@@ -1,4 +1,16 @@
 """
+Privex's Python Helpers - https://github.com/privex/python-helpers
+
+X11 / MIT License
+
+Submodules:
+
+  * common - Uncategorized functions and classes, including bool checks and data parsing
+  * decorators - Class / function decorators
+  * django - Django-specific functions/classes, only available if Django package is installed
+  * net - Network related functions/classes such as ASN name lookup, and IP version bool checks
+
+
     +===================================================+
     |                 © 2019 Privex Inc.                |
     |               https://www.privex.io               |

privex/helpers/common.py

@@ -39,7 +39,8 @@
 import argparse
 import logging
 import sys
-from typing import Sequence
+from os import getenv as env
+from typing import Sequence, List, Union, Tuple
 
 log = logging.getLogger(__name__)
 
@@ -97,14 +98,14 @@ def empty(v, zero: bool = False, itr: bool = False) -> bool:
         ...     print('Var x is None, blank string, or an empty dict/list/iterable')
 
     :param v:    The variable to check if it's empty
-    :param zero: if zero=True, then return True if the variable is 0
+    :param zero: if zero=True, then return True if the variable is int 0 or str '0'
     :param itr:  if itr=True, then return True if the variable is ``[]``, ``{}``, or is an iterable and has 0 length
     :return bool is_blank: True if a variable is blank (``None``, ``''``, ``0``, ``[]`` etc.)
     :return bool is_blank: False if a variable has content (or couldn't be checked properly)
     """
 
     _check = [None, '']
-    if zero: _check.append(0)
+    if zero: _check += [0, '0']
     if v in _check: return True
     if itr:
         if v == [] or v == {}: return True
@@ -163,6 +164,67 @@ def is_false(v, chk_none: bool = True) -> bool:
     chk += [None, 'none', 'null', ''] if chk_none else []
     return v in chk
 
+def keyval_parse(line: str) -> List[Tuple[str, str]]:
+    """
+    Parses a csv with key:value pairs such as:
+
+        John Alex:Doe,Jane Sarah:Doe
+    
+    Into a list with tuple pairs (can be easily converted to a dict):
+
+        [
+            ('John Alex', 'Doe'), 
+            ('Jane Sarah', 'Doe')
+        ]
+    
+    :param str line: A string of key:value pairs separated by commas e.g. "John Alex:Doe,Jane Sarah:Doe"
+    :return List[Tuple[str,str]] parsed_data:  A list of (key, value) tuples that can easily be casted to a dict()
+    """
+    line = [tuple(a.split(':')) for a in line.split(',')] if line != '' else []
+    return [(a.strip(), b.strip()) for a, b in line]
+
+def keyval_env(env_key: str, env_default = None) -> List[Tuple[str, str]]:
+    """
+    Parses "key:val,key:val" into a list of tuples [(key,val), (key,val)]
+    
+    See :py:meth:`keyval_parse`
+    """
+    d = env(env_key)
+    return env_default if empty(d) else keyval_parse(d)
+
+def csv_parse(line: str) -> List[str]:
+    """
+    Quick n' dirty parsing of a simple comma separated line, with automatic whitespace stripping
+    of both the ``line`` itself, and the values within the commas.
+
+    Example:
+    
+        >>> csv_parse('  hello ,  world, test')
+        ['hello', 'world', 'test']
+    
+    """
+    return [x.strip() for x in line.strip().split(',')]
+
+def csv_env(env_key: str, env_default = None) -> List[str]:
+    """
+    Quick n' dirty parsing of simple CSV formatted environment variables, with fallback
+    to user specified ``env_default`` (defaults to None)
+
+    Example:
+
+        >>> os.setenv('EXAMPLE', '  hello ,  world, test')
+        >>> csv_env('EXAMPLE', [])
+        ['hello', 'world', 'test']
+        >>> csv_env('NONEXISTANT', [])
+        []
+    
+    :param str env_key:     Environment var to attempt to load
+    :param any env_default: Fallback value if the env var is empty / not set
+    :return List[str] parsed_data: A list of str values parsed from the env var
+    """
+    d = env(env_key)
+    return env_default if empty(d) else csv_parse(d)
+
 
 class ErrHelpParser(argparse.ArgumentParser):
     """

setup.py

@@ -42,7 +42,7 @@
 setup(
     name='privex_helpers',
 
-    version='1.0.0',
+    version='1.0.1',
 
     description='A variety of helper functions and classes, useful for many different projects',
     long_description=long_description,

tests.py

@@ -0,0 +1,135 @@
+#!/usr/bin/env python3.7
+import unittest
+import logging
+from collections import namedtuple
+from privex import helpers
+from privex.loghelper import LogHelper
+
+
+class TestParseHelpers(unittest.TestCase):
+    """Test the parsing functions csv_parse and keyval_parse"""
+
+    def test_csv_spaced(self):
+        """Test csv parsing with excess outer whitespace, and value whitespace"""
+        c = helpers.csv_parse('  valid  , spaced out,   csv  ')
+        self.assertListEqual(c, ['valid', 'spaced out', 'csv'])
+    
+    def test_csv_single(self):
+        """Test that a single value still returns a list"""
+        self.assertListEqual(helpers.csv_parse('single'), ['single'])
+    
+    def test_kval_clean(self):
+        """Test that a clean key:val csv is parsed correctly"""
+        self.assertListEqual(
+            helpers.keyval_parse('John:Doe,Jane:Smith'), 
+            [('John', 'Doe'), ('Jane', 'Smith')]
+        )
+    
+    def test_kval_spaced(self):
+        """Test key:val csv parsing with excess outer whitespace, and value whitespace"""
+        self.assertListEqual(
+            helpers.keyval_parse(' John  : Doe  , Jane :  Smith '), 
+            [('John', 'Doe'), ('Jane', 'Smith')]
+        )
+    
+    def test_kval_single(self):
+        """Test that a single value still returns a list"""
+        self.assertListEqual(
+            helpers.keyval_parse('John:Doe'), 
+            [('John', 'Doe')]
+        )
+
+class EmptyIter(object):
+    """A mock iterable object with zero length for testing empty()"""
+    def __len__(self):
+        return 0
+
+class TestBoolHelpers(unittest.TestCase):
+    """Test the boolean check functions is_true, is_false, as well as empty()"""
+
+    falsey = ['false', 'FALSE', None, False, '', 0, '0', 'no', 'null']
+    truthy = [True, 'TRUE', 'true', 'yes', 'y', '1', 1]
+    empty_vals = [None, '']
+    empty_lst = empty_vals + [[], (), set(), {}, EmptyIter()]
+    empty_zero = empty_vals + [0, '0']
+
+    def test_isfalse_falsey(self):
+        for f in self.falsey:
+            self.assertTrue(helpers.is_false(f), msg=f"is_false({repr(f)}")
+    
+    def test_isfalse_truthy(self):
+        for f in self.truthy:
+            self.assertFalse(helpers.is_false(f), msg=f"!is_false({repr(f)}")
+    
+    def test_istrue_truthy(self):
+        for f in self.truthy:
+            self.assertTrue(helpers.is_true(f), msg=f"is_true({repr(f)}")
+
+    def test_istrue_falsey(self):
+        for f in self.falsey:
+            self.assertFalse(helpers.is_true(f), msg=f"!is_true({repr(f)}")
+    
+    def test_empty_vals(self):
+        for f in self.empty_vals:
+            self.assertTrue(helpers.empty(f), msg=f"empty({repr(f)})")
+
+    def test_empty_lst(self):
+        for f in self.empty_lst:
+            self.assertTrue(helpers.empty(f, itr=True), msg=f"empty({repr(f)})")
+    
+    def test_empty_zero(self):
+        for f in self.empty_zero:
+            self.assertTrue(helpers.empty(f, zero=True), msg=f"empty({repr(f)})")
+
+    def test_empty_combined(self):
+        for f in self.empty_zero + self.empty_lst:
+            self.assertTrue(helpers.empty(f, zero=True, itr=True), msg=f"empty({repr(f)})")
+    
+    def test_notempty(self):
+        # Basic string test
+        self.assertFalse(helpers.empty('hello'))
+        # Integer test
+        self.assertFalse(helpers.empty(1, zero=True))
+        # Iterable tests
+        self.assertFalse(helpers.empty(['world'], itr=True))
+        self.assertFalse(helpers.empty(('world',), itr=True))
+        self.assertFalse(helpers.empty({'hello': 'world'}, itr=True))
+    
+
+if __name__ == '__main__':
+    unittest.main()
+
+"""
+    +===================================================+
+    |                 © 2019 Privex Inc.                |
+    |               https://www.privex.io               |
+    +===================================================+
+    |                                                   |
+    |        Originally Developed by Privex Inc.        |
+    |                                                   |
+    |        Core Developer(s):                         |
+    |                                                   |
+    |          (+)  Chris (@someguy123) [Privex]        |
+    |          (+)  Kale (@kryogenic) [Privex]          |
+    |                                                   |
+    +===================================================+
+
+Copyright 2019     Privex Inc.   ( https://www.privex.io )
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of 
+this software and associated documentation files (the "Software"), to deal in 
+the Software without restriction, including without limitation the rights to use, 
+copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the 
+Software, and to permit persons to whom the Software is furnished to do so, 
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all 
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, 
+INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A 
+PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT 
+HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION 
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE 
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+"""