The main workflow of the program passes through three different types with different responsibilities.
Entry data
~~~~~~~~~~
Data for an output entry is kept and passed around in a dict with the following contents:
``date``
A datetime.date object (if this is omitted, the ``default_date`` hook will fill in the default date from the user's configuration)
``payee``
A string
``amount``
A string or other object that can be safely converted to a decimal.Decimal
``currency``
A string with a three-letter code, uppercase, identifying the transaction currency
It can optionally include additional keys for use as template variables.
Importers
~~~~~~~~~
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)``
This method makes the hook's transformations to the entry data dict, if any. If this method clears the entry data dict, that entry will not be output.
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.
Returns a string with the output entry, using the given entry data. This is expected to be called as ``render(**entry_data)``; the arguments take the same types as entry data dicts.
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 ``util`` module.
Main loop
---------
At a high level, import2ledger handles each input file this way::
usable_importers = importers where can_handle(input_file) returns true
for importer_class in usable_importers:
template = built from importer_class.TEMPLATE_KEY
input_file.seek(0)
for entry_data in importer_class(input_file):
for hook in all_hooks:
hook.run(entry_data)
if entry_data:
template.render(**entry_data)
Note in particular that multiple importers can handle the same input file. This helps support inputs like Patreon's earnings CSV, where completely different transactions are generated from the same source.
