/invoices

Quickly creating invoices with the power of LaTeX and Python

Primary LanguagePythonGNU General Public License v3.0GPL-3.0

Creating Invoices

To generate invoices, you need multiple local configurations. Your own information is declared in self.yaml, client information can be declared in files clients/<cname>.yaml, where cname is the client selector. Specific information for this invoice can be configured in details.yaml.

Setup

First, you need to install poetry. If you have nix it is as simple as nix-env -iA nixpkgs.poetry. After that, create a virtual environment and install all dependencies.

$ virtualenv -p python3 .venv
$ source .venv/bin/activate
$ poetry install                # install dependencies

Usage

When you have created all config files, creating an invoice is as simple as:

$ python main.py

There are a few more options available though:

usage: main.py [-h] [--clean] [--clients CLIENTS] [--date DATE] [--directory DIRECTORY]
               [--locale LOCALE] [--user USER] [--validate] [-v] [-y] [--nocolor]
               [DETAILS]

script to help create invoices based on information from config files. By default, ask for
confirmation on details before creating an invoice. This behavior can be deactivated with
`-y|--yes`.

positional arguments:
  DETAILS               file with details and content specific to this invoice (default:
                        details.yml)

optional arguments:
  -h, --help            show this help message and exit
  --clean               ignore previous temporary files in build environment. (default:
                        False)
  --clients CLIENTS     relative path (folder) in which information about your clients is
                        stored in `<cname>.yml` files. (default: clients/)
  --date DATE           datetime formatting string the invoice should be dated at. Can be a
                        specific day like '2021-09-01'. Defaults to today. (default:
                        %Y-%m-%d)
  --directory DIRECTORY
                        directory to expect USER, CLIENTS and DETAILS files in. (default: ./)
  --locale LOCALE       what language the invoice should be in. Ignored if set in
                        `details.yml` (default: de)
  --user USER           your contact details and bank information. (default: self.yml)
  --validate            only validate available information and check available
                        functionality, do not actually create invoice (default: False)
  -v, --verbose         make logging output (more) verbose. Default (or 0) is ERROR, -v is
                        WARN, -vv is INFO and -vvv is DEBUG. Can be passed multiple times.
                        (default: 0)
  -y, --yes             do not ask for confirmation before creating the actual invoice
                        (default: False)
  --nocolor             deactivate colored log output (default: False)

Config Files

Your own information: self.yaml

Have a file called self.yaml with your own information structured like this:

Field descriptions

Field Type description
name string Your full name or company name.
address string Your Address. Both street and number.
zip int Your area ZIP code.
city string The city you live in.
country string Optional. The country you live in.
IBAN string The IBAN of your bank account.
BIC string The BIC of your bank account.
bank string The name of your bank.
stid string Optional. Your tax number.
ustid string Optional. Your sales tax identification number. Will not show stid if available.
phone string Optional. Your phone number.
email string Optional. Your email address.
url string Optional. Link to your webpage.

Example

name: <name>
address: <address>
zip: <zip>
city: <name of city>
IBAN: <IBAN>
BIC: <BIC>
bank: <name of bank>

Clients: clients/<cname>.yaml

For every clients cname, have a clients/<cname>.yaml file structured like this:

Field descriptions

Field Type description
name string Your clients name or company name.
address string Your clients business address. Both street and number.
zip int ZIP code of your clients address.
city string City correlating to the zip code.
country string Optional. Country of your clients business address.

Example

name: <name>
address: <address>
zip: <zip>
city: <city>
country: <country>

Config: details.yaml

Specific information is in a file called details.yaml:

Field descriptions

Field Type description
title string Title of the invoice.
timeframe string Timeframe during which you accumulated the given number of hours.
client string File-Selector (cname, before the .yaml from your clients folder) of your client for this project.
invoice_id int Unique ID of this invoice. You need to ensure that this id is unique.
items list Optional. Entries must include description, amount and item_price_cents, can include unit.
description string Optional. Description of the work you did.
hours_worked/amount int/float Optional. Number of hours worked for the job. Can be point number with up to two decimal places.
unit string Optional. Only available in item-lists. Unit of the item, e.g. 'hours'/'h' or 'pieces'/'pcs'.
hourly_rate_cents/item_price_cents int Optional. The hourly rate you bill for in this invoice, in cents per hour.
mwst_percent int Optional. If the (global) calculation should include MwSt, and the percentage.
locale string Optional. de or en. Overrides --locale. Default: de

Example

title: <invoice title>
timeframe: <timeframe in which you worked>
client: <rname>
invoice_id: <int>
description: <work description>
hours_worked: <hours worked>
hourly_rate_cents: <int>
mwst_percent: 19
title: <invoice title>
timeframe: <timeframe in which you worked>
client: <rname>
invoice_id: <int>
items:
  - description: <work description 1>
    amount: <int/float>
    unit: h
    item_price_cents: <int>
  - description: <piece description 2>
    amount: <int/float>
    unit: pcs
    item_price_cents: <int>
mwst_percent: 19

Both styles can be combined, and the lower-level item is then placed first. It is not possible to specify individual mwst-rates, but individual unit types can be specified.