2.14.0 - new helpers.thread module + improved convert_datetime + fixes

 - `privex.helpers.thread` (new module)
    - Added `lock_acquire_timeout` context manager function, for acquiring locks on `threading.Lock` objects
      using a `with lock_acquire_timeout(lock)` context manager, allowing the use of a context manager, while still
      being able to set a timeout / control blocking, plus the option to raise an exception on timeout.

    - Added `BetterEvent` - a modified version of `threading.Event` with more flexibility, such as the ability to
      wait for "clear" state AND "set" state - not just "set" state.

    - Added `StopperThread` - a `threading.Thread` sub-class which comes with thread instance events allowing you
      to signal a thread to stop/start/pause/unpause without having to constantly re-create stop/pause signalling.

    - Added `SafeLoopThread` - based on `StopperThread`, which is a looping thread with stop/pause signalling support,
      along with two queue's pre-included on the instance: `in_queue` for sending objects to the thread,
      and `out_queue` for receiving objects from the thread.

    - Added `event_multi_wait` which allows for waiting on multiple thread Event's using `threading.Event.wait`, and
      some extra features if you pass Privex Helper's `BetterEvent` events instead of standard events.

 - `privex.helpers.converters`
    - `convert_datetime` can now handle `datetime.date` objects, and also attempts to fallback to converting
      the passed object into a string and parsing the string result if it's not a supported type.
    - Added aliases `parse_datetime` and `parse_date` for `convert_datetime`
    - Added aliases `parse_unixtime`, `parse_epoch` and `convert_epoch_datetime` for `convert_unixtime_datetime`

 - `privex.helpers.exceptions`
    - Added `LockConflict` exception for failed attempts at acquiring `threading.Lock` or `asyncio.Lock` objects.
    - Added `LockWaitTimeout` - a more specific sub-class of `LockConflict` for lock acquisition timeouts
    - Added `EventWaitTimeout` - for timeouts related to `threading.Event`

 - Possibly some other minor changes

**Unit Testing**

 - Adjusted timing for `tests.cache.test_async_memcached` to avoid race condition test bug where sometimes
   it would take too long to get the cache item to update it, and result in the item expiring before it can
   be updated.

 - Added more unit tests to `test_converters`
    - Test `convert_datetime` handling of `datetime.date` objects
    - Test `convert_datetime` handling of byte-strings
    - Test `convert_datetime` handling of just string dates without times

 - Added new `test_thread` module which tests a good portion of the new `privex.helpers.thread` module.

Author: Someguy123

local_tests.sh

@@ -52,7 +52,7 @@ USE_PYENV=$((USE_PYENV))
 # PY_VERS is an array which defines the local system python executables for each python version to run the tests for.
 [ -z ${PY_VERS+x} ] && PY_VERS=("python3.6" "python3.7" "python3.8")
 # PYENV_VERS is an array of Python version numbers to install & use for running tests if 'pyenv' is available.
-[ -z ${PYENV_VERS+x} ] && PYENV_VERS=("3.6.7" "3.7.1" "3.8.0")
+[ -z ${PYENV_VERS+x} ] && PYENV_VERS=("3.6.9" "3.7.1" "3.8.0")
 
 has_command pyenv && HAS_PYENV=1 || HAS_PYENV=0
 

privex/helpers/__init__.py

@@ -122,6 +122,11 @@
 except ImportError:
     log.debug('privex.helpers __init__ failed to import "geoip", not loading GeoIP2 helpers')
 
+try:
+    from privex.helpers.thread import *
+except ImportError:
+    log.debug('privex.helpers __init__ failed to import "thread", not loading python threading helpers')
+
 
 def _setup_logging(level=logging.WARNING):
     """
@@ -143,7 +148,7 @@ def _setup_logging(level=logging.WARNING):
 log = _setup_logging()
 name = 'helpers'
 
-VERSION = '2.13.0'
+VERSION = '2.14.0'
 
 
 

privex/helpers/converters.py

@@ -22,9 +22,9 @@
 
 
 """
-from datetime import datetime
+from datetime import datetime, date
 from decimal import Decimal
-from typing import Optional, Union
+from typing import Optional, Union, AnyStr
 
 
 from privex.helpers.common import empty, is_true, stringify
@@ -39,6 +39,8 @@
 YEAR = DAY * 365
 DECADE = YEAR * 10
 
+SUPPORTED_DT_TYPES = Union[str, bytes, int, datetime, date, AnyStr]
+
 
 def convert_datetime(d, if_empty=None, fail_empty=False, **kwargs) -> Optional[datetime]:
     """
@@ -79,6 +81,10 @@ def convert_datetime(d, if_empty=None, fail_empty=False, **kwargs) -> Optional[d
         if d.tzinfo is None and _tzinfo is not None:
             d = d.replace(tzinfo=_tzinfo)
         return d
+    
+    # For datetime.date objects, we first convert them into a string, then we can parse them into a datetime + set tzinfo
+    if isinstance(d, date):
+        d = str(d)
 
     d = stringify(d) if isinstance(d, bytes) else d
 
@@ -110,11 +116,25 @@ def convert_datetime(d, if_empty=None, fail_empty=False, **kwargs) -> Optional[d
     if empty(d):
         if fail_empty: raise AttributeError("Error converting datetime. Parameter 'd' was empty!")
         return if_empty
+    
+    try:
+        log.debug("Passed object is not a supported type. Object type: %s || object repr: %s", type(d), repr(d))
+        log.debug("Calling convert_datetime with object casted to string: %s", str(d))
+        _d = convert_datetime(str(d), fail_empty=True)
+        d = _d
+    except Exception as e:
+        log.info("Converted passed object with str() to try and parse string version, but failed.")
+        log.info("Exception thrown from convert_datetime(str(d)) was: %s %s", type(e), str(e))
+        d = None   # By setting d to None, it will trigger the ValueError code below.
+    
     if not isinstance(d, datetime):
         raise ValueError('Timestamp must be either a datetime object, or an ISO8601 string...')
     return d
 
 
+parse_datetime = parse_date = convert_datetime
+
+
 def convert_unixtime_datetime(d: Union[str, int, float, Decimal], if_empty=None, fail_empty=False) -> datetime:
     """Convert a unix timestamp into a :class:`datetime.datetime` object"""
     from dateutil.tz import tzutc
@@ -134,6 +154,9 @@ def convert_unixtime_datetime(d: Union[str, int, float, Decimal], if_empty=None,
     return t
 
 
+parse_unixtime = parse_epoch = convert_epoch_datetime = convert_unixtime_datetime
+
+
 def convert_bool_int(d, if_empty=0, fail_empty=False) -> int:
     """Convert a boolean ``d`` into an integer (``0`` for ``False``, ``1`` for ``True``)"""
     if type(d) is int: return 1 if d >= 1 else 0
@@ -153,6 +176,7 @@ def convert_int_bool(d, if_empty=False, fail_empty=False) -> bool:
 
 __all__ = [
     'convert_datetime', 'convert_unixtime_datetime', 'convert_bool_int', 'convert_int_bool',
+    'parse_date', 'parse_datetime', 'parse_epoch', 'parse_unixtime', 'convert_epoch_datetime',
     'MINUTE', 'HOUR', 'DAY', 'MONTH', 'YEAR', 'DECADE',
 ]
 

privex/helpers/exceptions.py

@@ -141,3 +141,25 @@ class InvalidHost(PrivexException, ValueError):
     """Raised when a passed IP address or hostname/domain is invalid."""
     pass
 
+
+class LockConflict(PrivexException):
+    """
+    Raised when attempting to acquire a lock with a :class:`threading.Lock` or :class:`asyncio.Lock`, and the lock object
+    is already locked.
+
+    This would only be raised either when non-blocking acquisition was requested, or the blocking wait timed out.
+    """
+
+
+class LockWaitTimeout(LockConflict):
+    """
+    Sub-class of :class:`.LockConflict` - only to be raised when a timeout has been reached while waiting
+    to acquire a :class:`threading.Lock`
+    """
+
+
+class EventWaitTimeout(PrivexException):
+    """
+    Raised when a timeout has been reached while waiting for an event (:class:`threading.Event`) to be signalled.
+    """
+