Python Bindings

From GnuCash
Revision as of 18:10, 3 July 2023 by Simon (talk | contribs) (Python not supported on Windows)
Jump to: navigation, search

Python in gnucash has two main aspects:

Python bindings provide SWIG wrapper functions for some of gnucashs C/C++ API. 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 on the other hand (if enabled) 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. The python bindings can be used in this shell. Be careful: gnucash is not designed to have multiple instances manipulating the data at the same time, reading should be secure.

Note, that there is also a pure python client, piecash, to read and manipulate GnuCash books if saved in of the three SQL backends (sqlite, MySQL, Postgres). Currently (Oct 2020), piecash supports files created up to GnuCash 4.2.

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. Python bindings are not installed on Windows.

See also

Setting things up

Requirements
At Runtime
A Python package must be installed:
Gnucash 5.x
requires Python ≥ 3.6.
GnuCash 3.x
GnuCash's Python bindings has been known to work with CPython version 3.2 or later as of GnuCash 3.0.
At Buildtime
Python Bindings must have been enabled like 
cmake -DWITH_PYTHON=ON $OTHER_OPTIONS
If you are bulding GnuCash yourself see CMake#GnuCash Configuration Variables for the OTHER_OPTIONS.
Linux
If they were enabled depends on your distribution:
Enabled
In Archlinux they are installed with the gnucash package.
Split in a separate package
You need to install an additional package, usually named python3-gnucash. In Debian based distributions like Ubuntu the easiest way to install the GnuCash Python bindings is via apt-get: 
sudo apt-get install python3-gnucash
Flatpak#Known Issues

Interactive Shell

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:/opt/gnc/git/lib/python3.6/site-packages
Note
3.6 should now be 3.6.

This adds the gnucash python bindings to your PYTHONPATH assuming that your gnucash resides in /opt/gnc/git/. Notice that if even if you install to the default CMAKE_INSTALL_PREFIX of /usr/local, the Ubuntu/Debian python is compiled to search for packages in dist-packages and does not find them in site-packages.

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

  1. Install GnuCash via MacPorts: 
    sudo port install gnucash +python36
    Notes
    1. 36 should now be 36.
    2. at the time of writing, only the non-quartz environment is supported.
  2. Setup the PYTHONPATH to point to your macports install: 
    export PYTHONPATH=$PYTHONPATH:/opt/local/lib/python3.6/site-packages
    Note
    3.6 should now be 3.6.
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. Below you will find some sources where you might be able to find what you are looking for. Generally speaking, this is not yet end-user friendly stuff.

Principles

Python bindings provide SWIG wrapper functions for some of gnucashs C/C++ API. They can be used to write standalone scripts to work with the gnucash financial data.

What SWIG does

How to use the Python bindings

Further Docs

Doxygen

Have a look at the python-bindings (bugfix branch) or python-bindings (feature branch) in the doxygen API documentation.

Github

The source code of gnucash including the python bindings can be accessed on github.

Inside python

Using python or ipython there is some sparse help:

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)

Mailing list

Again, http://article.gmane.org/gmane.comp.gnome.apps.gnucash.devel/23613[1] contained some more hopefully useful pointers, but the page is no longer available.

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.
    Retrieved from "https://wiki.gnucash.org/wiki/index.php?title=Python_Bindings&oldid=21761"