GitLocker: The Coding Marketplace

Description:

icemac.ab.importer 2.12

This package provides import infrastructure for icemac.addressbook.
Copyright (c) 2008-2020 Michael Howitz
This package is licensed under the MIT License, see LICENSE.txt inside the
package.

Contents

Concept
Hacking

Source code
Running Tests

Write your own import file reader

1. Write a reader class
2. Test reader class
3. Register the reader class
4. Create a python package
5. Integrate the reader in icemac.addressbook

Changelog

2.12 (2020-03-24)
2.11 (2019-12-30)
2.10 (2019-09-28)
Previous versions

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.

Hacking

Source code
Get the source code:
$ git clone https://github.com/icemac/icemac.ab.importer
or fork me at https://github.com/icemac/icemac.ab.importer.

Running Tests
To run the tests yourself call:
$ virtualenv-2.7 .
$ bin/pip install zc.buildout
$ bin/buildout
$ bin/py.test

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:

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.

Changelog

2.12 (2020-03-24)

Move repository to https://github.com/icemac/icemac.ab.importer.
Adapt code to icemac.addressbook >= 9.3.

2.11 (2019-12-30)

Adapt code to icemac.addressbook >= 9.2.

2.10 (2019-09-28)

Adapt to new feature in icemac.addressbook 9.0: customization of the labels
of pre-defined fields:

use customized labels in import forms
do not use field label customizations which are set for file fields on
fields of import files.

Adapt tests to icemac.addressbook >= 9.0.

Previous versions
See OLD_CHANGES.rst inside the package.