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

cdxcore/uniquehash.py

@@ -1,6 +1,54 @@
 """
-Basic utilities for Python
-Hans Buehler 2022
+Overview
+--------
+
+Framework for producing unique hashes for various Python elements. Hashing is key for caching strategies and managing data pipelines effectively.
+The module contains a range of utility functions to ease implementation of pipelines and other tasks where hashes of data are required.
+
+The functionality here follows by default important design principles which are discussed in :func:`cdxcore.uniquehash.UniqueHash.__init__`,
+such as
+
+* Members of objects, and elements of dictionaries which start with "_" are ignored.
+* Member functions of objects or dictionaries are ignored.
+* Dictionaries are assumed to be order-invariant, even though Python now
+  `maintains construction order for objects <https://docs.python.org/3/whatsnew/3.6.html#whatsnew36-compactdict>`__
+  and therefore also objects.
+
+Example::
+
+    class A(object):
+        def __init__(self, x):
+            self.x = x
+            self._y = x*2  # protected member will not be hashed by default
+    
+    from cdxcore.uniquehash import UniqueHash
+    uniqueHash = UniqueHash(length=12)
+    a = A(2)
+    print( uniqueHash(a) ) # --> "2d1dc3767730"
+
+The module contains a few pre-defined hash functions with different hash lengths:
+    
+* :func:`cdxcore.uniquehash.unique_hash8`
+* :func:`cdxcore.uniquehash.unique_hash16`
+* :func:`cdxcore.uniquehash.unique_hash32`
+* :func:`cdxcore.uniquehash.unique_hash48`
+* :func:`cdxcore.uniquehash.unique_hash64`
+
+
+Related functionality
+---------------------
+
+:func:`cdxcore.subdir.SubDir.cache` implements a lightweight versioned, hash-based caching mechanism
+using :class:`cdxcore.uniquehash.UniqueHash`.
+
+Import
+------
+.. code-block:: python
+
+    import cdxcore.uniquehash as uniquehash
+    
+Documentation
+-------------
 """
 
 import datetime as datetime
@@ -12,10 +60,16 @@ from collections import OrderedDict
 import numpy as np
 import pandas as pd
 import struct as struct
-from .util import isFunction, DEF_FILE_NAME_MAP, fmt_filename
-from .prettyobject import PrettyObject
+from .util import is_function, DEF_FILE_NAME_MAP, fmt_filename
+from .pretty import PrettyObject
+from .verbose import Context
 
 def _qual_name(x, with_mod=False):
+    """
+    Obtain a descriptive name of qualified name and module name
+
+    :meta private:
+    """#@private
     q = getattr(x, '__qualname__', x.__name__)
     if with_mod:
         m = getattr(x, "__module__", None)
@@ -23,14 +77,140 @@ def _qual_name(x, with_mod=False):
             q += "@" + m
     return q
 
+class DebugTrace(object):
+    """
+    Base class for tracing hashing operations. 
+    
+    Use either :class:`cdxcore.uniquehash.DebugTraceCollect` or
+    :class:`cdxcore.uniquehash.DebugTraceVerbose` for debugging. The latter prints out tracing during the computation
+    of a hash, while to former collects all this information in a simplistic data structure. Note that this can be quite memory intensive.
+    """
+    def _update( self, x, msg : str = None ):
+        """ Notify processing of `x`, with an optional process `msg`
+        :meta private:
+        """#@private
+        raise NotImplementedError()        
+    def _update_topic( self, x, msg : str = None ):
+        """ Notify processing of a topc `x` with message `msg`, and return a sub-trace context
+        :meta private:
+        """#@private
+        raise NotImplementedError()        
+    def _warning( self, msg : str):
+        """ Issue warning `msg`
+        :meta private:
+        """#@private
+        raise NotImplementedError()        
+
 # =============================================================================
 # Hashing
 # =============================================================================
 
 class UniqueHash( object ):
     """
-    Object to compute recursively unique hashes with.
-    See UniqueHash.__init__ for documentation
+    A calculator class which computes unique hashes of a fixed length. 
+    
+    There are a number of parameters which control the exact semantics
+    of the hashing algorithm as it iterates through collections and objects which are are
+    discussed with :class:`cdxcore.uniquehash.UniqueHash`.
+    
+    The base use case is to only specify the length of the unique ID string to be computed::
+    
+        class A(object):
+            def __init__(self, x):
+                self.x = x
+                self._y = x*2  # protected member will not be hashed by default
+        
+        from cdxcore.uniquehash import UniqueHash
+        uniqueHash = UniqueHash(length=12)
+        a = A(2)
+        print( uniqueHash(a) ) # --> "2d1dc3767730"
+
+    The callable ``uniquehash`` can be applied to "any" Python construct.
+
+    **Private and Protected members**
+
+    When an object is passed to this functional its members are iterated using ``__dict__`` or ``__slots__``, respectively.
+    By default this process ignores any fields in objects or dictionaries which starts with "_". The idea here is
+    that "functional" parameters are stored as members, but any derived data is stored in protected members.
+    This behaviour can be changed with `parse_underscore`.
+
+    Objects can optionally implement their own hashing scheme by implementing:
+
+    .. code-block:: python
+
+        __unique_hash__( self, uniqueHash : UniqueHash, debug_trace : DebugTrace  )
+        
+    This function may return a unique string, or any other non-None Python object which will then again be hashed.
+    A common use case is to ignore the parameters to this function and return a tuple of members of the class which are
+    pertinent for hashing.
+            
+    **Dictionaries**
+    
+    Since Python 3.6 `dictionaries preserve the order <https://docs.python.org/3/whatsnew/3.6.html#whatsnew36-compactdict>`__
+    in which they were constructed.
+    However, Python semantics remain otherwise order-invariant, i.e. ``{'x':1, 'y':2}`` tests equal to ``{'y':2',x':1}``.
+    For this reasom the default behaviour here for dictonaries is to sort them before hasing their content. This also applies
+    to objects processed via their ``__dict__``.
+
+    This can be turned off with `sort_dicts`.
+    OrderedDicts or any classes derived from them (such as :class:`cdxcore.prettydict.pdct`)
+    are processed in order and not sorted in any case.
+
+    **Functions**
+
+    By default function members of objects and dictionaries (which include @properties) are
+    ignored. You can set `parse_functions` to True to parse a reduced text of the function code.
+    There are a number of additional expert settings for handling functions, see below.
+    
+    **Numpy, Pandas**
+
+    Hashing of large datasets is not advised. Use hashes on the generating parameter set instead
+    where possible.
+    
+    Parameters
+    ----------
+        length : int, optional
+            Intended length of the hash function. Default is ``32``.
+            
+        parse_underscore : bool, optional
+            How to handle object members starting with "_".
+            
+            * ``"none"`` : ignore members starting with "_" (the default).                       
+            * ``"protected"`` : ignore 'private' members declared starting with "_" and containing "__".
+            * ``"private"`` : consider all members.
+            
+            Default is ``none``.
+             
+        sort_dicts : bool, optional
+            Since Python 3.6 `dictionaries are ordered <https://docs.python.org/3/whatsnew/3.6.html#whatsnew36-compactdict>`__.
+            That means that strictly speaking
+            the two dictionaries ``{'x':1, 'y':2}`` and ``{'y':2, 'x':1}`` are not indentical;
+            however Python will sematicallly still assume they are as ``==`` between the two will return True.
+            Accordingly, by default this hash function assumes the order of dictionaries does _not_ 
+            matter unless the are, or are derived from, :class:`OrderedDict` (as is :class:`cdxcore.prettydict.pdct`).
+            Practically that means the function first sorts the keys of mappings before
+            hashing their items. 
+            
+            This can be turned off by setting `sort_dicts=False`. Default is ``True``.
+            
+        parse_functions : bool, optional 
+            If True, then the function will attempt to generate unique hashes for functions. Default is ``False``.
+                
+        pd_ignore_column_order : bool, optional
+            (Advanced parameter).
+            Whether to ingore the order of panda columns. The default is ``True``.
+        np_nan_equal : bool, optional
+            (Advanced parameter).
+            Whether to ignore the specific type of a NaN. The default is ``False``.
+        f_include_defaults : bool, optional
+            (Advanced parameter).
+            When parsing functions whether to include default values. Default is `True``.
+        f_include_closure : bool, optional
+            (Advanced parameter).
+            When parsing functions whether to include the function colusure. This can be expensive. Default is `True``.
+        f_include_globals : bool, optional
+            (Advanced parameter).
+            When parsing functions whether to include globals used by the function. This can be expensicve. Default is ``False``.
     """
     
     def __init__(self, length                 : int = 32, *,
@@ -45,84 +225,8 @@ class UniqueHash( object ):
                        f_include_globals      : bool = True,
                        ):
         """
-        Initializes a callable object which iteratively generates hashes of length at most 'length'.
-        The algorithm is meant to be mostly hands-off, but there are a few considerations with making:
-            
-        Private and Protected members
-        -----------------------------
-        When an object is passed to this functional its members are iterated using __dict__ or __slots__, respectively.
-        By default this process ignores any fields in objects or dictionaries which start with "_". The idea here is
-        that 'functional' parameters are stored as members, but any derived data is stored in protected members.
-        This behaviour can be chanhed with 'parse_underscore'.
-
-        Objects can optionally implement their own hashing scheme by implementing
-        
-            __unique_hash__( self, uniqueHash : UniqueHash, debug_trace : DebugTrace  )
-            
-        This function may return a unique string, or any other non-None Python object which will then be passed to
-        UniqueHash.__call__. A common use case is to return a tuple of the members of the class which are
-        pertinent for hashing.
-                
-        Dictionaries
-        ------------
-        Since Python 3.7 dictionaries preserve the order in which they were constructed https://mail.python.org/pipermail/python-dev/2017-December/151283.html.
-        However, Python semantics otherwise remain order invariant, i.e. {'x':1, 'y':2} tests equal to {'y':2',x':1}.
-        For this reasom the default behaviour for dictonaries is to sort them before hasing their content
-        (also recall that objects are typicall treated via their __dict__).
-        This can be turned off with 'sort_dicts'.
-        OrderedDicts are not sorted in any case.
-
-        Functions
-        ---------
-        By default function members of objects and dictionaries (which include @properties) are
-        ignored. You can set 'parse_functions' = True to parse a reduced text of the function code.
-        There are a number of expert settings for handling functions, see below.
-        
-        Numpy, Pandas
-        -------------
-        Hashing of large datasets is not advised. Use hashes on the generating parameter set instead.
-        
-        Implementing custom object hashing
-        ----------------------------------
-        An object may implement
-            __unique_hash__( self, uniqueHashExt : UniqueHash  )
-        which is passed a unique hash object which contains all current run time parameters.
-        A good use case is:
-
-        Parameters
-        ----------
-            length : int
-                Intended length of the hash function.
-            parse_underscore : bool
-                How to handle object members starting with '_'.
-                 * 'none' : ignore members starting with '_' (the default)               
-                 * 'protected' : ignore 'private' members declared starting with '_' and containing '__' (*)
-                 * 'private' : consider all members
-            sort_dicts : bool
-                From python 3.7 dictionaries are ordered. That means that strictly speaking
-                the two dictionaries {'x':1, 'y':2} and {'y':2, 'x':1} are not indentical;
-                however Python will sematicallly assume they are as == between the two will return True.
-                Accordingly, this function by default sorts first the keys of mappings before
-                hashing their items. (If dictionaries are derived from OrderedDict, the function will still process those
-                in order.)
-                This can be turned off by setting sort_dicts=False.
-            parse_functions : bool
-                If True, then the function will attempt to generate
-                unique hashes for function and property objects
-                using compress_function_code
-                
-        Fine tuning
-        -----------
-            pd_ignore_column_order : bool
-                Whether to ingore the order of panda columns. The default is True
-            np_nan_equal : bool
-                Whether to ignore the specific type of a NaN. The default is False.
-            f_include_defaults : bool
-                When parsing functions whether to include default values. Default is True.
-            f_include_closure : bool
-                When parsing functions whether to include the function colusure. This can be expensive. Default is True.
-            f_include_globals : bool
-                When parsing functions whether to include globals used by the function. This can be expensicve. Default is False.
+        Initializes the hash calculator which can iteratively generate hashes of a given length for arbitrary input.
+        :meta public:
         """
         self.length             = int(length)
 
@@ -153,37 +257,50 @@ class UniqueHash( object ):
 
     @property
     def name(self) -> str:
+        """ Returns a descriptive name of `self`. """
         return f"uniqueHash({self.length};{self.parse_underscore},{self.sort_dicts},{self.parse_functions})"
     
     def clone(self):
-        """ Return copy of 'self' """
+        """ Return copy of `self`. """
         return UniqueHash( **{ k:v for k,v in self.__dict__.items() if not k[:1] == "_"} )
 
-    def __call__(self, *args, debug_trace = None, **kwargs):
+    def __call__(self, *args, debug_trace : DebugTrace = None, **kwargs) -> str:
         """
-        Returns a unique hash for the parameters passed to this function.
-
-        Hashing can have curious side effect, in particular when handling objects and functions.
-        For this reason this function allows tracing all hashing activity using its debug_trace
-        parameter.
+        :meta public:
+            
+        Returns a unique hash for the `arg` and `kwargs` parameters passed to this function.
         
+        Example::
+            
+            class A(object):
+                def __init__(self, x):
+                    self.x = x
+                    self._y = x*2  # protected member will not be hashed by default
+            
+            from cdxcore.uniquehash import UniqueHash
+            uniqueHash = UniqueHash(12)
+            a = A(2)
+            print( uniqueHash(a) ) # --> "2d1dc3767730"
+            
         Parameters
         ----------
-            args, kwargs:
-                Parameters to hash.
-            debug_trace : DebugTrace
-                Allows tracing of hashing activity.
-                Two classes are implemented:
-                    DebugTraceVerbose()
-                        Simply prints out hashing activity to stdout.
-                    DebugTraceCollect()
-                        Collects an array of tracing information.
-                        The object itself is an iterable which contains
-                        the respective tracing information.
+        args, kwargs:
+            Parameters to hash.
+            
+        debug_trace : :class:`cdxcore.uniquehash.DebugTrace`
+            Allows tracing of hashing activity for debugging purposes.
+            Two implementations of ``DebugTrace`` are available:
+                
+            * :class:`cdxcore.uniquehash.DebugTraceVerbose` simply prints out hashing activity to stdout.
+            
+            * :class:`cdxcore.uniquehash.DebugTraceCollect` collects an array of tracing information.
+              The object itself is an iterable which contains the respective tracing information
+              once the hash function has returned.
         
         Returns
         -------
-            String of at most length 'length'
+        Hash : str
+            String of at most `length`
         """
         h, _ = self._mk_blake( h=self.length//2 )
         if len(args) > 0:
@@ -197,7 +314,7 @@ class UniqueHash( object ):
     
     @staticmethod
     def _mk_blake( h ):
-        """ utility function to allow passing a hash 'h' or an 'int' """
+        """ utility function to allow passing a hash 'h' or an 'int' :meta private: """
         if not isinstance(h, int):
             return h, False
         h = int(h)
@@ -234,32 +351,32 @@ class UniqueHash( object ):
                 assert sz==8, ("Cannot handle itemsize",sz,"for numpy generic", type(x), "with value", x)
                 x = x.view(np.int64)
             h.update(x.tobytes())
-            if not debug_trace is None: debug_trace.update( x )
+            if not debug_trace is None: debug_trace._update( x )
             return
         # basic elements
         if isinstance( x, bool ):
             h.update( x.to_bytes(1,'little', signed=True) )
-            if not debug_trace is None: debug_trace.update( x )
+            if not debug_trace is None: debug_trace._update( x )
             return
         if isinstance( x, int ):
             h.update( x.to_bytes(8,'little', signed=True) )
-            if not debug_trace is None: debug_trace.update( x )
+            if not debug_trace is None: debug_trace._update( x )
             return
         if isinstance( x, ( float, complex ) ):
             h.update( struct.pack('<d', x) )  # little-endian double
-            if not debug_trace is None: debug_trace.update( x )
+            if not debug_trace is None: debug_trace._update( x )
             return
         if isinstance( x, bytes ):
             h.update( x )
-            if not debug_trace is None: debug_trace.update( x )
+            if not debug_trace is None: debug_trace._update( x )
             return
         if isinstance( x, str ):
             h.update( x.encode('utf-8') )
-            if not debug_trace is None: debug_trace.update( x )
+            if not debug_trace is None: debug_trace._update( x )
             return
         # datetime etc
         if isinstance(x,datetime.datetime):
-            if not debug_trace is None: debug_trace = debug_trace.update_topic( x )
+            if not debug_trace is None: debug_trace = debug_trace._update_topic( x )
             ts = float( x.timestamp() )
             td = x.tzinfo.utcoffset(x) if not x.tzinfo is None else None
             self._hash_any(h, ts, debug_trace=debug_trace)
@@ -274,7 +391,7 @@ class UniqueHash( object ):
             else:
                 h.update( int(0).to_bytes(4,'little', signed=True) )                
             """
-            if not debug_trace is None: debug_trace = debug_trace.update_topic( x )
+            if not debug_trace is None: debug_trace = debug_trace._update_topic( x )
             total_seconds = float(x.hour*60*60+x.minute*60+x.second) +\
                             float(x.microsecond) / 1000000.
             self._hash_any(h, total_seconds, debug_trace=debug_trace)
@@ -284,17 +401,17 @@ class UniqueHash( object ):
             h.update( x.second.to_bytes(2,'little', signed=True) )
             h.update( x.microsecond.to_bytes(4,'little', signed=True))
             if not debug_trace is None:
-                debug_trace = debug_trace.update_topic( x )
-                debug_trace.update( x.hour, "hour")
-                debug_trace.update( x.minute, "minute")
-                debug_trace.update( x.second, "second")
-                debug_trace.update( x.microsecond, "microsecond")
+                debug_trace = debug_trace._update_topic( x )
+                debug_trace._update( x.hour, "hour")
+                debug_trace._update( x.minute, "minute")
+                debug_trace._update( x.second, "second")
+                debug_trace._update( x.microsecond, "microsecond")
                 if not x.tzinfo is None:
-                    debug_trace.warning( "datetime.time support for tzinfo is not working well. Use datetime.datetime")
+                    debug_trace._warning( "datetime.time support for tzinfo is not working well. Use datetime.datetime")
             """
             return
         if isinstance(x,datetime.date):
-            if not debug_trace is None: debug_trace = debug_trace.update_topic( x )            
+            if not debug_trace is None: debug_trace = debug_trace._update_topic( x )            
             full = x.year * 10000 + x.month * 100 + x.day
             self._hash_any(h, full, debug_trace=debug_trace)
             """
@@ -302,26 +419,26 @@ class UniqueHash( object ):
             h.update( x.month.to_bytes(1,'little', signed=True) )
             h.update( x.day.to_bytes(2,'little', signed=True) )
             if not debug_trace is None:
-                debug_trace = debug_trace.update_topic( x )
-                debug_trace.update( x.year, "year" )
-                debug_trace.update( x.month, "month" )
-                debug_trace.update( x.day, "day" )
+                debug_trace = debug_trace._update_topic( x )
+                debug_trace._update( x.year, "year" )
+                debug_trace._update( x.month, "month" )
+                debug_trace._update( x.day, "day" )
             """
             return
         if isinstance(x,datetime.timedelta):
-            if not debug_trace is None: debug_trace = debug_trace.update_topic( x )
+            if not debug_trace is None: debug_trace = debug_trace._update_topic( x )
             self._hash_any(h, x.total_seconds(), debug_trace=debug_trace )
             return
         # functions
-        if isFunction(x) or isinstance(x,property):
+        if is_function(x) or isinstance(x,property):
             if self.parse_functions:
                 self._hash_function( h, x, debug_trace=debug_trace )
             elif not debug_trace is None:
-                debug_trace.warning( f"Ignored function: {x.__qualname__}")                
+                debug_trace._warning( f"Ignored function: {x.__qualname__}")                
             return
         # slice -> tuple
         if isinstance(x,slice):
-            if not debug_trace is None: debug_trace = debug_trace.update_topic( x )
+            if not debug_trace is None: debug_trace = debug_trace._update_topic( x )
             self._hash_any(h, (x.start,x.stop,x.step), debug_trace=debug_trace )
             return
         # test presence of __unique_hash__()
@@ -331,12 +448,12 @@ class UniqueHash( object ):
             if isinstance(unique_hash, str):
                 h.update(unique_hash.encode('utf-8') )
                 if not debug_trace is None:
-                    debug_trace = debug_trace.update_topic( x, msg="__unique_hash__ str" )
-                    debug_trace.update( unique_hash )
+                    debug_trace = debug_trace._update_topic( x, msg="__unique_hash__ str" )
+                    debug_trace._update( unique_hash )
                 return                        
-            debug_trace = None if debug_trace is None else debug_trace.update_topic( x, msg="__unique_hash__ function" )
+            debug_trace = None if debug_trace is None else debug_trace._update_topic( x, msg="__unique_hash__ function" )
             try:
-                unique_hash = unique_hash( self.clone(), debug_trace=debug_trace )
+                unique_hash = unique_hash( unique_hash=self.clone(), debug_trace=debug_trace )
             except Exception as e:
                 raise type(e)( e, f"Exception encountered while calling '__unique_hash__' of object of type {type(x)}.")
             if unique_hash is None:
@@ -344,10 +461,10 @@ class UniqueHash( object ):
             if isinstance(unique_hash, str):
                 h.update(unique_hash.encode('utf-8') )
                 if not debug_trace is None:
-                    debug_trace.update( unique_hash )
+                    debug_trace._update( unique_hash )
             else:
                 if not debug_trace is None:
-                    debug_trace = debug_trace.update_topic( unique_hash )
+                    debug_trace = debug_trace._update_topic( unique_hash )
                 self._hash_any(h, unique_hash, debug_trace=debug_trace )
             return
         # numpy
@@ -367,7 +484,7 @@ class UniqueHash( object ):
             # however, we here assume here that unless they are
             # specified as ordered, we can assume that the
             # order does not matter.
-            if not debug_trace is None: debug_trace = debug_trace.update_topic( x )
+            if not debug_trace is None: debug_trace = debug_trace._update_topic( x )
             keys = sorted(x) if self.sort_dicts and not isinstance(x,OrderedDict) else list(x)
             for k in keys: 
                 if isinstance(k,str):
@@ -381,14 +498,14 @@ class UniqueHash( object ):
         # lists, tuples and everything which looks like it --> lists
         if isinstance(x, (Sequence, Iterator)):
             assert not isinstance(x, dict)
-            if not debug_trace is None: debug_trace = debug_trace.update_topic( x )
+            if not debug_trace is None: debug_trace = debug_trace._update_topic( x )
             for k in x:
                 self._hash_any(h, k, debug_trace=debug_trace)
             return
         # all others such as sets need sorting first
         if isinstance(x, Collection):
             assert not isinstance(x, dict)
-            if not debug_trace is None: debug_trace = debug_trace.update_topic( x )
+            if not debug_trace is None: debug_trace = debug_trace._update_topic( x )
             x = sorted(x)
             for k in x:
                 self._hash_any(h, k, debug_trace=debug_trace)
@@ -412,7 +529,7 @@ class UniqueHash( object ):
                         print(x.__dict__)
                 A().f() will print '{'_A__p': 1}' even though 'x.__p' is a private member to X.
             """
-            if not debug_trace is None: debug_trace = debug_trace.update_topic( x, "object with __dict__" )
+            if not debug_trace is None: debug_trace = debug_trace._update_topic( x, "object with __dict__" )
             self._hash_any( h, _qual_name( type(x),False), debug_trace=debug_trace)
             x    = x.__dict__
             keys = sorted(x) if self.sort_dicts else list(x)
@@ -429,7 +546,7 @@ class UniqueHash( object ):
             self._hash_any(h, x.__dict__)
             return
         if hasattr(x,"__slots__"):
-            if not debug_trace is None: debug_trace = debug_trace.update_topic( x, "object with __slots__" )
+            if not debug_trace is None: debug_trace = debug_trace._update_topic( x, "object with __slots__" )
             self._hash_any( h, _qual_name( type(x),False), debug_trace=debug_trace)
             for k in  x.__slots__:
                 if isinstance(k,str):
@@ -452,7 +569,7 @@ class UniqueHash( object ):
             # Builtins: best we can do is identity by module + qualname
             ident = _qual_name(fn,False)
             h.update( ident.encode("utf-8") )
-            if not debug_trace is None: debug_trace.update( ident, "builtin function" )
+            if not debug_trace is None: debug_trace._update( ident, "builtin function" )
             return
     
         if not inspect.isfunction(fn):
@@ -460,12 +577,12 @@ class UniqueHash( object ):
                 obj_name = _qual_name(type(fn),False)
                 h.update( obj_name.encode("utf-8") )                
                 if not debug_trace is None:
-                    debug_trace = debug_trace.update_topic( fn, "using __call__" )
-                    debug_trace.update( obj_name )
+                    debug_trace = debug_trace._update_topic( fn, "using __call__" )
+                    debug_trace._update( obj_name )
                 return self._hash_function(h, fn.__call__, debug_trace = debug_trace )
             raise TypeError(f"'fn' is not a function but of type {type(fn)}.")
     
-        debug_trace = None if debug_trace is None else debug_trace.update_topic( fn )
+        debug_trace = None if debug_trace is None else debug_trace._update_topic( fn )
         func_name   = _qual_name(fn,False)
         self._hash_any( h, func_name )
 
@@ -480,25 +597,25 @@ class UniqueHash( object ):
         src = [ l.replace("\t"," ").replace(" ","").replace("\n","") for l in src ]    
         self._hash_any( h, src )
         if not debug_trace is None:
-            debug_trace.update( func_name )
-            debug_trace.update( src, "reduced source code")
+            debug_trace._update( func_name )
+            debug_trace._update( src, "reduced source code")
         del src, func_name
 
         if self.f_include_defaults:
             # Defaults
             if not fn.__defaults__ is None and len(fn.__defaults__) > 0:
-                def_debug_trace = None if debug_trace is None else debug_trace.update_topic( fn.__defaults__, "position defaults")
+                def_debug_trace = None if debug_trace is None else debug_trace._update_topic( fn.__defaults__, "position defaults")
                 self._hash_any( h, fn.__defaults__, debug_trace = def_debug_trace )
                 del def_debug_trace
 
             if not fn.__kwdefaults__ is None and len(fn.__kwdefaults__) > 0:
-                def_debug_trace = None if debug_trace is None else debug_trace.update_topic(fn.__kwdefaults__, "keyword defauls")
+                def_debug_trace = None if debug_trace is None else debug_trace._update_topic(fn.__kwdefaults__, "keyword defauls")
                 self._hash_any( h, fn.__kwdefaults__, debug_trace = def_debug_trace )
                 del def_debug_trace
     
         if self.f_include_closure and not fn.__closure__ is None and len(fn.__closure__) > 0:
             # Closure cells (can be large; disable if that’s a concern)
-            closure_debug_trace = None if debug_trace is None else debug_trace.update_topic( fn.__closure__, "closure" )
+            closure_debug_trace = None if debug_trace is None else debug_trace._update_topic( fn.__closure__, "closure" )
             for cell in fn.__closure__:
                 self._hash_any( h, cell.cell_contents, debug_trace=closure_debug_trace )
             del closure_debug_trace
@@ -506,7 +623,7 @@ class UniqueHash( object ):
         if self.f_include_globals and len(fn.__globals__) > 0 and len(fn.__code__.co_names) > 0:
             # Referenced globals (names actually used by the code)
             g = fn.__globals__
-            glb_debug_trace = None if debug_trace is None else debug_trace.update_topic( fn.__code__.co_names, "linked globals" )
+            glb_debug_trace = None if debug_trace is None else debug_trace._update_topic( fn.__code__.co_names, "linked globals" )
             for name in sorted(fn.__code__.co_names):
                 if name in g:
                     self._hash_any( h, (name, g[name]), debug_trace=glb_debug_trace )
@@ -520,14 +637,14 @@ class UniqueHash( object ):
         Does not hash attributes.
         """
         assert isinstance(df, pd.DataFrame), ("DataFrame expected", type(df))
-        debug_trace = None if debug_trace is None else debug_trace.update_topic( df )
+        debug_trace = None if debug_trace is None else debug_trace._update_topic( df )
         if self.pd_ignore_column_order:
             df = df.reindex(sorted(df.columns), axis=1)
     
         # hash index
         idx_h = pd.util.hash_pandas_object(df.index, index=False, categorize=True).values
         h.update(idx_h.tobytes())
-        if not debug_trace is None: debug_trace.update( idx_h )
+        if not debug_trace is None: debug_trace._update( idx_h )
     
         # hash each column’s content + its name + dtype
         for name, col in df.items():
@@ -536,15 +653,15 @@ class UniqueHash( object ):
             col_h = pd.util.hash_pandas_object(col, index=False, categorize=True).values
             h.update(col_h.tobytes())
             if not debug_trace is None:
-                debug_trace.update( str(name) )
-                debug_trace.update( str(col.dtype) )
-                debug_trace.update( col_h )
+                debug_trace._update( str(name) )
+                debug_trace._update( str(col.dtype) )
+                debug_trace._update( col_h )
 
         # attrs, if any
         attrs = getattr(df, "attrs", None)
         if not attrs is None:
             self._hash_any(h, attrs)
-            if not debug_trace is None: debug_trace.update( attrs, "attrs" )
+            if not debug_trace is None: debug_trace._update( attrs, "attrs" )
     
     def _hash_numpy( self, h, a : np.ndarray, *, debug_trace = None ):
         """
@@ -553,7 +670,7 @@ class UniqueHash( object ):
         assert isinstance(a, np.ndarray), ("ndarray expected", type(a))
         a = np.asarray(a)
     
-        debug_trace = None if debug_trace is None else debug_trace.update_topic( a )
+        debug_trace = None if debug_trace is None else debug_trace._update_topic( a )
         # Disallow arbitrary Python objects (define your own encoding first)
         if a.dtype.kind == 'O':
             raise TypeError("object-dtype array: map elements to bytes first (e.g., via str/utf-8).")
@@ -598,35 +715,56 @@ class UniqueHash( object ):
         h.update(a.dtype.str.encode('utf-8'))    
         h.update(a.tobytes())
         if not debug_trace is None:
-            debug_trace.update( a.shape )
-            debug_trace.update( a.dtype.str )
-            debug_trace.update( a.tobytes() )
+            debug_trace._update( a.shape )
+            debug_trace._update( a.dtype.str )
+            debug_trace._update( a.tobytes() )
     
 # Debugging
 # =========
 
-class DebugTrace(object):
-    def update( self, x, msg : str = None ):
-        """ Notify processing of 'x', with an optional process 'msg' """
-        raise NotImplementedError()        
-    def update_topic( self, x, msg : str = None ):
-        """ Notify and return a sub-trace context """
-        raise NotImplementedError()        
-    def warning( self, msg : str):
-        """ Issue warning """
-        raise NotImplementedError()        
-
 class DebugTraceCollect(DebugTrace):
     """
-    Simple collection of all arguments parsed with DebugTrace
+    Keep track of everything parsed during hashing.
+    
+    The result of the trace is contained in :attr:`cdxcore.uniquehash.DebugTraceCollect.trace`.
+    
+    Note that `DebugTraceCollect` itself implements :class:`Collection` and :class:`Sequence` semantics
+    so you can iterate it directly.
+    
+    Parameters
+    ----------
+        tostr: int
+            If set to a positive integer, then any object encountered will be represented as a string with :func:`repr`,
+            and the length of the string will be limited to `tostr`. This avoids generation of large amounts
+            of data if the objects hashed are large (e.g. numpy arrays).
+            
+            If set to ``None`` then the function collects the actual elements.
     """
     def __init__(self, tostr : int = None ):
-        """ Initialize data collection """
+        """
+        Initialize data collection
+        """
         if tostr and tostr<=0: raise ValueError("'tostr' must be None or a positive integer")
         self.tostr = tostr
-        self.trace = []        
-    def _update( self, x, msg, child ):
-        """ Notify processing of 'x', with an optional process 'msg' """
+        
+        #: Trace of the hashing operation.
+        #: Upon completion of :meth:`cdxcore.uniquehash.UniqueHash.__call__` this list contains
+        #: elemenets of the following type:
+        #:
+        #: * if `tostr` is a positive integer:
+        #:    * `typex`: type of the element
+        #:    * `reprx`: `repr` of the element, up to `tostr` length.
+        #:    * `msg`: message occured during hashing if any
+        #:    * `child`: if the element was a container or object
+        #:
+        #: * if `tostr` is ``None``:    
+        #:    * `x`: the element
+        #:    * `msg`: message occured during hashing if any
+        #:    * `child`: if the element was a container or object
+        self.trace = []     
+    def _mupdate( self, x, msg, child ):
+        """ Notify processing of 'x', with an optional process 'msg'
+        :meta private: """#@private
         if self.tostr:
             y = PrettyObject(   typex = type(x),
                                 reprx = repr(x)[:self.tostr],
@@ -637,17 +775,20 @@ class DebugTraceCollect(DebugTrace):
                                 msg   = msg,
                                 child = child )
         self.trace.append( y )        
-    def update( self, x, msg : str = None ):
-        """ Notify processing of 'x', with an optional process 'msg' """
-        self._update( x, msg, None )
-    def update_topic( self, x, msg : str = None ):
-        """ Notify and return a sub-trace context """
+    def _update( self, x, msg : str = None ):
+        """ Notify processing of `x`, with an optional process `msg`
+        :meta private: """#@private
+        self._mupdate( x=x, msg=msg, child=None )
+    def _update_topic( self, x, msg : str = None ):
+        """ Notify and return a sub-trace context
+        :meta private: """#@private
         child = DebugTraceCollect(tostr=self.tostr)
-        self._update( x, msg, child )
+        self._mupdate( x=x, msg=msg, child=child )
         return child
-    def warning( self, msg : str):
-        """ Issue warning """
-        self._update( None, msg, None )
+    def _warning( self, msg : str):
+        """ Issue warning
+        :meta private: """
+        self._mupdate( x=None, msg=msg, child=None )
         
     # results
     # -------
@@ -666,27 +807,32 @@ class DebugTraceCollect(DebugTrace):
         
 class DebugTraceVerbose(DebugTrace):
     """
-    Live printing of tracing information with cdxbasics.verbose.Context
+    Live printing of tracing information with :class:`cdxcore.verbose.Context`.
     for some formatting. All objects will be reported by type and
     their string representation, sufficiently reduced if necessary.
+
+    Parameters
+    ----------
+        strsize : int, optional
+            Maximum string size when using :func:`repr` on reported objects.
+            Default is ``50``.
+            
+        verbose : :class:`cdxcore.verbose.Context`, optional
+            Context object or ``None`` for a new context object
+            with full visibility (it prints everything).
     """
-    def __init__(self, strsize : int = 50, verbose = None ):
+    def __init__(self, strsize : int = 50, verbose : Context = None ):
         """
         Initialize tracer.
-        
-        Parameters
-        ----------
-            strsize : int
-                Maximum string size when using repr() on reported objects.
-            verbose :
-                Context object or None for a new context object.
         """                
         from .verbose import Context
         if strsize<=3: ValueError("'strsize' must exceed 3")
         self.strsize = strsize
         self.verbose = Context("all") if verbose is None else verbose
-    def update( self, x, msg : str = None ):
-        """ Notify processing of 'x', with an optional process 'msg' """
+    def _update( self, x, msg : str = None ):
+        """ Notify processing of 'x', with an optional process 'msg'
+        :meta private:
+        """#@private
         xstr = repr(x)
         if xstr[:1] == "'" and xstr[-1] == "'":
             xstr = xstr[1:-1]
@@ -696,72 +842,85 @@ class DebugTraceVerbose(DebugTrace):
             self.verbose.write( f"{type(x).__name__}: '{xstr}'" )
         else:
             self.verbose.write( f"{msg} {type(x).__name__}: '{xstr}'" )
-    def update_topic( self, x, msg : str = None ):
-        """ Notify and return a sub-trace context """
-        self.update( x, msg )
+    def _update_topic( self, x, msg : str = None ):
+        """ Notify and return a sub-trace context
+        :meta private:
+        """#@private
+        self._update( x, msg )
         return DebugTraceVerbose( self.strsize, self.verbose(1) )    
-    def warning( self, msg : str):
-        """ Issue warning """
+    def _warning( self, msg : str):
+        """ Issue warning
+        :meta private:"""#@private
         self.verbose.write( msg )
                 
 # =============================================================================
 # Utility wrappers
 # =============================================================================
 
-def uniqueHashExt(**parameters) -> UniqueHash:    
-    return UniqueHash(**parameters)
-uniqueHashExt.__doc__ = UniqueHash.__init__.__doc__
-
-def namedUniqueHashExt( max_length       : int = 60,
-                        id_length        : int = 16,  *,
-                        separator        : str = ' ',
-                        filename_by      : str = None,
-                        **unique_hash_arguments
-                        ):
+def NamedUniqueHash( max_length       : int = 60,
+                     id_length        : int = 16,  *,
+                     separator        : str = ' ',
+                     filename_by      : str = None,
+                     **unique_hash_arguments 
+                     ) -> Callable:
     """
-    Returns a function 
+    Generate user-readable unique hashes and filenames.    
     
-        f( label, **argv, **argp )
+    Returns a function::
+        
+        f( label, *args, **kwargs )
+
+    which generates unique strings of at most a length of `max_length` of the format ``label + separator + ID``
+    where ID has length `id_length`. Since `label` heads the resulting string this function is suited for
+    use cases where a user might want an indication what a hash refers to.
+
+    This function does not suppose that `label` is unqiue, hence the ID is prioritized.
+    See :func:`cdxcore.uniquehash.UniqueLabel` for a function which assumes the label is unique.
     
-    which generates unique strings of at most a length of max_length of the format
-        label + separator + ID
-    where ID has length id_length.
+    The maximum length of the returned string is `max_length`; if need be `label` will be truncated: 
+    the returned string will always end in `ID`.
 
-    The maximum length of the returned string is 'max_length'.
-    If total_lengths is id_length+len(separator) then the function just returns the ID of length max_length.
+    The function optionally makes sure that the returned string is a valid file name using
+    :func:`cdxcore.util.fmt_filename`.
 
-    This function does not suppose that 'label' is unqiue, hence the ID is prioritized.
-    See uniqueLabelExt() for a function which assumes the label is unique.
+    **Short Cut**
     
-    The function optionally makes sure that the returned string is a valid file name using cdxbasics.util.fmt_filename.
+    Consider :func:`cdxcore.verbose.named_unique_filename48_8` if the defaults used
+    for that function are suitable for your use case.
 
-    Important
-    ---------
-    It is strongly recommended to read the documentation for UniqueHash.__init__() for details on hashing logic
+    **Important**
+
+    It is *strongly recommended* to read the documentation for
+    :class:`cdxcore.uniquehash.UniqueHash` for details on hashing logic
     and the available parameters
 
     Parameters
     ----------
-        max_length : int
-            Total length of the returned string including the ID.
-            Defaults to 60 to allow file names with extensions with three letters.
-        id_length : int
-            Intended length of the hash function, default 16
-        separator : str
-            Separator between label and id_length.
-            Note that the separator will be included in the ID calculation, hence different separators
-            lead to different IDs.
-        filename_by : str, None
-            If not None, use fmt_filename( *, by=filename_by ) to ensure the returned string is a valid
-            filename for both windows and linux, of at most 'max_length' size.
-            If set to the string "default", use DEF_FILE_NAME_MAP as the default mapping of cdxbasics.util.fmt_filename
-        **unique_hash_arguments:
-            Parameters passed to UniqueHash.__init__.
+    max_length : int, optional
+        Total length of the returned string including the ID.
+        Defaults to ``60`` to allow file names with extensions of up to three letters.
+        
+    id_length : int, optional
+        Intended length of the hash `ID`, default ``16``.
+        
+    separator : str, optional
+        Separator between `label` and `id_length`.
+        Note that the separator will be included in the ID calculation, hence different separators
+        lead to different IDs. Default ``' '``.
+        
+    filename_by : str, optional
+        If not ``None``, use :class:`cdxcore.util.fmt_filename` with ``by=filename_by`` to ensure the returned string is a valid
+        filename for both windows and linux, of at most `max_length` size.
+        If set to the string ``default``, use :data:`cdxcore.util.DEF_FILE_NAME_MAP`
+        as the default mapping for :func:`cdxcore.util.fmt_filename`.
+        
+    ** unique_hash_arguments, optional
+        Parameters passed to :class:`cdxcore.uniquehash.UniqueHash`.
 
     Returns
     -------
-        hash function with signature (label, *args, **kwargs).
-        All arguments including label and separator will be used to generate the hash key.
+    uniqueHash : :class:`Callable`
+        hash function with signature ``(label, *args, **kwargs)``.        
     """
     if id_length < 4: raise ValueError("'id_length' must be at least 4. Found {id_length}")
     if id_length > max_length: raise ValueError(f"'max_length' must not be less than 'id_length'. Founb {max_length} and {id_length}, respectivelty")
@@ -786,48 +945,63 @@ def namedUniqueHashExt( max_length       : int = 60,
         return label
     return named_unique_hash
 
-def uniqueLabelExt(     max_length       : int = 60,
-                        id_length        : int = 8,
-                        separator        : str = ' ',
-                        filename_by      : str = None ):
+def UniqueLabel(     max_length       : int = 60,
+                     id_length        : int = 8,
+                     separator        : str = ' ',
+                     filename_by      : str = None ) -> Callable:
     """
-    Returns a function 
-    
+    Returns a function:: 
+        
         f( unique_label )
+
+    which generates strings of at most ``max_length``
+    based on a provided ``unique_label``; essentially::
     
-    which generates strings of at most max_length of the format:
-    If len(unique_label) <= max_length:
-        unique_label
-    else:
-        unique_label + separator + ID
-    where the ID is of maximum length 'id_length'.
+        If len(unique_label) <= max_length:
+            unique_label
+        else:
+            unique_label + separator + ID
+
+    where ``ID`` is a unqiue hash computed from ``unique_label`` of maximum length ``id_length``.
 
-    This function assumes that 'unique_label' is unique, hence the ID is dropped if 'unique_label' is less than 'max_length'
-    See namedUniqueHashExt() for a function does not assume the label is unique, hence the ID is always appended.
-    Note that if file name conversion is used, then this function will always attach the unique ID to the filename because
-    the reduction of the label to a filename is no longer guaranteed to be unique. If your label is unique as a filename, do not
-    use 'filename_by'. The function will return valid file names if label is a valid file name.
+    This function assumes that ``unique_label`` is unique, hence the ID is dropped if ``unique_label``
+    is less than ``max_length``.
+    Use :func:`cdxcore.uniquehash.NamedUniqueHash` if the label is not unique, and which therefore always appends the 
+    dynamically calculated unique ID.
+
+    Note that if ``filename_by`` conversion is used, then this function will always attach the unique ID
+    to the filename because
+    after the conversion of the label to a filename it is no longer guaranteed that the result is unique.
+    If your label is unique as a filename, do not
+    use ``filename_by``. The function will return valid file names if ``label`` is a valid file name.
 
     Parameters
     ----------
-        max_length : int
-            Total length of the returned string including the ID.
-            Defaults to 60 to allow file names with extensions with three letters.
-        id_length : int
-            Indicative length of the hash function, default 8.
-            id_length will be reduced to max_length if neccessary.
-        separator : str
-            Separator between label and id_length.
-            Note that the separator will be included in the ID calculation, hence different separators
-            lead to different IDs.
-        filename_by : str, None
-            If not None, use fmt_filename( *, by=filename_by ) to ensure the returned string is a valid
-            filename for both windows and linux, of at most 'max_length' size.
-            If set to the string "default", use DEF_FILE_NAME_MAP as the default mapping of cdxbasics.util.fmt_filename
+    max_length : int
+        Total length of the returned string including the ID.
+        Defaults to 60 to allow file names with extensions with three letters.
+        
+    id_length : int
+        Indicative length of the hash function, default 8.
+        id_length will be reduced to `max_length` if neccessary.
+        
+    separator : str
+        Separator between the label and the unique ID.
+        
+        Note that the separator will be included in the ID calculation, hence different separators
+        lead to different IDs.
+        
+    filename_by : str
+        If not ``None``, use :func:`cdxcore.util.fmt_filename` with ``by=filename_by``
+        to ensure the returned string is a valid
+        filename for both windows and linux, of at most ``max_length`` size.
+        If set to the string ``"default"``, :data:`cdxcore.util.DEF_FILE_NAME_MAP`
+        as the default mapping for :func:`cdxcore.util.fmt_filename`.
 
     Returns
     -------
-        hash function with signature (unique_label).
+    Hash function : :class:`Callable`
+        Hash function with signature ``(unique_label)``.
     """
     if id_length < 4: raise ValueError("'id_length' must be at least 4. Found {id_length}")
     if id_length > max_length: raise ValueError(f"'max_length' must not be less than 'id_length'. Founb {max_length} and {id_length}, respectivelty")
@@ -861,110 +1035,88 @@ def uniqueLabelExt(     max_length       : int = 60,
 # Short cuts
 # =============================================================================
 
-def uniqueHash8( *args, **argv ) -> str:
+def unique_hash8( *args, **kwargs ) -> str:
     """
-    Compute a unique ID of length 8 for the provided arguments.
-
-    The function
-        1) uses the repr() function to feed objects to the hash algorithm.
-           that means is only distinguishes floats up to str conversion precision
-        2) keys of dictionaries, and sets are sorted to ensure equality of hashes
-           accross different memory setups of strings
-        3) Members with leading '_' are ignored (*)
-        4) Functions and properties are ignored (*)
-        (*) you can create a hash function with different behaviour by using uniqueHashExt()
-
-    To support hashing directly in one of your objects, implement
-
-        __unique_hash__( length : int, parse_functions : bool, parse_underscore : str )
-
-        The parameters are the same as for uniqueHashExt.
-        The function is expected to return a hashable object, ideally a string.
+    Short-cut for the hash function returned by :class:`cdxcore.uniquehash.UniqueHash`
+    with parameter ``length=8``.
+    
+    *Important* please make sure you aware of the functional considerations
+    discussed in :class:`cdxcore.uniquehash.UniqueHash` around
+    elements starting with `_` or function members.
+    
+    :meta private:
     """
-    return UniqueHash(8)(*args,**argv)
+    return UniqueHash(8)(*args,**kwargs)
 
-def uniqueHash16( *args, **argv ) -> str:
+def unique_hash16( *args, **kwargs ) -> str:
     """
-    Compute a unique ID of length 16 for the provided arguments.
-    The function
-        1) uses the repr() function to feed objects to the hash algorithm.
-           that means is only distinguishes floats up to str conversion precision
-        2) keys of dictionaries, and sets are sorted to ensure equality of hashes
-           accross different memory setups of strings
-        3) Members with leading '_' are ignored (*)
-        4) Functions and properties are ignored (*)
-        (*) you can create a hash function with different behaviour by using uniqueHashExt()
-
-    To support hashing directly in one of your objects, implement
-
-        __unique_hash__( length : int, parse_functions : bool, parse_underscore : str )
-
-        The parameters are the same as for uniqueHashExt.
-        The function is expected to return a hashable object, ideally a string.
+    Short-cut for the hash function returned by :class:`cdxcore.uniquehash.UniqueHash`
+    with parameter ``length=16``.
+    
+    *Important* please make sure you aware of the functional considerations
+    discussed in :class:`cdxcore.uniquehash.UniqueHash` around
+    elements starting with `_` or function members.
     """
-    return UniqueHash(16)(*args,**argv)
+    return UniqueHash(16)(*args,**kwargs)
 
-def uniqueHash32( *args, **argv ) -> str:
+def unique_hash32( *args, **kwargs ) -> str:
     """
-    Compute a unique ID of length 32 for the provided arguments.
-    The function
-        1) uses the repr() function to feed objects to the hash algorithm.
-           that means is only distinguishes floats up to str conversion precision
-        2) keys of dictionaries, and sets are sorted to ensure equality of hashes
-           accross different memory setups of strings
-        3) Members with leading '_' are ignored (*)
-        4) Functions and properties are ignored (*)
-        (*) you can create a hash function with different behaviour by using uniqueHashExt()
-
-    To support hashing directly in one of your objects, implement
-
-        __unique_hash__( length : int, parse_functions : bool, parse_underscore : str )
-
-        The parameters are the same as for uniqueHashExt.
-        The function is expected to return a hashable object, ideally a string.
+    Short-cut for the hash function returned by :class:`cdxcore.uniquehash.UniqueHash`
+    with parameter ``length=32``.
+    
+    *Important* please make sure you aware of the functional considerations
+    discussed in :class:`cdxcore.uniquehash.UniqueHash` around
+    elements starting with `_` or function members.
     """
-    return UniqueHash(32)(*args,**argv)
+    return UniqueHash(32)(*args,**kwargs)
 
-uniqueHash = uniqueHash32
+def unique_hash48( *args, **kwargs ) -> str:
+    """
+    Short-cut for the hash function returned by :class:`cdxcore.uniquehash.UniqueHash`
+    with parameter ``length=48``.
+    
+    *Important* please make sure you aware of the functional considerations
+    discussed in :class:`cdxcore.uniquehash.UniqueHash` around
+    elements starting with `_` or function members.
+    """
+    return UniqueHash(48)(*args,**kwargs)
 
-def uniqueHash48( *args, **argv ) -> str:
+def unique_hash64( *args, **kwargs ) -> str:
     """
-    Compute a unique ID of length 48 for the provided arguments.
-    The function
-        1) uses the repr() function to feed objects to the hash algorithm.
-           that means is only distinguishes floats up to str conversion precision
-        2) keys of dictionaries, and sets are sorted to ensure equality of hashes
-           accross different memory setups of strings
-        3) Members with leading '_' are ignored (*)
-        4) Functions and properties are ignored (*)
-        (*) you can create a hash function with different behaviour by using uniqueHashExt()
-
-    To support hashing directly in one of your objects, implement
-
-        __unique_hash__( length : int, parse_functions : bool, parse_underscore : str )
-
-        The parameters are the same as for uniqueHashExt.
-        The function is expected to return a hashable object, ideally a string.
+    Short-cut for the hash function returned by :class:`cdxcore.uniquehash.UniqueHash`
+    with parameter ``length=64``.
+    
+    *Important* please make sure you aware of the functional considerations
+    discussed in :class:`cdxcore.uniquehash.UniqueHash` around
+    elements starting with `_` or function members.
     """
-    return UniqueHash(48)(*args,**argv)
+    return UniqueHash(64)(*args,**kwargs)
 
-def uniqueHash64( *args, **argv ) -> str:
+def named_unique_filename48_8( label : str, *args, **kwargs ) -> str:
     """
-    Compute a unique ID of length 64 for the provided arguments.
-    The function
-        1) uses the repr() function to feed objects to the hash algorithm.
-           that means is only distinguishes floats up to str conversion precision
-        2) keys of dictionaries, and sets are sorted to ensure equality of hashes
-           accross different memory setups of strings
-        3) Members with leading '_' are ignored (*)
-        4) Functions and properties are ignored (*)
-        (*) you can create a hash function with different behaviour by using uniqueHashExt()
-
-    To support hashing directly in one of your objects, implement
-
-        __unique_hash__( length : int, parse_functions : bool, parse_underscore : str )
-
-        The parameters are the same as for uniqueHashExt.
-        The function is expected to return a hashable object, ideally a string.
+    Returns a unique and valid filename which is composed of `label` and a unique ID
+    computed using all of `label`, `args`, and `kwargs`.
+    
+    Consider a use cases where an experiment defined by ``definition``
+    has produced ``results`` which we wish to :mod:`pickle` to disk.
+    Assume further that ``str(definition)`` provides an
+    informative user-readable but
+    not necessarily unique description of ``definition``.
+    
+    Pseudo-Code::
+        
+        def store_experiment( num : int, definition : object, results : object ):
+            label    = f"Experiment {str(definition)}"
+            filename = named_unique_hash48_8( label, (num, definition) )
+            with open(filename, "wb") as f:
+                pickle.dumps(results)
+    
+    This is the hash function returned by :class:`cdxcore.uniquehash.NamedUniqueHash`
+    with parameters ``max_length=48, id_length=8, filename_by="default"``.
+
+    *Important* please make sure you aware of the functional considerations
+    discussed in :class:`cdxcore.uniquehash.UniqueHash` around
+    elements starting with `_` or function members.
     """
-    return UniqueHash(64)(*args,**argv)
+    return NamedUniqueHash( max_length=48, id_length=8, filename_by="default" )
+