ABOUT
-----

gcinvoice (http://www.smoerz.org/gcinvoice) is a tool to parse Gnucash data
files, and create invoices from this data using templates. It is similar to
g2latex (http://stefans.datenbruch.de/gnucash/gc2latex.shtml) by Stefan
Tomanek, but the latter was not powerful enough for my needs, and did somehow
not work for me.

Features of gcinvoice:

* works with data files from Gnucash starting with version 2.0.

* powerful templating.

* full support for discount and taxes, but WARNING:
  In my opinion, Gnucash does not calculate POSTTAX discounts correctly, see
  bug http://bugzilla.gnome.org/show_bug.cgi?id=520547 in the Gnucash bug
  database. gcinvoice calculates the taxes the way I think it should be, and
  thus gives a different result for invoices with such discounts. If such
  discounts occure in a invoice generated by gcinvoice, a warning is
  generated.

* needs only a working Python version 2.7 or 3.x installation (tested with 2.7 and 3.4).

* can be run standalone, or easily integrated into python applications.

* gcinvoice is free software.

LICENSE AND CREDITS
-------------------

gcinvoice was written by Roman Bertle <bertle@smoerz.org> 2007-2008. It
contains an adapted version of YAPTU, a templating utility written by Alex
Martelli (ActiveState python Cookbook recipe 52305). gcinvoice is
published under the Python license (http://www.python.org/psf/license/).

INSTALLATION AND USAGE
----------------------

The only prerequisite of gcinvoice is a working installation of Python,
version 2.7 or 3.x installation.

Before (and also after) installation, various tests can be run by e.g.

  python test.py

There might be a warning about a missing locale 'de_DE.UTF'; this special
locale is used to test formatting of currency and quantity values. If it is
not available, these tests are not performed, but this does not indicate any
further problems. One test (testScriptrun) might also fail if you have
already installed a global /etc/gcinvoicerc or a $HOME/.gcinvoicerc, or have
a changed gcinvoicerc in the directory you run the test from, because it
assumes the default settings of gcinvoice.
Further a warning about PRETAX discounts is generated; it can be ignored. See
also my comment on PRETAX discount calculations above.

There are two ways to use gcinvoice. First, it can be run as a
stand-alone script by simply executing it. To copy the file into your
binary search path, simply run

  python setup.py install_scripts

where the version of python must be at least 2.5. For options, type

  python setup.py install_scripts --help

The other way is to install gcinvoice as a module, which is done by

  python setup.py install

installation help is available with

  python setup.py install --help

After installing gcinvoice this way, it can either be called as script
with

  python -m gcinvoice

or used from your own python scripts or running session using

  import gcinvoice

For the usage of gcinvoice, run it with option --help, and use the doc
strings of the module. An example for running gcinvoice as a script:

  ./gcinvoice.py -t mytemplate.tex  -o out.tex 13

This uses the invoice with id '13' to fill out the template 'mytemplate.tex'
and put the result into 'out.tex'. The gnucash data file is inferred in this
example from the configuration files, as described in the next section.

CONFIGURATION
-------------

gcinvoice reads configuration files from the following places:

* /etc/gcinvoicerc

* $HOME/.gcinvoicerc

* ./gcinvoicerc

and all files given to gcinvoice as a configuration option. The format of
the configuration files is defined by the python standard library module
'ConfigParser'; the file 'gcinvoicerc' distributed with gcinvoice is a
well documented sample configuration file which can be adapted for your
needs.

TEMPLATES
---------

gcinvoice uses a template file to generate invoices from the parsed
Gnucash data. The templating engine 'YAPTU' is built into gcinvoice, for
detailed information see
http://aspn.activestate.com/ASPN/Cookbook/Python/Recipe/52305.
In short, the template file can contain python statements, and python
expressions identified by (configurable) regular expressions. There is
no restriction on the used python code, hence be careful, a malicious
template could execute any code.

By default, python expressions are written as @{}, where the expression
is inside the curly brackets. Below are the defined variables extracted
from the Gnucash data file, with there type indicated. These variables
can also be None if not found in the Gnucash data file. The type
'formatted' is special: For each of such a variable 'x', there is a
variable 'x_', which is a decimal.Decimal instance. The variable 'x' is
the value formatted as a string according to the configurated settings.

  guid        -- The guid of the invoice (string).
  id          -- The id of the invoice (int if possible, else string).
  billing_id  -- The billing_id of the invoice (string).
  owner       -- The owner (customer or vendor) of the invoice (dict).
  job         -- The job of the invoice (dict).
  date_opened -- The open date of the invoice (Date).
  date_posted -- The post date of the invoice (Date).
  terms       -- The terms of the invoice (dict).
  notes       -- The notes of the invoice (string).
  currency    -- The currency of the invoice (string).
  entries     -- The entries of the invoice (list).
  amount_net  -- The total net amount of the invoice (formatted).
  amount_gross -- The total gross amount of the invoice (formatted).
  amount_taxes -- The total amount of taxes of the invoice (formatted).

In addition these useful functions and classes are provided:

  _currencyformatting -- A function to format monetary values.
  _quantityformatting -- A function to format other quantities.
  cformat -- The function to format monetary values as used by gcinvoice.
  qformat -- The function to format other quantities as used by gcinvoice.
  Decimal -- The decimal.Decimal class.

The dict 'owner' contains data of the customer or vendor:

  guid        -- The guid of the owner (string).
  id          -- The id of the owner (int if possible, else string).
  name        -- The name of the owner (string).
  address     -- The address of the owner (list of strings).
  email       -- The email of the (string).
  full_name   -- The full name of the (string).

The dict 'job' containes:

  guid        -- The guid of the job (string).
  id          -- The id of the job (int if possible, else string).
  name        -- The name of the job (string).
  reference   -- The reference of the job (string).
  owner       -- The owner (customer or vendor) of the job (dict).
                 The owner of the invoice is also accessible directly
                 in variable 'owner', see above.

The dict 'terms' contains:

  guid        -- The guid of the terms (string).
  name        -- The name of the terms (string).
  desc        -- The description of the terms (string).
  due-days    -- The due days of the terms (string).
  disc-days   -- The discount days of the terms (string).
  discount    -- The discount of the terms (Decimal number).

'entries' is a list of dicts, where amount_net, amount_gross and
amount_taxes are amounts after applying the discount:

  guid        -- The guid of the entry (string).
  date        -- The date of the entry (Date).
  entered     -- The datetime of entering of the entry (DateTime).
  description -- The description of the entry (string).
  action      -- The action of the entry (action).
  qty         -- The quantity of the entry (formatted).
  price       -- The price of the entry (formatted).
  amount_raw  -- The amount of the entry as entered into Gnucash,
        i.e. qty x price (formatted).
  amount_net  -- The amount of the entry without taxes (formatted).
  amount_gross -- The amount of the entry including taxes (formatted).
  amount_taxes -- The amount of the taxes for the entry (formatted).
  amount_discount -- The amount of the discount for the entry (formatted).
        for POSTTAX, this is the gross discount, else its the net discount.
  discount    -- The discount of the entry (Decimal number).
  discount_type -- The type of the discount (DISCOUNT/VALUE) (string).
  discount_how -- Taxing of the discount (PRETAX/SAMETIME/POSTTAX) (string).
  taxable     -- Flag if the entry is taxable (int).
  taxincluded -- Flag if the tax is included in amount_raw (int).
  taxtable    -- Tax table for the entry (dict).

The dict 'taxtable' contains:

  guid        -- The guid of the taxtable (string).
  name        -- The name of the taxtable (string).
  percent_sum -- Sum of percent entries of the taxtable (Decimal number).
  value_sum   -- Sum of value entries of the taxtable (Decimal number).

Python statements are identified by default by lines in the template
starting either with '%+', '%-' or '%='. The first one is for start
statements like 'for e in entries' or 'if ...', the second one marks
usually empty lines ending a python 'if' or 'for' construct, and the last
one is for continuations like e.g. 'else'.

Be aware that a template file must be encoded either as ascii or UTF-8.
Distributed with gcinvoice is a sample template file 'invoice_template.tex'
used to generate an invoice in latex format.


ISSUES:
-------

* Because templates can contain arbitrary python expression, malicious
  templates could execute code with the permissions of the user.

* I think that the calculation on POSTAX discounts is wrong in Gnucash (see
  bug report http://bugzilla.gnome.org/show_bug.cgi?id=520547). gcinvoice
  calculates such discounts in invoices the way I think it is correctly, hence
  the result differs for invoices with such discounts from the Gnucash result.