icemac.ab.importer 2.3

Source code

Get the source code:

$ hg clone https://bitbucket.org/icemac/icemac.ab.importer

or fork me on: https://bitbucket.org/icemac/icemac.ab.importer

Running Tests

To run the tests yourself call:

$ python2.7 bootstrap.py
$ bin/buildout
$ bin/py.test

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:

1. The directory structure must look like this: (directories in italic)

   • reader.py

   • tests

     • __init__.py

     • test_reader.py

     • data

       • short.file

       • long.file

2. The __init__.py file can be empty.

3. 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

4. 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:

     last name	firstname	birth_date
     Koch		1976-01-24

   • a file for the import_file attribute on the test class, containing the following data:

     last name	firstname	birth_date
     Koch	Andreas	1976-01-24
     Hula	Hanna	2000-01-01
     Jänsen	Jens
     Fruma		2001-12-31

3. Register the reader class

To register the reader class with icemac.addressbook write a configure.zcml file in the reader package:

<configure xmlns="http://namespaces.zope.org/zope">
  <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.

2.3 (2017-01-07)

• Bring branch test coverage to 100 %.

• Adapt configuration of user roles and code to icemac.addressbook >= 2.9.

2.2 (2016-03-05)

• Update to bootstrap.py from zc.buildout 2.3.1.

• Update tests to only run with py.test.

• Update code and tests to changes in icemac.addressbook 2.6.

2.1.0 (2014-07-01)

• The master data tab in the main menu is now highlighted when the importer is displayed.

• Update code and tests to changes in icemac.addressbook 2.5.

• Add py.test to run the tests.

Previous versions

See OLD_CHANGES.rst inside the package.