Package: icemac.ab.importer
This package provides import infrastructure foricemac.addressbook.Copyright (c) 2008-2020 Michael HowitzThis package is licensed under the MIT License, see LICENSE.txt inside the
package.ContentsConceptHackingSource codeRunning TestsWrite your own import file reader1. Write a reader class2. Test reader class3. Register the reader class4. Create a python package5. Integrate the reader in icemac.addressbookChangelog2.12 (2020-03-24)2.11 (2019-12-30)2.10 (2019-09-28)Previous versionsConceptImporting data requires the following steps:A user having theAdministratorrole 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.HackingSource codeGet the source code:$ git clone https://github.com/icemac/icemac.ab.importeror fork me athttps://github.com/icemac/icemac.ab.importer.Running TestsTo run the tests yourself call:$ virtualenv-2.7 .
$ bin/pip install zc.buildout
$ bin/buildout
$ bin/py.testWrite your own import file readerThe 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.importxlsprovides a reader for XLS files, so it could be
a starting point, too.1. Write a reader classThe reader class must implement the interfaceicemac.ab.importer.interfaces.IImportFileReader. There is a base
implementation inicemac.ab.importer.reader.base.BaseReaderwhich
the new reader class can extend, so there are only four things left to
implement (see the interface for a more specific description):titleattribute – shown to the user in the dialog when choosing
the readergetFieldNamesmethod – lists the names of the fields in the
import filegetFieldSamplesmethod – 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 thefileattribute.2. Test reader classicemac.ab.importer.reader.testing.ReaderTestprovides 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 initalic)reader.pytests__init__.pytest_reader.pydatashort.filelong.fileThe__init__.pyfile can be empty.Thetest_reader.pyfile contains the test class which extendsicemac.ab.importer.reader.testing.BaseReaderTest. Three
attributes have to be set on this class:reader_class- must point to the reader’s class objectimport_file- name of the longer import file (see below),
without pathimport_file_shortname of the shorter import file (see below),
without pathThere must be two files in thedatadirectory:a file for theimport_file_shortattribute on the test class,
containing the following data:last namefirstnamebirth_dateKoch1976-01-24a file for theimport_fileattribute on the test class, containing the
following data:last namefirstnamebirth_dateKochAndreas1976-01-24HulaHanna2000-01-01JänsenJensFruma2001-12-313. Register the reader classTo register the reader class withicemac.addressbookwrite aconfigure.zcmlfile in the reader package:<configure xmlns="http://namespaces.zope.org/zope">
  <include package="icemac.ab.importer" />
  <adapter
     name="<name>"
     factory="<path>" />
</configure>Theicemac.ab.importerpackage is necessary to integrate the
importer UI into the address book.  Thenameattribute contains a
unique name to identify the importer internally. Thefactoryattribute contains the python path to the reader class.4. Create a python packageThe reader class must be inside a python package. The package must
depend onicemac.ab.importer(install_requiresparameter insetup.py).5. Integrate the reader in icemac.addressbookDuring installingicemac.addressbook, it is possible to enter the
name of external dependencies. This is the place to integrate your
reader intoicemac.addressbook.Changelog2.12 (2020-03-24)Move repository tohttps://github.com/icemac/icemac.ab.importer.Adapt code toicemac.addressbook >= 9.3.2.11 (2019-12-30)Adapt code toicemac.addressbook >= 9.2.2.10 (2019-09-28)Adapt to new feature inicemac.addressbook 9.0: customization of the labels
of pre-defined fields:use customized labels in import formsdo not use field label customizations which are set for file fields on
fields of import files.Adapt tests toicemac.addressbook >= 9.0.Previous versionsSeeOLD_CHANGES.rstinside the package.