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')
