Index: /waeup/branches/ulif-rewrite/src/waeup/utils/helpers.txt
===================================================================
--- /waeup/branches/ulif-rewrite/src/waeup/utils/helpers.txt	(revision 4189)
+++ /waeup/branches/ulif-rewrite/src/waeup/utils/helpers.txt	(revision 4189)
@@ -0,0 +1,127 @@
+Helpers for the WAeUP SRP
+*************************
+
+:Test-Layer: unit
+
+`removeFileOrDirectory`
+=======================
+
+Removes a file or directory given by a path. We can remove files:
+
+    >>> import os
+    >>> from waeup.utils.helpers import removeFileOrDirectory
+    >>> open('blah', 'wb').write('nonsense')
+    >>> 'blah' in os.listdir('.')
+    True
+
+    >>> removeFileOrDirectory('blah')
+    >>> 'blah' in os.listdir('.')
+    False
+
+We can remove directories:
+
+    >>> os.mkdir('blah')
+    >>> 'blah' in os.listdir('.')
+    True
+
+    >>> removeFileOrDirectory('blah')
+    >>> 'blah' in os.listdir('.')
+    False
+
+
+`copyFileSystemTree`
+====================
+
+Copies the contents of an (existing) directory to another (existing)
+directory:
+
+    >>> os.mkdir('src')
+    >>> os.mkdir('dst')
+    >>> open(os.path.join('src', 'blah'), 'wb').write('nonsense')
+
+    >>> from waeup.utils.helpers import copyFileSystemTree
+    >>> result = copyFileSystemTree('src', 'dst')
+
+As a result we get a list of non-copied files:
+
+    >>> result
+    []
+
+The created file was indeed copied:
+
+    >>> 'blah' in os.listdir('dst')
+    True
+
+Hidden files (i.e. such starting with a dot) are not copied:
+
+    >>> open(os.path.join('src', '.blah'), 'wb').write('nonsense')
+    >>> result = copyFileSystemTree('src', 'dst')
+    >>> '.blah' in os.listdir('dst')
+    False
+
+This function supports some keyword parameters as explained below.
+
+`overwrite`
+-----------
+
+Boolean. If set to ``True``, any existing and same named files and
+directories in the destination dir are overwritten with copies from
+the source. Default is `False`.
+
+Normally, existing same named files in the destination are not
+overwritten:
+
+    >>> open(os.path.join('src', 'blah'), 'wb').write('newnonsense')
+    >>> result = copyFileSystemTree('src', 'dst')
+    >>> open(os.path.join('dst', 'blah'), 'rb').read()
+    'nonsense'
+
+Instead the filename is added to the result (a list of non-copied
+files):
+
+    >>> result
+    ['blah']
+
+If, however, we use `overwrite`, the existing file will be
+overwritten:
+
+    >>> result = copyFileSystemTree('src', 'dst', overwrite=True)
+    >>> open(os.path.join('dst', 'blah'), 'rb').read()
+    'newnonsense'
+
+    >>> result
+    []
+
+This also works for complete directories:
+
+    >>> os.mkdir(os.path.join('src', 'mydir'))
+    >>> os.mkdir(os.path.join('dst', 'mydir'))
+    >>> open(os.path.join(
+    ...   'src', 'mydir', 'blah'), 'wb').write('srcblah')
+    >>> open(os.path.join(
+    ...   'dst', 'mydir', 'blah'), 'wb').write('dstblah')
+
+    >>> result = copyFileSystemTree('src', 'dst', overwrite=True)
+    >>> open(os.path.join('dst', 'mydir', 'blah'), 'rb').read()
+    'srcblah'
+
+
+`del_old`
+---------
+
+Boolean. If set to ``True``, any copied files and directories will be
+removed from the src dir. Default is `False`.
+
+    >>> result = copyFileSystemTree('src', 'dst', overwrite=True, 
+    ...                                           del_old=True)
+    >>> os.listdir('src')
+    ['.blah']
+
+All files and directories are removed from src, except the hidden file
+we created in the beginning.
+
+
+Clean up:
+
+    >>> removeFileOrDirectory('src')
+    >>> removeFileOrDirectory('dst')
