import2ledger
=============

Introduction
------------

import2ledger provides a Python library and CLI tool to read financial data from various popular sources and generate entries for text-based accounting books from them.

Installation
------------

This is a pretty normal Python module, so if you have a favorite way to install those, it will probably work.  If you just want to install it to run the script locally, try running from the source directory::

  $ python3 -m pip install --user -U --upgrade-strategy only-if-needed .

Configuring import2ledger
-------------------------

Since different organizations follow different accounting rules, you need to define an entry template for each kind of data that you want to be able to import.  You do that in a configuration file.  By default, import2ledger reads a configuration file at ``~/.config/import2ledger.ini``.  You can specify a different path with the ``-C`` option, and you can specify that multiple times to read multiple configuration files in order.

Writing templates
~~~~~~~~~~~~~~~~~

A template looks like a Ledger entry with a couple of differences:

* You don't write the first payee line.
* You allocate percentages to each account, rather than specific currency amounts.

Here's a simple template for Patreon patron payments::

  [DEFAULT]
  template patreon income =
    ;Tag: Value
    Income:Patreon  -100%%
    Accrued:Accounts Receivable:Patreon  100%%

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 amount.  However, rather than a currency amount, specify a percentage amount between -100% and 100%.  You can specify any number of splits you want, as long as the negative splits total -100% and the positive splits total 100%.  ``%`` is a special character in INI file syntax; writing ``%%`` is the way to get a literal ``%`` in the string.  Alternatively, you can omit the ``%`` altogether; import2ledger will still treat any floating point value at the end of the line as a percentage.

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.

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.

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 variables
~~~~~~~~~~~~~~~~~~

import2ledger templates have access to a few variables for each transaction that can be included in the output entry using `Python's format string syntax <https://docs.python.org/3/library/string.html#formatstrings>`_.  For most uses, all you need to do is write ``{variable_name}`` in the template, and the variable's value will be filled in there.  For example, this template sets different payees for each side of the transaction::

  template patreon income =
    Income:Patreon  -100%%
    ;Payee: {payee}
    Accrued:Accounts Receivable:Patreon  100%%
    ;Payee: Patreon

You 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
================== ==========================================================

Custom hooks may add more template variables.

Other output options
~~~~~~~~~~~~~~~~~~~~

Various options control how import2ledger formats dates and currency amounts.  Run ``import2ledger --help`` for a full list; they're listed under the "default overrides" section.  You can specify these in your configuration file, too.  Just change any dashes (``-``) in the option name to underscores (``_``), and separate the switch name from your value with ``=``.  For example, add this to your configuration file to use ISO 8601-formatted dates in your Ledger entries::

  date_format = %%Y-%%m-%%d

Configuration sections
~~~~~~~~~~~~~~~~~~~~~~

If you keep different sets of books, it might be helpful to have different configuration settings for each.  For example, you might adjust the templates for each set of books to use different accounts or tags.  Or you might just need to change the formatting of dates or currency amounts.

import2ledger makes this easy by letting you define a new section of options, and then using them all when you import transactions.  For example, say you keep two sets of books, one for US accounts and another for European accounts.  You could write a configuration file like::

  [us]
  date_format = %%m/%%d/%%Y
  signed_currencies = USD

  [eu]
  date_format = %%d.%%m.%%Y
  signed_currencies = EUR

When you run import2ledger, you can tell it to load options from one of these sections with the option ``--use-config NAME``, or ``-c NAME`` for short.  In this example, ``import2ledger -c eu`` would load the settings for your European books.  import2ledger looks for configuration settings in the following places, and uses the first setting it finds:

1. The configuration section you specify with ``-c``
2. Command-line options
3. The ``[DEFAULT]`` configuration section
4. import2ledger defaults

Running import2ledger
---------------------

Once you've written a configuration file with your templates and any other configuration you need, you can run it with data to import::

  $ import2ledger [options …] file1.csv [file2.csv …]

import2ledger will read all the data sources and generate bookkeeping entries from them.

import2ledger needs to be able to seek within the source files.  Because of that, your input files need to be normal files, or symlinks to them.  Special files like devices and FIFOs aren't supported by import2ledger.

Exit status
~~~~~~~~~~~

import2ledger reports the following exit codes:

========= =================================================================
Exit code Meaning
========= =================================================================
0         Imported data from all source files
--------- -----------------------------------------------------------------
1         Internal error (probably a bug)
--------- -----------------------------------------------------------------
2         Error in the user's settings, such as a formatting error in a
          template or date, or a reference to a nonexistent file or
          configuration file section
--------- -----------------------------------------------------------------
11-99     Failed to import data from at least one source file.  The exit
          code is 10 + the number of files that couldn't be imported, up
          to the maximum exit code of 99.
========= =================================================================