Difference between revisions of "Python Bindings"

From GnuCash
Jump to: navigation, search
(Setting things up)
(Setting things up: 3.0 requires Python3.2+)
(13 intermediate revisions by 6 users not shown)
Line 1: Line 1:
Python bindings have been recently added to gnucash.  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 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
 
See also
Line 7: Line 7:
 
= Setting things up =
 
= Setting things up =
  
 +
'''N.B.''' GnuCash's Python bindings require python 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
 +
 +
 +
=== Other Linux distributions / GnuCash from source ===
 
I use ipython for an interactive shell.  If you prefer something else, let us know if there is any difference.
 
I use ipython for an interactive shell.  If you prefer something else, let us know if there is any difference.
  
  export PYTHONPATH=$PYTHONPATH:/export/gnucash/lib/python2.5/site-packages
+
  export PYTHONPATH=$PYTHONPATH:/export/gnucash/lib/python2.7/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.
+
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 ipython
  gnucash-env python $scriptyouwanttorun
+
  gnucash-env python /path/to/script
  
 
Note: to install ipython run
 
Note: to install ipython run
 +
  sudo pip ipython
  
   sudo easy_install ipython
+
== Mac OSX ==
 +
 
 +
Install GnuCash via [http://www.macports.org/ MacPorts]
 +
   sudo port install gnucash +python27
 +
 
 +
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/python2.7/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 =
 
= Documentation =
Line 24: Line 50:
 
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.
 
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 [http://svn.gnucash.org/docs/HEAD/python_bindings_page.html python-bindings] in [[doxygen]] source-documentation
+
* Have a look at the page [https://code.gnucash.org/docs/MASTER/python_bindings_page.html python-bindings] in [[doxygen]] source-documentation
* [http://svn.gnucash.org/trac/browser/gnucash/trunk/src/optional/python-bindings/example_scripts example scripts] from the source code and in [http://svn.gnucash.org/docs/HEAD/group__python__bindings__examples.html doxygen]
+
* [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
 
* inside ipython
 
** big long list of stuff
 
** big long list of stuff
 
*** import gnucash.gnucash_core_c
 
*** import gnucash.gnucash_core_c
*** help(gnucash_core_c)
+
*** help(gnucash.gnucash_core_c)
*** dir(gnucash_core_c)
+
*** dir(gnucash.gnucash_core_c)
 
** higher abstraction level help
 
** higher abstraction level help
 
*** import gnucash.gnucash_core
 
*** import gnucash.gnucash_core
Line 38: Line 65:
  
 
Again, http://article.gmane.org/gmane.comp.gnome.apps.gnucash.devel/23613 contains some more hopefully useful pointers.
 
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:
 +
 +
* 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)
 +
 +
'''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.

Revision as of 23:21, 7 August 2018

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

N.B. GnuCash's Python bindings require python 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


Other Linux distributions / GnuCash from source

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

export PYTHONPATH=$PYTHONPATH:/export/gnucash/lib/python2.7/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

Note: to install ipython run

 sudo pip ipython

Mac OSX

Install GnuCash via MacPorts

 sudo port install gnucash +python27

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/python2.7/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:

NB: 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.