Importing and Exporting Things
******************************

The waeup package tries to support all special object types to be
exportable and importable.

:Test-Layer: unit

As imports and exports of data are a cruical point when doing updates
or to enable data backups, this support must be considered a serious
topic for the base functionality of the whole software.

Exports and imports are implemented using the Zope component framework
capabilities. This means we need some adapters and utilities, which we
register, by grokking the whole package::

    >>> import grok
    >>> grok.testing.grok('waeup')


Exporting XML
=============

One of the major formats we support for data export is XML.

When we want to export an object, we can choose the kind of XML to
generate (plain or pretty) and the destination file. If we do not give
a file to write to, we get a StringIO object, i.e. an in-memory file.

To show this basic functionality provided for all XML exportable
objects, we choose faculties.

We can export faculties. First we create a faculty::

    >>> from waeup.university.faculty import Faculty
    >>> myfaculty = Faculty()
    >>> myfaculty.name = 'My very faculty.'

Exporting plain XML
-------------------

Now let's export it to XML. To do this we first ask the framework for
an exporter::

    >>> from waeup.interfaces import IWAeUPXMLExporter
    >>> exporter = IWAeUPXMLExporter(myfaculty)
    >>> exporter
    <waeup.utils.importexport.XMLExporter object at 0x...>

All exporters provide an ``export(<obj>)`` method::

    >>> result = exporter.export(myfaculty)

The result is an object of type StringIO. We therefore use its
`read()` method to get the actual XML data::

    >>> print result.read()
    <?xml version="1.0" encoding="UTF-8"?>...


Exporting pretty XML
--------------------

As the result is one long string (which is necessary to preserve
linebreaks), it is not very good readable. This special exporter
however, can also provide ``pretty XML``::

    >>> print exporter.exportPrettyXML(myfaculty).read()
    <?xml version="1.0" encoding="UTF-8"?>
    <waeupdata>
    	<object type="waeup.university.faculty.Faculty">
    		<attribute name="name" type="str">
    			My very faculty.
    		</attribute>
    	</object>
    </waeupdata>

Generating XML files
--------------------

Both methods (`export` and `exportPrettyXML`) support writing the
results to a file::

    >>> result = exporter.export(myfaculty, 'myexport.xml')
    >>> print open('myexport.xml', 'rb').read()
    <?xml version="1.0" encoding="UTF-8"?>...

We can also let the exporter format the output prettier::

    >>> result = exporter.exportPrettyXML(myfaculty, 'myexport.xml')
    >>> print open('myexport.xml', 'rb').read()
    <?xml version="1.0" encoding="UTF-8"?>
    <waeupdata>
    	<object type="waeup.university.faculty.Faculty">
    		<attribute name="name" type="str">
    			My very faculty.
    		</attribute>
    	</object>
    </waeupdata>

Clean up::

    >>> import os
    >>> os.unlink('myexport.xml')
