Define Import Handler
=====================

The obvious step here is to define a new :term:`import handler`, which
ultimately inherits from
:class:`~wuttasync.importing.handlers.ImportHandler`.  But the choice
of which class(es) *specifically* to inherit from, is a bit more
complicated.


Choose the Base Class(es)
-------------------------

If all else fails, or to get started simply, you can always just
inherit from :class:`~wuttasync.importing.handlers.ImportHandler`
directly as the only base class.  You'll have to define any methods
needed to implement desired behavior.

However depending on your particular source and/or target, there may
be existing base classes defined somewhere from which you can inherit.
This may save you some effort, and/or is just a good idea to share
code where possible.

Keep in mind your import handler can inherit from multiple base
classes, and often will - one base for the source side, and another
for the target side.  For instance::

   from wuttasync.importing import FromFileHandler, ToWuttaHandler

   class FromExcelToPoser(FromFileHandler, ToWuttaHandler):
       """
       Handler for Excel file → Poser app DB
       """

You generally will still need to define/override some methods to
customize behavior.

All built-in base classes live under :mod:`wuttasync.importing`.


.. _register-importer:

Register Importer(s)
--------------------

If nothing else, most custom handlers must override
:meth:`~wuttasync.importing.handlers.ImportHandler.define_importers()`
to "register" importer(s) as appropriate.  There are two primary goals
here:

* add "new" (totally custom) importers
* override "existing" importers (inherited from base class)

Obviously for this to actually work the importer(s) must exist in
code; see :doc:`importer`.

As an example let's say there's a ``FromFooToWutta`` handler which
defines a ``Widget`` importer.

And let's say you want to customize that, by tweaking slightly the
logic for ``WigdetImporter`` and adding a new ``SprocketImporter``::

   from somewhere_else import (FromFooToWutta, ToWutta,
                               WidgetImporter as WidgetImporterBase)

   class FromFooToPoser(FromFooToWutta):
       """
       Handler for Foo -> Poser
       """

       def define_importers(self):

           # base class defines the initial set
           importers = super().define_importers()

           # override widget importer
           importers['Widget'] = WidgetImporter

           # add sprocket importer
           importers['Sprocket'] = SprocketImporter

           return importers

   class SprocketImporter(ToWutta):
       """
       Sprocket importer for Foo -> Poser
       """

   class WidgetImporter(WidgetImporterBase):
       """
       Widget importer for Foo -> Poser
       """