<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter SYSTEM "gnc-gui-C.dtd">
<!-- (Do not remove this comment block.)
Version: 2.4.0
Last modified: 2011-01-01
Maintainers:
Author:
Mike Evans <mikee@saxicola.co.uk>
Translators:
(translators put your name and email here)
-->
<!-- Todo: Database backends offer read access;
           Guile is also a sripting language perhaps its stand alone use should be explained here, too? -->
<!-- Todo: after adding a procedure convert this page into a https://tdg.docbook.org/tdg/4.5/task.html -->
<chapter id="ch_python_bindings">
  <title>Python Bindings</title>

  <para>&app; historically has always been a traditional application in the sense that you open it, use it
    to manipulate your financial data via the windows it presents, save your data and close the
    windows again. This has the inherent limitation that you can only do whatever the windows, menus
    and toolbars allow you to do.
  </para>

  <para>Sometimes you might need a little more flexibility. For example, you need a report with just a
    little different information than what the built-in reports provide, or you want to automate a
    frequently recurring action. Such custom manipulations are ideal candidates to write in one or
    the other scripting language.
  </para>

  <para>Starting with &app; version 2.4 you can write
    <ulink url="&url-wp-en;Python_(programming_language)">&app-py;</ulink> scripts to manipulate
    your financial data.
  </para>

  <important>
    <para>The &app-py; extensions are an optional feature which creates additional dependencies. To be able to
      use &app-py; scripts, &app; must have been built with the <code language="sh">cmake
      -DWITH_PYTHON=ON …</code> option enabled, otherwise all what follows won&rsquo;t work. At
      present this option is not enabled by default, so if you need this, you may have to compile
      &app; from source yourself. But some distributions offer it also as a separate package with a
      name like
      <package>
        python[<replaceable>version</replaceable>]-&appname;
      </package>
    </para>
  </important>

  <para>The &app-py; extensions come with a couple of ready to use scripts. This chapter will show you how
    to <emphasis>use</emphasis> some of them.
  </para>

  <tip>
    <para>This chapter is not about how to write your own &app-py; scripts. Refer to the
      <ulink url="&url-doc-api-stable;python_bindings_page.html">developer documentation</ulink> for
      that instead.
    </para>
  </tip>
</chapter>
