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

cdxcore/subdir.py

@@ -1,61 +1,387 @@
 """
-subdir
-Simple class to keep track of directory sturctures and for automated caching on disk
-Hans Buehler 2020
-"""
+Overview
+--------
+
+This module contains utilities for file i/o, directory management and
+streamlined versioned caching.
+
+The key idea is to provide transparent, concise :mod:`pickle` access to the file system
+via the :class:`cdxcore.subdir.SubDir` class.
+
+**Key design features:**
+
+* Simple path construction via ``()`` operator. By default directories which do not exist yet
+  are only created upon writing a first file.
+     
+* Files managed by :class:`cdxcore.subdir.SubDir` all have the same extension.
+
+* Files support fast versioning: the version of a file can be read without having to read the
+  entire file.
+  
+* :dec:`cdxcore.subdir.SubDir.cache` implements a convenient versioned caching framework.
+
+Directories
+^^^^^^^^^^^
+
+The core of the framework is the :class:`cdxcore.subdir.SubDir` class which represents a directory
+with files of a given extension.
+
+Simply write::
+
+    from cdxcore.subdir import SubDir
+    subdir = SubDir("my_directory")      # relative to current working directory
+    subdir = SubDir("./my_directory")    # relative to current working directory
+    subdir = SubDir("~/my_directory")    # relative to home directory
+    subdir = SubDir("!/my_directory")    # relative to default temp directory
+    
+Note that ``my_directoy`` will not be created if it does not exist yet. It will be created the first
+time we write a file.
+
+You can specify a parent for relative path names::
+
+    from cdxcore.subdir import SubDir
+    subdir = SubDir("my_directory", "~")      # relative to home directory
+    subdir = SubDir("my_directory", "!")      # relative to default temp directory
+    subdir = SubDir("my_directory", ".")      # relative to current directory
+    subdir2 = SubDir("my_directory", subdir)  # subdir2 is relative to `subdir`
+
+Change the extension to "bin"::
+
+    from cdxcore.subdir import SubDir
+    subdir = SubDir("~/my_directory;*.bin")     
+    subdir = SubDir("~/my_directory", ext="bin")    
+    subdir = SubDir("my_directory", "~", ext="bin")    
+
+You can turn off extension management by setting the extension to ""::
+
+    from cdxcore.subdir import SubDir
+    subdir = SubDir("~/my_directory", ext="")
+
+You can also use :meth:`cdxcore.subdir.SubDir.__call__` to generate sub directories.
+
+    from cdxcore.subdir import SubDir
+    parent = SubDir("~/parent")
+    subdir = parent("subdir")
+
+Be aware that when the operator :meth:`cdxcore.subdir.SubDir.__call__`
+is called with two keyword arguments, then it reads files.
+
+You can obtain a list of all sub directories in a directory by using :meth:`cdxcore.subdir.SubDir.sub_dirs`.
+The list of files with the corresponding extension is accessible via :meth:`cdxcore.subdir.SubDir.files`. 
+
+File Format
+^^^^^^^^^^^
+
+:class:`cdxcore.subdir.SubDir` supports file i/o with a number of different file formats
+via :class:`cdxcore.subdir.Format`.
+
+* "PICKLE": standard pickling with default extension is "pck".
+
+* "JSON_PICKLE": uses the :mod:`jsonpickle` package; default extension "jpck".
+  The advantage of this format over "PICKLE" is that it is somewhat human-readable.
+  However, ``jsonpickle`` uses compressed formats for complex objects such as :mod:`numpy`
+  arrays, hence readablility is somewhat limited. Using "JSON_PICKLE"
+  comes at cost of slower i/o speed.
+
+* "JSON_PLAIN": calls :func:`cdxcore.util.plain` is used to generate human readable files
+  which cannot be loaded back from disk.
+  In this mode ``SubDir`` converts objects into plain Python objects before using :mod:`json`
+  to write them to disk.
+  That means that deserialized data does not have the correct object structure
+  to be able to restore files written in "JSON_PLAIN".
+  However, such files are much easier to read.
+
+* "BLOSC" uses `blosc <https://github.com/blosc/python-blosc>`__
+  to read/write compressed binary data. The blosc compression algorithm is very fast,
+  hence using this mode will not usually lead to notably slower performanbce than using
+  "PICKLE" but will generate smaller files, depending on your data structure.
+  
+  The default extension for "BLOSC" is "zbsc".
+
+* "GZIP": uses :mod:`gzip` to 
+  to read/write compressed binary data. The default extension is "pgz".
+
+Summary of properties:
+
+
++--------------+------------------+----------------+-------+-------------+-----------+
+| Format       | Restores objects | Human readable | Speed | Compression | Extension |
++==============+==================+================+=======+=============+===========+
+| PICKLE       | yes              | no             | high  | no          | .pck      |
++--------------+------------------+----------------+-------+-------------+-----------+
+| JSON_PLAIN   | no               | yes            | low   | no          | .json     |
++--------------+------------------+----------------+-------+-------------+-----------+
+| JSON_PICKLE  | yes              | limited        | low   | no          | .jpck     |
++--------------+------------------+----------------+-------+-------------+-----------+
+| BLOSC        | yes              | no             | high  | yes         | .zbsc     |
++--------------+------------------+----------------+-------+-------------+-----------+
+| GZIP         | yes              | no             | high  | yes         | .pgz      |
++--------------+------------------+----------------+-------+-------------+-----------+
+
+
+You may specify the file format when instantiating :class:`cdxcore.subdir.SubDir`::
+
+    from cdxcore.subdir import SubDir
+    subdir = SubDir("~/my_directory", fmt=SubDir.PICKLE)
+    subdir = SubDir("~/my_directory", fmt=SubDir.JSON_PICKLE)
+    ...
+
+If ``ext`` is not specified the extension will defaulted to 
+the respective default extension of the format requested.
+
+Reading Files
+^^^^^^^^^^^^^
+
+To read the data contained in a ``file`` from our subdirectory
+with its reference extension use :meth:`cdxcore.subdir.SubDir.read`::
+
+    from cdxcore.subdir import SubDir
+    subdir = SubDir("!/test")
+    
+    data = subdir.read("file")                 # returns the default `None` if file is not found
+    data = subdir.read("file", default=[])     # returns the default [] if file is not found
+
+This function will return the "default"``" (which in turns defaults to ``None``)
+if ``file.ext`` does not exist.
+You can opt for :meth:`cdxcore.subdir.SubDir.read` to raise an error instead of returning a default
+by using ``raise_on_error=True``::
+
+    data = subdir.read("file", raise_on_error=True)  # raises 'KeyError' if not found
+
+When calling ``read()`` you may specify an alternative extension::
+
+    data = subdir.read("file", ext="bin")     # change extension to "bin"
+    data = subdir.read("file.bin", ext="")    # no automatic extension
+
+Specifying a different format for :meth:`cdxcore.subdir.SubDir.read` only changes
+the extension automatically if you have not overwritten it before:
+
+.. code-block:: python
+
+    subdir = SubDir("!/test")                              # default format PICKLE with extension pck
+    data   = subdir.read("file", fmt=Subdir.JSON_PICKLE )  # uses "json" extension
+    
+    subdir = SubDir("!/test", ext="bin")                   # user-specified extension
+    data   = subdir.read("file", fmt=Subdir.JSON_PICKLE )  # keeps using "bin"
+    
+You can also use the :meth:`cdxcore.subdir.SubDir.__call__` to read files, in which case you must specify a default value
+(if you don't, then the operator will return a sub directory)::
+
+    data = subdir("file", None)   # returns None if file is not found
+
+You can also use item notation to access files.
+In this case, though, an error will be thrown if the file does not exist::
+
+    data = subdir['file']   # raises KeyError if file is not found
+
+You can read a range of files in one function call::
+
+    data = subdir.read( ["file1", "file2"] )   # returns list
+
+Finally, you can also iterate through all existing files using iterators::
+
+    # manual loading
+    for file in subdir:
+        data = subdir.read(file)
+        ...
+        
+    # automatic loading, with "None" as a default
+    for file, data in subdir.items():
+        ...
+
+To obtain a list of all files in our directory which have the correct extension, use :meth:`cdxcore.subdir.SubDir.files`.
+
+Writing Files
+^^^^^^^^^^^^^
 
+Writing files mirrors reading them::
 
-import os
-import os.path
-import uuid
-import threading
-import pickle
-import tempfile
-import shutil
-import datetime
-import inspect
+    from cdxcore.subdir import SubDir
+    subdir = SubDir("!/test")
+    
+    subdir.write("file", data)
+    subdir['file'] = data
+
+You may specifify different a extension::
+
+    subdir.write("file", data, ext="bin")
+
+You can also specify a file :class:`cdxcore.subdir.Format`.
+The extension will be changed automatically if you have not set it manually::
+
+    subdir = SubDir("!/test")
+    subdir.write("file", data, fmt=SubDir.JSON_PICKLE )   # will write to "file.json"
+
+To write several files at once, write::
+
+    subdir.write(["file1", "file"], [data1, data2])
+
+Note that when writing to a file, :meth:`cdxcore.subdir.SubDir.write`
+will first write to a temporary file, and then rename this file into the target file name.
+The temporary file name is generated by applying :func:`cdxcore.uniquehash.unique_hash48`
+to the
+target file name, 
+current time, process and thread ID, as well as the machines's UUID. 
+his is done to reduce collisions between processes/machines accessing the same files,
+potentially accross a network.
+It does not remove collision risk entirely, though.
+
+Filenames
+^^^^^^^^^
+
+:class:`cdxcore.subdir.SubDir` transparently handles directory access and extensions.
+That means a user usually only uses ``file`` names which do not contain either.
+To  obtain the full qualified filename given a "file" use :meth:`cdxcore.subdir.SubDir.full_file_name`.
+
+Reading and Writing Versioned Files
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+:class:`cdxcore.subdir.SubDir` supports versioned files.
+If versions are used, then they *must* be used for both reading and writing.
+:dec:`cdxcore.version.version` provides a standard decorator framework for definining
+versions for classes and functions including the version dependencies.
+
+If a ``version`` is provided to :func:`cdxcore.subdir.SubDir.write`
+then ``SubDir`` will write the version in a block ahead of the main content of the file.
+In case of the PICKLE format, this is a byte string. In case of JSON_PLAIN and JSON_PICKLE this is line of
+text starting with ``#`` ahead of the file. (Note that this violates
+the JSON file format.)
+  
+Writing short version block ahead of the main data allows :func:`cdxcore.subdir.SubDir.read`
+reading this version information back quickly without needing to read the entire file.
+``read()`` does attempt so if its called with a ``version`` parameter.
+In this case it will compare the read version with the provided version,
+and only return the main content of the file if versions match.
+
+Use :func:`cdxcore.subdir.SubDir.is_version` to check whether a given file has a specific version.
+Like ``read()`` this function only reads the information required to obtain the information and will
+be much faster than reading the whole file.
+
+*Important:* note that if a file was written, it has to be read again with a test version.
+You can specify ``version="*"`` for :func:`cdxcore.subdir.SubDir.read` to match any version.
+
+**Examples:**
+
+Writing a versioned file::
+
+    from cdxcore.subdir import SubDir
+    sub_dir = SubDir("!/test_version)
+    sub_dir.write("test", [1,2,3], version="0.0.1" )
+
+To read ``[1,2,3]`` from "test" we need to use the correct version::
+
+    _ = sub_dir.read("test", version="0.0.1") 
+
+The following will not read "test" as the versions do not match::
+
+    _ = sub_dir.read("test", version="0.0.2")
+
+By default :func:`cdxcore.subdir.SubDir.read` 
+will not fail if a version mismatch is encountered; rather it will
+attempt to delete the file and then return the ``default`` value.
+
+This can be turned off
+with the keyword ``delete_wrong_version`` set to ``False``.
+
+You can ignore the version used to write a file by using `*` as version::
+
+    _ = sub_dir.read("test", version="*")
+
+Note that reading files which have been written with a ``version`` without
+``version`` keyword will fail because ``SubDir`` will only append additional version information
+to the file if required.
+
+Test existence of Files
+^^^^^^^^^^^^^^^^^^^^^^^
+
+To test existence of 'file' in a directory, use one of::
+
+    subdir.exist('file')
+    'file' in subdir
+
+Deleting files
+^^^^^^^^^^^^^^
+
+To delete a 'file', use any of the following::
+
+    subdir.delete("file")
+    del subdir['file']
+
+All of these are *silent*, and will not throw errors if "file" does not exist.
+In order to throw an error use::
+
+    subdir.delete('file', raise_on_error=True)
+
+A few member functions assist in deleting a number of files:
+
+* :func:`cdxcore.subdir.SubDir.delete_all_files`: delete all files in the directory with matching extension. Do not delete sub directories, or files with extensions different to our own.
+* :func:`cdxcore.subdir.SubDir.delete_all_content`: delete all files with our extension, including in all sub-directories. If a sub-directory is left empty
+  upon ``delete_all_content`` delete it, too.
+* :func:`cdxcore.subdir.SubDir.delete_everything`: deletes *everything*, not just files with matching extensions.
+
+Caching
+^^^^^^^
+
+A :class:`cdxcore.subdir.SubDir` object offers an advanced context for caching calls to :class:`collection.abc.Callable``
+objects with :dec:`cdxcore.subdir.SubDir.cache`.
+
+This involves keying the cache by the function name and its current parameters using :class:`cdxcore.uniquehash.UniqueHash`,
+and monitoring the functions version using :dec:`cdxcore.version.version`. The caching behaviour itself can be controlled by
+specifying the desired :class:`cdxcore.subdir.CacheMode`.
+
+Import
+------
+.. code-block:: python
+
+    import cdxcore.uniquehash as uniquehash
+    
+Documentation
+-------------
+"""
+
+import os as os
+import uuid as uuid
+import threading as threading
+import pickle as pickle
+import tempfile as tempfile
+import shutil as shutil
+import datetime as datetime
+import inspect as inspect
+import platform as platform
 from collections import OrderedDict
-from collections.abc import Collection, Mapping, Callable
+from collections.abc import Collection, Mapping, Callable, Iterable
 from enum import Enum
-import json as json
-import platform as platform
 from functools import update_wrapper
-import warnings as warnings
         
-import numpy as np
-import jsonpickle as jsonpickle
-import jsonpickle.ext.numpy as jsonpickle_numpy
-import zlib as zlib
+import json as json
 import gzip as gzip
 import blosc as blosc
-
-from .prettydict import pdct
+import sys as sys
+from .err import verify, error, warn, fmt as txtfmt
+from .pretty import PrettyObject
 from .verbose import Context
-from .version import Version, version as version_decorator
-from .util import fmt_list, fmt_filename, DEF_FILE_NAME_MAP, fmt as txtfmt, plain
-from .uniquehash import uniqueHash48, uniqueLabelExt, namedUniqueHashExt
-
-def error( text, *args, exception = RuntimeError, **kwargs ):
-    raise exception( txtfmt(text, *args, **kwargs) )
-def verify( cond, text, *args, exception = RuntimeError, **kwargs ):
-    if not cond:
-        error( text, *args, **kwargs, exception=exception )
-def warn( text, *args, warning=warnings.RuntimeWarning, stack_level=1, **kwargs ):    
-    warnings.warn( txtfmt(text, *args, **kwargs), warning, stack_level=stack_level ) 
+from .version import Version, version as version_decorator, VersionError
+from .util import fmt_list, fmt_filename, DEF_FILE_NAME_MAP, plain, is_filename
+from .uniquehash import unique_hash48, UniqueLabel, NamedUniqueHash
+
 
 """
+:meta private:
 compression
 """
-jsonpickle_numpy.register_handlers()
+
+def _import_jsonpickle():
+    """ For some dodgy reason importing `jsonpickle` normally causes my tests to fail with a recursion error """
+    jsonpickle = sys.modules.get('jsonpickle', None)
+    if jsonpickle is None:
+        import jsonpickle as jsonpickle
+        import jsonpickle.ext.numpy as jsonpickle_numpy
+        jsonpickle_numpy.register_handlers()
+    return jsonpickle
+
 BLOSC_MAX_BLOCK = 2147483631
 BLOSC_MAX_USE   = 1147400000 # ... blosc really cannot handle large files
-
-"""
-Hashing
-"""
-uniqueFileName48 = uniqueHash48
-uniqueNamedFileName48_16 = namedUniqueHashExt(max_length=48,id_length=16,filename_by=DEF_FILE_NAME_MAP)
-uniqueLabelledFileName48_16 = uniqueLabelExt(max_length=48,id_length=16,filename_by=DEF_FILE_NAME_MAP)
+#
 
 def _remove_trailing( path ):
     if len(path) > 0:
@@ -63,13 +389,34 @@ def _remove_trailing( path ):
             return _remove_trailing(path[:-1])
     return path
 
+
+# ========================================================================
+# Basics
+# ========================================================================
+
 class Format(Enum):
-    """ File formats for SubDir """
-    PICKLE = 0
-    JSON_PICKLE = 1
-    JSON_PLAIN = 2
-    BLOSC = 3
-    GZIP = 4
+    """
+    File formats for :class:`cdxcore.subdir.SubDir`.
+    
+    +--------------+------------------+----------------+-------+-------------+-----------+
+    | Format       | Restores objects | Human readable | Speed | Compression | Extension |
+    +==============+==================+================+=======+=============+===========+
+    | PICKLE       | yes              | no             | high  | no          | .pck      |
+    +--------------+------------------+----------------+-------+-------------+-----------+
+    | JSON_PLAIN   | no               | yes            | low   | no          | .json     |
+    +--------------+------------------+----------------+-------+-------------+-----------+
+    | JSON_PICKLE  | yes              | limited        | low   | no          | .jpck     |
+    +--------------+------------------+----------------+-------+-------------+-----------+
+    | BLOSC        | yes              | no             | high  | yes         | .zbsc     |
+    +--------------+------------------+----------------+-------+-------------+-----------+
+    | GZIP         | yes              | no             | high  | yes         | .pgz      |
+    +--------------+------------------+----------------+-------+-------------+-----------+
+    """
+    PICKLE = 0       #: Standard binary :mod:`pickle` format.
+    JSON_PICKLE = 1  #: :mod:`jsonpickle` format.
+    JSON_PLAIN = 2   #: ``json`` format.
+    BLOSC = 3        #: :mod:`blosc` binary compressed format.
+    GZIP = 4         #: :mod:`gzip` binary compressed format.
     
 PICKLE = Format.PICKLE
 JSON_PICKLE = Format.JSON_PICKLE
@@ -77,31 +424,79 @@ JSON_PLAIN = Format.JSON_PLAIN
 BLOSC = Format.BLOSC
 GZIP = Format.GZIP
 
-"""
-Use the following for config calls:
-format = subdir.mkFormat( config("format", "pickle", subdir.FORMAT_NAMES, "File format") )
-"""
-FORMAT_NAMES = [ s.lower() for s in Format.__members__ ]
-def mkFormat( name ):
-    if not name in FORMAT_NAMES:
-        raise LookupError(f"Unknown format name '{name}'. Must be one of: {fmt_list(name)}")
-    return Format[name.upper()]
+class VersionPresentError(RuntimeError):
+    """
+    Exception raised in case a file was read which had a version, but no test version
+    was provided.
+    """
+    pass
+
+# ========================================================================
+# Caching utilities
+# ========================================================================
 
 class CacheMode(object):
     """
-    CacheMode
-    A class which encodes standard behaviour of a caching strategy:
+    A class which encodes standard behaviour of a caching strategy.
+
+    **Summary mechanics:**
+        
+    +-----------------------------------------+-------+-------+-------+---------+--------+----------+
+    | Action                                  | on    | gen   | off   | update  | clear  | readonly |
+    +=========================================+=======+=======+=======+=========+========+==========+
+    | load cache from disk if exists          | x     | x     |       |         |        | x        |
+    +-----------------------------------------+-------+-------+-------+---------+--------+----------+
+    | write updates to disk                   | x     | x     |       |  x      |        |          |
+    +-----------------------------------------+-------+-------+-------+---------+--------+----------+
+    | delete existing object                  |       |       |       |         | x      |          |
+    +-----------------------------------------+-------+-------+-------+---------+--------+----------+
+    | delete existing object if incompatible  | x     |       |       |  x      | x      |          |
+    +-----------------------------------------+-------+-------+-------+---------+--------+----------+      
+
+
+    **Standard Caching Semantics**
+
+    Assuming we wish to cache results from calling a function ``f`` in a file named ``filename``
+    in a directory ``directory``, then this is the ``CacheMode`` waterfall:
 
-                                                on    gen    off     update   clear   readonly
-        load cache from disk if exists          x     x     -       -        -       x
-        write updates to disk                   x     x     -       x        -       -
-        delete existing object                  -     -     -       -        x       -
-        delete existing object if incompatible  x     -     -       x        x       -
+    .. code-block:: python
 
-    See cdxbasics.subdir for functions to manage files.
+        def cache_f( filename : str, directory : SubDir, version : str, cache_mode : CacheMode ):
+            if cache_mode.delete:
+                directory.delete(filename)
+            if cache_mode.read:
+                r = directory.read(filename,
+                                   default=None,  
+                                   version=version,
+                                   raise_on_error=False,
+                                   delete_wrong_version=cache_mode.del_incomp
+                                   )
+                if not r is None:
+                    return r
+            
+            r = f(...) # compute result
+            
+            if cache_mode.write:
+                directory.write(filename,
+                                r,
+                                version=version,
+                                raise_on_error=False
+                                )
+    
+            return r
+
+    See :func:`cdxcore.subdir.SubDir.cache` for a comprehensive
+    implementation.
+
+    Parameters
+    ----------
+        mode : str, optional
+            Which mode to use: ``"on"``, ``"gen"``, ``"off"``, ``"update"``, ``"clear"`` or ``"readonly"``.
+            
+            The default is ``None`` in which case ``"on"`` is used.
     """
 
-    ON = "on"
+    ON = "on"  
     GEN = "gen"
     OFF = "off"
     UPDATE = "update"
@@ -109,22 +504,31 @@ class CacheMode(object):
     READONLY = "readonly"
 
     MODES = [ ON, GEN, OFF, UPDATE, CLEAR, READONLY ]
+    """
+    List of available modes in text form.
+    This list can be used as ``cast`` parameter when calling :func:`cdxcore.config.Config.__call__`::
+    
+        from cdxcore.config import Config
+        from cdxcore.subdir import CacheMode
+        
+        def get_cache_mode( config : Config ) -> CacheMode:
+            return CacheMode( config("cache_mode", "on", CacheMode.MODES, CacheMode.HELP) )
+    """
+        
     HELP = "'on' for standard caching; 'gen' for caching but keep existing incompatible files; 'off' to turn off; 'update' to overwrite any existing cache; 'clear' to clear existing caches; 'readonly' to read existing caches but not write new ones"
-
+    """
+    Standard ``config`` help text, to be used with  :func:`cdxcore.config.Config.__call__` as follows::
+        
+        from cdxcore.config import Config
+        from cdxcore.subdir import CacheMode
+        
+        def get_cache_mode( config : Config ) -> CacheMode:
+            return CacheMode( config("cache_mode", "on", CacheMode.MODES, CacheMode.HELP) )
+    """
+    
     def __init__(self, mode : str = None ):
         """
-        Encodes standard behaviour of a caching strategy:
-
-                                                    on    gen    off     update   clear   readonly
-            load upon start from disk if exists     x     x     -       -        -       x
-            write updates to disk                   x     x     -       x        -       -
-            delete existing object upon start       -     -     -       -        x       -
-            delete existing object if incompatible  x     -     -       x        x       -
-
-        Parameters
-        ----------
-            mode : str
-                Which mode to use.
+        :meta private:
         """
         if isinstance( mode, CacheMode ):
             return# id copy constuctor
@@ -145,22 +549,22 @@ class CacheMode(object):
 
     @property
     def read(self) -> bool:
-        """ Whether to load any existing data when starting """
+        """ Whether to load any existing cached data. """
         return self._read
 
     @property
     def write(self) -> bool:
-        """ Whether to write cache data to disk """
+        """ Whether to cache newly computed data to disk. """
         return self._write
 
     @property
     def delete(self) -> bool:
-        """ Whether to delete existing data """
+        """ Whether to delete existing data. """
         return self._delete
 
     @property
     def del_incomp(self) -> bool:
-        """ Whether to delete existing data if it is not compatible """
+        """ Whether to delete existing data if it is not compatible or has the wrong version. """
         return self._del_in
 
     def __str__(self) -> str:# NOQA
@@ -175,311 +579,327 @@ class CacheMode(object):
 
     @property
     def is_off(self) -> bool:
-        """ Whether this cache mode is OFF """
+        """ Whether this cache mode is OFF. """
         return self.mode == self.OFF
 
     @property
     def is_on(self) -> bool:
-        """ Whether this cache mode is ON """
+        """ Whether this cache mode is ON. """
         return self.mode == self.ON
 
     @property
     def is_gen(self) -> bool:
-        """ Whether this cache mode is GEN """
+        """ Whether this cache mode is GEN. """
         return self.mode == self.GEN
 
     @property
     def is_update(self) -> bool:
-        """ Whether this cache mode is UPDATE """
+        """ Whether this cache mode is UPDATE. """
         return self.mode == self.UPDATE
 
     @property
     def is_clear(self) -> bool:
-        """ Whether this cache mode is CLEAR """
+        """ Whether this cache mode is CLEAR. """
         return self.mode == self.CLEAR
 
     @property
     def is_readonly(self) -> bool:
-        """ Whether this cache mode is READONLY """
+        """ Whether this cache mode is READONLY. """
         return self.mode == self.READONLY
 
 class CacheController( object ):
-    """
-    Central control for versioning.
-    Enabes to to turn on/off caching, debugging and tracks all versions
+    r"""
+    Central control parameters for caching.
+    
+    When a parameter object of this type
+    is assigned to a :class:`cdxcore.subdir.SubDir`,
+    then it is passed on when sub-directories are
+    created. This way all ``SubDir`` have the same
+    caching behaviour.
+    
+    See :class:`cdxcore.subdir.CacheController` for
+    a list of control parameters.
+
+    Parameters
+    ----------
+        exclude_arg_types : list[type], optional
+            List of types to exclude from producing unique ids from function arguments.
+    
+            Defaults to ``[Context]``.
+            
+        cache_mode : CacheMode, optional
+            Top level cache control.
+            Set to "OFF" to turn off all caching.
+            Default is "ON".
+            
+        max_filename_length : int, optional
+            Maximum filename length. If unique id's exceed the file name a hash of length
+            ``hash_length`` will be intergated into the file name.
+            See :class:`cdxcore.uniquehash.NamedUniqueHash`.
+            Default is ``48``.
+            
+        hash_length : int, optional
+            Length of the hash used to make sure each filename is unique
+            See :class:`cdxcore.uniquehash.NamedUniqueHash`.
+            Default is ``8``.
+            
+        debug_verbose : :class:`cdxcore.verbose.Context`, optional
+            If not ``None`` print caching process messages to this object.
+            
+            Default is ``None``.
+            
+        keep_last_arguments : bool, optional
+            Keep a dictionary of all parameters as string representations after each function call.
+            If the function ``F`` was decorated using :meth:``cdxcore.subdir.SubDir.cache``,
+            you can access this information via ``F.cache_info.last_arguments``.
+
+            Note that strings are limited to 100 characters per argument to avoid memory
+            overload when large objects are passed.    
+            
+            Default is ``False``.
     """
     
     def __init__(self, *,
                     exclude_arg_types  : list[type] = [Context],
                     cache_mode         : CacheMode = CacheMode.ON,
                     max_filename_length: int = 48,
-                    hash_length        : int = 16,
+                    hash_length        : int = 8,
                     debug_verbose      : Context = None,
                     keep_last_arguments: bool = False
                     ):
         """
-        Background parameters to control caching
-        
-        Parameters
-        ----------
-            exclude_arg_types :
-                List of types to exclude from producing unique ids from function arguments. Defaults to [SubDir, Context]
-            cache_mode :
-                Top level cache control. Set to "OFF" to turn off all caching. Default is "ON"
-            max_filename_length :
-                Maximum filename length. If unique id's exceed the file name a hash of length 'hash_length' will be intergated into the file name.
-                See cdxbasics.util.namedUniqueHashExt and cdxbasics.util.uniqueLabelExt
-            hash_length :
-                Length of the hash used to make sure each filename is unique
-                See cdxbasics.util.namedUniqueHashExt and cdxbasics.util.uniqueLabelExt
-            debug_verbose :
-                If non-None print caching process messages to this object.
-            keep_last_arguments :
-                keep a dictionary of all parameters as string representations after each function call.
-                If the function F was decorated using SubDir.cache(), you can access this information via
-                    F.cache_info.last_arguments
-                Note that strings are limited to 100 characters per argument to avoid memory
-                overload when large objects are passed.
-        """
-        max_filename_length          = int(max_filename_length)
-        hash_length                  = int(hash_length)
+        :meta private:
+        """
+        max_filename_length         = int(max_filename_length)
+        hash_length                 = int(hash_length)
         assert max_filename_length>0, ("'max_filename_length' must be positive")
         assert hash_length>0 and hash_length<=max_filename_length, ("'hash_length' must be positive and at most 'max_filename_length'")
         assert max_filename_length>=hash_length, ("'hash_length' must not exceed 'max_filename_length")
         self.cache_mode             = CacheMode(cache_mode if not cache_mode is None else CacheMode.ON)
-        self.debug_verbose          = debug_verbose
+        self.debug_verbose          = Context(debug_verbose) if isinstance(debug_verbose, (int,str)) else debug_verbose
         self.exclude_arg_types      = set(exclude_arg_types) if not exclude_arg_types is None else None
-        self.versioned              = pdct()  # list
-        self.uniqueNamedFileName    = namedUniqueHashExt(max_length=max_filename_length,id_length=hash_length,filename_by=DEF_FILE_NAME_MAP)
-        self.uniqueLabelledFileName = uniqueLabelExt(max_length=max_filename_length,id_length=hash_length,filename_by=DEF_FILE_NAME_MAP)
+        self.versioned              = PrettyObject()  # list
+        self.labelledFileName       = NamedUniqueHash(max_length=max_filename_length,id_length=hash_length,filename_by=DEF_FILE_NAME_MAP)
+        self.uniqueFileName         = UniqueLabel(max_length=max_filename_length,id_length=hash_length,filename_by=None)
         self.keep_last_arguments    = keep_last_arguments
 
 default_cacheController = CacheController()
+#
 
+# ========================================================================
+# SubDir
+# ========================================================================
 
-class CacheTracker(object):
-    """
-    Utility class to track caching and be able to delete all dependent objects
+class SubDir(object):
+    r"""
+    ``SubDir`` implements a transparent i/o
+    interface for storing data in files.
     
-    """
-    def __init__(self):
-        """ track cache files """
-        self._files = []
-    def __iadd__(self, new_file):
-        """ Add a new file to the tracker """
-        self._files.append( new_file )
-    def delete_cache_files(self):
-        """ Delete all tracked files """
-        for file in self._files:
-            if os.path.exists(file):
-                os.remove(file)
-        self._files = []
-    def __str__(self) -> str:#NOQA
-        return f"Tracked: {self._files}"
-    def __repr__(self) -> str:#NOQA
-        return f"Tracked: {self._files}"
-
-class InitCacheInfo(object):
-    pass
+    **Directories**
 
-class CacheInfo(object):
-    pass
+    Instantiate a ``SubDir`` with a directory name. There are some
+    pre-defined relative system paths the name can refer to::
     
-# SubDir
-# ======
+        from cdxcore.subdir import SubDir
+        parent  = SubDir("!/subdir")         # relative to system temp directory
+        parent  = SubDir("~/subdir")         # relative to user home directory
+        parent  = SubDir("./subdir")         # relative to current working directory (explicit)
+        parent  = SubDir("subdir")           # relative to current working directory (implicit)
+        parent  = SubDir("/tmp/subdir")      # absolute path (linux)
+        parent  = SubDir("C:/temp/subdir")   # absolute path (windows)
+        parent  = SubDir("")                 # current working directory
+        
+    Sub-directories can be generated in a number of ways::
 
-class SubDir(object):
-    """
-    SubDir implements a transparent interface for storing data in files, with a common extension.
-    The generic pattern is:
+        subDir = parent('subdir')              # using __call__
+        subDir = SubDir('subdir', parent)      # explicit constructor
+        subDir = SubDir('subdir', parent="!/") # explicit constructor with parent being a string
 
-        1) create a root 'parentDir':
-            Absolute:                      parentDir = SubDir("C:/temp/root")
-            In system temp directory:      parentDir = SubDir("!/root")
-            In user directory:             parentDir = SubDir("~/root")
-            Relative to current directory: parentDir = SubDir("./root")
+    Files managed by ``SubDir`` will usually have the same extension.
+    This extension can be specified with ``ext``, or as part of the directory string::
+        
+        subDir = SubDir("~/subdir", ext="bin") # set extension to 'bin'
+        subDir = SubDir("~/subdir;*.bin")      # set extension to 'bin'
+                 
+    Leaving the extension as default ``None`` allows ``SubDir`` to automatically use
+    the extension associated with any specified format.
 
-        2) Use SubDirs to transparently create hierachies of stored data:
-           assume f() will want to store some data:
+    **Copy Constructor**
 
-               def f(parentDir, ...):
+    The constructor is shallow.
 
-                   subDir = parentDir('subdir')    <-- note that the call () operator is overloaded: if a second argument is provided, the directory will try to read the respective file.
-                   or
-                   subDir = SubDir('subdir', parentDir)
-                    :
-                    :
-            Write data:
+    **File I/O**
 
-                   subDir['item1'] = item1       <-- dictionary style
-                   subDir.item2 = item2          <-- member style
-                   subDir.write('item3',item3)   <-- explicit
+    Write data with :meth:`cdxcore.subdir.SubDir.write`::
 
-            Note that write() can write to multiple files at the same time.
+        subDir.write('item3',item3)          # explicit
+        subDir['item1'] = item1              # dictionary style
 
-        3) Reading is similar
+    Note that :meth:`cdxcore.subdir.SubDir.write` can write to multiple files at the same time.
 
-                def readF(parentDir,...):
+    Read data with :meth:`cdxcore.subdir.SubDir.read`::
 
-                    subDir = parentDir('subdir')
+        item = subDir('item', 'i1')          # returns 'i1' if not found.
+        item = subdir.read('item')           # returns None if not found
+        item = subdir.read('item','i2')      # returns 'i2' if not found
+        item = subDir['item']                # raises a KeyError if not found
 
-                    item = subDir('item', 'i1')     <-- returns 'i1' if not found.
-                    item = subdir.read('item')      <-- returns None if not found
-                    item = subdir.read('item','i2') <-- returns 'i2' if not found
-                    item = subDir['item']           <-- throws a KeyError if not found
-                    item = subDir.item              <-- throws an AttributeError if not found
+    Treat files in a directory like dictionaries::
 
-        4) Treating data like dictionaries
+        for file in subDir:
+            data = subDir[file]
+            f(item, data)
 
-                def scanF(parentDir,...)
+        for file, data in subDir.items():
+            f(item, data)
 
-                    subDir = parentDir('f')
+    Delete items::
 
-                    for item in subDir:
-                        data = subDir[item]
+        del subDir['item']                    # silently fails if 'item' does not exist
+        subDir.delete('item')                 # silently fails if 'item' does not exist
+        subDir.delete('item', True)           # raises a KeyError if 'item' does not exit
 
-            Delete items:
+    Cleaning up::
 
-                del subDir['item']             <-- silently fails if 'item' does not exist
-                del subDir.item                <-- silently fails if 'item' does not exist
-                subDir.delete('item')          <-- silently fails if 'item' does not exist
-                subDir.delete('item', True)    <-- throw a KeyError if 'item' does not exit
+        parent.delete_all_content()        # silently deletes all files with matching extensions, and sub directories.
 
-        5) Cleaning up
+    **File Format**
 
-                parentDir.deleteAllContent()       <-- silently deletes all files and sub directories.
+    ``SubDir`` supports a number of file formats via :class:`cdxcore.subdir.Format`.
+    Those can be controlled with the ``fmt`` keyword in various functions not least
+    :class:`cdxcore.subdir.SubDir`::
 
-        6) As of version 0.2.59 subdir supports json file formats. Those can be controlled with the 'fmt' keyword in various functions.
-        The most straightfoward way is to specify the format of the directory itself:
+        subdir = SubDir("!/.test", fmt=SubDir.JSON_PICKLE)
 
-                subdir = SubDir("!/.test", fmt=SubDir.JSON_PICKLE)
+    See :class:`cdxcore.subdir.Format` for supported formats.
+
+    Parameters
+    ----------
+        name : str:
+            Name of the directory.
+            
+            The name may start with any of the following special characters:
+
+            * ``'.'`` for current directory
+            * ``'~'`` for home directory
+            * ``'!'`` for system default temp directory
+ 
+            The directory name may also contain a formatting string for defining ``ext`` on the fly:
+            for example use ``"!/test;*.bin"`` to specify a directory ``"test"`` in the user's
+            temp directory with extension ``"bin"``.
+            
+            The directory name can be set to ``None`` in which case it is always empty
+            and attempts to write to it fail with  :class:`EOFError`.
+            
+        parent : str | SubDir, optional
+            Parent directory. 
+            
+            If ``parent`` is a :class:`cdxcore.subdir.SubDir` then its parameters are used
+            as default values here.
 
-        The following formats are supported:
+            Default is ``None``.
+            
+        ext : str, optional
+            Extension for files managed by this ``SubDir``. All files will share the same extension.
 
-            SubDir.PICKLE:
-                Use pickle
-            SubDir.JSON_PLAIN:
-                Uses cdxbasics.util.plain() to convert data into plain Python objects and writes
-                this to disk as text. Loading back such files will result in plain Python objects,
-                but *not* the original objects
-            SubDir.JSON_PICKLE:
-                Uses the jsonpickle package to load/write data in somewhat readable text formats.
-                Data can be loaded back from such a file, but files may not be readable (e.g. numpy arrays
-                are written in compressed form).
-            SubDir.BLOSC:
-                Uses https://www.blosc.org/python-blosc/ to compress data on-the-fly.
-                BLOSC is much faster than GZIP or ZLIB but is limited to 2GB data, sadly.
-            SubDir.ZLIB:
-                Uses https://docs.python.org/3/library/zlib.html to compress data on-the-fly
-                using, essentially, GZIP.
+            If set to ``""`` no extension is assigned to this directory. That means, for example, that
+            :meth:`cdxcore.subdir.SubDir.files` returns all files contained in the directory, not
+            just files with a specific extension.
+            
+            If ``None``, use an extension depending on ``fmt``:
+                
+            * 'pck' for the default PICKLE format.
+            * 'json' for JSON_PLAIN.
+            * 'jpck' for JSON_PICKLE.
+            * 'zbsc' for BLOSC.
+            * 'pgz' for GZIP.
+            
+            Default is ``None``.
+            
+        fmt : :class:`cdxcore.subdir.Format`, optional
 
-            Summary of properties:
+            One of the :class:`cdxcore.subdir.Format` codes.
+            If ``ext`` is left to ``None`` then setting the a format will also set the corrsponding ``ext``.
+            
+            Default is ``Format.PICKLE``.
 
-                          | Restores objects | Human readable | Speed | Compression
-             PICKLE       | yes              | no             | high  | no
-             JSON_PLAIN   | no               | yes            | low   | no
-             JSON_PICKLE  | yes              | limited        | low   | no
-             BLOSC        | yes              | no             | high  | yes
-             GZIP         | yes              | no             | high  | yes
+        create_directory : bool | None, optional
+        
+            Whether to create the directory upon creation of the ``SubDir`` object; otherwise it will be created upon first
+            :meth:`cdxcore.subdir.SubDir.write`.
+            
+            Set to ``None`` to use the setting of the parent directory, or ``False`` if no parent
+            is specified.
+            
+            Default is ``False``.
 
-        Several other operations are supported; see help()
+        delete_everything : bool, optional
+        
+            Delete all contents in the newly defined sub directory upon creation.
 
-        Hans Buehler May 2020
+            Default is ``False``.
+            
+        cache_controller : :class:`cdxcore.subdir.CacheController`, optional
+        
+            An object which fine-tunes the behaviour of :meth:`cdxcore.subdir.SubDir.cache`.
+            See that function's documentation for further details. Default is ``None``.
     """
 
     class __RETURN_SUB_DIRECTORY(object):
         pass
+    """ :meta private: """
 
-    Format = Format
-    PICKLE = Format.PICKLE
+    Format = Format # :meta private
+    """ :meta private: """
+    
+    PICKLE = Format.PICKLE     
+    """ :meta private: """
+    
     JSON_PICKLE = Format.JSON_PICKLE
+    """ :meta private: """
+    
     JSON_PLAIN = Format.JSON_PLAIN
+    """ :meta private: """
+    
     BLOSC = Format.BLOSC
+    """ :meta private: """
+    
     GZIP = Format.GZIP
-
-    DEFAULT_RAISE_ON_ERROR = False
+    """ :meta private: """
+    
     RETURN_SUB_DIRECTORY = __RETURN_SUB_DIRECTORY
+    """ :meta private: """
+    
     DEFAULT_FORMAT = Format.PICKLE
-    DEFAULT_CREATE_DIRECTORY = False  # legacy behaviour so that self.path is a valid path
+    """ Default :class:`cdxcore.subdir.Format`: ``Format.PICKLE`` """
+    
     EXT_FMT_AUTO = "*"
+    """ :meta private: """
 
     MAX_VERSION_BINARY_LEN = 128
-
+    """ :meta private: """
+    
     VER_NORMAL   = 0
+    """ :meta private: """
     VER_CHECK    = 1
+    """ :meta private: """
     VER_RETURN   = 2
+    """ :meta private: """
+
     
     def __init__(self, name : str, 
-                       parent = None, *, 
+                       parent : str|type = None, *, 
                        ext : str = None, 
                        fmt : Format = None, 
-                       eraseEverything : bool = False,
-                       createDirectory : bool = None,
-                       cacheController : CacheController = None
+                       create_directory : bool = None,
+                       delete_everything : bool = False,
+                       cache_controller : CacheController = None
                        ):
         """
-        Instantiates a sub directory which contains pickle files with a common extension.
-        By default the directory is created.
-
-        Absolute directories
-            sd  = SubDir("!/subdir")           - relative to system temp directory
-            sd  = SubDir("~/subdir")           - relative to user home directory
-            sd  = SubDir("./subdir")           - relative to current working directory (explicit)
-            sd  = SubDir("subdir")             - relative to current working directory (implicit)
-            sd  = SubDir("/tmp/subdir")        - absolute path (linux)
-            sd  = SubDir("C:/temp/subdir")     - absolute path (windows)
-        Short-cut
-            sd  = SubDir("")                   - current working directory
-
-        It is often desired that the user specifies a sub-directory name under some common parent directory.
-        You can create sub directories if you provide a 'parent' directory:
-            sd2 = SubDir("subdir2", parent=sd) - relative to other sub directory
-            sd2 = sd("subdir2")                - using call operator
-        Works with strings, too:
-            sd2 = SubDir("subdir2", parent="~/my_config") - relative to ~/my_config
-
-        All files managed by SubDir will have the same extension.
-        The extension can be specified with 'ext', or as part of the directory string:
-            sd  = SubDir("~/subdir;*.bin")      - set extension to 'bin'
-
-        COPY CONSTRUCTION
-        This function also allows copy construction and constrution from a repr() string.
-
-        HANDLING KEYS
-        SubDirs allows reading data using the item and attribute notation, i.e. we may use
-            sd = SubDir("~/subdir")
-            x  = sd.x
-            y  = sd['y']
-        If the respective keys are not found, exceptions are thrown.
-
-        NONE OBJECTS
-        It is possible to set the directory name to 'None'. In this case the directory will behave as if:
-            No files exist
-            Writing fails with a EOFError.
+        Instantiates a sub directory which contains files with a common extension.
 
-        Parameters
-        ----------
-            name            - Name of the directory.
-                               '.' for current directory
-                               '~' for home directory
-                               '!' for system default temp directory
-                              May contain a formatting string for defining 'ext' on the fly:
-                                Use "!/test;*.bin" to specify 'test' in the system temp directory as root directory with extension 'bin'
-                              Can be set to None, see above.
-            parent          - Parent directory. If provided, will also set defaults for 'ext' and 'raiseOnError'
-            ext             - standard file extenson for data files. All files will share the same extension.
-                              If None, use the parent extension, or if that is not specified use an extension depending on 'fmt':
-                                     'pck' for the default PICKLE format
-                                     'json' for JSON_PLAIN
-                                     'jpck' for JSON_PICKLE
-                              Set to "" to turn off managing extensions.
-            fmt             - format, current pickle or json
-            eraseEverything - delete all contents in the newly defined subdir
-            createDirectory - whether to create the directory.
-                              Otherwise it will be created upon first write().
-                              Set to None to use the setting of the parent directory       
-        """
-        createDirectory = bool(createDirectory) if not createDirectory is None else None
+        """
+        create_directory = bool(create_directory) if not create_directory is None else None
         
         # copy constructor support
         if isinstance(name, SubDir):
@@ -487,9 +907,9 @@ class SubDir(object):
             self._path  = name._path
             self._ext   = name._ext if ext is None else ext
             self._fmt   = name._fmt if fmt is None else fmt
-            self._crt   = name._crt if createDirectory is None else createDirectory
-            self._cctrl = name._cctrl if cacheController is None else cacheController
-            if eraseEverything: raise ValueError( "Cannot use 'eraseEverything' when cloning a directory")
+            self._crt   = name._crt if create_directory is None else create_directory
+            self._cctrl = name._cctrl if cache_controller is None else cache_controller
+            if delete_everything: raise ValueError( "Cannot use 'delete_everything' when cloning a directory")
             return
 
         # reconstruction from a dictionary
@@ -498,14 +918,14 @@ class SubDir(object):
             self._path  = name['_path']
             self._ext   = name['_ext'] if ext is None else ext
             self._fmt   = name['_fmt'] if fmt is None else fmt
-            self._crt   = name['_crt'] if createDirectory is None else createDirectory
-            self._cctrl = name['_cctrl'] if cacheController is None else cacheController
-            if eraseEverything: raise ValueError( "Cannot use 'eraseEverything' when cloning a directory")
+            self._crt   = name['_crt'] if create_directory is None else create_directory
+            self._cctrl = name['_cctrl'] if cache_controller is None else cache_controller
+            if delete_everything: raise ValueError( "Cannot use 'delete_everything' when cloning a directory")
             return
 
         # parent
         if isinstance(parent, str):
-            parent = SubDir( parent, ext=ext, fmt=fmt, createDirectory=createDirectory, cacheController=cacheController )
+            parent = SubDir( parent, ext=ext, fmt=fmt, create_directory=create_directory, cache_controller=cache_controller )
         if not parent is None and not isinstance(parent, SubDir):
             raise ValueError( "'parent' must be SubDir, str, or None. Found object of type '{type(parent)}'")
 
@@ -543,15 +963,15 @@ class SubDir(object):
         else:
             self._ext = SubDir._extract_ext(ext)
             
-        # createDirectory
-        if createDirectory is None:
-            self._crt = self.DEFAULT_CREATE_DIRECTORY if parent is None else parent._crt
+        # create_directory
+        if create_directory is None:
+            self._crt = False if parent is None else parent._crt
         else:
-            self._crt = bool(createDirectory)
+            self._crt = bool(create_directory)
             
         # cache controller
-        assert type(cacheController).__name__ == CacheController.__name__, ("'cacheController' should be of type 'CacheController'", type(cacheController))
-        self._cctrl = cacheController
+        assert cache_controller is None or type(cache_controller).__name__ == CacheController.__name__, ("'cache_controller' should be of type 'CacheController'", type(cache_controller))
+        self._cctrl = cache_controller
 
         # name
         if name is None:
@@ -566,12 +986,12 @@ class SubDir(object):
                 if len(name) > 1 and name[1] != '/':
                     raise ValueError( txtfmt("If 'name' starts with '%s', then the second character must be '/' (or '\\' on windows). Found 'name' set to '%s'", name[:1], _name ))
                 if name[0] == '!':
-                    name = SubDir.tempDir()[:-1] + name[1:]
+                    name = SubDir.temp_dir()[:-1] + name[1:]
                 elif name[0] == ".":
-                    name = SubDir.workingDir()[:-1] + name[1:]
+                    name = SubDir.working_dir()[:-1] + name[1:]
                 else:
                     assert name[0] == "~", ("Internal error", name[0] )
-                    name = SubDir.userDir()[:-1] + name[1:]
+                    name = SubDir.user_dir()[:-1] + name[1:]
             elif name == "..":
                 error("Cannot use name '..'")
             elif not parent is None:
@@ -587,33 +1007,37 @@ class SubDir(object):
             self._path = os.path.abspath(name) + '/'
             self._path = self._path.replace('\\','/')
 
-            if eraseEverything:
-                self.eraseEverything(keepDirectory=self._crt)
+            if delete_everything:
+                self.delete_everything(keep_directory=self._crt)
             if self._crt:
-                self.createDirectory()
+                self.create_directory()
 
     @staticmethod
-    def expandStandardRoot( name ):
+    def expand_std_root( name ):
         """
-        Expands 'name' by a standardized root directory if provided:
-        If 'name' starts with -> return
-            ! -> tempDir()
-            . -> workingDir()
-            ~ -> userDir()
+        Expands ``name`` by a standardized root directory if provided:
+            
+        The first character of ``name`` can be either of:
+            
+        * ``"!"`` returns :meth:`cdxcore.subdir.SubDir.temp_dir()`.
+        * ``"."`` returns :meth:`cdxcore.subdir.SubDir.working_dir()`.
+        * ``"~"`` returns :meth:`cdxcore.subdir.SubDir.user_dir()`.
+        
+        If neither of these matches the first character, ``name``
+        is returned as is.
         """
         if len(name) < 2 or name[0] not in ['.','!','~'] or name[1] not in ["\\","/"]:
             return name
         if name[0] == '!':
-            return SubDir.tempDir() + name[2:]
+            return SubDir.temp_dir() + name[2:]
         elif name[0] == ".":
-            return SubDir.workingDir() + name[2:]
+            return SubDir.working_dir() + name[2:]
         else:
-            return SubDir.userDir() + name[2:]
+            return SubDir.user_dir() + name[2:]
 
-    def createDirectory( self ):
+    def create_directory( self ):
         """
-        Creates the directory if it doesn't exist yet.
-        Does not do anything if is_none.
+        Creates the current directory if it doesn't exist yet.
         """
         # create directory/clean up
         if self._path is None:
@@ -628,8 +1052,8 @@ class SubDir(object):
         if not os.path.isdir(self._path[:-1]):
             raise NotADirectoryError(txtfmt( "Cannot use sub directory %s: object exists but is not a directory", self._path[:-1] ))
 
-    def pathExists(self) -> bool:
-        """ Returns True if the current directory exists """
+    def path_exists(self) -> bool:
+        """ Whether the current directory exists """
         return os.path.exists( self._path[:-1] ) if not self._path is None else False
         
     # -- a few basic properties --
@@ -659,60 +1083,79 @@ class SubDir(object):
 
     @property
     def is_none(self) -> bool:
-        """ Whether this object is 'None' or not """
+        """ Whether this object is ``None`` or not. For such ``SubDir`` object no files exists, and writing any file will fail. """
         return self._path is None
 
     @property
     def path(self) -> str:
         """
-        Return current path, including trailing '/'
-        Note that the path may not exist yet. If this is required, consider using existing_path
+        Return current path, including trailing ``'/'``.
+        
+        Note that the path may not exist yet. If existence is required, consider using
+        :meth:`cdxcore.subdir.SubDir.existing_path`.
         """
         return self._path
 
     @property
     def existing_path(self) -> str:
         """
-        Return current path, including training '/'.
-        In addition to self.path this property ensures that the directory structure exists (or raises an exception)
+        Return current path, including training ``'/'``.
+        
+        ``existing_path`` ensures that the directory structure exists (or raises an exception).
+        Use :meth:`cdxcore.subdir.SubDir.path` if creation on the fly is not desired.
         """
-        self.createDirectory()
+        self.create_directory()
         return self.path
 
     @property
     def fmt(self) -> Format:
-        """ Returns current format """
+        """ Returns current :class:`cdxcore.subdir.Format`. """
         return self._fmt
     
     @property
     def ext(self) -> str:
         """
-        Returns the common extension of the files in this directory, including leading '.'
-        Resolves '*' into the extension associated with the current format.
+        Returns the common extension of the files in this directory, including leading ``'.'``.
+        Resolves ``"*"`` into the extension associated with the current :class:`cdxcore.subdir.Format`.
         """
         return self._ext if self._ext != self.EXT_FMT_AUTO else self._auto_ext(self._fmt)
 
-    def autoExt( self, ext : str = None ) -> str:
+    def auto_ext( self, ext_or_fmt : str|Format = None ) -> str:
         """
-        Computes the effective extension based on inputs 'ext', defaulting to the SubDir's extension.
-        Resolves '*' into the extension associated with the specified format.
-        This function allows setting 'ext' also as a Format.
+        Computes the effective extension based on theh inputs ``ext_or_fmt``,
+        and the current settings for ``self``.
+
+        If ``ext_or_fmt`` is set to ``"*"`` then the extension associated to
+        the format of ``self`` is returned.
+        
+        Parameters
+        ----------
+            ext_or_fmt : str or :class:`cdxcore.subdir.Format`
+                An extension or a format.
         
-        Returns the extension with leading '.'
+        Returns
+        -------
+            ext : str
+                The extension with leading ``'.'``.
         """
-        if isinstance(ext, Format):
-            return self._auto_ext(ext)
+        if isinstance(ext_or_fmt, Format):
+            return self._auto_ext(ext_or_fmt)
         else:
-            ext = self._ext if ext is None else SubDir._extract_ext(ext)
+            ext = self._ext if ext_or_fmt is None else SubDir._extract_ext(ext_or_fmt)
             return ext if ext != self.EXT_FMT_AUTO else self._auto_ext(self._fmt)
 
-    def autoExtFmt( self, *, ext : str = None, fmt : Format = None ) -> str:
+    def auto_ext_fmt( self, *, ext : str = None, fmt : Format = None ) -> tuple[str]:
         """
-        Computes the effective extension and format based on inputs 'ext' and 'fmt', each of which defaults to the SubDir's current settings.
-        Resolves '*' into the extension associated with the specified format.
-        This function allows setting 'ext' also as a Format.
+        Computes the effective extension and format based on inputs ``ext`` and ``fmt``,
+        each of which defaults to the respective values of ``self``.
+
+        Resolves an ``ext`` of ``"*"`` into the extension associated with ``fmt``.
 
-        Returns (ext, fmt) where 'ext' contains the leading '.'
+        Returns
+        -------
+            (ext, fmt) : tuple
+                Here ``ext`` contains the leading ``'.'`` and ``fmt`` is
+                of type :class:`cdxcore.subdir.Format`.
         """
         if isinstance(ext, Format):
             verify( fmt is None or fmt == ext, "If 'ext' is a Format, then 'fmt' must match 'ext' or be None. Found '%s' and '%s', respectively.", ext, fmt, exception=ValueError )
@@ -724,8 +1167,8 @@ class SubDir(object):
         return ext, fmt
     
     @property
-    def cacheController(self):
-        """ Returns an assigned CacheController, or None """
+    def cache_controller(self):
+        """ Returns an assigned :class:`cdxcore.subdir.CacheController`, or ``None`` """
         return self._cctrl if not self._cctrl is None else default_cacheController
 
     # -- static helpers --
@@ -747,7 +1190,10 @@ class SubDir(object):
 
     @staticmethod
     def _version_to_bytes( version : str ) -> bytearray:
-        """ Convert string version to byte string of at most size MAX_VERSION_BINARY_LEN + 1 """
+        """
+        Convert string version to byte string of at most size
+        :data:`cdxcore.subdir.SubDir.MAX_VERSION_BINARY_LEN` + 1
+        """
         if version is None:
             return None
         version_    = bytearray(version,'utf-8')
@@ -790,69 +1236,67 @@ class SubDir(object):
             
     # -- public utilities --
 
-    def fullFileName(self, key : str, *, ext : str = None) -> str:
+    def full_file_name(self, file : str, *, ext : str = None) -> str:
         """
         Returns fully qualified file name.
-        The function tests that 'key' does not contain directory information.
-
-        If 'self' is None, then this function returns None
-        If key is None then this function returns None
+        
+        The function tests that ``file`` does not contain directory information.
 
         Parameters
         ----------
-            key : str
-                Core file name, e.g. the 'key' in a data base sense
+            file : str
+                Core file name without path or extension.
             ext : str
-                If not None, use this extension rather than self.ext
+                If not ``None``, use this extension rather than :attr:`cdxcore.subdir.SubDir.ext`.
 
         Returns
         -------
-            Fully qualified system file name
-
-        [This function has an alias 'fullKeyName' for backward compatibility]
+            Filename : str
+                Fully qualified system file name.
+                If ``self`` is ``None``, then this function returns ``None``; if ``file`` is ``None`` then this function also returns ``None``.
         """
-        if self._path is None or key is None:
+        if self._path is None or file is None:
             return None
-        key = str(key)
-        verify( len(key) > 0, "'key' cannot be empty")
+        file = str(file)
+        verify( len(file) > 0, "'file' cannot be empty")
 
-        sub, _ = os.path.split(key)
-        verify( len(sub) == 0, "Key '%s' contains directory information", key)
+        sub, _ = os.path.split(file)
+        verify( len(sub) == 0, "Key '%s' contains directory information", file)
 
-        verify( key[0] != "!", "Key '%s' cannot start with '!' (this symbol indicates the temp directory)", key, exception=ValueError )
-        verify( key[0] != "~", "Key '%s' cannot start with '~' (this symbol indicates the user's directory)", key, exception=ValueError )
+        verify( file[0] != "!", "Key '%s' cannot start with '!' (this symbol indicates the temp directory)", file, exception=ValueError )
+        verify( file[0] != "~", "Key '%s' cannot start with '~' (this symbol indicates the user's directory)", file, exception=ValueError )
 
-        ext = self.autoExt( ext )
-        if len(ext) > 0 and key[-len(ext):] != ext:
-            return self._path + key + ext
-        return self._path + key
-    fullKeyName = fullFileName # backwards compatibility
+        ext = self.auto_ext( ext )
+        if len(ext) > 0 and file[-len(ext):] != ext:
+            return self._path + file + ext
+        return self._path + file
+    full_file_name = full_file_name # backwards compatibility
 
     @staticmethod
-    def tempDir() -> str:
+    def temp_dir() -> str:
         """
-        Return system temp directory. Short cut to tempfile.gettempdir()
-        Result contains trailing '/'
+        Return system temp directory. Short-cut to :func:`tempfile.gettempdir`.
+        Result contains trailing ``'/'``.
         """
         d = tempfile.gettempdir()
         assert len(d) == 0 or not (d[-1] == '/' or d[-1] == '\\'), ("*** Internal error 13123212-1", d)
         return d + "/"
 
     @staticmethod
-    def workingDir() -> str:
+    def working_dir() -> str:
         """
-        Return current working directory. Short cut for os.getcwd()
-        Result contains trailing '/'
+        Return current working directory. Short-cut for :func:`os.getcwd`.
+        Result contains trailing ``'/'``.
         """
         d = os.getcwd()
         assert len(d) == 0 or not (d[-1] == '/' or d[-1] == '\\'), ("*** Internal error 13123212-2", d)
         return d + "/"
 
     @staticmethod
-    def userDir() -> str:
+    def user_dir() -> str:
         """
-        Return current working directory. Short cut for os.path.expanduser('~')
-        Result contains trailing '/'
+        Return current working directory. Short-cut for :func:`os.path.expanduser` with parameter ``'~'``.
+        Result contains trailing ``'/'``.
         """
         d = os.path.expanduser('~')
         assert len(d) == 0 or not (d[-1] == '/' or d[-1] == '\\'), ("*** Internal error 13123212-3", d)
@@ -860,95 +1304,101 @@ class SubDir(object):
 
     # -- read --
 
-    def _read_reader( self, reader, key : str, default, raiseOnError : bool, *, ext : str = None ):
+    def _read_reader( self, reader, file : str, default, raise_on_error : bool, *, ext : str = None ):
         """
         Utility function for read() and readLine()
 
         Parameters
         ----------
-            reader( key, fullFileName, default )
+            reader( file, full_file_name, default )
                 A function which is called to read the file once the correct directory is identified
-                key : key (for error messages, might include '/')
-                fullFileName : full file name
+                file : file (for error messages, might include '/')
+                full_file_name : full file name
                 default value
-            key : str or list
-                str: fully qualified key
+            file : str or list
+                str: fully qualified file
                 list: list of fully qualified names
             default :
                 default value. None is a valid default value
                 list : list of defaults for a list of keys
-            raiseOnError : bool
+            raise_on_error : bool
                 If True, and the file does not exist, throw exception
             ext :
                 Extension or None for current extension.
                 list : list of extensions for a list of keys
         """
         # vector version
-        if not isinstance(key,str):
-            if not isinstance(key, Collection): raise ValueError(txtfmt( "'key' must be a string, or an interable object. Found type %s", type(key)))
-            l = len(key)
+        if not isinstance(file,str):
+            if not isinstance(file, Collection): raise ValueError(txtfmt( "'file' must be a string, or an interable object. Found type %s", type(file)))
+            l = len(file)
             if default is None or isinstance(default,str) or not isinstance(default, Collection):
                 default = [ default ] * l
             else:
-                if len(default) != l: raise ValueError(txtfmt("'default' must have same lengths as 'key' if the latter is a collection; found %ld and %ld", len(default), l ))
+                if len(default) != l: raise ValueError(txtfmt("'default' must have same lengths as 'file' if the latter is a collection; found %ld and %ld", len(default), l ))
             if ext is None or isinstance(ext, str) or not isinstance(ext, Collection):
                 ext = [ ext ] * l
             else:
-                if len(ext) != l: raise ValueError(txtfmt("'ext' must have same lengths as 'key' if the latter is a collection; found %ld and %ld", len(ext), l ))
-            return [ self._read_reader(reader=reader,key=k,default=d,raiseOnError=raiseOnError,ext=e) for k, d, e in zip(key,default,ext) ]
+                if len(ext) != l: raise ValueError(txtfmt("'ext' must have same lengths as 'file' if the latter is a collection; found %ld and %ld", len(ext), l ))
+            return [ self._read_reader(reader=reader,file=k,default=d,raise_on_error=raise_on_error,ext=e) for k, d, e in zip(file,default,ext) ]
 
         # deleted directory?
         if self._path is None:
-            verify( not raiseOnError, "Trying to read '%s' from an empty directory object", key, exception=NotADirectoryError)
+            verify( not raise_on_error, "Trying to read '%s' from an empty directory object", file, exception=NotADirectoryError)
             return default
 
-        # single key
-        if len(key) == 0: raise ValueError(txtfmt("'key' missing (the filename)" ))
-        sub, key_ = os.path.split(key)
+        # single file
+        if len(file) == 0: raise ValueError(txtfmt("'file' missing (the filename)" ))
+        sub, key_ = os.path.split(file)
         if len(sub) > 0:
-            return self(sub)._read_reader(reader=reader,key=key_,default=default,raiseOnError=raiseOnError,ext=ext)
-        if len(key_) == 0: ValueError(txtfmt("'key' %s indicates a directory, not a file", key))
+            return self(sub)._read_reader(reader=reader,file=key_,default=default,raise_on_error=raise_on_error,ext=ext)
+        if len(key_) == 0: ValueError(txtfmt("'file' %s indicates a directory, not a file", file))
 
         # don't try if directory doesn't exist
-        fullFileName = self.fullFileName(key,ext=ext)
-        if not self.pathExists():
-            if raiseOnError:
-                raise KeyError(key, fullFileName)
+        full_file_name = self.full_file_name(file,ext=ext)
+        if not self.path_exists():
+            if raise_on_error:
+                raise KeyError(file, full_file_name)
             return default
         
         # does file exit?
-        if not os.path.exists(fullFileName):
-            if raiseOnError:
-                raise KeyError(key,fullFileName)
+        if not os.path.exists(full_file_name):
+            if raise_on_error:
+                raise KeyError(file,full_file_name)
             return default
-        if not os.path.isfile(fullFileName):
-            raise IOError(txtfmt( "Cannot read %s: object exists, but is not a file (full path %s)", key, fullFileName ))
+        if not os.path.isfile(full_file_name):
+            raise IOError(txtfmt( "Cannot read '%s': object exists, but is not a file (full path %s)", file, full_file_name ))
 
         # read content
         # delete existing files upon read error
         try:
-            return reader( key, fullFileName, default )
+            return reader( file, full_file_name, default )
         except EOFError as e:
             try:
-                os.remove(fullFileName)
-                warn("Cannot read %s; file deleted (full path %s).\nError: %s",key,fullFileName, str(e))
+                os.remove(full_file_name)
+                warn("Cannot read '%s'; file deleted (full path '%s').\nError: %s",file,full_file_name, str(e))
             except Exception as e:
-                warn("Cannot read %s; attempt to delete file failed (full path %s): %s",key,fullFileName,str(e))
+                warn("Cannot read '%s'; subsequent attempt to delete file failed (full path '%s''): %s",file,full_file_name,str(e))
         except FileNotFoundError as e:
-            if raiseOnError:
-                raise KeyError(key, fullFileName, str(e)) from e
+            if raise_on_error:
+                raise KeyError(file, full_file_name, str(e)) from e
+        except VersionError as e:
+            if raise_on_error:
+                raise e
+        except VersionPresentError as e:
+            if raise_on_error:
+                raise e
         except Exception as e:
-            if raiseOnError:
-                raise KeyError(key, fullFileName, str(e)) from e
+            if raise_on_error:
+                raise KeyError(file, full_file_name, str(e)) from e
         except (ImportError, BaseException) as e:
-            e.add_note( key )
-            e.add_note( fullFileName )
+            e.add_note( file )
+            e.add_note( full_file_name )
             raise e
         return default
 
-    def _read( self, key : str,
+    def _read( self, file : str,
                     default = None,
-                    raiseOnError : bool = False,
+                    raise_on_error : bool = False,
                     *,
                     version : str = None,
                     ext : str = None,
@@ -957,18 +1407,34 @@ class SubDir(object):
                     handle_version : int = 0
                     ):
         """ See read() """
-        ext, fmt = self.autoExtFmt(ext=ext, fmt=fmt)
+        ext, fmt = self.auto_ext_fmt(ext=ext, fmt=fmt)
         version  = str(version) if not version is None else None
         version  = version if handle_version != SubDir.VER_RETURN else ""
         assert not fmt == self.EXT_FMT_AUTO, ("'fmt' is '*' ...?")
 
         if version is None and fmt in [Format.BLOSC, Format.GZIP]:
-            version = ""
+            # blosc and gzip have unexpected side effects
+            # a version is attempted to be read but is not present
+            # (e.g. blosc causes a MemoryError)
+            version = ""            
 
-        def reader( key, fullFileName, default ):
+        def reader( file, full_file_name, default ):
             test_version = "(unknown)"
-            if fmt == Format.PICKLE or fmt == Format.BLOSC:
-                with open(fullFileName,"rb") as f:
+            
+            def handle_pickle_error(e):
+                err = "invalid load key, '\\x03'."
+                if not version is None or e.args[0] != err:
+                    print("####", e.args)
+                    raise e
+                raise VersionPresentError(
+                                   f"Error reading '{full_file_name}': encountered an unpickling error '{err}' "+\
+                                   f"while attempting to read file using {str(fmt)}. "+\
+                                    "This is likely caused by attempting to read a file which was written with "+\
+                                    "version information without providing a test version during read(). If the version is of the file "+\
+                                    "is not important, use `version=\"*\"'", e) from e
+            if fmt == Format.PICKLE:
+                # we do not read any version information if not requested
+                with open(full_file_name,"rb") as f:
                     # handle version as byte string
                     ok      = True
                     if not version is None:
@@ -981,37 +1447,55 @@ class SubDir(object):
                     if ok:
                         if handle_version == SubDir.VER_CHECK:
                             return True
-                        if fmt == Format.PICKLE:
+                        try:
                             data = pickle.load(f)
-                        elif fmt == Format.BLOSC:
-                            if blosc is None:
-                                raise ModuleNotFoundError("blosc", "'blosc' not found.")
-                            nnbb       = f.read(2)
-                            num_blocks = int.from_bytes( nnbb, 'big', signed=False )
-                            data       = bytearray()
-                            for i in range(num_blocks):
-                                blockl = int.from_bytes( f.read(6), 'big', signed=False )
-                                if blockl>0:
-                                    bdata  = blosc.decompress( f.read(blockl) )
-                                    data  += bdata
-                                    del bdata
+                        except pickle.UnpicklingError as e:
+                            handle_pickle_error(e)
+                        return data
+
+            elif fmt == Format.BLOSC:
+                # we do not write 
+                # any version information if not requested
+                with open(full_file_name,"rb") as f:
+                    # handle version as byte string
+                    ok      = True
+                    if not version is None: # it's never None
+                        test_len     = int( f.read( 1 )[0] )
+                        test_version = f.read(test_len)
+                        test_version = test_version.decode("utf-8")
+                        if handle_version == SubDir.VER_RETURN:
+                            return test_version
+                        ok = (version == "*" or test_version == version)
+                    if ok:
+                        if handle_version == SubDir.VER_CHECK:
+                            return True
+                        nnbb       = f.read(2)
+                        num_blocks = int.from_bytes( nnbb, 'big', signed=False )
+                        data       = bytearray()
+                        for i in range(num_blocks):
+                            blockl = int.from_bytes( f.read(6), 'big', signed=False )
+                            if blockl>0:
+                                bdata  = blosc.decompress( f.read(blockl) )
+                                data  += bdata
+                                del bdata
+                        try:
                             data = pickle.loads(data)
-                        else:
-                            raise NotImplementedError(fmt, txtfmt("Unkown format '%s'", fmt))
+                        except pickle.UnpicklingError as e:
+                            handle_pickle_error(e)
                         return data
 
             elif fmt == Format.GZIP:
-                if gzip is None:
-                    raise ModuleNotFoundError("gzip", "'gzip' not found'")
-                with gzip.open(fullFileName,"rb") as f:
+                # always read version information
+                with gzip.open(full_file_name,"rb") as f:
                     # handle version as byte string
-                    ok           = True
-                    test_len     = int( f.read( 1 )[0] )
-                    test_version = f.read(test_len)
-                    test_version = test_version.decode("utf-8")
-                    if handle_version == SubDir.VER_RETURN:
-                        return test_version
-                    ok = (version == "*" or test_version == version)
+                    ok      = True
+                    if not version is None: # it's never None
+                        test_len     = int( f.read( 1 )[0] )
+                        test_version = f.read(test_len)
+                        test_version = test_version.decode("utf-8")
+                        if handle_version == SubDir.VER_RETURN:
+                            return test_version
+                        ok = (version == "*" or test_version == version)
                     if ok:
                         if handle_version == SubDir.VER_CHECK:
                             return True
@@ -1019,13 +1503,16 @@ class SubDir(object):
                         return data
 
             elif fmt in [Format.JSON_PLAIN, Format.JSON_PICKLE]:
-                with open(fullFileName,"rt",encoding="utf-8") as f:
+                # only read version information if requested
+                with open(full_file_name,"rt",encoding="utf-8") as f:
                     # handle versioning
                     ok      = True
                     if not version is None:
                         test_version = f.readline()
                         if test_version[:2] != "# ":
-                            raise EnvironmentError("Error reading '%s': file does not appear to contain a version (it should start with '# ')" % fullFileName)
+                            raise VersionError("Error reading '{full_file_name}' using {fmt}: file does not appear to contain a version (it should start with '# ')",
+                                               version_found="",
+                                               version_expected=version)                                               
                         test_version = test_version[2:]
                         if test_version[-1:] == "\n":
                             test_version = test_version[:-1]
@@ -1037,8 +1524,7 @@ class SubDir(object):
                             return ok
                         # read
                         if fmt == Format.JSON_PICKLE:
-                            if jsonpickle is None:
-                                raise ModuleNotFoundError("jsonpickle", "'jsonpickle' not found'")
+                            jsonpickle = _import_jsonpickle()
                             return jsonpickle.decode( f.read() )
                         else:
                             assert fmt == Format.JSON_PLAIN, ("Internal error: unknown Format", fmt)
@@ -1048,25 +1534,33 @@ class SubDir(object):
 
             # arrive here if version is wrong
             # delete a wrong version
+
+            if version == "":
+                raise VersionPresentError(f"Error reading '{full_file_name}' using {fmt}: the file has version '{test_version}', but was attempted to be read without "+\
+                                           "a test version. If you intended to accept any version, use 'version=\"*\"' instead.")
+
             deleted = ""
             if delete_wrong_version:
                 try:
-                    os.remove(fullFileName)
+                    os.remove(full_file_name)
                     e = None
                 except Exception as e_:
                     e = str(e_)
             if handle_version == SubDir.VER_CHECK:
                 return False
-            if not raiseOnError:
+            if not raise_on_error:
                 return default
             deleted = " (file was deleted)" if e is None else " (attempt to delete file failed: %s)" % e
-            raise EnvironmentError("Error reading '%s': found version '%s' not '%s'%s" % (fullFileName,str(test_version),str(version),deleted))
+            raise VersionError( f"Error reading '{full_file_name}' using {fmt}: found version '{test_version}' not '{version}'{deleted}",
+                                version_found=test_version,
+                                version_expected=version
+                                )
 
-        return self._read_reader( reader=reader, key=key, default=default, raiseOnError=raiseOnError, ext=ext )
+        return self._read_reader( reader=reader, file=file, default=default, raise_on_error=raise_on_error, ext=ext )
 
-    def read( self, key : str,
+    def read( self, file : str,
                     default = None,
-                    raiseOnError : bool = False,
+                    raise_on_error : bool = False,
                     *,
                     version : str = None,
                     delete_wrong_version : bool = True,
@@ -1074,296 +1568,323 @@ class SubDir(object):
                     fmt : Format = None
                     ):
         """
-        Read pickled data from 'key' if the file exists, or return 'default'
-        -- Supports 'key' containing directories
-        -- Supports 'key' (and default, ext) being iterable.
-           In this case any any iterable 'default' except strings are considered accordingly.
-           In order to have a unit default which is an iterable, you will have to wrap it in another iterable, e.g.
-           E.g.:
-              keys = ['file1', 'file2']
-
-              sd.read( keys )
-              --> works, both are using default None
+        Read data from a file if the file exists, or return ``default``.
 
-              sd.read( keys, 1 )
-              --> works, both are using default '1'
+        * Supports ``file`` containing directory information.
+        * Supports ``file`` (and ``default``as well as ``ext``) being iterable.
+          Examples::
+              
+            from cdxcore.subdir import SubDir
+            files = ['file1', 'file2']
+            sd = SubDir("!/test")
 
-              sd.read( keys, [1,2] )
-              --> works, defaults 1 and 2, respectively
+            sd.read( files )          # both files are using default None
+            sd.read( files, 1 )       # both files are using default '1'
+            sd.read( files, [1,2] )   # files use defaults 1 and 2, respectively
 
-              sd.read( keys, [1] )
-              --> produces error as len(keys) != len(default)
+            sd.read( files, [1] )      # produces error as len(keys) != len([1])
 
-            Strings are iterable but are treated as single value.
-            Therefore
-                sd.read( keys, '12' )
-            means the default value '12' is used for both files.
-            Use
-                sd.read( keys, ['1','2'] )
-            in case the intention was using '1' and '2', respectively.
-
-        Returns the read object, or a list of objects if 'key' was iterable.
-        If the current directory is 'None', then behaviour is as if the file did not exist.
+          Strings are iterable but are treated as single value.
+          Therefore::
+              
+            sd.read( files, '12' )      # the default value '12' is used for both files
+            sd.read( files, ['1','2'] ) # use defaults '1' and '2', respectively
 
         Parameters
         ----------
-            key : str
-                A core filename ("key") or a list thereof. The 'key' may contain subdirectory information '/'.
+            file : str
+                A file name or a list thereof. ``file`` may contain subdirectories.
+                
             default :
-                Default value, or default values if key is a list
-            raiseOnError : bool
+                Default value, or default values if ``file`` is a list.
+                
+            raise_on_error : bool
                 Whether to raise an exception if reading an existing file failed.
                 By default this function fails silently and returns the default.
+                
             version : str
-                If not None, specifies the version of the current code base.
+                If not ``None``, specifies the version of the current code base.
+                
                 In this case, this version will be compared to the version of the file being read.
-                If they do not match, read fails (either by returning default or throwing an exception).
-                You can specify version "*" to read any version. This is distrinct from reading a file without version.
+                If they do not match, read fails (either by returning default or throwing a :class:`cdxcore.version.VersionError` exception).
+
+                You can specify version ``"*"`` to accept any version.
+                Note that this is distinct
+                to using ``None`` which stipulates that the file should not 
+                have version information.
+                
             delete_wrong_version : bool
-                If True, and if a wrong version was found, delete the file.
+                If ``True``, and if a wrong version was found, delete the file.
+
             ext : str
-                Extension overwrite, or a list thereof if key is a list
-                Set to:
-                -- None to use directory's default
-                -- '*' to use the extension implied by 'fmt' 
-                -- for convenience 'ext' can also be a Format (in this case leave fmt to None)
-            fmt : Format
-                File format or None to use the directory's default.
-                Note that 'fmt' cannot be a list even if 'key' is.
-                Note that unless 'ext' or the SubDir's extension is '*', changing the format does not automatically change the extension.
+                Extension overwrite, or a list thereof if ``file`` is a list.
+                
+                Use:
+                    
+                * ``None`` to use directory's default.
+                * ``'*'`` to use the extension implied by ``fmt``.
+                * ``""`` to turn of extension management.
+                
+            fmt : :class:`cdxcore.subdir.Format`
+                File :class:`cdxcore.subdir.Format` or ``None`` to use the directory's default.
+                
+                Note:
+                    
+                * ``fmt`` cannot be a list even if ``file`` is.
+                * Unless ``ext`` or the SubDir's extension is ``'*'``, changing the format does not automatically change the extension.
 
         Returns
         -------
-            For a single 'key': Content of the file if successfully read, or 'default' otherwise.
-            If 'key' is a list: list of contents.
+            Content 
+                For a single ``file`` returns the content of the file if successfully read, or ``default`` otherwise.
+                If ``file``` is a list: list of contents.
+                
+        Raises
+        ------
+            :class:`cdxcore.version.VersionError`:
+                If the file's version did not match the ``version`` provided.
+                
         """
-        return self._read( key=key,
+        return self._read( file=file,
                            default=default,
-                           raiseOnError=raiseOnError,
+                           raise_on_error=raise_on_error,
                            version=version,
                            ext=ext,
                            fmt=fmt,
                            delete_wrong_version=delete_wrong_version,
                            handle_version=SubDir.VER_NORMAL )
 
-    get = read # backwards compatibility
-
-    def is_version( self, key : str, version : str = None, raiseOnError : bool = False, *, ext : str = None, fmt : Format = None, delete_wrong_version : bool = True ):
+    def is_version( self, file : str, version : str = None, raise_on_error : bool = False, *, ext : str = None, fmt : Format = None, delete_wrong_version : bool = True ):
         """
-        Compares the version of 'key' with 'version'.
+        Tests the version of a file.
 
         Parameters
         ----------
-            key : str
-                A core filename ("key") or a list thereof. The 'key' may contain subdirectory information '/'.
+            file : str
+                A filename, or a list thereof.
+ 
             version : str
-                Specifies the version of the current code base to compare with.
-                You can use '*' to match any version
+                Specifies the version to compare the file's version with.
+                
+                You can use ``"*"`` to match any version.
 
-            raiseOnError : bool
+            raise_on_error : bool
                 Whether to raise an exception if accessing an existing file failed (e.g. if it is a directory).
                 By default this function fails silently and returns the default.
+ 
             delete_wrong_version : bool
-                If True, and if a wrong version was found, delete the file.
+                If True, and if a wrong version was found, delete ``file``.
+                
             ext : str
-                Extension overwrite, or a list thereof if key is a list.
+                Extension overwrite, or a list thereof if file is a list.
+                
                 Set to:
-                -- None to use directory's default
-                -- '*' to use the extension implied by 'fmt' 
-                -- for convenience 'ext' can also be a Format (in this case leave fmt to None)
-            fmt : Format
-                File format or None to use the directory's default.
-                Note that 'fmt' cannot be a list even if 'key' is.
-                Note that unless 'ext' or the SubDir's extension is '*', changing the format does not automatically change the extension.
+                    
+                * ``None`` to use directory's default.
+                * ``"*"`` to use the extension implied by ``fmt``.
+                * ``""`` for no extension.
+                
+            fmt : :class:`cdxcore.subdir.Format`
+                File format or ``None`` to use the directory's default.
+                Note that ``fmt`` cannot be a list even if ``file`` is.
 
         Returns
         -------
-            Returns True only if the file exists and has the correct version.
+            Status : bool
+                Returns `True` only if the file exists, has version information, and its version is equal to ``version``.
         """
-        return self._read( key=key,default=False,raiseOnError=raiseOnError,version=version,ext=ext,fmt=fmt,delete_wrong_version=delete_wrong_version,handle_version=SubDir.VER_CHECK )
+        return self._read( file=file,default=False,raise_on_error=raise_on_error,version=version,ext=ext,fmt=fmt,delete_wrong_version=delete_wrong_version,handle_version=SubDir.VER_CHECK )
 
-    def get_version( self, key : str, raiseOnError : bool = False, *, ext : str = None, fmt : Format = None ):
+    def get_version( self, file : str, raise_on_error : bool = False, *, ext : str = None, fmt : Format = None ):
         """
-        Returns the version ID stored in 'key'.
+        Returns a version stored in a file.
+        
         This requires that the file has previously been saved with a version.
-        Otherwise this function will return unpredictable results.
+        Otherwise this function will have unpredictable results.
 
         Parameters
         ----------
-            key : str
-                A core filename ("key") or a list thereof. The 'key' may contain subdirectory information '/'.
-            raiseOnError : bool
+            file : str
+                A filename, or a list thereof. 
+
+            raise_on_error : bool
                 Whether to raise an exception if accessing an existing file failed (e.g. if it is a directory).
                 By default this function fails silently and returns the default.
+ 
+            delete_wrong_version : bool
+                If ``True``, and if a wrong version was found, delete ``file``.
+                
             ext : str
-                Extension overwrite, or a list thereof if key is a list.
+                Extension overwrite, or a list thereof if ``file`` is a list.
+                
                 Set to:
-                -- None to use directory's default
-                -- '*' to use the extension implied by 'fmt' 
-                -- for convenience 'ext' can also be a Format (in this case leave fmt to None)
-            fmt : Format
-                File format or None to use the directory's default.
-                Note that 'fmt' cannot be a list even if 'key' is.
-                Note that unless 'ext' or the SubDir's extension is '*', changing the format does not automatically change the extension.
+                    
+                * ``None`` to use directory's default.
+                * ``"*"`` to use the extension implied by ``fmt``.
+                * ``""`` for no extension.
+                
+            fmt : :class:`cdxcore.subdir.Format`
+                File format or ``None`` to use the directory's default.
+                Note that ``fmt`` cannot be a list even if ``file`` is.
 
         Returns
         -------
-            Version ID.
+            version : str
         """
-        return self._read( key=key,default=None,raiseOnError=raiseOnError,version="",ext=ext,fmt=fmt,delete_wrong_version=False,handle_version=SubDir.VER_RETURN )
+        return self._read( file=file,default=None,raise_on_error=raise_on_error,version="",ext=ext,fmt=fmt,delete_wrong_version=False,handle_version=SubDir.VER_RETURN )
 
-    def readString( self, key : str, default = None, raiseOnError : bool = False, *, ext : str = None ) -> str:
+    def read_string( self, file : str, default = None, raise_on_error : bool = False, *, ext : str = None ) -> str:
         """
-        Reads text from 'key' or returns 'default'. Removes trailing EOLs
-        -- Supports 'key' containing directories#
-        -- Supports 'key' being iterable. In this case any 'default' can be a list, too.
-
-        Returns the read string, or a list of strings if 'key' was iterable.
-        If the current directory is 'None', then behaviour is as if the file did not exist.
-
-        Use 'ext' to specify the extension.
-        You cannot use 'ext' to specify a format as the format is plain text.
-        If 'ext' is '*' or if self._ext is '*' then the default extension is 'txt'.
+        Reads text from a file. Removes trailing EOLs.
+        
+        Returns the read string, or a list of strings if ``file`` was iterable.
         """
         verify( not isinstance(ext, Format), "Cannot change format when writing strings. Found extension '%s'", ext)
         ext = ext if not ext is None else self._ext
         ext = ext if ext != self.EXT_FMT_AUTO else ".txt"
 
-        def reader( key, fullFileName, default ):
-            with open(fullFileName,"rt",encoding="utf-8") as f:
+        def reader( file, full_file_name, default ):
+            with open(full_file_name,"rt",encoding="utf-8") as f:
                 line = f.readline()
                 if len(line) > 0 and line[-1] == '\n':
                     line = line[:-1]
                 return line
-        return self._read_reader( reader=reader, key=key, default=default, raiseOnError=raiseOnError, ext=ext )
+        return self._read_reader( reader=reader, file=file, default=default, raise_on_error=raise_on_error, ext=ext )
 
     # -- write --
 
-    def _write( self, writer, key : str, obj, raiseOnError : bool, *, ext : str = None ) -> bool:
+    def _write( self, writer, file : str, obj, raise_on_error : bool, *, ext : str = None ) -> bool:
         """ Utility function for write() and writeLine() """
         if self._path is None:
-            raise EOFError("Cannot write to '%s': current directory is not specified" % key)
-        self.createDirectory()
+            raise EOFError("Cannot write to '%s': current directory is not specified" % file)
+        self.create_directory()
 
         # vector version
-        if not isinstance(key,str):
-            if not isinstance(key, Collection): error( "'key' must be a string or an interable object. Found type %s", type(key))
-            l = len(key)
+        if not isinstance(file,str):
+            if not isinstance(file, Collection): error( "'file' must be a string or an interable object. Found type %s", type(file), exception=ValueError)
+            l = len(file)
             if obj is None or isinstance(obj,str) or not isinstance(obj, Collection):
                 obj = [ obj ] * l
             else:
-                if len(obj) != l: error("'obj' must have same lengths as 'key' if the latter is a collection; found %ld and %ld", len(obj), l )
+                if len(obj) != l: error("'obj' must have same lengths as 'file' if the latter is a collection; found %ld and %ld", len(obj), l, exception=ValueError )
             if ext is None or isinstance(ext,str) or not isinstance(ext, Collection):
                 ext = [ ext ] * l
             else:
-                if len(ext) != l: error("'ext' must have same lengths as 'key' if the latter is a collection; found %ld and %ld", len(ext), l )
+                if len(ext) != l: error("'ext' must have same lengths as 'file' if the latter is a collection; found %ld and %ld", len(ext), l, exception=ValueError )
             ok = True
-            for k,o,e in zip(key,obj,ext):
-                ok |= self._write( writer, k, o, raiseOnError=raiseOnError, ext=e )
+            for k,o,e in zip(file,obj,ext):
+                ok |= self._write( writer, k, o, raise_on_error=raise_on_error, ext=e )
             return ok
 
-        # single key
-        if not len(key) > 0: error("'key is empty (the filename)" )
-        sub, key = os.path.split(key)
-        if len(key) == 0: error("'key '%s' refers to a directory, not a file", key)
+        # single file
+        if not len(file) > 0: error("'file is empty (the filename)" )
+        sub, file = os.path.split(file)
+        if len(file) == 0: error("'file '%s' refers to a directory, not a file", file)
         if len(sub) > 0:
-            return SubDir(sub,parent=self)._write(writer,key,obj, raiseOnError=raiseOnError,ext=ext )
+            return SubDir(sub,parent=self)._write(writer,file,obj, raise_on_error=raise_on_error,ext=ext )
 
         # write to temp file, then rename into target file
         # this reduces collision when i/o operations are slow
-        fullFileName = self.fullKeyName(key,ext=ext)
-        tmp_file     = uniqueHash48( [ key, uuid.getnode(), os.getpid(), threading.get_ident(), datetime.datetime.now() ] )
+        full_file_name = self.full_file_name(file,ext=ext)
+        tmp_file     = unique_hash48( [ file, uuid.getnode(), os.getpid(), threading.get_ident(), datetime.datetime.now() ] )
         tmp_i        = 0
-        fullTmpFile  = self.fullKeyName(tmp_file,ext="tmp" if not ext=="tmp" else "_tmp")
+        fullTmpFile  = self.full_file_name(tmp_file,ext="tmp" if not ext=="tmp" else "_tmp")
         while os.path.exists(fullTmpFile):
-            fullTmpFile = self.fullKeyName(tmp_file) + "." + str(tmp_i) + ".tmp"
+            fullTmpFile = self.full_file_name(tmp_file) + "." + str(tmp_i) + ".tmp"
             tmp_i       += 1
             if tmp_i >= 10:
-                raise RuntimeError("Failed to generate temporary file for writing '%s': too many temporary files found. For example, this file already exists: '%s'" % ( fullFileName, fullTmpFile ) )
+                raise RuntimeError("Failed to generate temporary file for writing '%s': too many temporary files found. For example, this file already exists: '%s'" % ( full_file_name, fullTmpFile ) )
 
         # write
-        if not writer( key, fullTmpFile, obj ):
+        if not writer( file, fullTmpFile, obj ):
             return False
-        assert os.path.exists(fullTmpFile), ("Internal error: file does not exist ...?", fullTmpFile, fullFileName)
+        assert os.path.exists(fullTmpFile), ("Internal error: file does not exist ...?", fullTmpFile, full_file_name)
         try:
-            if os.path.exists(fullFileName):
-                os.remove(fullFileName)
-            os.rename(fullTmpFile, fullFileName)
+            if os.path.exists(full_file_name):
+                os.remove(full_file_name)
+            os.rename(fullTmpFile, full_file_name)
         except Exception as e:
             os.remove(fullTmpFile)
-            if raiseOnError:
+            if raise_on_error:
                 raise e
             return False
         return True
 
-    def write( self, key : str,
+    def write( self, file : str,
                      obj,
-                     raiseOnError : bool = True,
+                     raise_on_error : bool = True,
                      *,
                      version : str = None,
                      ext : str = None,
                      fmt : Format = None ) -> bool:
         """
-        Pickles 'obj' into key.
-        -- Supports 'key' containing directories
-        -- Supports 'key' being a list.
-           In this case, if obj is an iterable it is considered the list of values for the elements of 'keys'
-           If 'obj' is not iterable, it will be written into all 'key's
-
-              keys = ['file1', 'file2']
-
-              sd.write( keys, 1 )
-              --> works, writes '1' in both files.
-
-              sd.read( keys, [1,2] )
-              --> works, writes 1 and 2, respectively
+        Writes an object to file.
+        
+        * Supports ``file`` containing directories.
+        * Supports ``file`` being a list.
+          In this case, if ``obj`` is an iterable it is considered the list of values for the elements of ``file``.
+          If ``obj`` is not iterable, it will be written into all files from ``file``::
 
-              sd.read( keys, "12" )
-              --> works, writes '12' in both files
+              from cdxcore.subdir import SubDir
 
-              sd.write( keys, [1] )
-              --> produces error as len(keys) != len(obj)
+              keys = ['file1', 'file2']
+              sd = SubDir("!/test")
+              sd.write( keys, 1 )               # works, writes '1' in both files.
+              sd.write( keys, [1,2] )           # works, writes 1 and 2, respectively
+              sd.write( keys, "12" )            # works, writes '12' in both files
+              sd.write( keys, [1] )             # produces error as len(keys) != len(obj)
 
-        If the current directory is 'None', then the function throws an EOFError exception
+        If the current directory is ``None``, then the function raises an :class:`EOFError` exception.
 
         Parameters
         ----------
-            key : str
-                Core filename ("key"), or list thereof
+            file : str
+                Core filename, or list thereof.
+                
             obj :
-                Object to write, or list thereof if 'key' is a list
-            raiseOnError : bool
-                If False, this function will return False upon failure
+                Object to write, or list thereof if ``file`` is a list.
+                
+            raise_on_error : bool
+                If ``False``, this function will return ``False`` upon failure.
+
             version : str
-                If not None, specifies the version of the code which generated 'obj'.
+                If not ``None``, specifies the version of the code which generated ``obj``.
                 This version will be written to the beginning of the file.
+
             ext : str
-                Extension, or list thereof if 'key' is a list.
-                Set to:
-                -- None to use directory's default
-                -- '*' to use the extension implied by 'fmt' 
-                -- for convenience 'ext' can also be a Format (in this case leave fmt to None)
-            fmt : Format
-                File format or None to use the directory's default.
-                Note that 'fmt' cannot be a list even if 'key' is.
-                Note that unless 'ext' or the SubDir's extension is '*', changing the format does not automatically change the extension.
+                Extension, or list thereof if ``file`` is a list.
+                
+                * Use ``None`` to use directory's default extension.
+                * Use ``"*"`` to use the extension implied by ``fmt``.
+
+            fmt : :class:`cdxcore.subdir.Format`
+                File format or ``None`` to use the directory's default.
+                Note that ``fmt`` cannot be a list even if ``file`` is.
+                Note that unless ``ext`` or the SubDir's extension is '*',
+                changing the format does not automatically change the extension used.
 
         Returns
         -------
-            Boolean to indicate success if raiseOnError is False.
+            Success : bool         
+                Boolean to indicate success if ``raise_on_error`` is ``False``.
         """
-        ext, fmt = self.autoExtFmt(ext=ext, fmt=fmt)
+        ext, fmt = self.auto_ext_fmt(ext=ext, fmt=fmt)
         version  = str(version) if not version is None else None
         assert ext != self.EXT_FMT_AUTO, ("'ext' is '*'...?")
 
         if version=='*': error("You cannot write version '*'. Use None to write a file without version.")
+        
         if version is None and fmt in [Format.BLOSC, Format.GZIP]:
-            version = ""
+            # blosc and gzip have unexpected side effects
+            # a version is attempted to be read but is not present
+            # (e.g. blosc causes a MemoryError)
+            version = ""            
 
-        def writer( key, fullFileName, obj ):
+        def writer( file, full_file_name, obj ):
             try:
-                if fmt == Format.PICKLE or fmt == Format.BLOSC:
-                    with open(fullFileName,"wb") as f:
+                if fmt == Format.PICKLE:
+                    # only if a version is provided write it into the file
+                    with open(full_file_name,"wb") as f:
                         # handle version as byte string
                         if not version is None:
                             version_ = bytearray(version, "utf-8")
@@ -1372,35 +1893,41 @@ class SubDir(object):
                             len8[0]  = len(version_)
                             f.write(len8)
                             f.write(version_)
-                        if fmt == Format.PICKLE:
-                            pickle.dump(obj,f,-1)
-                        else:
-                            assert fmt == fmt.BLOSC, ("Internal error: unknown format", fmt)
-                            if blosc is None:
-                                raise ModuleNotFoundError("blosc", "'blosc' not found")
-                            pdata      = pickle.dumps(obj)  # returns data as a bytes object
-                            del obj
-                            len_data   = len(pdata)
-                            num_blocks = max(0,len_data-1) // BLOSC_MAX_USE + 1
-                            f.write(num_blocks.to_bytes(2, 'big', signed=False))
-                            for i in range(num_blocks):
-                                start  = i*BLOSC_MAX_USE
-                                end    = min(len_data,start+BLOSC_MAX_USE)
-                                assert end>start, ("Internal error; nothing to write")
-                                block  = blosc.compress( pdata[start:end] )
-                                blockl = len(block)
-                                f.write( blockl.to_bytes(6, 'big', signed=False) )
-                                if blockl > 0:
-                                    f.write( block )
-                                del block
-                            del pdata
+                        pickle.dump(obj,f,-1)
+
+                elif fmt == Format.BLOSC:
+                    # only if a version is provided write it into the file
+                    with open(full_file_name,"wb") as f:
+                        # handle version as byte string
+                        if not version is None: # it's never None
+                            version_ = bytearray(version, "utf-8")
+                            if len(version_) > 255: error("Version '%s' is way too long: its byte encoding has length %ld which does not fit into a byte", version, len(version_))
+                            len8     = bytearray(1)
+                            len8[0]  = len(version_)
+                            f.write(len8)
+                            f.write(version_)
+                        pdata      = pickle.dumps(obj)  # returns data as a bytes object
+                        del obj
+                        len_data   = len(pdata)
+                        num_blocks = max(0,len_data-1) // BLOSC_MAX_USE + 1
+                        f.write(num_blocks.to_bytes(2, 'big', signed=False))
+                        for i in range(num_blocks):
+                            start  = i*BLOSC_MAX_USE
+                            end    = min(len_data,start+BLOSC_MAX_USE)
+                            assert end>start, ("Internal error; nothing to write")
+                            block  = blosc.compress( pdata[start:end] )
+                            blockl = len(block)
+                            f.write( blockl.to_bytes(6, 'big', signed=False) )
+                            if blockl > 0:
+                                f.write( block )
+                            del block
+                        del pdata
 
                 elif fmt == Format.GZIP:
-                    if gzip is None:
-                        raise ModuleNotFoundError("gzip", "'gzip' not found")
-                    with gzip.open(fullFileName,"wb") as f:
+                    # only if a version is provided write it into the file
+                    with gzip.open(full_file_name,"wb") as f:
                         # handle version as byte string
-                        if not version is None:
+                        if not version is None: # it's never None
                             version_ = bytearray(version, "utf-8")
                             if len(version_) > 255: error("Version '%s' is way too long: its byte encoding has length %ld which does not fit into a byte", version, len(version_))
                             len8     = bytearray(1)
@@ -1410,12 +1937,12 @@ class SubDir(object):
                         pickle.dump(obj,f,-1)
 
                 elif fmt in [Format.JSON_PLAIN, Format.JSON_PICKLE]:
-                    with open(fullFileName,"wt",encoding="utf-8") as f:
+                    # only if a version is provided write it into the file
+                    with open(full_file_name,"wt",encoding="utf-8") as f:
                         if not version is None:
                             f.write("# " + version + "\n")
                         if fmt == Format.JSON_PICKLE:
-                            if jsonpickle is None:
-                                raise ModuleNotFoundError("jsonpickle", "'jsonpickle' not found")
+                            jsonpickle = _import_jsonpickle()
                             f.write( jsonpickle.encode(obj) )
                         else:
                             assert fmt == Format.JSON_PLAIN, ("Internal error: invalid Format", fmt)
@@ -1424,27 +1951,21 @@ class SubDir(object):
                 else:
                     raise NotImplementedError(fmt, txtfmt("Internal error: invalid format '%s'", fmt))
             except Exception as e:
-                if raiseOnError:
+                if raise_on_error:
                     raise e
                 return False
             return True
-        return self._write( writer=writer, key=key, obj=obj, raiseOnError=raiseOnError, ext=ext )
-
-    set = write
+        return self._write( writer=writer, file=file, obj=obj, raise_on_error=raise_on_error, ext=ext )
 
-    def writeString( self, key : str, line : str, raiseOnError : bool = True, *, ext : str = None ) -> bool:
+    def write_string( self, file : str, line : str, raise_on_error : bool = True, *, ext : str = None ) -> bool:
         """
-        Writes 'line' into key. A trailing EOL will not be read back
-        -- Supports 'key' containing directories
-        -- Supports 'key' being a list.
-           In this case, line can either be the same value for all key's or a list, too.
-
-        If the current directory is 'None', then the function throws an EOFError exception
-        See additional comments for write()
+        Writes a line of text into a file.
         
-        Use 'ext' to specify the extension.
-        You cannot use 'ext' to specify a format as the format is plain text.
-        If 'ext' is '*' or if self._ext is '*' then the default extension is 'txt'.
+        * Supports ``file``` containing directories.
+        * Supports ``file``` being a list.
+          In this case, ``line`` can either be the same value for all file's or a list, too.
+
+        If the current directory is ``None``, then the function throws an EOFError exception
         """
         verify( not isinstance(ext, Format), "Cannot change format when writing strings. Found extension '%s'", ext, exception=ValueError )
         ext = ext if not ext is None else self._ext
@@ -1452,38 +1973,37 @@ class SubDir(object):
         
         if len(line) == 0 or line[-1] != '\n':
             line += '\n'
-        def writer( key, fullFileName, obj ):
+        def writer( file, full_file_name, obj ):
             try:
-                with open(fullFileName,"wt",encoding="utf-8") as f:
+                with open(full_file_name,"wt",encoding="utf-8") as f:
                     f.write(obj)
             except Exception as e:
-                if raiseOnError:
+                if raise_on_error:
                     raise e
                 return False
             return True
-        return self._write( writer=writer, key=key, obj=line, raiseOnError=raiseOnError, ext=ext )
+        return self._write( writer=writer, file=file, obj=line, raise_on_error=raise_on_error, ext=ext )
 
     # -- iterate --
 
     def files(self, *, ext : str = None) -> list:
         """
-        Returns a list of keys in this subdirectory with the current extension, or the specified extension.
+        Returns a list of files in this subdirectory with the current extension, or the specified extension.
 
         In other words, if the extension is ".pck", and the files are "file1.pck", "file2.pck", "file3.bin"
         then this function will return [ "file1", "file2" ]
 
-        If 'ext' is
-        -- None, the directory's default extension will be used
-        -- "" then this function will return all files in this directory.
-        -- a Format, then the default extension of the format will be used.
-
-        This function ignores directories. Use subDirs() to retrieve those.
+        If ``ext`` is:
+        
+        * ``None``, then the directory's default extension will be used.
+        * ``""`` then this function will return all files in this directory.
+        * ``"*"`` then the extension corresponding to the current format will be used.
 
-        [This function has an alias 'keys']
+        This function ignores directories. Use :meth:`cdxcore.subdir.SubDir.sub_dirs` to retrieve those.
         """
-        if not self.pathExists():
+        if not self.path_exists():
             return []
-        ext   = self.autoExt( ext=ext )
+        ext   = self.auto_ext( ext )
         ext_l = len(ext)
         keys = []
         with os.scandir(self._path) as it:
@@ -1497,15 +2017,15 @@ class SubDir(object):
                 else:
                     keys.append( entry.name )
         return keys
-    keys = files
 
-    def subDirs(self) -> list:
+    def sub_dirs(self) -> list:
         """
-        Returns a list of all sub directories
-        If self does not refer to an existing directory, then this function returns an empty list.
+        Retrieve a list of all sub directories.
+        
+        If ``self`` does not refer to an existing directory, then this function returns an empty list.
         """
         # do not do anything if the object was deleted
-        if not self.pathExists():
+        if not self.path_exists():
             return []
         subdirs = []
         with os.scandir(self._path[:-1]) as it:
@@ -1517,322 +2037,345 @@ class SubDir(object):
 
     # -- delete --
 
-    def delete( self, key : str, raiseOnError: bool  = False, *, ext : str = None ):
+    def delete( self, file : str, raise_on_error: bool  = False, *, ext : str = None ):
         """
-        Deletes 'key'; 'key' might be a list.
+        Deletes ``file``.
+        
+        This function will quietly fail if ``file`` does not exist unless ``raise_on_error``
+        is set to ``True``.
 
         Parameters
         ----------
-            key :
+            file :
                 filename, or list of filenames
-            raiseOnError :
-                if False, do not throw KeyError if file does not exist.
-            ext :
-                Extension, or list thereof if 'key' is an extension.
+                
+            raise_on_error : bool
+                If ``False``, do not throw :class:`KeyError` if file does not exist
+                or another error occurs.
+                
+            ext : str
+                Extension, or list thereof if ``file`` is a list.
+                
                 Use
-                -- None for the directory default
-                -- "" to not use an automatic extension.
-                -- A Format to specify the default extension for that format.
+                
+                * ``None`` for the directory default.
+                * ``""`` to not use an automatic extension.
+                * ``"*"`` to use the extension associated with the format of the directory.
         """
         # do not do anything if the object was deleted
         if self._path is None:
-            if raiseOnError: raise EOFError("Cannot delete '%s': current directory not specified" % key)
+            if raise_on_error: raise EOFError("Cannot delete '%s': current directory not specified" % file)
             return
             
         # vector version
-        if not isinstance(key,str):
-            if not isinstance(key, Collection): error( "'key' must be a string or an interable object. Found type %s", type(key))
-            l = len(key)
+        if not isinstance(file,str):
+            if not isinstance(file, Collection): error( "'file' must be a string or an interable object. Found type %s", type(file))
+            l = len(file)
             if ext is None or isinstance(ext,str) or not isinstance(ext, Collection):
                 ext = [ ext ] * l
             else:
-                if len(ext) != l: error("'ext' must have same lengths as 'key' if the latter is a collection; found %ld and %ld", len(ext), l )
-            for k, e in zip(key,ext):
-                self.delete(k, raiseOnError=raiseOnError, ext=e)
+                if len(ext) != l: error("'ext' must have same lengths as 'file' if the latter is a collection; found %ld and %ld", len(ext), l )
+            for k, e in zip(file,ext):
+                self.delete(k, raise_on_error=raise_on_error, ext=e)
             return
 
-        # handle directories in 'key'
-        if len(key) == 0: error( "'key' is empty" )
-        sub, key_ = os.path.split(key)
-        if len(key_) == 0: error("'key' %s indicates a directory, not a file", key)
-        if len(sub) > 0: return SubDir(sub,parent=self).delete(key_,raiseOnError=raiseOnError,ext=ext)
+        # handle directories in 'file'
+        if len(file) == 0: error( "'file' is empty" )
+        sub, key_ = os.path.split(file)
+        if len(key_) == 0: error("'file' %s indicates a directory, not a file", file)
+        if len(sub) > 0: return SubDir(sub,parent=self).delete(key_,raise_on_error=raise_on_error,ext=ext)
         # don't try if directory doesn't existy
-        if not self.pathExists():
-            if raiseOnError:
-                raise KeyError(key)
+        if not self.path_exists():
+            if raise_on_error:
+                raise KeyError(file)
             return        
-        fullFileName = self.fullKeyName(key, ext=ext)
-        if not os.path.exists(fullFileName):
-            if raiseOnError:
-                raise KeyError(key)
+        full_file_name = self.full_file_name(file, ext=ext)
+        if not os.path.exists(full_file_name):
+            if raise_on_error:
+                raise KeyError(file)
         else:
-            os.remove(fullFileName)
+            os.remove(full_file_name)
 
-    def deleteAllKeys( self, raiseOnError : bool = False, *, ext : str = None ):
+    def delete_all_files( self, raise_on_error : bool = False, *, ext : str = None ):
         """
         Deletes all valid keys in this sub directory with the correct extension.
         
         Parameters
         ----------
-            key :
-                filename, or list of filenames
-            raiseOnError :
-                if False, do not throw KeyError if file does not exist.
-            ext :
-                File extension to match.
-                Use
-                -- None for the directory default
-                -- "" to match all files regardless of extension.
-                -- A Format to specify the default extension for that format.
+            raise_on_error : bool
+                Set to ``False`` to quietly ignore errors.
+                
+            ext : str
+                Extension to be used:
+                    
+                * ``None`` for the directory default.
+                * ``""`` to not use an automatic extension.
+                * ``"*"`` to use the extension associated with the format of the directory.
         """
         if self._path is None:
-            if raiseOnError: raise EOFError("Cannot delete all files: current directory not specified")
+            if raise_on_error: raise EOFError("Cannot delete all files: current directory not specified")
             return
-        if not self.pathExists():
+        if not self.path_exists():
             return
-        self.delete( self.keys(ext=ext), raiseOnError=raiseOnError, ext=ext )
+        self.delete( self.files(ext=ext), raise_on_error=raise_on_error, ext=ext )
 
-    def deleteAllContent( self, deleteSelf : bool = False, raiseOnError : bool = False, *, ext : str = None ):
+    def delete_all_content( self, delete_self : bool = False, raise_on_error : bool = False, *, ext : str = None ):
         """
         Deletes all valid keys and subdirectories in this sub directory.
+        
         Does not delete files with other extensions.
-        Use eraseEverything() if the aim is to delete everything.
+        Use :meth:`cdxcore.subdir.SubDir.delete_everything` if the aim is to delete, well, everything.
 
         Parameters
         ----------
-            deleteSelf:
-                whether to delete the directory or only its contents
-            raiseOnError:
-                False for silent failure
-            ext:
-                Extension for keys, or None for the directory's default.
-                You can also provide a Format for 'ext'.
-                Use "" to match all files regardless of extension.
+            delete_self: bool
+                Whether to delete the directory itself as well, or only its contents.
+            raise_on_error: bool
+                ``False`` for silent failure
+            ext: str
+                Extension for keys, or ``None`` for the directory's default.
+                Use ``""`` to match all files regardless of extension.
         """
         # do not do anything if the object was deleted
         if self._path is None:
-            if raiseOnError: raise EOFError("Cannot delete all contents: current directory not specified")
+            if raise_on_error: raise EOFError("Cannot delete all contents: current directory not specified")
             return
-        if not self.pathExists():
+        if not self.path_exists():
             return
         # delete sub directories
-        subdirs = self.subDirs();
+        subdirs = self.sub_dirs();
         for subdir in subdirs:
-            SubDir(subdir, parent=self).deleteAllContent( deleteSelf=True, raiseOnError=raiseOnError, ext=ext )
+            SubDir(subdir, parent=self).delete_all_content( delete_self=True, raise_on_error=raise_on_error, ext=ext )
         # delete keys
-        self.deleteAllKeys( raiseOnError=raiseOnError,ext=ext )
+        self.delete_all_files( raise_on_error=raise_on_error,ext=ext )
         # delete myself
-        if not deleteSelf:
+        if not delete_self:
             return
         rest = list( os.scandir(self._path[:-1]) )
         txt = str(rest)
         txt = txt if len(txt) < 50 else (txt[:47] + '...')
         if len(rest) > 0:
-            if raiseOnError: error( "Cannot delete my own directory %s: directory not empty: found %ld object(s): %s", self._path,len(rest), txt)
+            if raise_on_error: error( "Cannot delete my own directory %s: directory not empty: found %ld object(s): %s", self._path,len(rest), txt)
             return
         os.rmdir(self._path[:-1])   ## does not work ????
         self._path = None
 
-    def eraseEverything( self, keepDirectory : bool = True ):
+    def delete_everything( self, keep_directory : bool = True ):
         """
-        Deletes the entire sub directory will all contents
-        WARNING: deletes ALL files, not just those with the present extension.
-        Will keep the subdir itself by default.
-        If not, it will invalidate 'self._path'
-
-        If self is None, do nothing. That means you can call this function several times.
+        Deletes the entire sub directory will all contents.
+        
+        *WARNING:* deletes *all* files and sub-directories, not just those with the present extension.
+        If ``keep_directory`` is ``False``, the directory referred to by this object will also be deleted.
+        In this case, ``self`` will be set to ``None``.
         """
         if self._path is None:
             return
-        if not self.pathExists():
+        if not self.path_exists():
             return
         shutil.rmtree(self._path[:-1], ignore_errors=True)
-        if not keepDirectory and os.path.exists(self._path[:-1]):
+        if not keep_directory and os.path.exists(self._path[:-1]):
             os.rmdir(self._path[:-1])
             self._path = None
-        elif keepDirectory and not os.path.exists(self._path[:-1]):
+        elif keep_directory and not os.path.exists(self._path[:-1]):
             os.makedirs(self._path[:-1])
 
     # -- file ops --
 
-    def exists(self, key : str, *, ext : str = None ) -> bool:
+    def exists(self, file : str, *, ext : str = None ) -> bool:
         """
-        Checks whether 'key' exists. Works with iterables
+        Checks whether a file exists.
 
         Parameters
         ----------
-            key :
-                filename, or list of filenames
-            ext :
-                Extension, or list thereof if 'key' is an extension.
+            file :
+                Filename, or list of filenames.
+                
+            ext : str
+                Extension, or list thereof if ``file`` is a list.
+                
                 Use
-                -- None for the directory default
-                -- "" for no automatic extension
-                -- A Format to specify the default extension for that format.
+                
+                * ``None`` for the directory default.
+                * ``""`` to not use an automatic extension.
+                * ``"*"`` to use the extension associated with the format of the directory.
 
         Returns
         -------
-            If 'key' is a string, returns True or False, else it will return a list of bools.
+            Status : bool
+                If ``file`` is a string, returns ``True`` or ``False``, else it will return a list of ``bool`` values.
         """
         # vector version
-        if not isinstance(key,str):
-            verify( isinstance(key, Collection), "'key' must be a string or an interable object. Found type %s", type(key))
-            l = len(key)
+        if not isinstance(file,str):
+            verify( isinstance(file, Collection), "'file' must be a string or an interable object. Found type %s", type(file))
+            l = len(file)
             if ext is None or isinstance(ext,str) or not isinstance(ext, Collection):
                 ext = [ ext ] * l
             else:
-                if len(ext) != l: error("'ext' must have same lengths as 'key' if the latter is a collection; found %ld and %ld", len(ext), l )
-            return [ self.exists(k,ext=e) for k,e in zip(key,ext) ]
+                if len(ext) != l: error("'ext' must have same lengths as 'file' if the latter is a collection; found %ld and %ld", len(ext), l )
+            return [ self.exists(k,ext=e) for k,e in zip(file,ext) ]
         # empty directory
         if self._path is None:
             return False
-        # handle directories in 'key'
-        if len(key) == 0: raise ValueError("'key' missing (the filename)")
-        sub, key_ = os.path.split(key)
-        if len(key_) == 0: raise IsADirectoryError( key, txtfmt("'key' %s indicates a directory, not a file", key) )
+        # handle directories in 'file'
+        if len(file) == 0: raise ValueError("'file' missing (the filename)")
+        sub, key_ = os.path.split(file)
+        if len(key_) == 0: raise IsADirectoryError( file, txtfmt("'file' %s indicates a directory, not a file", file) )
         if len(sub) > 0:
-            return self(sub).exists(key=key_,ext=ext)
+            return self(sub).exists(file=key_,ext=ext)
         # if directory doesn't exit
-        if not self.pathExists():
+        if not self.path_exists():
             return False
-        # single key
-        fullFileName = self.fullKeyName(key, ext=ext)
-        if not os.path.exists(fullFileName):
+        # single file
+        full_file_name = self.full_file_name(file, ext=ext)
+        if not os.path.exists(full_file_name):
             return False
-        if not os.path.isfile(fullFileName):
-            raise IsADirectoryError("Structural error: key %s: exists, but is not a file (full path %s)",key,fullFileName)
+        if not os.path.isfile(full_file_name):
+            raise IsADirectoryError("Structural error: file %s: exists, but is not a file (full path %s)",file,full_file_name)
         return True
     
-    def _getFileProperty( self, *, key : str, ext : str, func ):
+    def _getFileProperty( self, *, file : str, ext : str, func ):
         # vector version
-        if not isinstance(key,str):
-            verify( isinstance(key, Collection), "'key' must be a string or an interable object. Found type %s", type(key))
-            l = len(key)
+        if not isinstance(file,str):
+            verify( isinstance(file, Collection), "'file' must be a string or an interable object. Found type %s", type(file))
+            l = len(file)
             if ext is None or isinstance(ext,str) or not isinstance(ext, Collection):
                 ext = [ ext ] * l
             else:
-                if len(ext) != l: error("'ext' must have same lengths as 'key' if the latter is a collection; found %ld and %ld", len(ext), l )
-            return [ self._getFileProperty(key=k,ext=e,func=func) for k,e in zip(key,ext) ]
+                if len(ext) != l: error("'ext' must have same lengths as 'file' if the latter is a collection; found %ld and %ld", len(ext), l )
+            return [ self._getFileProperty(file=k,ext=e,func=func) for k,e in zip(file,ext) ]
         # empty directory
         if self._path is None:
             return None
-        # handle directories in 'key'
-        if len(key) == 0: raise ValueError("'key' missing (the filename)")
-        sub, key_ = os.path.split(key)
-        if len(key_) == 0: raise IsADirectoryError( key, txtfmt("'key' %s indicates a directory, not a file", key) )
-        if len(sub) > 0: return self(sub)._getFileProperty(key=key_,ext=ext,func=func)
+        # handle directories in 'file'
+        if len(file) == 0: raise ValueError("'file' missing (the filename)")
+        sub, key_ = os.path.split(file)
+        if len(key_) == 0: raise IsADirectoryError( file, txtfmt("'file' %s indicates a directory, not a file", file) )
+        if len(sub) > 0: return self(sub)._getFileProperty(file=key_,ext=ext,func=func)
         # if directory doesn't exit
-        if not self.pathExists():
+        if not self.path_exists():
             return None
-        # single key
-        fullFileName = self.fullKeyName(key, ext=ext)
-        if not os.path.exists(fullFileName):
+        # single file
+        full_file_name = self.full_file_name(file, ext=ext)
+        if not os.path.exists(full_file_name):
             return None
-        return func(fullFileName)
+        return func(full_file_name)
 
-    def getCreationTime( self, key : str, *, ext : str = None ) -> datetime.datetime:
+    def get_creation_time( self, file : str, *, ext : str = None ) -> datetime.datetime:
         """
-        Returns the creation time of 'key', or None if file was not found.
-        See comments on os.path.getctime() for compatibility
+        Returns the creation time of a file.
+        
+        See comments on :func:`os.path.getctime` for system compatibility information.
 
         Parameters
         ----------
-            key :
-                filename, or list of filenames
+            file :
+                filename, or list of filenames.
             ext :
-                Extension, or list thereof if 'key' is an extension.
-                Use
-                -- None for the directory default
-                -- "" for no automatic extension
-                -- A Format to specify the default extension for that format.
+                Extension, or list thereof if ``file`` is an extension.
+                Use:
+                    
+                * ``None`` for the directory default.
+                * ``""`` for no automatic extension.
+                * A :class:`cdxcore.subdir.Format` to use the default extension for that format.
 
         Returns
         -------
-            datetime.datetime if 'key' is a string, otherwise a list of datetime's
+            Datetime : :class:`datetime.datetime`
+                A single ``datetime`` if ``file`` is a string, otherwise a list of ``datetime``'s.
+                Returns ``None`` if an error occured.
         """
-        return self._getFileProperty( key=key, ext=ext, func=lambda x : datetime.datetime.fromtimestamp(os.path.getctime(x)) )
+        return self._getFileProperty( file=file, ext=ext, func=lambda x : datetime.datetime.fromtimestamp(os.path.getctime(x)) )
 
-    def getLastModificationTime( self, key : str, *, ext : str = None ) -> datetime.datetime:
+    def get_last_modification_time( self, file : str, *, ext : str = None ) -> datetime.datetime:
         """
-        Returns the last modification time of 'key', or None if file was not found.
-        See comments on os.path.getmtime() for compatibility
+        Returns the last modification time a file.
+        
+        See comments on :func:`os.path.getmtime` for system compatibility information.
 
         Parameters
         ----------
-            key :
-                filename, or list of filenames
+            file :
+                filename, or list of filenames.
             ext :
-                Extension, or list thereof if 'key' is an extension.
-                Use
-                -- None for the directory default
-                -- "" for no automatic extension
-                -- A Format to specify the default extension for that format.
+                Extension, or list thereof if ``file`` is an extension.
+                Use:
+                    
+                * ``None`` for the directory default.
+                * ``""`` for no automatic extension.
+                * A :class:`cdxcore.subdir.Format` to use the default extension for that format.
 
         Returns
         -------
-            datetime.datetime if 'key' is a string, otherwise a list of datetime's
+            Datetime : :class:`datetime.datetime`
+                A single ``datetime`` if ``file`` is a string, otherwise a list of ``datetime``'s.
+                Returns ``None`` if an error occured.
         """
-        return self._getFileProperty( key=key, ext=ext, func=lambda x : datetime.datetime.fromtimestamp(os.path.getmtime(x)) )
+        return self._getFileProperty( file=file, ext=ext, func=lambda x : datetime.datetime.fromtimestamp(os.path.getmtime(x)) )
 
-    def getLastAccessTime( self, key : str, *, ext : str = None ) -> datetime.datetime:
+    def get_last_access_time( self, file : str, *, ext : str = None ) -> datetime.datetime:
         """
-        Returns the last access time of 'key', or None if file was not found.
-        See comments on os.path.getatime() for compatibility
+        Returns the last access time of a file.
+        
+        See comments on :func:`os.path.getatime` for system compatibility information.
 
         Parameters
         ----------
-            key :
-                filename, or list of filenames
-            ext :
-                Extension, or list thereof if 'key' is an extension.
-                Use
-                -- None for the directory default
-                -- "" for no automatic extension
-                -- A Format to specify the default extension for that format.
+            file : str
+                Filename, or list of filenames.
+
+            ext : str
+                Extension, or list thereof if ``file`` is an extension.
+                    
+                * Use ``None`` for the directory default.
+                * Use ``""`` for no automatic extension.
 
         Returns
         -------
-            datetime.datetime if 'key' is a string, otherwise a list of datetime's
+            Datetime : :class:`datetime.datetime`
+                A single ``datetime`` if ``file`` is a string, otherwise a list of ``datetime``'s.
+                Returns ``None`` if an error occured.
         """
-        return self._getFileProperty( key=key, ext=ext, func=lambda x : datetime.datetime.fromtimestamp(os.path.getatime(x)) )
+        return self._getFileProperty( file=file, ext=ext, func=lambda x : datetime.datetime.fromtimestamp(os.path.getatime(x)) )
 
-    def getFileSize( self, key : str, *, ext : str = None ) -> int:
+    def file_size( self, file : str, *, ext : str = None ) -> int:
         """
-        Returns the file size of 'key', or None if file was not found.
-        See comments on os.path.getatime() for compatibility
+        Returns the file size of a file.
+        
+        See comments on :func:`os.path.getatime` for system compatibility information.
 
         Parameters
         ----------
-            key :
-                filename, or list of filenames
-            ext :
-                Extension, or list thereof if 'key' is an extension.
-                Use
-                -- None for the directory default
-                -- "" for no automatic extension
-                -- A Format to specify the default extension for that format.
+            file : str
+                Filename, or list of filenames.
+
+            ext : str
+                Extension, or list thereof if ``file`` is an extension.
+                    
+                * Use ``None`` for the directory default.
+                * Use ``""`` for no automatic extension.
 
         Returns
         -------
-            File size if 'key' is a string, otherwise a list thereof.
+            File size if ``file``, or ``None`` if an error occured.
         """
-        return self._getFileProperty( key=key, ext=ext, func=lambda x : os.path.getsize(x) )
+        return self._getFileProperty( file=file, ext=ext, func=lambda x : os.path.getsize(x) )
 
     def rename( self, source : str, target : str, *, ext : str = None ):
         """
-        Rename "source" key into "target" key.
-        Function will raise an exception if not successful
+        Rename a file.
+        
+        This function will raise an exception if not successful.
 
         Parameters
         ----------
-            source, target:
-                filenames
-            ext :
-                Extension, or list thereof if 'key' is an extension.
-                Use
-                -- None for the directory default
-                -- "" for no automatic extensions.
-                -- A Format to specify the default extension for that format.
+            source, target : str
+                Filenames.
+                
+            ext : str
+                Extension.
+                
+                * Use ``None`` for the directory default.
+                * Use ``""`` for no automatic extension.
         """
         # empty directory
         if self._path is None:
@@ -1843,9 +2386,9 @@ class SubDir(object):
         sub, source_ = os.path.split(source)
         if len(source_) == 0: raise IsADirectoryError( source, txtfmt("'source' %s indicates a directory, not a file", source ))
         if len(sub) > 0:
-            src_full = self(sub).fullKeyName(key=source_,ext=ext)
+            src_full = self(sub).full_file_name(file=source_,ext=ext)
         else:
-            src_full = self.fullKeyName( source, ext=ext )
+            src_full = self.full_file_name( source, ext=ext )
             
         # handle directories in 'target'
         if len(target) == 0: raise ValueError("'target' missing (the filename)" )
@@ -1853,191 +2396,257 @@ class SubDir(object):
         if len(target_) == 0: raise IsADirectoryError( target, txtfmt("'target' %s indicates a directory, not a file", target))
         if len(sub) > 0:
             tar_dir  = self(sub)
-            tar_dir.createDirectory()
-            tar_full = tar_dir.fullKeyName(key=target_,ext=ext)
+            tar_dir.create_directory()
+            tar_full = tar_dir.full_file_name(file=target_,ext=ext)
         else:
-            tar_full = self.fullKeyName( target, ext=ext )
-            self.createDirectory()
+            tar_full = self.full_file_name( target, ext=ext )
+            self.create_directory()
             
         os.rename(src_full, tar_full)
 
     # utilities
     
     @staticmethod
-    def removeBadKeyCharacters( key:str, by:str=' ' ) -> str:
+    def remove_bad_file_characters( file : str, by : str="default" ) -> str:
         """
-        Replaces invalid characters in a filename by 'by'.
-        See util.fmt_filename() for documentation and further options.
+        Replaces invalid characters in a filename using the map ``by``.
+        
+        See :func:`cdxcore.util.fmt_filename` for documentation and further options.
         """
-        return fmt_filename( key, by=by )
-   
-    def unqiueLabelToKey( self, unique_label:str, id_length:int=8, separator:str='-', max_length:int=64 ) -> str:
-        """
-        Converts a unique label which might contain invalid characters into a unique file name, such that the full file name does not exceed 'max_length' bytes.
-        The returned key has the format 
-            name + separator + ID
-        where ID has length id_length.
-        If unique_label is already guaranteed to be a valid filename, use unqiueLongFileNameToKey() instead.
-        """
-        len_ext      = len(self.ext)
-        assert len_ext < max_length, ("'max_length' must exceed the length of the extension", max_length, self.ext)
-        uqf          = uniqueLabelExt( max_length=max_length-len_ext, id_length=id_length, separator=separator, filename_by="default" )
-        return uqf( unique_label )
+        return fmt_filename( file, by=by )
    
-    def unqiueLongFileNameToKey( self, unique_filename:str, id_length:int=8, separator:str='-', max_length:int=64 ) -> str:
-        """
-        Converts a unique filename which might be too long to a unique filename such that the total length plus 'ext' does not exceed 'max_length' bytes.
-        If the filename is already short enough, no change is made.
-
-        If 'unique_filename' is not guaranteed to be a valid filename, use unqiueLabelToKey() instead.
-        """
-        len_ext      = len(self.ext)
-        assert len_ext < max_length, ("'max_length' must exceed the length of the extension", max_length, self.ext)
-        uqf          = uniqueLabelExt( max_length=max_length-len_ext, id_length=id_length, separator=separator )
-        return uqf( unique_filename )
+    if False:
+        def unqiueLabelToKey( self, unique_label:str, id_length:int=8, separator:str='-', max_length:int=64 ) -> str:
+            """
+            Converts a unique label which might contain invalid characters into a unique file name, such that the full file name does not exceed 'max_length' bytes.
+            The returned file has the format 
+                name + separator + ID
+            where ID has length id_length.
+            If unique_label is already guaranteed to be a valid filename, use unqiueLongFileNameToKey() instead.
+            """
+            len_ext      = len(self.ext)
+            assert len_ext < max_length, ("'max_length' must exceed the length of the extension", max_length, self.ext)
+            uqf          = UniqueLabel( max_length=max_length-len_ext, id_length=id_length, separator=separator, filename_by="default" )
+            return uqf( unique_label )
+       
+        def unqiueLongFileNameToKey( self, unique_filename:str, id_length:int=8, separator:str='-', max_length:int=64 ) -> str:
+            """
+            Converts a unique filename which might be too long to a unique filename such that the total length plus 'ext' does not exceed 'max_length' bytes.
+            If the filename is already short enough, no change is made.
+    
+            If 'unique_filename' is not guaranteed to be a valid filename, use unqiueLabelToKey() instead.
+            """
+            len_ext      = len(self.ext)
+            assert len_ext < max_length, ("'max_length' must exceed the length of the extension", max_length, self.ext)
+            uqf          = UniqueLabel( max_length=max_length-len_ext, id_length=id_length, separator=separator )
+            return uqf( unique_filename )
    
     # -- dict-like interface --
 
-    def __call__(self, keyOrSub : str,
+    def __call__(self, element : str,
                        default = RETURN_SUB_DIRECTORY,
-                       raiseOnError : bool = False,
+                       raise_on_error : bool = False,
                        *,
                        version : str = None,
                        ext : str = None,
                        fmt : Format = None,
                        delete_wrong_version : bool = True,
-                       createDirectory : bool = None ):
+                       create_directory : bool = None ):
         """
-        Return either the value of a sub-key (file), or return a new sub directory.
-        If only one argument is used, then this function returns a new sub directory.
-        If two arguments are used, then this function returns read( keyOrSub, default ).
+        Read either data from a file, or return a new sub directory.
+        
+        If only the ``element`` argument is used, then this function returns a new sub directory
+        named ``element``.
+        
+        If both ``element`` and ``default`` arguments are used, then this function attempts to read the file ``element``
+        from disk, returning ``default`` if it does not exist.
 
-        sd  = SubDir("!/test")
+        Assume we have a subdirectory ``sd``::
+        
+            from cdxcore.subdir import SubDir
+            sd  = SubDir("!/test")
 
-        Member access:
-            x   = sd('x', None)                      reads 'x' with default value None
-            x   = sd('sd/x', default=1)              reads 'x' from sub directory 'sd' with default value 1
-            x   = sd('x', default=1, ext="tmp")      reads 'x.tmp' from sub directory 'sd' with default value 1
+        Reading files::
+            
+            x   = sd('file', None)                   # reads 'file' with default value None
+            x   = sd('sd/file', default=1)           # reads 'file' from sub directory 'sd' with default value 1
+            x   = sd('file', default=1, ext="tmp")   # reads 'file.tmp' with default value 1
 
-        Create sub directory:
-            sd2 = sd("subdir")                       creates and returns handle to subdirectory 'subdir'
-            sd2 = sd("subdir1/subdir2")              creates and returns handle to subdirectory 'subdir1/subdir2'
-            sd2 = sd("subdir1/subdir2", ext=".tmp")  creates and returns handle to subdirectory 'subdir1/subdir2' with extension "tmp"
-            sd2 = sd(ext=".tmp")                     returns handle to current subdirectory with extension "tmp"
+        Create sub directory::
+            
+            sd2 = sd("subdir")                       # creates and returns handle to subdirectory 'subdir'
+            sd2 = sd("subdir1/subdir2")              # creates and returns handle to subdirectory 'subdir1/subdir2'
+            sd2 = sd("subdir1/subdir2", ext=".tmp")  # creates and returns handle to subdirectory 'subdir1/subdir2' with extension "tmp"
+            sd2 = sd(ext=".tmp")                     # returns handle to current subdirectory with extension "tmp"
 
         Parameters
         ----------
-            keyOrSub : str
-                identify the object requested. Should be a string or a list of strings.
-            default:
-                If specified, this function reads 'keyOrSub' with read( keyOrSub, default, *args, **kwargs )
-                If not specified, then this function calls SubDir(keyOrSub,parent=self,ext=ext,fmt=fmt)
+            element : str
+                File or directory name, or a list thereof.
+                
+            default : optional
+                If specified, this function reads ``element`` with
+                ``read( element, default, *args, **kwargs )``.
 
-        The following keywords are only relevant when reading files.
-        They echo the parameters of read()
+                If ``default`` is not specified, then this function returns a new sub-directory by calling
+                ``SubDir(element,parent=self,ext=ext,fmt=fmt)``.
 
-            raiseOnError : bool
+            create_directory : bool, optional
+                *When creating sub-directories:*
+                
+                Whether or not to instantly create the sub-directory. The default, ``None``, is to inherit the behaviour from ``self``.
+                
+            raise_on_error : bool, optional
+                *When reading files:*
+                
                 Whether to raise an exception if reading an existing file failed.
-                By default this function fails silently and returns the default.
-            version : str
-                If not None, specifies the version of the current code base.
-                Use '*' to read any version (this is distrinct from reading a file without version).
-                If version  is not' '*', then this version will be compared to the version of the file being read.
-                If they do not match, read fails (either by returning default or throwing an exception).
-            delete_wrong_version : bool
-                If True, and if a wrong version was found, delete the file.
-            ext : str
-                Extension overwrite, or a list thereof if key is a list
-                Set to:
-                -- None to use directory's default
-                -- '*' to use the extension implied by 'fmt' 
-                -- for convenience 'ext' can also be a Format (in this case leave fmt to None)
-            fmt : Format
-                File format or None to use the directory's default.
-                Note that 'fmt' cannot be a list even if 'key' is.
-                Note that unless 'ext' or the SubDir's extension is '*', changing the format does not automatically change the extension.
+                By default this function fails silently and returns ``default``.
                 
-        The following keywords are only relevant when accessing directories
-        They echo the parameters of __init__
-        
-            createDirectory : bool
-                Whether or not to create the directory. The default, None, is to inherit the behaviour from self.
-            ext : str
-                Set to None to inherit the parent's extension.
-            fmt : Format
-                Set to None to inherit the parent's format.
+                Default is ``False``.
+                
+            version : str, optional
+                *When reading files:*
+                
+                If not ``None``, specifies the version of the current code base.
+                
+                In this case, this version will be compared to the version of the file being read.
+                If they do not match, read fails (either by returning default or throwing a :class:`cdxcore.version.VersionError` exception).
+
+                You can specify version ``"*"`` to accept any version.
+                Note that this is distinct
+                to using ``None`` which stipulates that the file should not 
+                have version information.
+                
+                Default is ``None``.
+
+            delete_wrong_version : bool, optional
+                *When reading files:*
+                
+                If ``True``, and if a wrong version was found, delete the file.
+
+                Default is ``True``.
+
+            ext : str, optional
+                *When reading files:*
+                
+                Extension to be used, or a list thereof if ``element`` is a list. Defaults
+                to the extension of ``self``.
+                
+                Semantics:
+                    
+                * ``None`` to use the default extension of ``self``.
+                * ``"*"`` to use the extension implied by ``fmt``.
+                * ``""`` to turn off extension management.
+
+                *When creating sub-directories:*
+                
+                Extension for the new subdirectory; set to ``None`` to inherit the parent's extension.
+                
+                Default is ``None``.
+
+
+            fmt : :class:`cdxcore.subdir.Format`, optional
+                *When reading files:*
+                
+                File format or ``None`` to use the directory's default.
+                Note that ``fmt`` cannot be a list even if ``element`` is.
+                Unless 
+                ``ext`` or the SubDir's extension is ``"*"``, changing the
+                format does not automatically change the extension.
+
+                *When creating sub-directories:*
                 
+                Format for the new sub-directory; set to ``None`` to inherit the parent's format.
+
+                Default is ``None``.
+                                
         Returns
         -------
+        Object : type|SubDir
             Either the value in the file, a new sub directory, or lists thereof.
-            Returns None if an element was not found.
         """
         if default == SubDir.RETURN_SUB_DIRECTORY:
-            if not isinstance(keyOrSub, str):
-                if not isinstance(keyOrSub, Collection): 
-                    raise ValueError(txtfmt("'keyOrSub' must be a string or an iterable object. Found type '%s;", type(keyOrSub)))
-                return [ SubDir( k,parent=self,ext=ext,fmt=fmt,createDirectory=createDirectory) for k in keyOrSub ]
-            return SubDir(keyOrSub,parent=self,ext=ext,fmt=fmt,createDirectory=createDirectory)
-        return self.read( key=keyOrSub,
+            if not isinstance(element, str):
+                if not isinstance(element, Collection): 
+                    raise ValueError(txtfmt("'element' must be a string or an iterable object. Found type '%s;", type(element)))
+                return [ SubDir( k,parent=self,ext=ext,fmt=fmt,create_directory=create_directory) for k in element ]
+            return SubDir(element,parent=self,ext=ext,fmt=fmt,create_directory=create_directory)
+        return self.read( file=element,
                           default=default,
-                          raiseOnError=raiseOnError,
+                          raise_on_error=raise_on_error,
                           version=version,
                           delete_wrong_version=delete_wrong_version,
                           ext=ext,
                           fmt=fmt )
 
-    def __getitem__( self, key ):
+    def __getitem__( self, file ):
         """
-        Reads self[key]
-        If 'key' does not exist, throw a KeyError
+        Reads ``file`` using :meth:`cdxcore.subdir.SubDir.read`.
+        If '`file'` does not exist, throw a :class:`KeyError`.
         """
-        return self.read( key=key, default=None, raiseOnError=True )
+        return self.read( file=file, default=None, raise_on_error=True )
 
-    def __setitem__( self, key, value):
-        """ Writes 'value' to 'key' """
-        self.write(key,value)
+    def __setitem__( self, file, value):
+        """ Writes ``value`` to ``file`` using :meth:`cdxcore.subdir.SubDir.write`. """
+        self.write(file,value)
 
-    def __delitem__(self,key):
-        """ Silently delete self[key] """
-        self.delete(key, False )
+    def __delitem__(self,file):
+        """ Silently delete ``file`` using :meth:`cdxcore.subdir.SubDir.delete`. """
+        self.delete(file, False )
 
     def __len__(self) -> int:
-        """ Return the number of files (keys) in this directory """
-        return len(self.keys())
+        """ Return the number of files in this directory with matching extension. """
+        return len(self.files())
 
     def __iter__(self):
-        """ Returns an iterator which allows traversing through all keys (files) below this directory """
-        return self.keys().__iter__()
-
-    def __contains__(self, key):
-        """ Implements 'in' operator """
-        return self.exists(key)
-
-    # -- object like interface --
+        """ Returns an iterator which allows traversing through all files below in this directory with matching extension. """
+        return self.files().__iter__()
 
-    def __getattr__(self, key):
-        """
-        Allow using member notation to get data
-        This function throws an AttributeError if 'key' is not found.
+    def __contains__(self, file):
+        """ Tests whether ``file`` :meth:`cdxcore.subdir.SubDir.exists`. """
+        return self.exists(file)
+    
+    def items(self, *, ext : str = None, raise_on_error : bool = False) -> Iterable:
         """
-        if not self.exists(key):
-            raise AttributeError(key)
-        return self.read( key=key, raiseOnError=True )
+        Dictionary-style iterable of filenames and their content.
+
+        Usage::
+            
+            subdir = SubDir("!")
+            for file, data in subdir.items():
+                print( file, str(data)[:100] )
 
-    def __setattr__(self, key, value):
+        Parameters
+        ----------
+            ext : str
+                Extension or ``None`` for the directory's current extension. Use ``""``
+                for all file extension.
+        
+        Returns
+        -------
+            Iterable
+                An iterable generator
+        """       
+        class ItemIterable(Iterable):
+            def __init__(_):
+                _._files  = self.files(ext=ext)
+                _._subdir = self
+            def __len__(_):
+                return len(_._files)
+            def __iter__(_):
+                for file in _._files:
+                    data = _._subdir.read(file, ext=ext, raise_on_error=raise_on_error)
+                    yield file, data
+        return ItemIterable()
+
+    # convenient path ops
+    # -------------------
+    
+    def __add__(self, directory : str) -> str:
         """
-        Allow using member notation to write data
-        Note: keys starting with '_' are /not/ written to disk
+        Returns a the subdirectory ``directory`` of ``self``.
         """
-        if key[0] == '_':
-            self.__dict__[key] = value
-        else:
-            self.write(key,value)
-
-    def __delattr__(self, key):
-        """ Silently delete a key with member notation. """
-        verify( key[:1] != "_", "Deleting protected or private members disabled. Fix __delattr__ to support this")
-        return self.delete( key=key, raiseOnError=False )
+        return SubDir(directory,parent=self)
 
     # pickling
     # --------
@@ -2052,7 +2661,22 @@ class SubDir(object):
         self._ext = state['ext']
         self._fmt = state['fmt']
         self._crt = state['crt']
+
+    @staticmethod
+    def as_format( format_name : str ) -> int:
+        """
+        Converts a named format into the respective format code.
+        
+        Example::
         
+            format = SubDir.as_format( config("format", "pickle", SubDir.FORMAT_NAMES, "File format") )    
+        """
+        format_name = format_name.upper()
+        if not format_name in SubDir.FORMAT_NAMES:
+            raise LookupError(f"Unknown format name '{format_name}'. Must be one of: {fmt_list(SubDir.FORMAT_NAMES)}")
+        return Format[format_name]
+    
+
     # caching
     # -------
 
@@ -2066,129 +2690,249 @@ class SubDir(object):
                       exclude_arg_types   : list[type] = None,
                       version_auto_class  : bool = True):
         """
-        Wraps a callable or a class into a cachable function.
-        Caching is based on the following two simple principles:
-            
-            1) Unique Call ID:
-               When a function is called with some parameters, the wrapper identifies a unique ID based
-               on the qualified name of the function and on its runtime functional parameters (ie those
-               which alter the outcome of the function).
-               When a function is called the first time with a given unique call ID, it will store
-               the result of the call to disk. If the function is called with the same call ID again,
-               the result is read from disk and returned.
-
-               To compute unique call IDs' cdxbasics.util.namedUniqueHashExt() is used.
-               Please read implementation comments there:
-               Key default features:
-                   * It hashes objects via their __dict__ or __slot__ members.
-                     This can be overwritten for a class by implementing __unique_hash__; see cdxbasics.util.namedUniqueHashExt().
-                   * Function members of objects or any members starting with '_' are not considered
-                     unless this behaviour is changed using CacheController().
-                   * Numpy and panda frames are hashed using their byte representation.
-                     That is slow and not recommended. It is better to identify numpy/panda inputs
-                     via their generating characteristic ID.
-                           
-            2) Version:
-               Each function has a version, which includes dependencies on other functions or classes.
-               If the version of a result on disk does not match the current version, it is deleted
-               and the function is called again. This way you can use your code to drive updates
-               to data generated with cached functions.               
-               Behind the scenes this is implemented using cdxbasics.version.version() which means
-               that the version of a cached function can also depend on versions of non-cached functions
-               or other objects.
-
-        Functions
-        ---------
-        Example of caching functions:
-
-            Cache a simple function 'f':            
-
-                from cdxbasics.subdir import SubDir
-                cache   = SubDir("!/.cache", cacheController : CacheController(debug_verbose=Context("all")))
-                
-                @cache.cache("0.1")
-                def f(x,y):
-                    return x*y
-                
-                _ = f(1,2)    # function gets computed and the result cached
-                _ = f(1,2)    # restore result from cache
-                _ = f(2,2)    # different parameters: compute and store result
+        Advanced versioned caching for callables.
+        
+        Versioned caching is based on the following two simple principles:
+            
+        1) **Unique Call IDs:**
+
+           When a function is called with some parameters, the wrapper identifies a unique ID based
+           on the qualified name of the function and on its runtime functional parameters (ie those
+           which alter the outcome of the function).
+           When a function is called the first time with a given unique call ID, it will store
+           the result of the call to disk. If the function is called with the same call ID again,
+           the result is read from disk and returned.
+
+           To compute unique call IDs :class:`cdxcore.uniquehash.NamedUniqueHash` is used
+           by default.
+
+        2) **Code Version:**
+    
+           Each function has a version, which includes dependencies on other functions or classes.
+           If the version of data on disk does not match the current version, it is deleted
+           and the generating function is called again. This way you can use your code to drive updates
+           to data generated with cached functions.               
+           
+           Behind the scenes this is implemented using :dec:`cdxcore.version.version` which means
+           that the version of a cached function can also depend on versions of non-cached functions
+           or other objects.
+           
+        Caching Functions
+        ^^^^^^^^^^^^^^^^^
+        
+        Caching a simple function ``f`` is staight forward:
+
+        .. code-block:: python
+
+            from cdxcore.subdir import SubDir
+            cache   = SubDir("!/.cache")
+            cache.delete_all_content()   # for illustration
+            
+            @cache.cache("0.1")
+            def f(x,y):
+                return x*y
+            
+            _ = f(1,2)    # function gets computed and the result cached
+            _ = f(1,2)    # restore result from cache
+            _ = f(2,2)    # different parameters: compute and store result
+
+        Cache another function ``g`` which calls ``f``, and whose version therefore on ``f``'s version:
+        
+        .. code-block:: python
+
+            @cache.cache("0.1", dependencies=[f])
+            def g(x,y):
+                return g(x,y)**2
+
+        **Debugging**
+        
+        When using automated caching it
+        is important to understand how changes in parameters and the version of the a function
+        affect caching. To this end, :dec:`cdxcore.subdir.SubDir.cache` supports
+        a tracing mechanism via the use of a :class:`cdxcore.subdir.CacheController`:
+
+        .. code-block:: python
+
+            from cdxcore.subdir import SubDir, CacheController, Context
+            
+            ctrl    = CacheController( debug_verbose=Context("all") )
+            cache   = SubDir("!/.cache", cache_controller=ctrl )
+            cache.delete_all_content()   # <- delete previous cached files, for this example only
+            
+            @cache.cache("0.1")
+            def f(x,y):
+                return x*y
+            
+            _ = f(1,2)    # function gets computed and the result cached
+            _ = f(1,2)    # restore result from cache
+            _ = f(2,2)    # different parameters: compute and store result
+            
+        Returns:
 
-            Another function g which calls f, and whose version therefore on f's version:
+        .. code-block:: python
+            
+            00: cache(f@__main__): function registered for caching into 'C:/Users/hans/AppData/Local/Temp/.cache/'.
+            00: cache(f@__main__): called 'f@__main__' version 'version 0.1' and wrote result into 'C:/Users/hans/AppData/Local/Temp/.cache/f@__main__ 668a6b111549e288.pck'.
+            00: cache(f@__main__): read 'f@__main__' version 'version 0.1' from cache 'C:/Users/hans/AppData/Local/Temp/.cache/f@__main__ 668a6b111549e288.pck'.
+            00: cache(f@__main__): called 'f@__main__' version 'version 0.1' and wrote result into 'C:/Users/hans/AppData/Local/Temp/.cache/f@__main__ b5609542d7da0b04.pck'.
             
-                from cdxbasics.subdir import SubDir
-                cache   = SubDir("!/.cache", cacheController : CacheController(debug_verbose=Context("all")))
+        **Non-Functional Parameters**
+
+        A function may have non-functional parameters which do not alter the function's outcome.
+        An example are ``debug`` flags:
+
+        .. code-block:: python
+                         
+            from cdxcore.subdir import SubDir
+            cache   = SubDir("!/.cache")
+
+            @cache.cache("0.1", dependencies=[f], exclude_args='debug')
+            def g(x,y,debug): # <--' 'debug' is a non-functional parameter
+                if debug:
+                    print(f"h(x={x},y={y})")  
+                return g(x,y)**2
+                         
+        You can define certain types as non-functional for *all* functions wrapped
+        by :meth:`cdxcore.subdir.SubDir.cache` when construcing
+        the :class:`cdccore.cache.CacheController` parameter for in :class:`cdxcore.subdir.SubDir`:
+        
+        .. code-block:: python
 
-                @cache.cache("0.1", dependencies=[f])
-                def g(x,y):
-                    return g(x,y)**2
+            from cdxcore.subdir import SubDir
+            
+            class Debugger:
+                def output( cond, message ):
+                    print(message)
+            
+            ctrl    = CacheController(exclude_arg_types=[Debugger])   # <- exclude 'Debugger' parameters from hasing
+            cache   = SubDir("!/.cache")
 
-            A function may have non-functional parameters which do not alter the function's outcome.
-            An example are 'debug' flags:
-                             
-                from cdxbasics.subdir import SubDir
-                cache   = SubDir("!/.cache", cacheController : CacheController(debug_verbose=Context("all")))
+            @cache.cache("0.1", dependencies=[f], exclude_args='debug')
+            def g(x,y,debugger : Debugger): # <-- 'debugger' is a non-functional parameter
+                debugger.output(f"h(x={x},y={y})")  
+                return g(x,y)**2
+            
+        **Unique IDs and File Naming**
+                         
+        The unique call ID of a decorated functions is by default generated by its fully qualified name
+        and a unique hash of its functional parameters.
+        
+        Key default behaviours of :class:`cdxcore.uniquehash.NamedUniqueHash`:
+            
+        * The ``NamedUniqueHash`` hashes objects via their ``__dict__`` or ``__slot__`` members.
+          This can be overwritten for a class by implementing ``__unique_hash__``; see :class:`cdxcore.uniquehash.NamedUniqueHash`.
+          
+        * Function members of objects or any members starting with '_' are not hashed
+          unless this behaviour is changed using :class:`cdxcore.subdir.CacheController`.
+          
+        * Numpy and panda frames are hashed using their byte representation.
+          That is slow and not recommended. It is better to identify numpy/panda inputs
+          via their generating characteristic ID.
+                           
+        Either way, hashes are not particularly human readable. It is often useful
+        to have unique IDs and therefore filenames which carry some context information.
+        
+        This can be achieved by using ``label``:
 
-                @cache.cache("0.1", dependencies=[f], exclude_args='debug')
-                def g(x,y,debug): # <-- debug is a non-functional parameter
-                    if debug:
-                        print(f"h(x={x},y={y})")  
-                    return g(x,y)**2
-                             
-            You can systematically define certain types as non-functional for *all* functions wrapped
-            by this SubDir by specifying the respective parameter for the CacheController() in SubDir.__init__().
-
-            The Unique Call ID of a functions is by default generated by its fully qualified name
-            and a unique hash of its functional parameters.            
-            This can be made more readable by using id=
-
-                from cdxbasics.subdir import SubDir
-                cache   = SubDir("!/.cache", cacheController : CacheController(debug_verbose=Context("all")))
-                
-                @cache.cache("0.1", id="f({x},{y}") # <- using a string to be passed to str.format()
-                def f(x,y):
-                    return x*y
+        .. code-block:: python
 
-            You can also use functions:
-    
-                from cdxbasics.subdir import SubDir
-                cache   = SubDir("!/.cache", cacheController : CacheController(debug_verbose=Context("all")))
-                
-                # Using a function 'id'. Note the **_ to catch uninteresting parameters, here 'debug'
-                @cache.cache("0.1", id=lambda x,y,**_: f"h({x},{y})", exclude_args='debug') 
-                def h(x,y,debug=False):
-                    if debug:
-                        print(f"h(x={x},y={y})")  
-                    return x*y
+            from cdxcore.subdir import SubDir, CacheController
+            ctrl    = CacheController( debug_verbose=Context("all") )
+            cache   = SubDir("!/.cache", cache_controller=ctrl )
+            cache.delete_all_content()   # for illustration
+            
+            @cache.cache("0.1")                     # <- no ID 
+            def f1(x,y):
+                return x*y
+            
+            @cache.cache("0.1", label="f2({x},{y})") # <- label uses a string to be passed to str.format()
+            def f2(x,y):
+                return x*y
+            
+        We can also use a function to generate a ``label``. In that case all parameters
+        to the function including its ``name`` are passed to the function. In below example
+        we eat any parameters we are not interested in with ``** _``:
 
-            Note that by default it is not assumed that the call Id returned by id is unique,
-            and a hash generated from all pertinent arguments will be generated.
-            That is why in the previous example we still need to exclude_args 'debug' here.
+        .. code-block:: python
 
-            If the id you generate is guaranteed to be unique for all functional parameter values,
-            you can add unique=True. In this case the filename of the function 
+            @cache.cache("0.1", label=lambda x,y,**_: f"h({x},{y})", exclude_args='debug') 
+            def h(x,y,debug=False):
+                if debug:
+                    print(f"h(x={x},y={y})")  
+                return x*y
 
-                from cdxbasics.subdir import SubDir
-                cache   = SubDir("!/.cache", cacheController : CacheController(debug_verbose=Context("all")))
-                
-                # Using a function 'id' with 'unique' to generate a unique ID.
-                @cache.cache("0.1", id=lambda x,y,**_: f"h({x},{y})", unique=True) 
-                def h(x,y,debug=False):
-                    if debug:
-                        print(f"h(x={x},y={y})")  
-                    return x*y
+        We obtain:
+
+        .. code-block:: python
+
+            f1(1,1)
+            f2(1,1)
+            h(1,1)        
+            
+            00: cache(f1@__main__): function registered for caching into 'C:/Users/hans/AppData/Local/Temp/.cache/'.
+            00: cache(f2@__main__): function registered for caching into 'C:/Users/hans/AppData/Local/Temp/.cache/'.
+            00: cache(h@__main__): function registered for caching into 'C:/Users/hans/AppData/Local/Temp/.cache/'.
+            00: cache(f1@__main__): called 'f1@__main__' version 'version 0.1' and wrote result into 'C:/Users/hans/AppData/Local/Temp/.cache/f1@__main__ ef197d80d6a0bbb0.pck'.
+            00: cache(f2@__main__): called 'f2(1,1)' version 'version 0.1' and wrote result into 'C:/Users/hans/AppData/Local/Temp/.cache/f2(1,1) bdc3cd99157c10f7.pck'.
+            00: cache(h@__main__): called 'h(1,1)' version 'version 0.1' and wrote result into 'C:/Users/hans/AppData/Local/Temp/.cache/h(1,1) d3fdafc9182070f4.pck'.            
+
+        Note that the file names ``f2(1,1) bdc3cd99157c10f7.pck``
+        and ``h(1,1) d3fdafc9182070f4.pck`` for the ``f2`` and ``h`` function calls are now easier to read as
+        they are comprised of the label
+        of the function and a terminal hash key.
+        The trailing hash is appended because we do not assume that the label returned by ``label`` is unique.
+        Therefore, a hash generated from all the ``label`` itself and
+        all pertinent arguments will be appended to the filename.
+        
+        If we know how to generate truly unique IDs which are always valid filenames, then we can use ``uid``
+        instead of ``label``:
+        
+        .. code-block:: python
+
+            @cache.cache("0.1", uid=lambda x,y,**_: f"h2({x},{y})", exclude_args='debug') 
+            def h2(x,y,debug=False):
+                if debug:
+                    print(f"h(x={x},y={y})")  
+                return x*y
+            h2(1,1)
+            
+        yields::
+            
+            00: cache(h2@__main__): function registered for caching into 'C:/Users/hans/AppData/Local/Temp/.cache/'.
+            00: cache(h2@__main__): called 'h2(1,1)' version 'version 0.1' and wrote result into 'C:/Users/hans/AppData/Local/Temp/.cache/h2(1,1).pck'.            
+            
+        In particular, the filename is now ``h2(1,1).pck`` without any hash.
+        If ``uid`` is used the parameter of the function are not hashed. Like ``label`` 
+        the parameter ``uid`` can also be a :func:`str.format` string or a callable.
             
-        Numpy/Panda
-        -----------
+        **Controlliong which Parameters to Hash**
+            
+        To specify which parameters are pertinent for identifying a unique id, use:
+            
+        * ``include_args``: list of functions arguments to include. If ``None``, use all parameteres as input in the next step
+        
+        * ``exclude_args``: list of function arguments to exclude, if not ``None``.
+        
+        * ``exclude_arg_types``: a list of types to exclude.
+          This is helpful if control flow is managed with dedicated data types.
+          An example of such a type is :class:`cdxcore.verbose.Context` which is used to print hierarchical output messages.
+          Types can be globally excluded using a :class:`cdccore.cache.CacheController`
+          when calling
+          :class:`cdxcore.subdir.SubDir`.
+                       
+        **Numpy/Pandas**
+
         Numpy/Panda data should not be hashed for identifying unique call IDs.
         Instead, use the defining characteristics for generating the data frames.
         
         For example:
-            
-            from cdxbasics.subdir import SubDir
-            cache   = SubDir("!/.cache", cacheController : CacheController(debug_verbose=Context("all")))
 
-            from cdxbasics.prettydict import pdct
+        .. code-block:: python
+            
+            from cdxcore.pretty import PrettyObject
+            from cdxcore.subdir import SubDir
+            cache   = SubDir("!/.cache")
+            cache.delete_all_content()   # for illustration
             
             @cache.cache("0.1")
             def load_src( src_def ):
@@ -2201,22 +2945,24 @@ class SubDir(object):
                 stats = ... using data
                 return stats
             
-            src_def = pdct()
+            src_def = PrettyObject()
             src_def.start = "2010-01-01"
             src_def.end = "2025-01-01"
             src_def.x = 0.1
 
-            stats_def = pdct()
+            stats_def = PrettyObject()
             stats_def.lambda = 0.1
             stats_def.window = 100
 
             data  = load_src( src_def )
             stats = statistics( stats_def, src_def, data )
 
-        While instructive, this case is not optimal: we do not really need to load 'data'
-        if we can reconstruct 'stats' from 'data' (unless we need 'data' further on).
+        While instructive, this case is not optimal: we do not really need to load ``data``
+        if we can reconstruct ``stats`` from ``data`` (unless we need ``data`` further on).
         
-        Consider therefore
+        Consider therefore:
+
+        .. code-block:: python
 
             @cache.cache("0.1")
             def load_src( src_def ):
@@ -2232,14 +2978,18 @@ class SubDir(object):
             
             stats = statistics_only( stats_def, src_def )
 
-        Member functions
-        ----------------
+        Caching Member Functions
+        ^^^^^^^^^^^^^^^^^^^^^^^^
+
         You can cache member functions like any other function.
-        Note that version information are by default inherited, i.e. member functions will be dependent on the version of their 
-        defining class, and class versions will be dependent on their base classes' versions.
+        Note that :dec:`cdxcore.version.version` information are by default inherited, i.e. member functions will be dependent on the version of their 
+        defining class, and class versions will be dependent on their base classes' versions:
             
-            from cdxbasics.subdir import SubDir, version
-            cache   = SubDir("!/.cache", cacheController : CacheController(debug_verbose=Context("all")))
+        .. code-block:: python
+
+            from cdxcore.subdir import SubDir, version
+            cache   = SubDir("!/.cache")
+            cache.delete_all_content()   # for illustration
             
             @version("0.1")
             class A(object):
@@ -2259,18 +3009,26 @@ class SubDir(object):
             _ = b.f(y=1)   # same unique call ID as previous call -> restore result from disk
             
         **WARNING**
-        The hashing function used -- cdxbasics.util.uniqueHashExt() -- does by default *not* process members of objects or dictionaries
-        which start with a "_". This behaviour can be changed using CacheController().
-        For reasonably complex objects it is recommended to implement:
-            __unique_hash__( self, length : int, parse_functions : bool, parse_underscore : str )
-        (it is also possible to simply set this value to a string constant).
+        :class:`cdxcore.uniquehash.UniqueHash` does *not* by default process members of objects or dictionaries
+        which start with a "_". This behaviour can be changed using :class:`cdxcore.subdir.CacheController`.
+        For reasonably complex objects it is recommended to implement for your objects 
+        the a custom hashing function::
+        
+            __unique_hash__( self, uniqueHash : UniqueHash, debug_trace : DebugTrace  )
+
+        This function is described at :class:`cdxcore.uniquehash.UniqueHash`.
+            
+        Caching Bound Member Functions
+        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-        Bound Member Functions
-        ----------------------
-        Note that above is functionally different to decorating a bound member function:
+        Caching bound member functions is technically quite different to caching a function of a class in general,
+        but also supported:
             
-            from cdxbasics.subdir import SubDir, version
-            cache   = SubDir("!/.cache", cacheController : CacheController(debug_verbose=Context("all")))
+        .. code-block:: python
+        
+            from cdxcore.subdir import SubDir, version
+            cache   = SubDir("!/.cache", cache_controller : CacheController(debug_verbose=Context("all")))
+            cache.delete_all_content()   # for illustration
 
             class A(object):
                 def __init__(self,x):
@@ -2282,133 +3040,177 @@ class SubDir(object):
             f = cache.cache("0.1", id=lambda self, y : f"a.f({y})")(a.f)  # <- decorate bound 'f'.
             r = c(y=2)
 
-        In this case the function 'f' is bound to 'a'. The object is added as 'self' to the function
-        parameter list even though the bound function parameter list does not include 'self'.
-        This, together with the comments on hashing objects above, ensures that (hashed) changes to 'a' will
+        In this case the function ``f`` is bound to ``a``. The object is added as ``self`` to the function
+        parameter list even though the bound function parameter list does not include ``self``.
+        This, together with the comments on hashing objects above, ensures that (hashed) changes to ``a`` will
         be reflected in the unique call ID for the member function.
 
-        Classes
-        -------
-        Classes can also be cached.
-        This is done in two steps: first, the class itself is decorated to provide version information at its own level.
-        Secondly, decorate __init__ which also helps to define the unique call id. You do not need to specify a version
-        for __init__ as its version usually coincides with the version of the class.
-
-            Simple example:            
-        
-                cache   = SubDir("!/.cache", cacheController : CacheController(debug_verbose=Context("all")))
-                
-                @cache.cache("0.1")
-                class A(object):
-                    
-                    @cache.cache(exclude_args=['debug'])
-                    def __init__(self, x, debug):
-                        if debug:
-                            print("__init__",x)
-                        self.x = x
+        Caching Classes
+        ^^^^^^^^^^^^^^^
 
-            __init__ does not actually return a value; for this reason the actual function decorated will be __new__.
-            Attempting to cache decorate __new__ will lead to an exception.
+        Classes can also be cached. In this case the creation of a class is cached, i.e. a call to
+        the class constructor restores the respectiv object from disk.
 
-            A nuance for __init__ vs ordinary member function is that 'self' is non-functional.
-            It is therefore automatically excluded from computing a unique call ID.
-            Specifically, 'self' is not part of the arguments passed to 'id':
+        This is done in two steps:
             
-                @cache.cache("0.1")
-                class A(object):
+        1) first, the class itself is decorated using 
+           :dec:`cdxcore.subdir.SubDir.cache`
+           to provide version information at class level. Only version information are provided here.
+           
+        2) Secondly, decorate ``__init__``. You do not need to specify a version
+           for ``__init__`` as its version usually coincides with the version of the class. At ``__init__``
+           you define how unique IDs are generated from the parameters passed to object construction.
+
+        Simple example:
+            
+        .. code-block:: python
+    
+            from cdxcore.subdir import SubDir
+            cache   = SubDir("!/.cache")
+            cache.delete_all_content()   # for illustration
+            
+            @cache.cache("0.1")
+            class A(object):
+                
+                @cache.cache(exclude_args=['debug'])
+                def __init__(self, x, debug):
+                    if debug:
+                        print("__init__",x)
+                    self.x = x
                     
-                    @cache.cache("0.1", id=lambda x, debug: f"A.__init__(x={x})")  # <-- 'self' is not passed to the lambda function; no need to add **_
-                    def __init__(self, x, debug):
-                        if debug:
-                            print("__init__",x)
-                        self.x = x
+            a = A(1)    # caches 'a'
+            b = A(1)    # reads the cached object into 'b'
 
-            Decorating classes with __slots__ does not yet work.
-                                    
-        Non-functional parameters
-        -------------------------
-        Often functions have parameters which do not alter the output of the function but control i/o or other aspects of the overall environment.
-        An example is a function parameter 'debug':
-        
-            def f(x,y,debug=False):
-                z = x*y
-                if not debug:
-                    print(f"x={x}, y={y}, z={z}")
-                return z
-
-        To specify which parameters are pertinent for identiying a unique id, use:
-            
-            a) include_args: list of functions arguments to include. If None, use all as input in the next step
-            b) exclude_args: list of funciton arguments to exclude, if not None.
-            c) exclude_arg_types: a list of types to exclude. This is helpful if control flow is managed with dedicated data types.
-               An example of such a type is cdxbasics.verbose.Context which is used to print hierarchical output messages.
-               Types can be globally excluded using the CacheController.
+        **Technical Comments**
+        
+        The function ``__init__`` does not actually return a value; for this reason
+        behind the scenes it is actually ``__new__`` which is being decorated.
+        Attempting to cache-decorate ``__new__`` manually will lead to an exception.
+
+        A nuance for ``__init__`` vs ordinary member function is that the
+        ``self`` parameter is non-functional
+        (in the sense that it is an empty object when ``__init__`` is called).
+        ``self`` is therefore automatically excluded from computing a unique call ID.
+        That also means ``self`` is not part of the arguments passed to ``uid``:
+        
+        .. code-block:: python
+        
+            @cache.cache("0.1")
+            class A(object):
                 
+                @cache.cache("0.1", id=lambda x, debug: f"A.__init__(x={x})")  # <-- 'self' is not passed to the lambda function; no need to add **_
+                def __init__(self, x, debug):
+                    if debug:
+                        print("__init__",x)
+                    self.x = x
+
+        Decorating classes with ``__slots__`` does not yet work.
+                                    
         See also
-        --------                
-        For project-wide use it is usually inconvenient to control caching at the level of a 'directory'.
-        See VersionedCacheRoot() is a thin wrapper around a SubDir with a CacheController.
+        ^^^^^^^^
+
+        For project-wide use it is usually inconvenient to control caching at the level of a 
+        project-wide cache root directory.
+        See :class:`cdxcore.subdir.VersionedCacheRoot` for a thin convenience wrapper around a :class:`cdxcore.subdir.SubDir`
+        with a :class:`cdxcore.subdir.CacheController`.
         
         Parameters
         ----------
         version : str, optional
             Version of the function.
-            * If None then F must be decorated with cdxbasics.version.version().
-            * If set, the function F is first decorated with cdxbasics.version.version().
-        dependencies : list, optional
-            List of version dependencies
-        
-        id : str, Callable
-            Create a call label for the function call and its parameters.
-            See above for a description.
-            * A plain string without {} formatting: this is the fully qualified id
-            * A string with {} formatting: id.str( name=name, **parameters ) will be used to generate the fully qualified id
-            * A Callable, in which case id( name=name, **parameters ) will be used to generate the fully qualified id
-        
-        unique : bool
-            Whether the 'id' generated by 'id' is unique for this function call with its parameters.
-            If True, then the function will attempt to use 'id' as filename as long as it has no invalid characters and is short
-            enough (see 'max_filename_length').
-            If False, the function will append to the 'id' a unique hash of the qualified function name and all pertinent parameters
-        
-        name : str
-            The name of the function, or None for using the fully qualified function name.
             
+            * If ``None`` then ``F`` must be decorated with :dec:`cdxcore.version.version`.
+            * If set, the function ``F`` is first decorated with :dec:`cdxcore.version.version`.
+            
+        dependencies : list[type], optional
+            A list of version dependencies, either by reference or by name.
+            See :dec:`cdxcore.version.version` for details on name lookup if strings are used.
+        
+        label : str | Callable
+            Specify a human-readable label for the function call given its parameters.
+            This label is used to generate the cache file name, and is also printed in when tracing
+            hashing operations. Labels are not assumed to be unique, hence a unique hash of
+            the label and the parameters to this function will be appended to generate
+            the actual cache file name.
+            
+            Use ``uid`` instead if ``label`` represents valid unique filenames.
+            
+            
+            **Usage:**
+            
+            * If ``label`` is a plain string without ``{}`` formatting: use this string as-is.
+            
+            * If ``label`` is a string with ``{}`` formatting, then ``label.format( name=name, **parameters )``
+              will be used to generate the actual label.
+            
+            * If ``label`` is a ``Callable`` then ``label( name=name, **parameters )`` will be called
+              to generate the actual label.
+
+            See above for examples.
+            
+            ``label`` cannot be used alongside ``uid``.
+            
+        uid : str | Callable
+            Alternative to ``label`` which is assumed to generate a unique cache file name. It has the same
+            semantics as ``label``. When used, parameters to the decorated function are not hashed.
+            
+            ``uid`` be used alongside ``label``.
+        
+        name : str, optional
+            Name of this function which is used either on its own if neither ``label`` not ``uid`` are used.
+            If either of them is used, ``name`` is passed as a parameter to either the callable or the
+            formatting operator.
+            
+            If ``name`` is not specified it defaults to ``__qualname__`` expanded
+            by the module name the function is defined in.
+        
         include_args : list[str]
-            List of arguments to include in generating a unqiue id, or None for all.
+            List of arguments to include in generating an unqiue ID, or ``None`` for all.
         
         exclude_args : list[str]:
-            List of argumernts to exclude
+            List of arguments to exclude from generating an unique ID.
             
         exclude_arg_types : list[type]
-            List of types to exclude.
+            List of parameter types to exclude from generating an unique ID.
             
         version_auto_class : bool
-        
-
+            Whether to automaticallty add version dependencies on base classes or, for member functions, on containing
+            classes. This is the ``auto_class`` parameter for :dec:`cdxcore.version.version`.
             
         Returns
         -------
-            A callable to execute F if need be.
-            This callable has a member 'cache_info' which can be used to access information on caching activity.
-
-                Information available at any time after decoration:
-                    F.cache_info.name : qualified name of the function
-                    F.cache_info.signature : signature of the function
+        Decorated F: Callable
+        
+            A decorator ``cache(F)`` whose ``__call__`` implements the cached call to ``F``.
             
-                Additonal information available during a call to a decorated function F, and thereafter:                    
-                    F.cache_info.version : unique version string reflecting all dependencies.
-                    F.cache_info.uid : unique call ID. 
-                    F.cache_info.label : last id generated, or None (if id was a string and unique was True)
-                    F.cache_info.arguments : arguments parsed to create a unique call ID, or None (if id was a string and unique was True)
+            This callable has a member ``cache_info``
+            of type :class:`cdxcore.subdir.CacheInfo`
+            which can be used to access information on caching activity.
+
+            * Information available at any time after decoration:**
+                
+              * ``F.cache_info.name`` : qualified name of the function
+              * ``F.cache_info.signature`` : signature of the function
+        
+            * Additonal information available during a call to a decorated function F, and thereafter:                    
+                
+              * ``F.cache_info.version`` : unique version string reflecting all dependencies.
+              * ``F.cache_info.filename`` : unique filename used for caching logic during the last function call.
+              * ``F.cache_info.label`` : last label generated, or ``None``.
+              * ``F.cache_info.arguments`` : arguments parsed to create a unique call ID, or ``None``.
 
-                Additonal information available after a call to F:
-                    F.cache_info.last_cached : whether the last function call returned a cached object
+            * Additonal information available after a call to ``F``:
+                
+              * ``F.cache_info.last_cached`` : whether the last function call returned a cached object.
                 
-            The function F has additional function parameters
-                override_cache_mode : allows to override caching mode temporarily, in particular "off"
-                track_cached_files : pass a CacheTracker object to keep track of all files used (loaded from or saved to).
-                      This can be used to delete intermediary files when a large operation was completed.
+            The decorated ``F()`` has additional function parameters, namely:
+                
+            * ``override_cache_mode`` : allows to override caching mode temporarily, in particular you can set it to ``"off"``.
+            * ``track_cached_files`` : allows passing a :class:`cdxcore.subdir.CacheTracker`
+              object to keep track of all
+              files used (loaded from or saved to). 
+              The function :meth:`cdxcore.subdir.CacheTracker.delete_cache_files` can be used
+              to delete all files involved in caching.
         """
         return CacheCallable(subdir = self,
                              version = version,
@@ -2428,14 +3230,153 @@ class SubDir(object):
                      version_auto_class  : bool = True
                      ):
         """
-        Short cut for SubDir.cache() for classes
-        See  SubDir.cache() for documentation.
+        Short-cut for :dec:`cdxcore.subdir.SubDir.cache` applied to classes
+        with a reduced number of available parameters.
+        
+        Example::
+
+            cache   = SubDir("!/.cache")
+            
+            @cache.cache_class("0.1")
+            class A(object):
+                
+                @cache.cache(exclude_args=['debug'])
+                def __init__(self, x, debug):
+                    if debug:
+                        print("__init__",x)
+                    self.x = x
+
         """
         return self.cache( name=name,
-                      version=version,
-                      dependencies=dependencies,
-                      version_auto_class=version_auto_class)        
-                      
+                           version=version,
+                           dependencies=dependencies,
+                           version_auto_class=version_auto_class)        
+
+# ========================================================================
+# Caching, convenience
+# ========================================================================
+
+def VersionedCacheRoot( directory          : str, *,
+                        ext                : str = None, 
+                        fmt                : Format = None,
+                        create_directory   : bool = False,
+                        **controller_kwargs
+                        ):
+    """
+    Create a root directory for versioned caching on disk
+    using :dec:`cdxcore.subdir.SubDir.cache`.
+    
+    **Usage:**
+
+    In a central file, define a root directory for all caching activity::
+        
+        from cdxcore.subdir import VersionedCacheRoot
+        vroot = VersionedCacheRoot("!/cache")
+
+    Create sub-directories as suitable, for example::
+        
+        vtest = vroot("test")
+
+    Use these for caching::
+            
+        @vtest.cache("1.0")
+        def f1( x=1, y=2 ):
+            print(x,y)
+            
+        @vtest.cache("1.0", dps=[f1])
+        def f2( x=1, y=2, z=3 ):
+            f1( x,y )
+            print(z)
+    
+    Parameters
+    ----------
+        directory : str
+            Name of the root directory for caching.
+            
+            Using SubDir the following Short-cuts are supported:
+                
+            * ``"!/dir"`` creates ``dir`` in the temporary directory.
+            * ``"~/dir"`` creates ``dir`` in the home directory.
+            * ``"./dir"`` creates ``dir`` relative to the current directory.
+            
+        ext : str
+            Extension, which will automatically be appended to file names.
+            The default value depends on ``fmt`; for ``Format.PICKLE`` it is "pck".
+            
+        fmt : :class:`cdxcore.subdir.Format`
+            File format; if ``ext`` is not specified, the format drives the extension, too.
+            Default is ``Format.PICKLE``.
+
+        create_directory : bool
+            Whether to create the directory upon creation. Default is ``False``.
+            
+        controller_kwargs: dict
+            Parameters passed to :class:`cdxcore.subdir.CacheController``.
+            
+            Common parameters used:
+                
+            * ``exclude_arg_types``: list of types or names of types to exclude when auto-generating function
+              signatures from function arguments.
+              An example is :class:`cdxcore.verbose.Context` which is used to print progress messages.
+              
+            * ``max_filename_length``: maximum filename length.
+            
+            * ``hash_length``: length used for hashes, see :class:`cdxcore.uniquehash.UniqueHash`.
+        
+    Returns
+    -------
+        Root : SubDir
+            A root directory suitable for caching.
+    """    
+    controller = CacheController(**controller_kwargs) if len(controller_kwargs) > 0 else None
+    return SubDir( directory=directory, ext=ext, fmt=fmt, create_directory=create_directory, controller=controller )
+
+version = version_decorator
+                
+class CacheTracker(object):
+    """
+    Utility class to track caching and be able to delete all dependent objects.
+    """
+    def __init__(self):
+        """ track cache files """
+        self._files = []
+    def __iadd__(self, new_file):
+        """ Add a new file to the tracker """
+        self._files.append( new_file )
+    def delete_cache_files(self):
+        """ Delete all tracked files """
+        for file in self._files:
+            if os.path.exists(file):
+                os.remove(file)
+        self._files = []
+    def __str__(self) -> str:#NOQA
+        return f"Tracked: {self._files}"
+    def __repr__(self) -> str:#NOQA
+        return f"Tracked: {self._files}"
+
+class CacheInfo(object):
+    """
+    Information on cfunctions decorated with :dec:`cdxcore.subdir.SubDir.cache`.
+    
+    Functions decorated with :dec:`cdxcore.subdir.SubDir.cache` 
+    will have a member ``cache_info`` of this type
+    """
+    def __init__(self, name, F, keep_last_arguments):
+        """
+        :meta private:
+        """
+        self.name        = name                  #: Decoded name of the function.
+        
+        self.signature   = inspect.signature(F)  #: :func:`inspect.signature` of the function.
+    
+        self.filename    = None                  #: Unique filename of the last function call.
+        self.label       = None                  #: Label of the last function call.
+        self.version     = None                  #: Last version used.
+        
+        self.last_cached = None                  #: Whether the last function call restored data from disk.
+        
+        if keep_last_arguments:             
+            self.arguments = None                #: Last arguments used. This member is only present if ``keep_last_arguments`` was set to ``True`` for the relevant :class:`cdxcore.subdir.CacheController`.
 
 def _ensure_has_version( F,
                          version      : str = None,
@@ -2486,8 +3427,9 @@ def _qualified_name( F, name ):
 
 class CacheCallable(object):
     """
-    Utility class for SubDir.cache_callable.
-    See documentation for that function.
+    Wrapper for a cached function.
+    
+    This is the wrapper returned by :dec:`cdxcore.subdir.SubDir.cache`.    
     """
     
     def __init__(self, 
@@ -2503,8 +3445,9 @@ class CacheCallable(object):
                     version_auto_class  : bool = True,
                     name_of_name_arg    : str = "name"):
         """
-        Utility class for SubDir.cache_callable.
-        See documentation for that function.
+        Utility class for :dec:`cdxcore.subdir.SubDir.cache`.
+        
+        *Do not use directly.*
         """
         if not label is None and not uid is None:
             error("Cannot specify both 'label' and 'uid'.")
@@ -2523,35 +3466,41 @@ class CacheCallable(object):
         
     @property
     def uid_or_label(self) -> Callable:
+        """ ID or label """
         return self._uid if self._label is None else self._label
     @property
     def unique(self) -> bool:
+        """ Whether the ID is unique """
         return not self._uid is None
-        
     @property
-    def cacheController(self) -> CacheController:
-        """ Returns the cache controller """
-        return self._subdir.cacheController
+    def cache_controller(self) -> CacheController:
+        """ Returns the :class:`cdxcore.subdir.CacheController` """
+        return self._subdir.cache_controller
     @property
-    def cache_mode(self) -> Context:
-        return self.cacheController.cache_mode
+    def cache_mode(self) -> CacheMode:
+        """ Returns the :class:`cdxcore.subdir.CacheMode` of the underlying :class:`cdxcore.subdir.CacheController` """ 
+        return self.cache_controller.cache_mode
     @property
     def debug_verbose(self) -> Context:
-        return self.cacheController.debug_verbose
+        """ Returns the debug :class:`cdxcore.verbose.Context` used to print caching information, or ``None`` """
+        return self.cache_controller.debug_verbose
     @property
-    def uniqueNamedFileName(self) -> Callable:
-        return self.cacheController.uniqueNamedFileName
+    def labelledFileName(self) -> Callable:
+        """ Returns ``labelledFileName()`` of the underlying :class:`cdxcore.subdir.CacheController` """ 
+        return self.cache_controller.labelledFileName
     @property
-    def uniqueLabelledFileName(self) -> Callable:
-        return self.cacheController.uniqueLabelledFileName
+    def uniqueFileName(self) -> Callable:
+        """ Returns ``uniqueFileName()`` of the underlying :class:`cdxcore.subdir.CacheController` """ 
+        return self.cache_controller.uniqueFileName
     @property
     def global_exclude_arg_types(self) -> list[type]:
-        return self.cacheController.exclude_arg_types
+        """ Returns ``exclude_arg_types`` of the underlying :class:`cdxcore.subdir.CacheController` """ 
+        return self.cache_controller.exclude_arg_types
     
     def __call__(self, F : Callable):
         """
-        Decorate 'F' as cachable callable. Can also decorate classes via ClassCallable()
-        See SubDir.cache() for documentation.
+        Decorate ``F`` as cachable callable.
+        See :dec:`cdxcore.subdir.SubDir.cache` for documentation.
         """
         if inspect.isclass(F):
             if not self._label is None: raise ValueError("'{F.__qualname__}': when decorating a class specify 'label' for __init__, not the class")
@@ -2566,11 +3515,13 @@ class CacheCallable(object):
     def _wrap_class(self, C : type):
         """
         Wrap class
+        
         This wrapper:
-            1) Assigns a cdxbasics.version.version() for the class (if not yet present)
-            2) Extracts from __init__ the wrapper to decorate __new__
+            
+        * Assigns a :dec:`cdxcore.version.version` for the class (if not yet present).
+        * Extracts from ``__init__`` the wrapper to decorate`` __new__``.
         """
-        debug_verbose = self.cacheController.debug_verbose
+        debug_verbose = self.cache_controller.debug_verbose
 
         assert not inspect.isclass(C), ("Not a class", C)
          
@@ -2609,8 +3560,7 @@ class CacheCallable(object):
         """
         Decorate callable 'F'.
         """
-    
-        debug_verbose = self.cacheController.debug_verbose
+        debug_verbose = self.cache_controller.debug_verbose
         assert not inspect.isclass(F), ("Internal error")
         
         # check validity
@@ -2712,21 +3662,24 @@ class CacheCallable(object):
             # determine unique id_ for this function call
             # -------------------------------------------
             
-            label        = None
-            uid          = None 
             uid_or_label = self.uid_or_label
+            filename     = None
             if isinstance(uid_or_label, str) and self.unique:
-                # if 'id' does not contain formatting codes, and the result is 'unique' then do not bother collecting
+                # if 'id' does not contain formatting codes,
+                # and the result is 'unique' then do not bother collecting
                 # function arguments
                 try:
-                    uid = uid_or_label.format()   # throws a KeyError if 'id' contains formatting information
+                    filename = uid_or_label.format()   # throws a KeyError if 'id' contains formatting information
                 except KeyError:
                     pass
 
-            if not uid is None:
+            if not filename is None:
                 # generate name with the unique string provided by the user
-                label     = uid
-                uid       = self.uniqueLabelledFileName( self.id )
+                if not is_filename(filename):
+                    raise ValueError(f"The unique filename '{filename}' computed for '{name}' contains invalid characters for filename. When using `uid` make sure that "+\
+                                     "the returned ID is a valid filename (and unique)")
+                label     = filename
+                filename  = self.uniqueFileName( filename )
                 arguments = None
                 
             else:
@@ -2767,9 +3720,9 @@ class CacheCallable(object):
                         if arg in arguments:
                             del arguments[arg]
                                 
-                # apply logics                
+                # did the user provide a label or unique ID?
                 if uid_or_label is None:
-                    label = name
+                    uid_or_label = name
                     
                 else:
                     if self._name_of_name_arg in arguments:
@@ -2789,24 +3742,30 @@ class CacheCallable(object):
                     # call format or function                    
                     if isinstance( uid_or_label, str ):
                         try:
-                            label = str.format( uid_or_label, **arguments )
+                            uid_or_label = str.format( uid_or_label, **arguments )
                         except KeyError as e:
                             raise KeyError(e, f"Error while generating id for '{name}' using format string '{uid_or_label}': {e}. Available arguments: {list(arguments)}")
 
                     else:
                         which = 'uid' if not self._uid is None else 'label'
                         try:
-                            label = uid_or_label(**arguments)
+                            uid_or_label = uid_or_label(**arguments)
                         except TypeError as e:
                             raise TypeError(e, f"Error while generating '{which}' for '{name}' using a function: {e}. Available arguments: {list(arguments)}")
                         except Exception as e:
                             raise type(e)(f"Error while generating '{which}' for '{name}': attempt to call '{which}' of type {type(uid_or_label)} failed: {e}")
-                        assert isinstance(label, str), ("Error:", which,"callable must return a string. Found",type(label))
+                        assert isinstance(uid_or_label, str), ("Error:", which, "callable must return a string. Found",type(uid_or_label))
 
                 if self.unique:
-                    uid = self.uniqueLabelledFileName( label )
+                    if not is_filename(uid_or_label):
+                        raise ValueError(f"The unique filename '{uid_or_label}' computed for '{name}' contains invalid characters for filename. When using `uid` make sure that "+\
+                                         "the returned filename is indeed a valid filename (and unique)")
+
+                    label    = uid_or_label
+                    filename = self.uniqueFileName( uid_or_label )
                 else:
-                    uid = self.uniqueNamedFileName( label, **arguments )
+                    label    = uid_or_label
+                    filename = self.labelledFileName( uid_or_label, **arguments )
 
             # determine version, cache mode
             # ------------------
@@ -2818,11 +3777,11 @@ class CacheCallable(object):
             # store process information
             # -------------------------
 
-            execute.cache_info.label   = str(label) if not label is None else None
-            execute.cache_info.uid     = uid
-            execute.cache_info.version = version_
+            execute.cache_info.label    = str(label) if not label is None else None
+            execute.cache_info.filename = filename
+            execute.cache_info.version  = version_
             
-            if self.cacheController.keep_last_arguments:
+            if self.cache_controller.keep_last_arguments:
                 info_arguments = OrderedDict()
                 for argname, argvalue in arguments.items():
                     info_arguments[argname] = str(argvalue)[:100]
@@ -2833,26 +3792,26 @@ class CacheCallable(object):
             # ---------------
 
             if cache_mode.delete:
-                self._subdir.delete( uid )
+                self._subdir.delete( filename )
             elif cache_mode.read:
                 class Tag:
                     pass
                 tag = Tag()
                 if not is_new:
-                    r = self._subdir.read( uid, tag, version=version_ )
+                    r = self._subdir.read( filename, tag, version=version_ )
                 else:
                     try:
                         execute.__new_during_read = True
-                        r = self._subdir.read( uid, tag, version=version_ )
+                        r = self._subdir.read( filename, tag, version=version_ )
                     finally:
                         execute.__new_during_read = False
                         
                 if not r is tag:
                     if not track_cached_files is None:
-                        track_cached_files += self._fullFileName(uid)
+                        track_cached_files += self._fullFileName(filename)
                     execute.cache_info.last_cached = True 
                     if not debug_verbose is None:
-                        debug_verbose.write(f"cache({name}): read '{label}' version 'version {version_}' from cache '{self._subdir.fullFileName(uid)}'.")
+                        debug_verbose.write(f"cache({name}): read '{label}' version 'version {version_}' from cache '{self._subdir.full_file_name(filename)}'.")
                     if is_new:
                         assert r.__magic_cache_call_init__ is None, ("**** Internal error. __init__ should reset __magic_cache_call_init__", F.__qualname__, label)
                         r.__magic_cache_call_init__ = False # since we called __new__, __init__ will be called next
@@ -2871,9 +3830,9 @@ class CacheCallable(object):
                 assert r.__magic_cache_call_init__ is None, ("**** Internal error. __init__ should reset __magic_cache_call_init__")
             
             if cache_mode.write:
-                self._subdir.write(uid,r,version=version_)      
+                self._subdir.write(filename,r,version=version_)      
                 if not track_cached_files is None:
-                    track_cached_files += self._subdir.fullFileName(uid)
+                    track_cached_files += self._subdir.full_file_name(filename)
             execute.cache_info.last_cached = False
 
             if is_new:
@@ -2883,81 +3842,21 @@ class CacheCallable(object):
             
             if not debug_verbose is None:
                 if cache_mode.write:
-                    debug_verbose.write(f"cache({name}): called '{label}' version 'version {version_}' and wrote result into '{self._subdir.fullFileName(uid)}'.")
+                    debug_verbose.write(f"cache({name}): called '{label}' version 'version {version_}' and wrote result into '{self._subdir.full_file_name(filename)}'.")
                 else:
-                    debug_verbose.write(f"cache({name}): called '{label}' version 'version {version_}' but did *not* write into '{self._subdir.fullFileName(uid)}'.")
+                    debug_verbose.write(f"cache({name}): called '{label}' version 'version {version_}' but did *not* write into '{self._subdir.full_file_name(filename)}'.")
             return r
 
         update_wrapper( wrapper=execute, wrapped=F )
-        execute.cache_info = CacheInfo()
-        
-        execute.cache_info.name = name                       # decoded name of the function
-        execute.cache_info.signature = inspect.signature(F)  # signature of the function
-
-        execute.cache_info.uid = None           # last function call ID
-        execute.cache_info.label = None    # last unique file name cached to
-        execute.cache_info.version = None      # last version used
-
-        execute.cache_info.last_cached = None       # last function call restored from disk?
-
-        if self.cacheController.keep_last_arguments:
-            execute.cache_info.arguments = None    # last function call arguments dictionary of strings
+        execute.cache_info = CacheInfo(name, F, self.cache_controller.keep_last_arguments)
             
         if is_new:
             execute.__new_during_read = False
         
         if not debug_verbose is None:
             debug_verbose.write(f"cache({name}): {'function' if not is_new else 'class constructor function'} registered for caching into '{self._subdir.path}'.")
-        self.cacheController.versioned[name] = execute
+        self.cache_controller.versioned[name] = execute
         return execute          
 
-def VersionedCacheRoot( directory          : str, *,
-                        ext                : str = None, 
-                        fmt                : Format = None,
-                        createDirectory    : bool = None,
-                        **controller_kwargs
-                        ):
-    """
-    Create a root directory for versioning caching on disk
-    
-    Usage:
-        In a central file, define a root directory                
-            vroot = VersionedCacheRoot("!/cache")
 
-        and a sub-directory
-            vtest = vroot("test")
-            
-        @vtest.cache("1.0")
-        def f1( x=1, y=2 ):
-            print(x,y)
-            
-        @vtest.cache("1.0", dps=[f1])
-        def f2( x=1, y=2, z=3 ):
-            f1( x,y )
-            print(z)
-    
-    Parameters
-    ----------
-        directory : name of the directory. Using SubDir the following short cuts are supported:
-                        "!/dir" creates 'dir' in the temporary directory
-                        "~/dir" creates 'dir' in the home directory
-                        "./dir" created 'dir' relative to the current directory
-        ext : extension, which will automatically be appended to file names (see SubDir). Default depends on format. For Format.PICKLE it is 'pck'
-        fmt : format, see SubDir.Format. Default is Format.PICKLE
-        createDirectory : whether to create the directory upon creation. Default is no.
-        controller_kwargs: parameters passed to VersionController, for example:
-            exclude_arg_types : list of types or names of types to exclude when auto-generating function signatures from function arguments.
-                             A standard example from cdxbasics is "Context" as it is used to print progress messages.
-            max_filename_length : maximum filename length
-            hash_length: length used for hashes, see cdxbasics.util.uniqueHash() 
-        
-    Returns
-    -------
-        A root cache directory
-    """    
-    controller = CacheController(**controller_kwargs) if len(controller_kwargs) > 0 else None
-    return SubDir( directory=directory, ext=ext, fmt=fmt, createDirectory=createDirectory, controller=controller )
 
-version = version_decorator
-                
-