Python Bindings

From GnuCash
Revision as of 14:16, 13 September 2020 by Fell (talk | contribs) (Setting things up: More use of templates)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

Python in gnucash has two main aspects:

Python bindings provide SWIG wrapper functions for some of gnucashs C/C++ parts. They can be used to write standalone scripts to work with the gnucash financial data. In the source tree they are located at bindings/python.

The python shell opens at gnucash startup and provides a python environment to use with the running gnucash instance. In the source tree it is located at gnucash/python. You use the python bindings in this shell. Be careful: gnucash is not designed to have multiple instances changing the data at the same time, reading should be secure.

Note, that there also is a pure python client to read and manipulate sqlite databases created by GnuCash: piecash. Currently (Aug 2020), piecash only supports files created by GnuCash 3.0.X.

General notice

Python bindings have been added to gnucash in 2008 or earlier. There is still very little documentation and probably few people would know how to use it. While not a manual, this page was created in the hope to provide information for those interested in gnucash and python.

See also

Setting things up

Requirements
Gnucash 4.x requires Python 3.6.
GnuCash's Python bindings has been known to work with CPython version 3.2 or later as of GnuCash 3.0.

Linux

Ubuntu/Debian

The easiest way to install the GnuCash Python bindings is via apt-get:
sudo apt-get install python-gnucash

Archlinux

The python bindings are install with the gnucash package.

Other Linux distributions / GnuCash from source

Fix me
Is it still possible since we require Python3?
I use https://en.wikipedia.org/wiki/IPython IPython for an interactive shell. If you prefer something else, let us know if there is any difference.
export PYTHONPATH=$PYTHONPATH:/export/gnucash/lib/python{{Python_Version}}/site-packages

This adds the gnucash python bindings to your PYTHONPATH assuming that your gnucash resides in /export/gnucash.

You can then either start up an interactive python session with ipython or call your script to be executed:
gnucash-env ipython
gnucash-env python /path/to/script
Notes
To install ipython run
sudo pip ipython
pip is the package installer for Python.

Mac OSX

Install GnuCash via MacPorts:
sudo port install gnucash +python{{Python_Version_short}}

Note: at the time of writing, only the non-quartz environment is supported.

Setup the PYTHONPATH to point to your macports install:
export PYTHONPATH=$PYTHONPATH:/opt/local/lib/python{{Python_Version}}/site-packages
You can then either start up an interactive python session with ipython or call your script to be executed:
ipython
python /path/to/script

Documentation

As pointed out in the introductory paragraph, the documentation is rather slim at this point in time. Here are some sources where you might be able to find what you are looking for. Generally speaking, this is not yet end-user friendly stuff.

  • Have a look at the page python-bindings in doxygen source-documentation
  • scripts from the source code.
  • business functions documentation
  • inside ipython
    • big long list of stuff
      • import gnucash.gnucash_core_c
      • help(gnucash.gnucash_core_c)
      • dir(gnucash.gnucash_core_c)
    • higher abstraction level help
      • import gnucash.gnucash_core
      • import gnucash.gnucash_business
      • help(gnucash.gnucash_core)
      • help(gnucash.gnucash_business)

Again, http://article.gmane.org/gmane.comp.gnome.apps.gnucash.devel/23613 contains some more hopefully useful pointers.

Example Usages

This section should contain some pointers to scripts using the GnuCash Python bindings:

Important
GnuCash uses DeprecationWarnings, which are disabled by default in Python. Be sure to test periodically with python -Wd or with PYTHONWARNINGS=default set in the environment so that you know about API that will disappear in the next major release. See Development_Process#LibGnuCash API Stability for the policy.