Latest revision as of 11:05, 20 August 2024

Python in gnucash has two main aspects:

Python bindings
Python shell

Python bindings: provide SWIG wrapper functions for some of GnuCash' 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 safe though.

Other: Note there is also an independent project that offers a pure python client, piecash, to read and manipulate GnuCash books if saved in of the three SQL backends (sqlite, MySQL, Postgres). This is not endorsed by the GnuCash developers as it's not using the gnucash api to manipulate your data. Use with caution.; 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.

Setting things up

Python package

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.

GnuCash

On the other hand one needs a GnuCash package with python bindings enabled. Most linux distributions either build GnuCash with these bindings enabled by default or provide it via a separate package, usually named python3-gnucash or something similar. For example:

Enabled by default

The GnuCash packages in Archlinux and Fedora have been built with the python bindings enabled by default.

Split in a separate package

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

Building from source

It is also possible to use python bindings when building gnucash from source yourself. In this case you need to make sure the bindings are enabled while configuring the build, for example with

cmake -DWITH_PYTHON=ON $OTHER_OPTIONS

Notes: - If you are bulding GnuCash yourself see CMake#GnuCash Configuration Variables for the OTHER_OPTIONS.; - The flatpaks we create currently don't ship with python bindings enabled; - Similarly we don't ship python bindings with our Windows and MacOS packages. It may be possible to build Windows and MacOS packages yourself based on our Windows and MacOS build scripts (by enabling python bindings during the build), but I have not tested this.

Prepare the environment

If you are using a distribution package, you are probably all set and can skip this step. Similarly if you build gnucash and install it in the default system location (/usr/local), what follows is probably not necessary.

However if you are building from source (on any platform) but install into a non-default location, or don't install at all you will need to set up a few environment variables to help gnucash and python to find each other and their dependencies (like where gnucash can find its gsettings schema). Consult Directory Standards#XDG for defaults.

Build and install

These apply when you have built and installed gnucash from source.

In what follows you should set INST_DIR to the path where gnucash is installed during your build. This is often referred to as the installation prefix or something similar.

INST_DIR=xyz           # Point this to the actual directory gnucash was installed in !!
PYTHONPATH=$INST_DIR/lib64/python3.6/site-packages:$PYTHONPATH
XDG_DATA_DIRS=$INST_DIR/share:${XDG_DATA_DIRS}
export PYTHONPATH XDG_DATA_DIRS
# More path settings may be needed to interface with the guile bindings (if that's possible) or finance::quote
# You can check prefix/etc/gnucash/environment for the full list the gnucash sets up for itself

Note: 3.6 should match the python version used to build GnuCash.

User:Kohtala notes 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. So you may have to change the PYTHONPATH line above accordingly.

Build

It is also possible to use the python bindings from the gnucash build directory. During development that saves an extra install step for each code iteration. However this needs you to set up two more parameters in addition to those set up when gnucash is installed and we need to point at the build directory instead of the install directory.

In what follows you should set BUILD_DIR to the path where gnucash is built. This is the directory in which cmake and make/ninja are executed.

BUILD_DIR=xyz           # Point this to the actual directory gnucash was installed in !!
PYTHONPATH=$BUILD_DIR/lib64/python3.6/site-packages:$PYTHONPATH
XDG_DATA_DIRS=$BUILD_DIR/share:${XDG_DATA_DIRS}
GNC_UNINSTALLED=1
GNC_BUILDDIR=$BUILD_DIR
export PYTHONPATH XDG_DATA_DIRS GNC_UNINSTALLED GNC_BUILDDIR
# More path settings may be needed to interface with the guile bindings (if that's possible) or finance::quote
# You can check prefix/etc/gnucash/environment for the full list the gnucash sets up for itself

Note: 3.6 should match the python version used to build GnuCash.

Interactive Shell

I use IPython for an interactive shell. If you prefer something else, let us know if there is any difference.

If you have followed the setup steps above you can either start up an interactive python session with ipython

ipython

or call your script to be executed

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 +python36
```
Notes
1. 36 should now be 36.
2. 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/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

see API: python-bindings (stable branch)

How to use the Python bindings

see API: python-bindings (stable branch)

Further Docs

Doxygen

Have a look at the python-bindings (stable branch) or, if it exists python-bindings (future branch) in the doxygen API documentation.

Github

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

Example scripts from the source code.

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:

https://github.com/hjacobs/gnucash-qif-import --- imports transactions from QIF text files into GnuCash's own file format
https://github.com/hjacobs/gnucash-stock-portfolio --- script using the GnuCash commodity/price table
https://github.com/hjacobs/gnucash-fiximports --- tries to fix target accounts using regular expression rules (e.g. PIZZA -> Expenses:Dining)
Happy New Year --- A full Python program to generate a new GnuCash file at the beginning of a new accounting period.

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.

↑ ^1.0 ^1.1 ^1.2 Links to gmane are broken since several years. To avoid it, please link to our mailing list archives!

[1]

@@ Line 1: / Line 1: @@
+[[Category:Python]]
 Python in gnucash has two main aspects:
@@ Line 4: / Line 5: @@
 * [[Python shell]]
-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.
+;Python bindings: provide SWIG wrapper functions for some of GnuCash' C/C++ [[Using the API|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 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.
+;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 safe though.
+;Other:Note there is also an independent project that offers a pure python client, [https://piecash.readthedocs.io/ piecash], to read and manipulate GnuCash books if saved in of the three SQL backends (sqlite, MySQL, Postgres). This is not endorsed by the GnuCash developers as it's not using the gnucash api to manipulate your data. Use with caution.
+: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.
-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
-* http://article.gmane.org/gmane.comp.gnome.apps.gnucash.devel/23800 "Re: documentation for python bindings" and
+* <s>http://article.gmane.org/gmane.comp.gnome.apps.gnucash.devel/23800</s><ref name='broken_link'>Links to gmane are broken since several years. To avoid it, please link to [[Mailing Lists#Existing Lists|our mailing list archives]]!</ref> "Re: documentation for python bindings" and
-* http://article.gmane.org/gmane.comp.gnome.apps.gnucash.devel/23613 "Re: documentation for python bindings" with some pointers on how to look up the existing documentation
+* <s>http://article.gmane.org/gmane.comp.gnome.apps.gnucash.devel/23613</s><ref name='broken_link'/> "Re: documentation for python bindings" with some pointers on how to look up the existing documentation
+* Perhaps it was this thread: [{{URL:mail archive|devel}}2008-July/023431.html documentation for python bindings]
 = Setting things up =
-'''N.B.''' GnuCash's Python bindings is known to work with [https://en.wikipedia.org/wiki/CPython CPython] version {{Python_Version}} or later as of GnuCash 3.0.
+== Python package ==
+A Python package must be installed:
+;Gnucash {{MainVersion}}.x: requires Python ≥ {{Python_Version}}.
+;GnuCash 3.x: GnuCash's Python bindings has been known to work with [{{URL:wp}}CPython CPython] version 3.2 or later as of GnuCash 3.0.
+== GnuCash ==
+On the other hand one needs a GnuCash package with python bindings enabled. Most linux distributions either build GnuCash with these bindings enabled by default or provide it via a separate package, usually named <tt>python{{Python Major}}-gnucash</TT> or something similar. For example:
+;Enabled by default: The GnuCash packages in '''Archlinux''' and '''Fedora''' have been built with the python bindings enabled by default.
+;Split in a separate package: In '''Debian''' based distributions like '''Ubuntu''' the easiest way to install the GnuCash Python bindings is via apt-get: <syntaxhighlight lang="sh">
+sudo apt-get install python3-gnucash
+</syntaxhighlight>
-== Linux ==
+;Building from source: It is also possible to use python bindings when building gnucash from source yourself. In this case you need to make sure the bindings are enabled while configuring the build, for example with<syntaxhighlight lang="sh">
+cmake -DWITH_PYTHON=ON $OTHER_OPTIONS
+</syntaxhighlight>
-=== Ubuntu/Debian ===
+;Notes:
-The easiest way to install the GnuCash Python bindings is via apt-get:
+:- If you are bulding GnuCash yourself see [[CMake#GnuCash Configuration Variables]] for the OTHER_OPTIONS.
+:- The flatpaks we create currently don't ship with python bindings enabled
+:- Similarly we don't ship python bindings with our Windows and MacOS packages. It may be possible to build Windows and MacOS packages yourself based on our Windows and MacOS build scripts (by enabling python bindings during the build), but I have not tested this.
- sudo apt-get install python-gnucash
+== Prepare the environment ==
+If you are using a distribution package, you are probably all set and can skip this step. Similarly if you build gnucash and install it in the default system location (/usr/local), what follows is probably not necessary.
-=== Other Linux distributions / GnuCash from source ===
+However if you are building from source (on any platform) but install into a non-default location, or don't install at all you will need to set up a few environment variables to help gnucash and python to find each other and their dependencies (like where gnucash can find its gsettings schema). Consult [[Directory Standards#XDG]] for defaults.
-;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. <syntaxhighlight lang="sh">
+=== Build and install ===
-export PYTHONPATH=$PYTHONPATH:/export/gnucash/lib/python{{Python_Version}}/site-packages
+These apply when you have built and installed gnucash from source.
+In what follows you should set '''INST_DIR''' to the path where gnucash is installed during your build. This is often referred to as the installation prefix or something similar.
+<syntaxhighlight lang="sh">
+INST_DIR=xyz           # Point this to the actual directory gnucash was installed in !!
+PYTHONPATH=$INST_DIR/lib64/python3.6/site-packages:$PYTHONPATH
+XDG_DATA_DIRS=$INST_DIR/share:${XDG_DATA_DIRS}
+export PYTHONPATH XDG_DATA_DIRS
+# More path settings may be needed to interface with the guile bindings (if that's possible) or finance::quote
+# You can check prefix/etc/gnucash/environment for the full list the gnucash sets up for itself
 </syntaxhighlight>
-This adds the gnucash python bindings to your PYTHONPATH assuming that your gnucash resides in /export/gnucash.
+;Note: <q>3.6</q> should match the python version used to build GnuCash.
-You can then either start up an interactive python session with ipython or call your script to be executed: <syntaxhighlight lang="sh">
+[[User:Kohtala]] notes 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. So you may have to change the PYTHONPATH line above accordingly.
-gnucash-env ipython
-gnucash-env python /path/to/script
+=== Build ===
+It is also possible to use the python bindings from the gnucash build directory. During development that saves an extra install step for each code iteration. However this needs you to set up two more parameters in addition to those set up when gnucash is installed and we need to point at the build directory instead of the install directory.
+In what follows you should set '''BUILD_DIR''' to the path where gnucash is built. This is the directory in which cmake and make/ninja are executed.
+<syntaxhighlight lang="sh">
+BUILD_DIR=xyz           # Point this to the actual directory gnucash was installed in !!
+PYTHONPATH=$BUILD_DIR/lib64/python3.6/site-packages:$PYTHONPATH
+XDG_DATA_DIRS=$BUILD_DIR/share:${XDG_DATA_DIRS}
+GNC_UNINSTALLED=1
+GNC_BUILDDIR=$BUILD_DIR
+export PYTHONPATH XDG_DATA_DIRS GNC_UNINSTALLED GNC_BUILDDIR
+# More path settings may be needed to interface with the guile bindings (if that's possible) or finance::quote
+# You can check prefix/etc/gnucash/environment for the full list the gnucash sets up for itself
+</syntaxhighlight>
+;Note: <q>3.6</q> should match the python version used to build GnuCash.
+==Interactive Shell==
+I use [{{URL:wp}}IPython IPython] for an interactive shell.  If you prefer something else, let us know if there is any difference.
+If you have followed the setup steps above you can either start up an interactive python session with ipython <syntaxhighlight lang="sh">
+ipython
+</syntaxhighlight> or call your script to be executed <syntaxhighlight lang="sh">
+python /path/to/script
 </syntaxhighlight>
 ;Notes
@@ Line 47: / Line 103: @@
 == Mac OSX ==
-Install GnuCash via [http://www.macports.org/ MacPorts]
+# Install GnuCash via [https://www.macports.org/ MacPorts]: <syntaxhighlight lang="sh">
-  sudo port install gnucash +python{{Python_Version_short}}
+sudo port install gnucash +python36
+</syntaxhighlight>
+#;Notes:
+#:# <q>36</q> should now be <q>{{Python_Version_short}}</q>.
+#:# at the time of writing, only the non-quartz environment is supported.
+# Setup the PYTHONPATH to point to your macports install: <syntaxhighlight lang="sh">
+export PYTHONPATH=$PYTHONPATH:/opt/local/lib/python3.6/site-packages
+</syntaxhighlight>
+#;Note: <q>3.6</q> should now be <q>{{Python_Version}}</q>.
+You can then either start up an interactive python session with ipython or call your script to be executed: <syntaxhighlight lang="sh">
+ipython
+python /path/to/script
+</syntaxhighlight>
+= 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++ [[Using the API|API]]. They can be used to write standalone scripts to work with the gnucash financial data.
-Note: at the time of writing, only the non-quartz environment is supported.
+=== What SWIG does ===
+* see [{{URL:docs:API}}python_bindings_page.html API: python-bindings (stable branch)]
-Setup the PYTHONPATH to point to your macports install
+=== How to use the Python bindings ===
-  export PYTHONPATH=$PYTHONPATH:/opt/local/lib/python{{Python_Version}}/site-packages
+* see [{{URL:docs:API}}python_bindings_page.html API: python-bindings (stable branch)]
-You can then either start up an interactive python session with ipython or call your script to be executed.
+= Further Docs =
-  ipython
-  python /path/to/script
-= Documentation =
+== Doxygen ==
+Have a look at the [{{URL:docs:API}}python_bindings_page.html python-bindings (stable branch)] or, if it exists [{{URL:docs:API|FUTURE}}python_bindings_page.html python-bindings (future branch)] in the [[Doxygen|doxygen]] '''API documentation'''.
+* [{{URL:docs:API}}group__Business.html business functions documentation]
+* [{{URL:docs:API}}group__python__bindings__examples.html Example scripts]
+== Github ==
+The source code of gnucash including the python bindings can be accessed on [{{GitURL}} github].
+* [{{URL:git}}gnucash/tree/stable/bindings/python/example_scripts Example scripts] from the source code.
+== Inside python ==
+Using python or ipython there is some sparse help:
+big long list of stuff <syntaxhighlight lang="py">
+import gnucash.gnucash_core_c
+help(gnucash.gnucash_core_c)
+dir(gnucash.gnucash_core_c)
+</syntaxhighlight>
-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.
+higher abstraction level help <syntaxhighlight lang="py">
+import gnucash.gnucash_core
+import gnucash.gnucash_business
+help(gnucash.gnucash_core)
+help(gnucash.gnucash_business)
+</syntaxhighlight>
-* Have a look at the page [https://code.gnucash.org/docs/MASTER/python_bindings_page.html python-bindings] in [[doxygen]] source-documentation
+== Mailing list ==
-* [https://github.com/Gnucash/gnucash/tree/master/bindings/python/example_scripts scripts] from the source code.
-* [http://code.gnucash.org/docs/MASTER/group__Business.html 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.
+Again, <s>http://article.gmane.org/gmane.comp.gnome.apps.gnucash.devel/23613</s><ref name='broken_link'/> 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:
-* https://github.com/hjacobs/gnucash-qif-import --- imports transactions from QIF text files into GnuCash's own file format
+* {{URL:GH}}hjacobs/gnucash-qif-import --- imports transactions from QIF text files into GnuCash's own file format
-* https://github.com/hjacobs/gnucash-stock-portfolio --- script using the GnuCash commodity/price table
+* {{URL:GH}}hjacobs/gnucash-stock-portfolio --- script using the GnuCash commodity/price table
-* https://github.com/hjacobs/gnucash-fiximports --- tries to fix target accounts using regular expression rules (e.g. PIZZA -> Expenses:Dining)
+* {{URL:GH}}hjacobs/gnucash-fiximports --- tries to fix target accounts using regular expression rules (e.g. PIZZA -> Expenses:Dining)
+* [{{URL:GL}}wiese28/gnucash-happy-new-year/ Happy New Year] --- A full Python program to generate a new GnuCash file at the beginning of a new accounting period.
-'''NB:''' GnuCash uses DeprecationWarnings, which are disabled by default in Python. Be sure to test periodically with <tt>python -Wd</tt> or with <tt>PYTHONWARNINGS=default</tt> 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.
+;Important: GnuCash uses '''DeprecationWarnings,''' which are disabled by default in Python. Be sure to test periodically with <tt>python -Wd</tt> or with <tt>PYTHONWARNINGS=default</tt> 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.

Difference between revisions of "Python Bindings"

Latest revision as of 11:05, 20 August 2024

Contents

General notice

Setting things up

Python package

GnuCash

Prepare the environment

Build and install

Build

Interactive Shell

Mac OSX

Documentation

Principles

What SWIG does

How to use the Python bindings

Further Docs

Doxygen

Github

Inside python

Mailing list

Example Usages

Navigation menu

Personal tools

Namespaces

Variants

Views

More

Search

Navigation

Related Sites

Contributing

Tools