Changeset 4962 for main/waeup.sirp/trunk

Timestamp:

1 Feb 2010, 16:25:15 (15 years ago)

Author:

uli

Message:

Remove quick-import tests.

File:

• main/waeup.sirp/trunk/src/waeup/sirp/datacenter.txt (modified) (1 diff)

main/waeup.sirp/trunk/src/waeup/sirp/datacenter.txt

@@ -257 +257 @@
 
     >>> shutil.rmtree(verynewpath)
-
-Handling imports
-================
-
-Data centers can find objects ready for CSV imports and associate
-appropriate importers with them.
-
-Getting importers
------------------
-
-To do so, data centers look up their parents for the nearest ancestor,
-that implements `ICSVDataReceivers` and grab all attributes, that
-provide some importer.
-
-We therefore have to setup a proper scenario first.
-
-We start by creating a simple thing that is ready for receiving CSV
-data:
-
-    >>> class MyCSVReceiver(object):
-    ...   pass
-
-Then we create a container for such a CSV receiver:
-
-    >>> import grok
-    >>> from waeup.sirp.interfaces import ICSVDataReceivers
-    >>> from waeup.sirp.datacenter import DataCenter
-    >>> class SomeContainer(grok.Container):
-    ...   grok.implements(ICSVDataReceivers)
-    ...   def __init__(self):
-    ...     self.some_receiver = MyCSVReceiver()
-    ...     self.other_receiver = MyCSVReceiver()
-    ...     self.datacenter = DataCenter()
-
-By implementing `ICSVDataReceivers`, a pure marker interface, we
-indicate, that we want instances of this class to be searched for CSV
-receivers.
-
-This root container has two CSV receivers.
-
-The datacenter is also an attribute of our root container.
-
-Before we can go into action, we also need an importer, that is able
-to import data into instances of MyCSVReceiver:
-
-    >>> from waeup.sirp.csvfile.interfaces import ICSVFile
-    >>> from waeup.sirp.interfaces import IWAeUPCSVImporter
-    >>> from waeup.sirp.utils.importexport import CSVImporter
-    >>> class MyCSVImporter(CSVImporter):
-    ...   grok.adapts(ICSVFile, MyCSVReceiver)
-    ...   grok.provides(IWAeUPCSVImporter)
-    ...   datatype = u'My Stuff'
-    ...   def doImport(self, filepath, clear_old_data=True,
-    ...                                overwrite=True):
-    ...     print "Data imported!"
-
-We grok the components to get the importer (which is actually an
-adapter) registered with the component architechture:
-
-    >>> grok.testing.grok('waeup')
-    >>> grok.testing.grok_component('MyCSVImporter', MyCSVImporter)
-    True
-
-Now we can create an instance of `SomeContainer`:
-
-    >>> mycontainer = SomeContainer()
-
-As we are not creating real sites and the objects are 'placeless' from
-the ZODB point of view, we fake a location by telling the datacenter,
-that its parent is the container:
-
-    >>> mycontainer.datacenter.__parent__ = mycontainer
-    >>> datacenter = mycontainer.datacenter
-
-When a datacenter is stored in the ZODB, this step will happen
-automatically.
-
-Before we can go on, we have to set a usable path where we can store
-files without doing harm:
-
-    >>> os.mkdir('filestore')
-    >>> filestore = os.path.abspath('filestore')
-    >>> datacenter.setStoragePath(filestore)
-    []
-
-Furthermore we must create a file for possible import, as we will get
-only importers, for which also an importable file is available:
-
-    >>> import os
-    >>> filepath = os.path.join(datacenter.storage, 'mydata.csv')
-    >>> open(filepath, 'wb').write("""col1,col2
-    ... 'ATerm','Something'
-    ... """)
-
-The datacenter is now able to find the CSV receivers in its parents:
-
-    >>> datacenter.getImporters()
-    [<MyCSVImporter object at 0x...>, <MyCSVImporter object at 0x...>]
-
-
-Imports with the WAeUP portal
------------------------------
-
-The examples above looks complicated, but this is the price for
-modularity. If you create a new container type, you can define an
-importer and it will be used automatically by other components.
-
-In the WAeUP portal the only component that actually provides CSV data
-importables is the `University` object.
-
-
-Getting imports (not: importers)
---------------------------------
-
-We can get 'imports':
-
-    >>> datacenter.getPossibleImports()
-    [(<...DataCenterFile object at 0x...>, 
-      [(<MyCSVImporter object at 0x...>, '...'),
-       (<MyCSVImporter object at 0x...>, '...')])]
-
-As we can see, an import is defined here as a tuple of a
-DataCenterFile and a list of available importers with an associated
-data receiver (the thing where the data should go to).
-
-The data receiver is given as an ZODB object id (if the data receiver
-is persistent) or a simple id (if it is not).
-
-Clean up:
-
-    >>> import shutil
-    >>> shutil.rmtree(filestore)
-
-
-Data center helpers
-===================
-
-Data centers provide several helper methods to make their usage more
-convenient.
-
-
-Receivers and receiver ids
---------------------------
-
-As already mentioned above, imports are defined as triples containing
-
-* a file to import, 
-
-* an importer to do the import and 
-
-* an object, which should be updated by the data file.
-
-The latter normally is some kind of container, like a faculty
-container or similar. This is what we call a ``receiver`` as it
-receives the data from the file via the importer.
-
-The datacenter finds receivers by looking up its parents for a
-component, that implements `ICSVDataReceivers` and scanning that
-component for attributes, that can be adapted to `ICSVImporter`.
-
-I.e., once found an `ICSVDataReceiver` parent, the datacenter gets all
-importers that can be applied to attributes of this component. For
-each attribute there can be at most one importer.
-
-When building the importer list for a certain file, we also check,
-that the headers of the file comply with what the respective importers
-expect. So, if a file contains broken headers, the file won't be
-offered for import at all.
-
-The contexts of the found importers then build our list of available
-receivers. This means also, that for each receiver provided by the
-datacenter, there is also an importer available.
-
-If for a potential receiver no importer can be found, this receiver
-will be skipped.
-
-As one type of importer might be able to serve several receivers, we
-also have to provide a unique id for each receiver. This is, where
-``receiver ids`` come into play.
-
-Receiver ids of objects are determined as
-
-* the ZODB oid of the object if the object is persistent
-
-* the result of id(obj) otherwise.
-
-The value won this way is a long integer which we turn into a
-string. If the value was get from the ZODB oid, we also prepend it
-with a ``z`` to avoid any clash with non-ZODB objects (they might
-deliver the same id, although this is *very* unlikely).