cdxcore 0.1.5__py3-none-any.whl → 0.1.9__py3-none-any.whl

cdxcore/util.py

@@ -1,5 +1,17 @@
 """
-Basic utilities for Python such as type management, formatting, some trivial timers
+Overview
+--------
+
+Basic utilities for Python such as type management, formatting, some trivial timers.
+
+Import
+------
+.. code-block:: python
+
+    import cdxcore.util as util
+    
+Documentation
+-------------
 """
 
 import datetime as datetime
@@ -12,9 +24,7 @@ from collections import OrderedDict
 from sortedcontainers import SortedDict
 import numpy as np
 import pandas as pd
-import os as os
-import warnings as warnings
-from collections.abc import Callable, Collection
+from .err import fmt, _fmt, verify, error, warn_if, warn #NOQA
 
 # =============================================================================
 # basic indentification short cuts
@@ -22,187 +32,83 @@ from collections.abc import Callable, Collection
 
 __types_functions = None
 
-def types_functions():
-    """ Returns all types.* considered function """
+#: a set of all ``types`` considered functions
+def types_functions() -> tuple[type]:
+    """ Returns a set of all ``types`` considered functions """
     global __types_functions
     if __types_functions is None:
-        __types_functions = set()
-        try: __types_functions.add(types.FunctionType)
+        fs = set()
+        try: fs.add(types.FunctionType)
         except: pass
-        try: __types_functions.add(types.LambdaType)
+        try: fs.add(types.LambdaType)
         except: pass
-        try: __types_functions.add(types.CodeType)
+        try: fs.add(types.CodeType)
         except: pass
         #types.MappingProxyType
         #types.SimpleNamespace
-        try: __types_functions.add(types.GeneratorType)
+        try: fs.add(types.GeneratorType)
         except: pass
-        try: __types_functions.add(types.CoroutineType)
+        try: fs.add(types.CoroutineType)
         except: pass
-        try: __types_functions.add(types.AsyncGeneratorType)
+        try: fs.add(types.AsyncGeneratorType)
         except: pass
-        try: __types_functions.add(types.MethodType)
+        try: fs.add(types.MethodType)
         except: pass
-        try: __types_functions.add(types.BuiltinFunctionType)
+        try: fs.add(types.BuiltinFunctionType)
         except: pass
-        try: __types_functions.add(types.BuiltinMethodType)
+        try: fs.add(types.BuiltinMethodType)
         except: pass
-        try: __types_functions.add(types.WrapperDescriptorType)
+        try: fs.add(types.WrapperDescriptorType)
         except: pass
-        try: __types_functions.add(types.MethodWrapperType)
+        try: fs.add(types.MethodWrapperType)
         except: pass
-        try: __types_functions.add(types.MethodDescriptorType)
+        try: fs.add(types.MethodDescriptorType)
         except: pass
-        try: __types_functions.add(types.ClassMethodDescriptorType)
+        try: fs.add(types.ClassMethodDescriptorType)
         except: pass
         #types.ModuleType,
         #types.TracebackType,
         #types.FrameType,
-        try: __types_functions.add(types.GetSetDescriptorType)
+        try: fs.add(types.GetSetDescriptorType)
         except: pass
-        try: __types_functions.add(types.MemberDescriptorType)
+        try: fs.add(types.MemberDescriptorType)
         except: pass
-        try: __types_functions.add(types.DynamicClassAttribute)
+        try: fs.add(types.DynamicClassAttribute)
         except: pass
-        __types_functions = tuple(__types_functions)
+        __types_functions = tuple(fs)
     return __types_functions
 
-def isFunction(f) -> bool:
+def is_function(f) -> bool:
     """
-    Checks whether 'f' is a function in an extended sense.
-    Check 'types_functions' for what is tested against.
-    In particular it does not test positive for properties.    
+    Checks whether ``f`` is a function in an extended sense.
+    
+    Check :func:`cdxcore.util.types_functions` for what is tested against.
+    In particular ``is_function`` does not test positive for properties.    
     """
     return isinstance(f,types_functions())
 
-def isAtomic( o ):
-    """ Returns true if 'o' is a string, int, float, date or bool, or a numpy generic """
+def is_atomic( o ):
+    """
+    Whether an element is atomic.
+    
+    Returns ``True`` if ``o`` is a
+    ``string``, ``int``, ``float``, :class:`datedatime.date`, ``bool``, 
+    or a :class:`numpy.generic`
+    """
     if type(o) in [str,int,bool,float,datetime.date]:
         return True
     if isinstance(o,np.generic):
         return True
     return False
 
-def isFloat( o ):
-    """ Checks whether a type is a float """
+def is_float( o ):
+    """ Checks whether a type is a ``float`` which includes numpy floating types """
     if type(o) is float:
         return True
     if isinstance(o,np.floating):
         return True
     return False
 
-# =============================================================================
-# exceptions
-# =============================================================================
-
-def _verify( cond : bool, msgf : Callable, exception : Exception = Exception, **msg_kwargs ):
-    """
-    Verifies 'cond' and raises an exception of type 'exception' with message 'msgf()' if cond is not True.
-    The message itself is generated by calling msgf() if it is a callable, or by str.fomrat(msgf,**msg_kwargs) if it is a string.
-    That means that the message is only formatted if the conditon was not met and an exception is to be thrown:
-    
-    Functional use case:    
-        x=1
-        verify(x==1, lambda : f"Error: x is {x}")   # <- the use of 'lambda' delays generation of the error message
-
-    If 'msgf' is a string, then str.format(msgf, **msg_kwargs) is called:
-        x=1
-        verify(x==1, "Error: x is {x}", x=x )       # <- do *not* use f-string !
-    
-    Basically    
-        verify(cond, msgf, exception, **msg_kwargs)
-    is functionally equivalent to
-       if not cond: raise exception(msgf())
-    or, if 'msgf' is a string:
-       if not cond: raise exception(str.format(msgf,**msg_kwargs))
-   
-    Parameters
-    ----------
-        cond:
-            condition to be tested. An exception is thrown if it is not true
-        msgf:
-            function to call to generate the error message if 'cond' is False,
-            or str.format formatting string using {} [this is *not* an f-string].
-            In both case the message is only generated if the conditon 'cond' is False.
-
-            Two main use cases:
-                For complicated formatting, use a lambda function which returns an f-string.
-                For simple formatting, use a non-fstring.
-                    exception:
-                        
-            Anything the function msfg() returns is passed to the constructor
-            of the 'exception', except if msgf() returns itself an Exception
-            object. In that case that will be raised.
-            The function msgf cannot return None.
-        exception:
-            Exception type to raise.
-        msg_kwargs :
-            Keywords for msgf if msgf is a string; must be empty otherwise.
-    """    
-    if not bool(cond):
-        if not isinstance( msgf, str ):
-            assert len(msg_kwargs) == 0, ("Superflous arguments passed", str(msg_kwargs)[:100] )
-            msg = msgf()
-            assert not msg is None, ("'msgf' returned None")
-            if isinstance(msg, Exception):
-                raise msg
-        else:
-            msg = str.format(msgf,**msg_kwargs)
-        raise exception( msg )
-
-_warn_skips = (os.path.dirname(__file__),)
-
-def _warn( message : str, category : Warning = RuntimeWarning, stack_level : int = 1 ):
-    """ Standard warning """
-    warnings.warn( message=str(message), category=category, stacklevel=stack_level, skip_file_prefixes=_warn_skips )
-
-def _warn_if( cond : bool, msgf : Callable, *, category : Warning = RuntimeWarning, stack_level : int = 1, **msg_kwargs ):
-    """
-    Tests 'cond' and issues a warning with message 'msgf()'.
-    The message itself is generated by calling msgf() if it is a callable, or by str.fomrat(msgf,**msg_kwargs) if it is a string.
-    That means that the message is only formatted if the conditon was met and the warning is printed.
-    
-    Functional use case:    
-        x=1
-        warn_if(x!=0, lambda : f"Warn: x is {x}")   # <- the use of 'lambda' delays generation of the warning message
-
-    If 'msgf' is a string, then str.format(msgf, **msg_kwargs) is called:
-        x=1
-        verify(x!=1, "Warn: x is {x}", x=x )             # <- do *not* use f-string !
-    
-    Basically    
-        warn_if(cond, msgf, exception, **msg_kwargs)        
-    is functionally equivalent to
-       if cond: warn(msgf())
-    or, if 'msgf' is a string:
-       if cond: warn(str.format(msgf,**msg_kwargs))
-   
-    Parameters
-    ----------
-        cond:
-            condition to be tested. An exception is thrown if it is not true
-        msgf:
-            function to call to generate the error message if 'cond' is False,
-            or str.format formatting string using {} [this is *not* an f-string].
-            In both case the message is only generated if the conditon 'cond' is False.
-
-            Two main use cases:
-                For complicated formatting, use a lambda function which returns an f-string.
-                For simple formatting, use a non-fstring.
-                    exception:
-        exception:
-            Exception type to raise.
-        msg_kwargs :
-            Keywords for msgf if msgf is a string; must be empty otherwise.
-    """    
-    if bool(cond):
-        if not isinstance( msgf, str ):
-            assert len(msg_kwargs) == 0, ("Superflous arguments passed?", str(msg_kwargs)[:100] )
-            msg = msgf()
-        else:
-            msg = str.format(msgf,**msg_kwargs)
-        _warn( msg, category=category, stack_level=stack_level )
-
 # =============================================================================
 # python basics
 # =============================================================================
@@ -210,6 +116,7 @@ def _warn_if( cond : bool, msgf : Callable, *, category : Warning = RuntimeWarni
 def _get_recursive_size(obj, seen=None):
     """
     Recursive helper for sizeof
+    :meta private: 
     """
     if seen is None:
         seen = set()  # Keep track of seen objects to avoid double-counting
@@ -222,7 +129,7 @@ def _get_recursive_size(obj, seen=None):
         return 0
     seen.add(id(obj))
 
-    if isinstance( obj, np.ndarray ):
+    if isinstance( obj, (np.ndarray, pd.DataFrame) ):
         size += obj.nbytes
     elif isinstance(obj, Mapping):
         for key, value in obj.items():
@@ -244,8 +151,11 @@ def _get_recursive_size(obj, seen=None):
 
 def getsizeof(obj):
     """
-    Approximates the size of 'obj'.
-    In addition to sys.getsizeof this function also iterates through embedded containers.
+    Approximates the size of an object.
+    
+    In addition to calling :func:`sys.getsizeof` this function
+    also iterates embedded containers, numpy arrays, and panda dataframes.
+    :meta private: 
     """
     return _get_recursive_size(obj,None)    
 
@@ -253,38 +163,22 @@ def getsizeof(obj):
 # string formatting
 # =============================================================================
 
-def _fmt( text : str, args = None, kwargs = None ) -> str:
-    """ Utility function. See fmt() """
-    if text.find('%') == -1:
-        return text
-    if not args is None and len(args) > 0:
-        assert kwargs is None or len(kwargs) == 0, "Cannot specify both 'args' and 'kwargs'"
-        return text % tuple(args)
-    if not kwargs is None and len(kwargs) > 0:
-        return text % kwargs
-    return text
-
-def fmt(text : str,*args,**kwargs) -> str:
-    """
-    String formatting made easy
-        text - pattern
-    Examples
-        fmt("The is one = %ld", 1)
-        fmt("The is text = %s", 1.3)
-        fmt("Using keywords: one=%(one)d, two=%(two)d", two=2, one=1)
+def fmt_seconds( seconds : float, *, eps : float = 1E-8 ) -> str:
     """
-    return _fmt(text,args,kwargs)
-
-def prnt(text : str,*args,**kwargs) -> str:
-    """ Prints a fmt() string. """
-    print(_fmt(text,args,kwargs))
-
-def write(text : str,*args,**kwargs) -> str:
-    """ Prints a fmt() string without EOL, e.g. uses print(fmt(..),end='') """
-    print(_fmt(text,args,kwargs),end='')
+    Generate format string for seconds, e.g. "23s"" for ``seconds=23``, or "1:10" for ``seconds=70``.
+    
+    Parameters
+    ----------
+    seconds : float
+        Seconds as a float.
+        
+    eps : float
+        anything below ``eps`` is considered zero. Default ``1E-8``.
 
-def fmt_seconds( seconds : float, *, eps : float = 1E-8 ) -> str:
-    """ Print nice format string for seconds, e.g. '23s' for seconds=23, or 1:10 for seconds=70 """
+    Returns
+    -------
+    Seconds : string
+    """
     assert eps>=0., ("'eps' must not be negative")
     if seconds < -eps:
         return "-" + fmt_seconds(-seconds, eps=eps)
@@ -304,19 +198,25 @@ def fmt_seconds( seconds : float, *, eps : float = 1E-8 ) -> str:
 
 def fmt_list( lst : list, *, none : str = "-", link : str = "and", sort : bool = False ) -> str:
     """
-    Returns a nicely formatted list of string with commas
-
+    Returns a formatted string of a list, its elements separated by commas and (by default) a final 'and'.
+    
+    If the list is ``[1,2,3]`` then the function will return ``"1, 2 and 3"``.
+    
     Parameters
     ----------
-        lst  : list. The list() operator is applied to it, so it will resolve dictionaries and generators.
-        none : string used when list was empty
-        link : string used to connect the last item. Default is 'and'
-               If the list is [1,2,3] then the function will return 1, 2 and 3
-        sort : whether to sort the list
+    lst  : list.
+        The ``list()`` operator is applied to ``lst``, so it will resolve dictionaries and generators.
+    none : str, optional
+        String to be used when ``list`` is empty. Default is ``"-"``.
+    link : str, optional
+        String to be used to connect the last item. Default is ``"and"``.
+    sort : bool, optional
+        Whether to sort the list. Default is ``False``.
 
     Returns
     -------
-        String of the list.
+    Text : str
+        String.
     """
     if lst is None:
         return str(none)
@@ -343,21 +243,27 @@ def fmt_list( lst : list, *, none : str = "-", link : str = "and", sort : bool =
 
 def fmt_dict( dct : dict, *, sort : bool = False, none : str = "-", link : str = "and" ) -> str:
     """
-    Return a nice readable representation of a dictionary
-    This assumes that the elements of the dictionary itself can be formatted well with 'str()'
-
-    For a dictionary dict(a=1,b=2,c=3) this function will return a: 1, b: 2, and c: 3
+    Return a readable representation of a dictionary.
+    
+    This assumes that the elements of the dictionary itself can be formatted well with :func:`str()`.
+    
+    For a dictionary ``dict(a=1,b=2,c=3)`` this function will return ``"a: 1, b: 2, and c: 3"``.
 
     Parameters
     ----------
-        x : dict
-        sort : whether to sort the keys
-        none : string to be used if dictionary is empty
-        link : string to be used to link the last element to the previous string
+    dct : dict
+        The dictionary to format.
+    sort : bool, optional
+        Whether to sort the keys. Default is ``False``.
+    none :  str, optional
+        String to be used if dictionary is empty. Default is ``"-"``.
+    link : str, optional
+        String to be used to link the last element to the previous string. Default is ``"and"``.
 
     Returns
     -------
-        String
+    Text : str
+        String.
     """
     if len(dct) == 0:
         return str(none)
@@ -368,46 +274,52 @@ def fmt_dict( dct : dict, *, sort : bool = False, none : str = "-", link : str =
     strs = [ str(k) + ": " + str(dct[k]) for k in keys ]
     return fmt_list( strs, none=none, link=link, sort=False )
 
-def fmt_digits( uint : int, sep : str = "," ):
+def fmt_digits( integer : int, sep : str = "," ):
     """
-    String representation of 'uint' with 1000 separators
-    So 10000 becomes "10,000".
+    String representation of an integer with 1000 separators: 10000 becomes "10,000".
     
     Parameters
     --------
-        uint : integer
-            The number. The function will int() the input which allows
-            for processing of a number of inputs (such as strings) but
-            might cut off floating point numbers.
-        sep : str
-            Separator, ","" by default
+    integer : int
+        The number. The function will :func:`int()` the input which allows
+        for processing of a number of inputs (such as strings) but
+        might cut off floating point numbers.
+        
+    sep : str
+        Separator; ``","`` by default.
+
     Returns
     -------
-        String
-    """
-    if isinstance( uint, float ):
-        raise ValueError("float value provided", uint)
-    uint = int(uint)
-    if uint < 0:
-        return "-" + fmt_digits( -uint, sep )
-    assert uint >= 0
-    if uint < 1000:
-        return "%ld" % uint
+    Text : str
+        String.
+    """
+    if isinstance( integer, float ):
+        raise ValueError("float value provided", integer)
+    integer = int(integer)
+    if integer < 0:
+        return "-" + fmt_digits( -integer, sep )
+    assert integer >= 0
+    if integer < 1000:
+        return "%ld" % integer
     else:
-        return fmt_digits(uint//1000, sep) + ( sep + "%03ld" % (uint % 1000) )
+        return fmt_digits(integer//1000, sep) + ( sep + "%03ld" % (integer % 1000) )
 
 def fmt_big_number( number : int ) -> str:
     """
     Return a formatted big number string, e.g. 12.35M instead of all digits.
+    
     Uses decimal system and "B" for billions.
-    Use fmt_big_byte_number for byte sizes ie 1024 units.
+    Use :func:`cdxcore.util.fmt_big_byte_number` for byte sizes i.e. 1024 units.
 
     Parameters
     ----------
-        number : int
+    number : int
+        Number to format.
+
     Returns
     -------
-        String number
+    Text : str
+        String.
     """
     if isinstance( number, float ):
         raise ValueError("float value provided", number)
@@ -439,20 +351,31 @@ def fmt_big_number( number : int ) -> str:
         return "%gK" % number
     return str(number)
 
-def fmt_big_byte_number( byte_cnt : int, str_B = True ) -> str:
+def fmt_big_byte_number( byte_cnt : int, str_B : bool = True ) -> str:
     """
-    Return a formatted big number string, e.g. 12.35M instead of all digits.
+    Return a formatted big byte string, e.g. 12.35MB.
+    Uses 1024 as base for KB.
+    
+    Use :func:`cdxcore.util.fmt_big_number` for converting general numbers
+    using 1000 blocks instead.
 
     Parameters
     ----------
-        byte_cnt : int
-        str_B : bool
-            If true, return GB, MB and KB. If False, return G, M, K
-            If 'byte_cnt' is less than 10KB, then this will add 'bytes'
-            e.g. '1024 bytes'
+    byte_cnt : int
+        Number of bytes.
+        
+    str_B : bool
+        If ``True``, return ``"GB"``, ``"MB"`` and ``"KB"`` units.
+        Moreover, if ``byte_cnt` is less than 10KB, then this will add ``"bytes"``
+        e.g. ``"1024 bytes"``.
+
+        If ``False``, return ``"G"``, ``"M"`` and ``"K"`` only, and do not
+        add ``"bytes"`` to smaller ``byte_cnt``.
+
     Returns
     -------
-        String number
+    Text : str
+        String.
     """
     if isinstance( byte_cnt, float ):
         raise ValueError("float value provided", byte_cnt)
@@ -487,36 +410,45 @@ def fmt_big_byte_number( byte_cnt : int, str_B = True ) -> str:
         return str(byte_cnt) if not str_B else f"{byte_cnt} bytes"
     return s if not str_B else s+"B"
 
-def fmt_datetime(dt        : datetime.datetime, *, 
+def fmt_datetime(dt        : datetime.datetime|datetime.date|datetime.time, *, 
                  sep       : str = ':', 
                  ignore_ms : bool = False,
                  ignore_tz : bool = True
                  ) -> str:
     """
-    Returns string for 'dt' of the form "YYYY-MM-DD HH:MM:SS" if 'dt' is a datetime,
-    or a the respective version for time or date.
+    Convert :class:`datetime.datetime` to a string of the form "YYYY-MM-DD HH:MM:SS".
     
-    Microseconds are added as digits:
-        "YYYY-MM-DD HH:MM:SS,MICROSECONDS"
+    If present, microseconds are added as digits::
+        
+        YYYY-MM-DD HH:MM:SS,MICROSECONDS
+        
+    Optinally a time zone is added via::
         
-    Optinally a time zone is added via:
-        "YYYY-MM-DD HH:MM:SS+HH"
-        "YYYY-MM-DD HH:MM:SS+HH:MM"
+        YYYY-MM-DD HH:MM:SS+HH
+        YYYY-MM-DD HH:MM:SS+HH:MM
         
+    Output is reduced accordingly if ``dt`` is a :class:`datetime.time`
+    or :class:`datetime.date`.
+    
     Parameters
     ----------
-        dt : datetime, date, or time
-            String represent this.
-        sep : str
-            Seperator for hours, minutes, seconds. The default ':' looks better
-            but is not suitable for filenames
-        ignore_ms : bool
-            Whether to ignore microseconds. Default False
-        ignore_tz : bool
-            Whether to ignore the time zone. Default True
+    dt : :class:`datetime.datetime`, :class:`datetime.date`, or :class:`datetime.time`
+        Input.
+
+    sep : str, optional
+        Seperator for hours, minutes, seconds. The default ``':'`` is most appropriate for viusalization
+        but is not suitable for filenames.
+
+    ignore_ms : bool, optional
+        Whether to ignore microseconds. Default ``False``.
+
+    ignore_tz : bool, optional
+        Whether to ignore the time zone. Default ``True``.
+
     Returns
     -------
-        String, see above.
+    Text : str
+        String.
     """
     if not isinstance(dt, datetime.datetime):
         if isinstance(dt, datetime.date):
@@ -552,12 +484,13 @@ def fmt_datetime(dt        : datetime.datetime, *,
     
 def fmt_date(dt : datetime.date) -> str:
     """
-    Returns string representation for date 'dt' of the form YYYY-MM-DD
-    If passed a datetime, it will extract its date().
+    Returns string representation for a date of the form "YYYY-MM-DD".
+    
+    If passed a :class:`datetime.datetime`, it will format its :func:`datetime.datetime.date`.
     """
     if isinstance(dt, datetime.datetime):
         dt = dt.date()
-    assert isinstance(dt, datetime.date), "'dt' must be datetime.date. Found %s" % type(dt)
+    assert isinstance(dt, datetime.date), "'dt' must be :class:`datetime.date`. Found %s" % type(dt)
     return f"{dt.year:04d}-{dt.month:02d}-{dt.day:02d}"
 
 def fmt_time(dt        : datetime.time, *,
@@ -565,34 +498,46 @@ def fmt_time(dt        : datetime.time, *,
              ignore_ms : bool = False
              ) -> str:
     """
-    Returns string for 'dt' of the form "HH:MM:SS" if 'dt'.
+    Convers a time to a string with format "HH:MM:SS".
     
-    Microseconds are added as digits:
-        "HH:MM:SS,MICROSECONDS"
+    Microseconds are added as digits::
+
+        HH:MM:SS,MICROSECONDS
         
-    Optinally a time zone is added via:
-        "HH:MM:SS+HH"
-
-    If passed a datetime, it will extract its time().
-    Note that while datetime.time objects may carry a tzinfo object,
-    the corresponding otcoffset() function returns None without
-    providing a 'dt' parameter, see https://docs.python.org/3/library/datetime.html#tzinfo-objects
-    We bypass this inconsistency by only allowing datetime to process time zones.
+    If passed a :class:`datetime.datetime`, then this function will format
+    only its :func:`datetime.datetime.time` part.
+
+    **Time Zones**
+    
+    Note that while :class:`datetime.time` objects may carry a ``tzinfo`` time zone object,
+    the corresponding :func:`datetime.time.otcoffset` function returns ``None`` if we donot
+    provide a ``dt`` parameter, see
+    `tzinfo documentation <https://docs.python.org/3/library/datetime.html#tzinfo-objects>`__.
+    That means :func:`datetime.time.otcoffset` is only useful if we have :class:`datetime.datetime`
+    object at hand. 
+    That makes sense as a time zone can chnage date as well.
     
+    We therefore here do not allow ``dt`` to contain
+    a time zone.
+        
+    Use :func:`cdxcore.util.fmt_datetime` for time zone support
         
     Parameters
     ----------
-        dt : time
-            String represent this.
-        sep : str
-            Seperator for hours, minutes, seconds. The default ':' looks better
-            but is not suitable for filenames
-        ignore_ms : bool
-            Whether to ignore microseconds. Default False
+    dt : :class:`datetime.time`
+        Input.
+    sep : str, optional
+    
+        Seperator for hours, minutes, seconds. The default ``':'`` is most appropriate for viusalization
+        but is not suitable for filenames.
+        
+    ignore_ms : bool
+        Whether to ignore microseconds. Default is ``False``.
             
     Returns
     -------
-        String, see above.
+    Text : str
+        String.
     """
     if isinstance(dt, datetime.datetime):
         dt = dt.timetz()
@@ -606,28 +551,33 @@ def fmt_time(dt        : datetime.time, *,
 def fmt_timedelta(dt      : datetime.timedelta, *,
                   sep     : str = "" )  -> str:
     """
-    Returns string representation for a time delta in the form DD:HH:MM:SS,MS
-    
+    Returns string representation for a time delta in the form "DD:HH:MM:SS,MS".
     
     Parameters
     ----------
-        dt : timedelta
-            Timedelta.
-        sep :
-            Identify the three separators: between days and HMS and between microseconds:
-                DD*HH*MM*SS*MS
-                  0  1  1  2
-            'sep' can be a string, in which case:
-                * If it is an empty string, all separators are ''
-                * A single character will be reused for all separators
-                * If the string has length 2, then the last character is used for '2'
-                * If the string has length 3, then the chracters are used accordingly
-            'sep' can also be a collection ie a tuple or list. In this case each element
-            is used accordingly.
+    dt : :class:`datetime.timedelta`
+        Timedelta.
+        
+    sep :
+        Identify the three separators: between days, and HMS and between microseconds:
+        
+        .. code-block:: python
+
+            DD*HH*MM*SS*MS
+              0  1  1  2
+
+        * ``sep`` can be a string, in which case:
+            * If it is an empty string, all separators are ``''``.
+            * A single character will be reused for all separators.
+            * If the string has length 2, then the last character is used for ``'2'``.
+            * If the string has length 3, then the chracters are used accordingly.
+
+        * ``sep`` can also be a collection ie a ``tuple`` or ``list``. In this case each element is used accordingly.
             
     Returns
     -------
-        String with leading sign. Returns "" if timedelta is 0.
+    Text : str
+        String with leading sign. Returns "" if ``timedelta`` is 0.
     """
     assert isinstance(dt, datetime.timedelta), "'dt' must be datetime.timedelta. Found %s" % type(dt)
 
@@ -690,10 +640,10 @@ def fmt_timedelta(dt      : datetime.timedelta, *,
     return f"{sign}{days}d{rest}"
 
 def fmt_now() -> str:
-    """ Returns string for 'now' """
+    """ Returns the :func:`cdxcore.util.fmt_datetime` applied to :func:`datetime.datetime.now` """
     return fmt_datetime(datetime.datetime.now())
 
-DEF_FILE_NAME_MAP = {
+DEF_FILE_NAME_MAP = {  
                  '/' : "_",
                  '\\': "_",
                  '|' : "_",
@@ -703,144 +653,109 @@ DEF_FILE_NAME_MAP = {
                  '?' : "!",
                  '*' : "@",
                  }
-INVALID_FILE_NAME_CHARCTERS = set(DEF_FILE_NAME_MAP)
+"""
+Default map from characters which cannot be used for filenames under either
+Windows or Linux to valid characters.
+"""
 
-def fmt_filename( s : str , by : str = DEF_FILE_NAME_MAP ):
-    """
-    Replaces invalid filename characters by a differnet character.
+def fmt_filename( filename : str , by : str | Mapping = "default" ) -> str:
+    r"""
+    Replaces invalid filename characters such as `\\', ':', or '/' by a differnet character.
     The returned string is technically a valid file name under both windows and linux.
     
     However, that does not prevent the filename to be a reserved name, for example "." or "..".
     
     Parameters
     ----------
-        s : str
-            Input string
-        by :
-            Either a single character or a dictionary with elements.
+    filename : str
+        Input string.
+        
+    by : str | Mapping, optional.
+        A dictionary of characters and their replacement.
+        The default value ``"default"`` leads to using :data:`cdxcore.util.DEF_FILE_NAME_MAP`.
+    
+    Returns
+    -------
+    Text : str
+        Filename
     """
+    if not isinstance(by, Mapping):
+        if not isinstance(by, str):
+            raise ValueError(f"'by': must be a Mapping or 'default'. Found type {type(by).__qualname__}")
+        if by != "default":
+            raise ValueError(f"'by': must be a Mapping or 'default'. Found string '{by}'")                            
+        by = DEF_FILE_NAME_MAP
 
-    if isinstance(by, Mapping):
-        for c in INVALID_FILE_NAME_CHARCTERS:
-            s = s.replace(c, by[c])
-    else:
-        assert isinstance(by, str), ("by: 'str' or mapping expected", type(by))
-        for c in INVALID_FILE_NAME_CHARCTERS:
-            s = s.replace(c, by)
-    return s
+    for c, cby in by.items():
+        filename = filename.replace(c, cby)
+    return filename
+fmt_filename.DEF_FILE_NAME_MAP = DEF_FILE_NAME_MAP
 
-class WriteLine(object):
+def is_filename( filename : str , by : str | Collection = "default" ) -> bool:
     """
-    Class to manage the current text output line.
-    This class is a thin wrapper around print(text + '\r', end='') or IPython.display.display()
-    to ensure the current line is cleared correctly when replaced with the next line.
-
-    Example 1 (how to use \r and \n)
-        write = WriteLine("Initializing...")
-        import time
-        for i in range(10):
-            time.sleep(1)
-            write("\rRunning %g%% ...", round(float(i+1)/float(10)*100,0))
-        write(" done.\nProcess finished.\n")
-
-    Example 2 (line length is getting shorter)
-        write = WriteLine("Initializing...")
-        import time
-        for i in range(10):
-            time.sleep(1)
-            write("\r" + ("#" * (9-i)))
-        write("\rProcess finished.\n")
-    """
-
-    def __init__(self, text : str = "", *kargs, **kwargs):
-        """
-        Creates a new WriteLine object which manages the current print output line.
-        Subsequent calls to __call__() will replace the text in the current line using `\r` in text mode, or a display() object in jupyter
-
-        Parameters
-        ----------
-            text : str
-                Classic formatting text. 'text' may not contain newlines (\n) except at the end.
-            kargs, kwargs:
-                Formatting arguments.
-        """
-        self._last_len        = 0
-        if text != "":
-            self(text,*kargs,**kwargs)
+    Tests whether a filename is indeed a valid filename.
 
-    def __call__(self, text : str, *kargs, **kwargs ):
-        """
-        Print lines of text.
-        The last line of 'text' becomes the current line and will be overwritten by the next line.
-
-        Parameters
-        ----------
-            text : str
-                Classic formatting text. 'text' may not contain newlines (\n) except at the end.
-            kargs, kwargs:
-                Formatting arguments.
-        """
-        text  = _fmt(text,kargs,kwargs)
-        lines = text.split("\n")
-        assert len(lines) > 0, "Internal error"
-
-        for line in lines[:-1]:
-            self._write_line(line)
-            self.cr()
-        if len(lines[-1]) > 0:
-            self._write_line(lines[-1])
-        sys.stdout.flush()
-
-    def cr(self):
-        """ Creates a new line. """
-        sys.stdout.write("\n")
-        sys.stdout.flush()
-        self._last_len    = 0
-
-    def _write_line(self, line):
-        """ Write a line; no newlines """
-        assert not '\n' in line, "Error: found newline in '%s'" % line
-        if line == "":
-            return
-        i    = line.rfind('\r')
-        if i == -1:
-            # no `\r': append text to current line
-            sys.stdout.write(line)
-            self._last_len += len(line)
-        else:
-            # found '\r': clear previous line and print new line
-            line = line[i+1:]
-            if len(line) < self._last_len:
-                sys.stdout.write("\r" + (" " * self._last_len)) # clear current line
-            sys.stdout.write("\r" + line)
-            self._last_len = len(line)
+    Parameters
+    ----------
+    filename : str
+        Supposed filename.
+        
+    by : str | Collection, optional
+        A collection of invalid characters.
+        The default value ``"default"`` leads to using
+        they keys of :data:`cdxcore.util.DEF_FILE_NAME_MAP`.
+    
+    Returns
+    -------
+    Validity : vool 
+        ``True`` if ``filename`` does not contain any invalid characters contained in ``by``.
+    """
+    
+    if not isinstance(by, Mapping):
+        if not isinstance(by, str):
+            raise ValueError(f"'by': must be a Mapping or 'default'. Found type {type(by).__qualname__}")
+        if by != "default":
+            raise ValueError(f"'by': must be a Mapping or 'default'. Found string '{by}'")                            
+        by = DEF_FILE_NAME_MAP
+
+    for c in by:
+        if c in filename:
+            return False
+    return True
 
 # =============================================================================
 # Conversion of arbitrary python elements into re-usable versions
 # =============================================================================
 
-# deprecated
 def plain( inn, *, sorted_dicts : bool = False,
                    native_np    : bool = False,
                    dt_to_str    : bool = False):
     """
     Converts a python structure into a simple atomic/list/dictionary collection such
     that it can be read without the specific imports used inside this program.
-    or example, objects are converted into dictionaries of their data fields.
+
+    For example, objects are converted into dictionaries of their data fields.
 
     Parameters
     ----------
-        inn          : some object
-        sorted_dicts : Use SortedDicts instead of dicts.
-        native_np    : convert numpy to Python natives.
-        dt_to_str    : convert date times to strings
+    inn :
+        some object.
+    sorted_dicts : bool, optional
+        use SortedDicts instead of dicts. Since Python 3.7 all dictionaries are sorted anyway.
+    native_np : bool, optional
+        convert numpy to Python natives.
+    dt_to_str : bool, optional
+        convert dates, times, and datetimes to strings.
 
-    Hans Buehler, Dec 2013
+    Returns
+    -------
+    Text : str
+        Filename
     """
     def rec_plain( x ):
         return plain( x, sorted_dicts=sorted_dicts, native_np=native_np, dt_to_str=dt_to_str )
     # basics
-    if isAtomic(inn) or inn is None:
+    if is_atomic(inn) or inn is None:
         return inn
     if isinstance(inn,(datetime.time,datetime.date,datetime.datetime)):
         return fmt_datetime(inn) if dt_to_str else inn
@@ -852,11 +767,11 @@ def plain( inn, *, sorted_dicts : bool = False,
         elif isinstance(inn, np.floating):
             return float(inn)
     # can't handle functions --> return None
-    if isFunction(inn) or isinstance(inn,property):
+    if is_function(inn) or isinstance(inn,property):
         return None
     # dictionaries
     if isinstance(inn,Mapping):
-        r  = { k: rec_plain(v) for k, v in inn.items() if not isFunction(v) and not isinstance(v,property) }
+        r  = { k: rec_plain(v) for k, v in inn.items() if not is_function(v) and not isinstance(v,property) }
         return r if not sorted_dicts else SortedDict(r)
     # pandas
     if not pd is None and isinstance(inn,pd.DataFrame):
@@ -877,10 +792,12 @@ def plain( inn, *, sorted_dicts : bool = False,
 # Misc Jupyter
 # =============================================================================
 
-def is_jupyter():
+def is_jupyter() -> bool:
     """
-    Wheher we operate in a jupter session
-    Somewhat unreliable function. Use with care
+    Whether we operate in a jupter session.
+    Somewhat unreliable function. Use with care.
+    
+    :meta private: 
     """
     parent_process = psutil.Process().parent().cmdline()[-1]
     return  'jupyter' in parent_process
@@ -892,8 +809,10 @@ def is_jupyter():
 class TrackTiming(object):
     """
     Simplistic class to track the time it takes to run sequential tasks.
-    Usage:
 
+    Usage::
+
+        from cdxcore.util import TrackTiming
         timer = TrackTiming()   # clock starts
 
         # do job 1
@@ -944,23 +863,28 @@ class TrackTiming(object):
         """ Returns dictionary of tracked texts """
         return self._tracked
 
-    def summary(self, frmat : str = "%(text)s: %(fmt_seconds)s", jn_fmt : str = ", " ) -> str:
+    def summary(self, fmat : str = "%(text)s: %(fmt_seconds)s", jn_fmt : str = ", " ) -> str:
         """
         Generate summary string by applying some formatting
 
         Parameters
         ----------
-            format : str
-                Format string. Arguments are 'text', 'seconds' (as int) and 'fmt_seconds' (as text, see fmt_seconds())
-            jn_fmt : str
-                String to be used between two texts
+        fmat : str, optional
+            Format string using ``%()``. Arguments are ```text``, ``seconds`` (as int) and ``fmt_seconds`` (a string).
+            
+            Default is ``"%(text)s: %(fmt_seconds)s"``.
+
+        jn_fmt : str, optional
+            String to be used between two texts. Default ``", " ``.
+            
         Returns
         -------
+        Summary : str
             The combined summary string
         """
         s = ""
         for text, seconds in self._tracked.items():
-            tr_txt = frmat % dict( text=text, seconds=seconds, fmt_seconds=fmt_seconds(seconds))
+            tr_txt = fmat % dict( text=text, seconds=seconds, fmt_seconds=fmt_seconds(seconds))
             s      = tr_txt if s=="" else s+jn_fmt+tr_txt
         return s
 
@@ -970,11 +894,14 @@ class TrackTiming(object):
 
 class Timer(object):
     """
-    Micro utility which allows keeing track of time using 'with'
-    
-    with Timer() as t:
-        .... do somthing ...
-        print(f"This took {t}.")
+    Micro utility to measure passage of time.
+
+    Example::
+
+        from cdxcore.util import Timer
+        with Timer() as t:
+            .... do somthing ...
+            print(f"This took {t}.")
     """
     
     def __init__(self):
@@ -982,6 +909,7 @@ class Timer(object):
         self.intv = None
         
     def reset(self):
+        """ Resets the timer. """
         self.time = time.time()
         self.intv = None
         
@@ -990,19 +918,26 @@ class Timer(object):
         return self
     
     def __str__(self):
+        """
+        Seconds elapsed since construction or :meth:`cdxcore.util.Timer.reset`,
+        formatted using :func:`cdxcore.util.Timer.fmt_seconds`
+        """
         return self.fmt_seconds
     
-    def interval_test( self, interval : float ):
-        """
-        Tests if 'interval' seconds have passed.
-        If yes, reset timer and return True. Otherwise return False
+    def interval_test( self, interval : float ) -> bool:
+        r"""
+        Tests if `interval` seconds have passed.
+        If yes, reset timer and return True. Otherwise return False.
         
-        Usage:
-        ------
+        Usage::
+            
+            from cdxcore.util import Timer
             tme = Timer()
             for i in range(n):
-                if tme.test_dt_seconds(2.): print(f"\r{i+1}/{n} done. Time taken so far {tme}.", end='', flush=True)
+                if tme.test_dt_seconds(2.):
+                    print(f"\r{i+1}/{n} done. Time taken so far {tme}.", end='', flush=True)
             print("\rDone. This took {tme}.")
+
         """
         if interval is None:
             self.intv = self.seconds
@@ -1017,18 +952,24 @@ class Timer(object):
 
     @property
     def fmt_seconds(self):
+        """
+        Seconds elapsed since construction or :meth:`cdxcore.util.Timer.reset`, formatted using :func:`cdxcore.util.fmt_seconds`
+        """
         return fmt_seconds(self.seconds)
 
     @property
-    def seconds(self):
+    def seconds(self) -> float:
+        """ Seconds elapsed since construction or :meth:`cdxcore.util.Timer.reset` """
         return time.time() - self.time
 
     @property
-    def minutes(self):
+    def minutes(self) -> float:
+        """ Minutes passed since construction or :meth:`cdxcore.util.Timer.reset` """
         return self.seconds / 60.
 
     @property
-    def hours(self):
+    def hours(self) -> float:
+        """ Hours passed since construction or :meth:`cdxcore.util.Timer.reset` """
         return self.minutes / 60.
 
     def __exit__(self, *kargs, **wargs):