text: icemac.ab.importer 1.8.0
  Import infrastructure for icemac.addressbook
  This package provides import infrastructure for icemac.addressbook.
  Contents
  - Concept
  - Write your own import file reader
  - Changelog
  Concept
  Importing data requires the following steps:
  - A user having the Administrator role uploads an import file to the address book. It gets stored there inside the importer.
  - When the user decides to import the the uploaded file, he is presented with a list of readers which claim to be able to read the import file.
  - After choosing the import file reader the user has to map which field data in the import file should be stored in which field in the address book.
  - The imported data gets shown and the user can decide to keep or to discard the imported data.
  Write your own import file reader
  The key to extend the import mechanism is to provide a reader for the needed import file type.
  This package already provides an import file reader for CSV files.
  icemac.ab.importxls provides a reader for XLS files, so it could be a starting point, too.
  1. Write a reader class
  The reader class must implement the interface icemac.ab.importer.interfaces.IImportFileReader. There is a base implementation in icemac.ab.importer.reader.base.BaseReader which the new reader class can extend, so there are only four things left to implement (see the interface for a more specific description):
  - title attribute -- shown to the user in the dialog when choosing the reader
  - getFieldNames method -- lists the names of the fields in the import file
  - getFieldSamples method -- returns samples of a specific field to ease the mapping task for the user
  - __iter__ method -- iterates the import file to get the data for the import.
  The base class file stores the file for reading on the file attribute.
  2. Test reader class
  icemac.ab.importer.reader.testing.ReaderTest provides a (base) test class which checks whether the reader behaves as expected. It requires some example files for the reader. The derived reader tests must fulfill the following conventions:
  The directory structure must look like this: (directories in italic)
  - reader.py
  - tests
  - __init__.py
  - test_reader.py
  - data
  - short.file
  - long.file
  The __init__.py file can be empty.
  The test_reader.py file contains the test class which extends icemac.ab.importer.reader.testing.BaseReaderTest. Three attributes have to be set on this class:
  - reader_class - must point to the reader's class object
  - import_file - name of the longer import file (see below), without path
  - import_file_short name of the shorter import file (see below), without path
  There must be two files in the data directory:
  a file for the import_file_short attribute on the test class, containing the following data:
  a file for the import_file attribute on the test class, containing the following data:
  3. Register the reader class
  To register the reader class with icemac.addressbook write a configure.zcml file in the reader package:
  <configure xmlns=""> <include package="icemac.ab.importer" /> <adapter name="<name>" factory="<path>" /> </configure>
  The icemac.ab.importer package is necessary to integrate the importer UI into the address book. The name attribute contains a unique name to identify the importer internally. The factory attribute contains the python path to the reader class.
  4. Create a python package
  The reader class must be inside a python package. The package must depend on icemac.ab.importer (install_requires parameter in setup.py).
  5. Integrate the reader in icemac.addressbook
  During installing icemac.addressbook, it is possible to enter the name of external dependencies. This is the place to integrate your reader into icemac.addressbook.
  Changelog
  1.8.0 (2011-12-14)
  - Adapted test and test set up to run with icemac.addressbook version 1.8.
  1.7.2 (2011-11-22)
  - Fixed a missing import which was masked by the Python import bug.
  1.7.1 (2011-11-03)
  - Fixing brown bag release: only namespace packages were installed.
  1.7.0 (2011-11-03)
  - Using stacked test layers for faster tests.
  - Extracted reuseable parts of import wizard to icemac.addressbook.
  - Adapted code, test set up and tests to run with icemac.addressbook version 1.7.
  1.6.0 (2011-02-03)
  - Adapted code and tests to run with icemac.addressbook version 1.6.
  Previous Versions
  See OLD_CHANGES.txt inside the package.
  - Author: Michael Howitz
  - Keywords: icemac.addressbook
  - License: ZPL 2.1
  - Categories
  - Development Status :: 3 - Alpha
  - Environment :: Web Environment
  - Framework :: Paste
  - Framework :: Zope3
  - License :: OSI Approved
  - License :: OSI Approved :: Zope Public License
  - Natural Language :: English
  - Operating System :: OS Independent
  - Programming Language :: Python
  - Programming Language :: Python :: 2.6
  - Package Index Owner: icemac
  - DOAP record: icemac.ab.importer-1.8.0.xml