Launchpad helper to write tar files
===================================

LaunchpadWriteTarFile is a helper class to make .tar.gz generation
easy.

    >>> from StringIO import StringIO
    >>> from lp.services.tarfile_helpers import LaunchpadWriteTarFile

First, we are going to define a function we are going to use to validate the
output we will get.

    >>> def examine_tarfile(tarfile):
    ...     names = tarfile.getnames()
    ...     # Calculate the length of the longest name.
    ...     max_length = max(len(name) for name in names)
    ...     # Use this length to generate an appropriate format string.
    ...     format = '%%-%ds | %%s' % max_length
    ...
    ...     for name in names:
    ...         file = tarfile.extractfile(name)
    ...
    ...         # XXX: 2010-04-26, Salgado, bug=570244: This is to make the
    ...         # test pass on python2.5 and 2.6.
    ...         name = name.rstrip('/')
    ...         if file is not None:
    ...             print format % (name, file.read())
    ...         else:
    ...             print format % (name, '')

    # Start off by creating a blank archive.
    # We'll need a filehandle to store it in.
    >>> buffer = StringIO()
    >>> archive = LaunchpadWriteTarFile(buffer)

We can add files individually. First argument is the file name, second
argument is the file content.

    >>> archive.add_file('foo', '1')

Or add many files simultaneously using a dictionary that use the key as
the file name and the value the file content.

    >>> archive.add_files({'bar': '2', 'baz': '3'})

Once we are done adding files, the archive needs to be closed.

    >>> archive.close()

And now we can inspect the produced file.

    >>> import tarfile
    >>> buffer.seek(0)
    >>> archive = tarfile.open('', 'r', buffer)
    >>> examine_tarfile(archive)
    foo | 1
    bar | 2
    baz | 3

There are also some convenience methods for getting directly from several
files, represented with a dictionary, which have the file name as key and
file content as the value, to a stream...

If we have several files to import...

    >>> files = {
    ...     'eins': 'zwei',
    ...     'drei': 'vier'
    ... }

...then we can easily turn it into a tarfile file object with
files_to_tarfile...

    >>> archive = LaunchpadWriteTarFile.files_to_tarfile(files)
    >>> examine_tarfile(archive)
    drei | vier
    eins | zwei

...or a tarfile stream with files_to_stream...

    >>> stream = LaunchpadWriteTarFile.files_to_stream(files)
    >>> archive = tarfile.open('', 'r', stream)
    >>> examine_tarfile(archive)
    drei | vier
    eins | zwei

...or a data string.

    >>> data = LaunchpadWriteTarFile.files_to_string(files)
    >>> archive = tarfile.open('', 'r', StringIO(data))
    >>> examine_tarfile(archive)
    drei | vier
    eins | zwei

If a filename contains slashes, containing directories are automatically
created.

    >>> archive = LaunchpadWriteTarFile.files_to_tarfile({
    ...     'uno/dos/tres/cuatro': 'blah'
    ...     })
    >>> examine_tarfile(archive)
    uno                 |
    uno/dos             |
    uno/dos/tres        |
    uno/dos/tres/cuatro | blah

Also, if there is a duplicated file, last one is the one that remains there.

    >>> archive = LaunchpadWriteTarFile.files_to_tarfile({
    ...     'foo.po': 'blah',
    ...     'foo.po': 'duplicated file'
    ...     })
    >>> examine_tarfile(archive)
    foo.po | duplicated file