Metadata-Version: 2.4
Name: g2b
Version: 0.2.1
Summary: Initialize a beancount ledger from a GnuCash file
License: MIT License
        
        Copyright (c) 2024 dtrai2
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/dtrai2/gnucash-csv-to-beancount
Project-URL: Documentation, https://github.com/dtrai2/gnucash-csv-to-beancount/blob/main/README.md
Project-URL: Repository, https://github.com/dtrai2/gnucash-csv-to-beancount
Project-URL: Issues, https://github.com/dtrai2/gnucash-csv-to-beancount/issues
Keywords: gnucash,beancount,finance,accounting
Classifier: Development Status :: 3 - Alpha
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Office/Business :: Financial :: Accounting
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: beancount
Requires-Dist: click
Requires-Dist: rich
Requires-Dist: pyyaml
Requires-Dist: piecash
Provides-Extra: dev
Requires-Dist: black; extra == "dev"
Requires-Dist: pylint; extra == "dev"
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: coverage; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Requires-Dist: pre-commit; extra == "dev"
Dynamic: license-file

# Gnucash to Beancount

This project can convert a [Gnucash](https://github.com/Gnucash/gnucash) sql file into a new
[beancount](https://github.com/beancount/beancount) file.
It is not intended to continuously import gnucash data into an existing beancount ledger, as this
script will also add plugins and beancount options to the beginning of the file.
This project started with the intention to convert a gnucash csv export, but it turned out that the
csv exported from gnucash is not quite reliable.
Read more about that at in the section [Unreliable Export](#unreliable-gnucash-csv-export).
Because of that I refactored it to use the [piecash](https://pypi.org/project/piecash/) library.
With that it has the same goal as the already existing repository from
[henriquebastos/gnucash-to-beancount](https://github.com/henriquebastos/gnucash-to-beancount).
The implementation in this repository does offer few configuration options though.

One downside I have encountered sofar are stock splits.
Those are currently not supported and have to be added manually to the output by following the
official documentation
[Beancount Stock Splits](https://beancount.github.io/docs/trading_with_beancount.html#stock-splits).
Luckily those splits don't happen too often.

## Prerequisite

Your gnucash file must be in a sql format.
I implemented it with a sqlite3 file, which was saved by GnuCash v5.4.
If your current genucash file is not in the right format it is always possible to just save it
as a sqlite3 file.

## Install

To install `gnucash to beancount` simply use `pip`:

```bash
pip install g2b
```

Test with `g2b --version` if the installation was successful.

## Usage

### Create Configuration for g2b

In order for a successful conversion you need to create a `yaml` configuration file.
An example would look like this:

```yaml
converter:
  loglevel: INFO
gnucash:  # here you can specify details about your gnucash export
  default_currency: EUR
  thousands_symbol: "."
  decimal_symbol: ","
  reconciled_symbol: "b"
  not_reconciled_symbol: "n"
  account_rename_patterns:  # Here you can rename accounts that might not align with the beancount format
    - ["OpenBalance", "Equity:Opening-Balance"]
    - ["Money@[Bank]", "Assets:Money at Bank"]
  non_default_account_currencies:  # Here you have to name all accounts that deviate from the default currency
    Assets:Cash:Wallet: "NZD"
beancount:  # here you can add beancount options, plugins and events that should be added to output file
  flag_postings: false  # if false, will set all transactions automatically to '*' (default: true)
  options:
    - ["title", "Exported GnuCash Book"]  # options should be key value pairs
    - ["operating_currency", "EUR"]
  plugins:
    - "beancount.plugins.check_commodity"  # plugins can be named directly
    - "beancount.plugins.coherent_cost"
    - "beancount.plugins.nounused"
    - "beancount.plugins.auto"
  events:
    2024-05-05: type description string  # optional events that should be added to the output, the
                                         # first space is used to split between space and description
fava:  # optional configuration specific to fava
  commodity-precision: 3  # set the render precision of values for the fava web-frontend
```

## Execute g2b

Once you created the needed configuration file you can call:

```bash
g2b -i book.gnucash -c config.yaml -o my.beancount
```

The script will, at the end, automatically call beancount to parse and verify the export, such
that you know if the conversion was successful or not.

## Limitations

Currently, this project can not deal with stock splits.
Those will not be added to the beancount output and have to be added manually.
To do that follow the official
[Documentation](https://beancount.github.io/docs/trading_with_beancount.html#stock-splits).

## Unreliable Gnucash CSV Export

While starting out with CSV exports I found the following issues that kept me from
progressing with the CSV exports.

- The gnucash csv export does not offer reliable currency information.
  Transaction with values like `100 $` cannot be properly understood as it, for example, could be
  USD or NZD.
  An offical bug report is open since 2017:
  [gnucash bug - use ISO 4217 currency symbols in output](https://bugs.gnucash.org/show_bug.cgi?id=791651).
- The `Rate/Price` value is sometimes added to the wrong posting in transactions with multiple
  currencies.
  Because of that it wasn't easily recognizable how to convert which prices.
- And probably the most severe issue: Some transactions were completely missing inside the export.
  As I couldn't figure out why I decided to use the `piecash` library.
