[DEFAULT]

  template patreon income =

    ;Tag: Value

    Income:Patreon  -{amount}

    Accrued:Accounts Receivable:Patreon  {amount}

Let's walk through this line by line.

Every setting in your configuration file has to be in a section.  ``[DEFAULT]`` is the default section, and import2ledger reads configuration settings from here if you don't specify another one.  This documentation explains how to use sections later.

``template patreon income =`` specifies which entry template this is.  Every template is found from a setting with a name in the pattern ``template <SOURCE> <TYPE>``.  The remaining lines are indented further than this name; this defines a multiline value.  Don't worry about the exact indentation of your template; import2ledger will indent its output nicely.

The first line of the template is a Ledger tag.  The program will leave all kinds of tags and Ledger comments alone, except to indent them nicely.

The next two lines split the money across accounts.  They follow almost the same format as they do in Ledger: there's an account named, followed by a tab or two or more spaces, and then an expression.  Each time import2ledger generates an entry, it will evaluate this expression using the data it imported to calculate the actual currency amount to write.  Your expression can use numbers, basic arithmetic operators (including parentheses for grouping), and imported data referred to as ``{variable_name}``.

import2ledger uses decimal math to calculate each amount, and rounds to the number of digits appropriate for that currency.  If the amount of currency being imported doesn't split evenly, spare change will be allocated to the last split to keep the entry balanced on both sides.

Refer to the `Python documentation for INI file structure <https://docs.python.org/3/library/configparser.html#supported-ini-file-structure>`_ for full details of the syntax.  Note that import2ledger doesn't use ``;`` as a comment prefix, since that's the primary comment prefix in Ledger.

Template variables

~~~~~~~~~~~~~~~~~~

import2ledger templates have access to a few variables for each transaction that can be included anywhere in the entry, not just amount expressions.  In other parts of the entry, they're treated as strings, and you can control their formatting using `Python's format string syntax <https://docs.python.org/3/library/string.html#formatstrings>`_.  For example, this template customizes the payee line and sets different payees for each side of the transaction::

  template patreon income =

    {date}  Patreon payment from {payee}

    Income:Patreon  -{amount}

    ;Payee: {payee}

    Accrued:Accounts Receivable:Patreon  {amount}

    ;Payee: Patreon

Templates automatically detect whether or not you have a custom payee line by checking if the first line begins with a date variable.  If it does, it's assumed to be your payee line.  Otherwise, the template uses a default payee line of ``{date} {payee}``.

Every template can use the following variables:

================== ==========================================================

Name               Contents

================== ==========================================================

amount             The total amount of the transaction, as a simple decimal

                   number (not currency-formatted)

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

currency           The three-letter code for the transaction currency

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

date               The date of the transaction, in your configured output

                   format

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

payee              The name of the transaction payee

================== ==========================================================

Specific importers and hooks may provide additional variables.

Supported templates

~~~~~~~~~~~~~~~~~~~

You can define the following templates.

Patreon

^^^^^^^

``template patreon income``

  Imports one transaction per patron per month.  Generated from Patreon's monthly patron report CSVs.

``template patreon cardfees``

  Imports one expense transaction per month for that month's credit card fees.  Generated from Patreon's earnings report CSV.

``template patreon svcfees``

  Imports one expense transaction per month for that month's Patreon service fees.  Generated from Patreon's earnings report CSV.

``template patreon vat``

  Imports one transaction per country per month each time Patreon withheld VAT.  Generated from Patreon's VAT report CSV.

  This template can use these variables:

  ============== ============================================================

  Name           Contents

  ============== ============================================================

  country_name   The full name of the country VAT was withheld for

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

  country_code   The two-letter ISO country code of the country VAT was

                 withheld for

  ============== ============================================================

Stripe

^^^^^^

``template stripe payments``

  Imports one transaction per payment.  Generated from Stripe's payments CSV export.

  This template can use these variables:

  ============ ============================================================

  Name         Contents

  ============ ============================================================

  description  The description given to the payment when it was created

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

import contextlib

import logging

import sys

from . import config, errors, hooks, importers

logger = logging.getLogger('import2ledger')

class FileImporter:

    def __init__(self, config, stdout):

        self.config = config

        self.importers = list(importers.load_all())

        self.hooks = [hook(config) for hook in hooks.load_all()]

        self.stdout = stdout

        importers = []

        for importer in self.importers:

            in_file.seek(0)

            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):

                    entry_data['_hook_cancel'] = False

                    for hook in self.hooks:

                        hook.run(entry_data)

                        if entry_data['_hook_cancel']:

                            break

                    else:

                        del entry_data['_hook_cancel']

    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)

    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)

    logger.addHandler(handler)

def main(arglist=None, stdout=sys.stdout, stderr=sys.stderr):

    try:

        my_config = config.Configuration(arglist)

    except errors.UserInputError as error:

        my_config.error("{}: {!r}".format(error.strerror, error.user_input))

        return 3

    setup_logger(logger, my_config, stderr)

    importer = FileImporter(my_config, stdout)

    failures = 0

    for input_path, error in importer.import_paths(my_config.args.input_paths):

        if error is None:

            logger.info("%s: imported", input_path)

        else:

            logger.warning("%s: failed to import: %s", input_path or error.path, error)

            failures += 1

    if failures == 0:

        return 0

    else:

        return min(10 + failures, 99)

if __name__ == '__main__':

    exit(main())

[DEFAULT]

default_date = 2016/04/04

loglevel = critical

signed_currencies = USD

[One]

template patreon cardfees =

 Accrued:Accounts Receivable  -{amount}

 Expenses:Fees:Credit Card  {amount}

template patreon svcfees =

 Accrued:Accounts Receivable  -{amount}

 Expenses:Fundraising  {amount}

2017/09/01 Patreon

  Accrued:Accounts Receivable  $-52.47

  Expenses:Fees:Credit Card  $52.47

2017/10/01 Patreon

  Accrued:Accounts Receivable  $-99.47

  Expenses:Fees:Credit Card  $99.47

2017/10/01 Patreon

  Accrued:Accounts Receivable  $-117.03

  Expenses:Fundraising  $117.03

import io

import pathlib

import pytest

from . import DATA_DIR, normalize_whitespace

from import2ledger import __main__ as i2lmain

ARGLIST = [

    '-C', (DATA_DIR / 'test_main.ini').as_posix(),

]

def run_main(arglist):

    stdout = io.StringIO()

    stderr = io.StringIO()

    exitcode = i2lmain.main(arglist, stdout, stderr)

    stdout.seek(0)

    stderr.seek(0)

    return exitcode, stdout, stderr

def iter_entries(in_file):

    lines = []

    for line in in_file:

        if line == '\n':

            if lines:

                yield ''.join(lines)

            lines = []

        else:

            lines.append(line)

    if lines:

        yield ''.join(lines)

    path = pathlib.Path(path)

    if not path.is_absolute():

        path = DATA_DIR / path

    with path.open() as in_file:

def test_fees_import():

    arglist = ARGLIST + [

        '-c', 'One',

    ]

    exitcode, stdout, _ = run_main(arglist)

    assert exitcode == 0

def test_date_range_import():

    arglist = ARGLIST + [

        '-c', 'One',

        '--date-range', '2017/10/01-',

    ]

    exitcode, stdout, _ = run_main(arglist)

    assert exitcode == 0

    assert actual == expected