At a high level, importers read a source file, and generate data for output entries.

Class method ``can_handle(source_file)``

  Returns true if the importer can generate entries from the given source file object, false otherwise.

``__init__(source_file)``

  Initializes an importer to generate entries from the given source file object.

``__iter__()``

  Returns a iterator of entry data dicts.

Class attribute ``TEMPLATE_KEY``

  A string with the full key to load the corresponding template from the user's configuration (e.g., ``'template patreon income'``).

Hooks

~~~~~

Hooks make arbitrary transformations to entry data dicts.  Every entry data dict generated by an importer is run through every hook before being output.

``__init__(config)``

  Initializes the hook with the user's configuration.

``run(entry_data)``

Templates

~~~~~~~~~

Templates receive entry data dicts and format them into final output entries.

``__init__(template_str)``

  Initializes the template from a single string, as read from the user's configuration.

``render(entry_data)``

  Returns a string with the output entry, using the given entry data.

Loading importers and hooks

---------------------------

Importers and hooks are both loaded and found dynamically when the program starts.  This makes it easy to extend the program: you just need to write the class following the established pattern, no registration needed.

import2ledger finds importers by looking at all ``.py`` files in the ``importers/`` directory, skipping files whose names start with ``.`` (hidden) or ``_`` (private).  It tries to import that file as a module.  If it succeeds, it looks for things in the module named ``*Importer``, and adds those to the list of importers.

Hooks follow the same pattern, searching the ``hooks/`` directory and looking for things named ``*Hook``.

Technically this is done by ``importers.load_all()`` and ``hooks.load_all()`` functions, but most of the code to do this is in the ``dynload`` module.

Main loop

            if importer.can_import(in_file):

                try:

                    template = self.config.get_template(importer.TEMPLATE_KEY)

                except errors.UserInputConfigurationError as error:

                    if error.strerror.startswith('template not defined '):

                        have_template = False

                    else:

                        raise

                else:

                    have_template = not template.is_empty()

                if have_template:

                    importers.append((importer, template))

        if not importers:

            raise errors.UserInputFileError("no importers available", in_file.name)

        with contextlib.ExitStack() as exit_stack:

            output_path = self.config.get_output_path()

            if output_path is None:

                out_file = self.stdout

            else:

                out_file = exit_stack.enter_context(output_path.open('a'))

            for importer, template in importers:

                default_date = self.config.get_default_date()

                in_file.seek(0)

                for entry_data in importer(in_file):

                    for hook in self.hooks:

                        hook.run(entry_data)

                            break

                    else:

                        print(template.render(**entry_data), file=out_file, end='')

    def import_path(self, in_path):

        if in_path is None:

            raise errors.UserInputFileError("only seekable files are supported", '<stdin>')

        with in_path.open(errors='replace') as in_file:

            if not in_file.seekable():

                raise errors.UserInputFileError("only seekable files are supported", in_path)

            return self.import_file(in_file)

    def import_paths(self, path_seq):

        for in_path in path_seq:

            try:

                retval = self.import_path(in_path)

            except (OSError, errors.UserInputError) as error:

                yield in_path, error

            else:

                yield in_path, retval

def setup_logger(logger, main_config, stream):

    formatter = logging.Formatter('%(name)s: %(levelname)s: %(message)s')

    handler = logging.StreamHandler(stream)

    handler.setFormatter(formatter)

class FilterByDateHook:

    def __init__(self, config):

        self.config = config

    def run(self, entry_data):

        try:

            date = entry_data['date']

        except KeyError:

            pass

        else:

            if not self.config.date_in_want_range(date):

    def date_in_want_range(self, date):

        return (

            ((self.start_date is None) or (date >= self.start_date))

            and ((self.end_date is None) or (date <= self.end_date))

        )

@pytest.mark.parametrize('entry_date,start_date,end_date,allowed', [

    (datetime.date(2016, 5, 10), datetime.date(2016, 1, 1), datetime.date(2016, 12, 31), True),

    (datetime.date(2016, 1, 1), datetime.date(2016, 1, 1), datetime.date(2016, 12, 31), True),

    (datetime.date(2016, 12, 31), datetime.date(2016, 1, 1), datetime.date(2016, 12, 31), True),

    (datetime.date(2016, 1, 1), datetime.date(2016, 1, 1), None, True),

    (datetime.date(2016, 12, 31), None, datetime.date(2016, 12, 31), True),

    (datetime.date(1999, 1, 2), None, None, True),

    (datetime.date(2016, 1, 25), datetime.date(2016, 2, 1), datetime.date(2016, 12, 31), False),

    (datetime.date(2016, 12, 26), datetime.date(2016, 1, 1), datetime.date(2016, 11, 30), False),

    (datetime.date(2016, 1, 31), datetime.date(2016, 2, 1), None, False),

    (datetime.date(2016, 12, 1), None, datetime.date(2016, 11, 30), False),

])

def test_filter_by_date(entry_date, start_date, end_date, allowed):

    entry_data = {'date': entry_date}

    hook = filter_by_date.FilterByDateHook(DateRangeConfig(start_date, end_date))

    hook.run(entry_data)

class DefaultDateConfig:

    ONE_DAY = datetime.timedelta(days=1)

    def __init__(self, start_date=None):

        if start_date is None:

            start_date = datetime.date(2016, 3, 5)

        self.date = start_date - self.ONE_DAY

    def get_default_date(self, section_name=None):

        self.date += self.ONE_DAY

        return self.date

class TestDefaultDate:

    def test_simple_case(self):

        expect_date = datetime.date(2016, 2, 4)

        config = DefaultDateConfig(expect_date)

        data = {}

        hook = default_date.DefaultDateHook(config)

        hook.run(data)

        assert data['date'] == expect_date

    def test_no_caching(self):