% Generated by Sphinx.
\def\sphinxdocclass{report}
\documentclass[letterpaper,10pt,english]{sphinxmanual}
\usepackage[utf8]{inputenc}
\DeclareUnicodeCharacter{00A0}{\nobreakspace}
\usepackage{cmap}
\usepackage[T1]{fontenc}
\usepackage{babel}
\usepackage{times}
\usepackage[Bjarne]{fncychap}
\usepackage{longtable}
\usepackage{sphinx}
\usepackage{multirow}


\title{Python interface to GnuCash documents Documentation}
\date{December 23, 2014}
\release{0.3.0}
\author{sdementen}
\newcommand{\sphinxlogo}{}
\renewcommand{\releasename}{Release}
\makeindex

\makeatletter
\def\PYG@reset{\let\PYG@it=\relax \let\PYG@bf=\relax%
    \let\PYG@ul=\relax \let\PYG@tc=\relax%
    \let\PYG@bc=\relax \let\PYG@ff=\relax}
\def\PYG@tok#1{\csname PYG@tok@#1\endcsname}
\def\PYG@toks#1+{\ifx\relax#1\empty\else%
    \PYG@tok{#1}\expandafter\PYG@toks\fi}
\def\PYG@do#1{\PYG@bc{\PYG@tc{\PYG@ul{%
    \PYG@it{\PYG@bf{\PYG@ff{#1}}}}}}}
\def\PYG#1#2{\PYG@reset\PYG@toks#1+\relax+\PYG@do{#2}}

\expandafter\def\csname PYG@tok@nf\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.02,0.16,0.49}{##1}}}
\expandafter\def\csname PYG@tok@nv\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.73,0.38,0.84}{##1}}}
\expandafter\def\csname PYG@tok@s1\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.25,0.44,0.63}{##1}}}
\expandafter\def\csname PYG@tok@m\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.13,0.50,0.31}{##1}}}
\expandafter\def\csname PYG@tok@err\endcsname{\def\PYG@bc##1{\setlength{\fboxsep}{0pt}\fcolorbox[rgb]{1.00,0.00,0.00}{1,1,1}{\strut ##1}}}
\expandafter\def\csname PYG@tok@sb\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.25,0.44,0.63}{##1}}}
\expandafter\def\csname PYG@tok@kr\endcsname{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.00,0.44,0.13}{##1}}}
\expandafter\def\csname PYG@tok@gh\endcsname{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.00,0.00,0.50}{##1}}}
\expandafter\def\csname PYG@tok@cm\endcsname{\let\PYG@it=\textit\def\PYG@tc##1{\textcolor[rgb]{0.25,0.50,0.56}{##1}}}
\expandafter\def\csname PYG@tok@mi\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.13,0.50,0.31}{##1}}}
\expandafter\def\csname PYG@tok@gi\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.00,0.63,0.00}{##1}}}
\expandafter\def\csname PYG@tok@kp\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.00,0.44,0.13}{##1}}}
\expandafter\def\csname PYG@tok@kt\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.56,0.13,0.00}{##1}}}
\expandafter\def\csname PYG@tok@sd\endcsname{\let\PYG@it=\textit\def\PYG@tc##1{\textcolor[rgb]{0.25,0.44,0.63}{##1}}}
\expandafter\def\csname PYG@tok@gd\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.63,0.00,0.00}{##1}}}
\expandafter\def\csname PYG@tok@c1\endcsname{\let\PYG@it=\textit\def\PYG@tc##1{\textcolor[rgb]{0.25,0.50,0.56}{##1}}}
\expandafter\def\csname PYG@tok@s\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.25,0.44,0.63}{##1}}}
\expandafter\def\csname PYG@tok@sx\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.78,0.36,0.04}{##1}}}
\expandafter\def\csname PYG@tok@se\endcsname{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.25,0.44,0.63}{##1}}}
\expandafter\def\csname PYG@tok@sr\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.14,0.33,0.53}{##1}}}
\expandafter\def\csname PYG@tok@si\endcsname{\let\PYG@it=\textit\def\PYG@tc##1{\textcolor[rgb]{0.44,0.63,0.82}{##1}}}
\expandafter\def\csname PYG@tok@ne\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.00,0.44,0.13}{##1}}}
\expandafter\def\csname PYG@tok@mh\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.13,0.50,0.31}{##1}}}
\expandafter\def\csname PYG@tok@sc\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.25,0.44,0.63}{##1}}}
\expandafter\def\csname PYG@tok@go\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.20,0.20,0.20}{##1}}}
\expandafter\def\csname PYG@tok@kc\endcsname{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.00,0.44,0.13}{##1}}}
\expandafter\def\csname PYG@tok@kd\endcsname{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.00,0.44,0.13}{##1}}}
\expandafter\def\csname PYG@tok@ow\endcsname{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.00,0.44,0.13}{##1}}}
\expandafter\def\csname PYG@tok@na\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.25,0.44,0.63}{##1}}}
\expandafter\def\csname PYG@tok@w\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.73,0.73,0.73}{##1}}}
\expandafter\def\csname PYG@tok@c\endcsname{\let\PYG@it=\textit\def\PYG@tc##1{\textcolor[rgb]{0.25,0.50,0.56}{##1}}}
\expandafter\def\csname PYG@tok@nb\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.00,0.44,0.13}{##1}}}
\expandafter\def\csname PYG@tok@o\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.40,0.40,0.40}{##1}}}
\expandafter\def\csname PYG@tok@gu\endcsname{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.50,0.00,0.50}{##1}}}
\expandafter\def\csname PYG@tok@cp\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.00,0.44,0.13}{##1}}}
\expandafter\def\csname PYG@tok@vc\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.73,0.38,0.84}{##1}}}
\expandafter\def\csname PYG@tok@il\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.13,0.50,0.31}{##1}}}
\expandafter\def\csname PYG@tok@bp\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.00,0.44,0.13}{##1}}}
\expandafter\def\csname PYG@tok@gr\endcsname{\def\PYG@tc##1{\textcolor[rgb]{1.00,0.00,0.00}{##1}}}
\expandafter\def\csname PYG@tok@no\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.38,0.68,0.84}{##1}}}
\expandafter\def\csname PYG@tok@gs\endcsname{\let\PYG@bf=\textbf}
\expandafter\def\csname PYG@tok@sh\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.25,0.44,0.63}{##1}}}
\expandafter\def\csname PYG@tok@vg\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.73,0.38,0.84}{##1}}}
\expandafter\def\csname PYG@tok@gp\endcsname{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.78,0.36,0.04}{##1}}}
\expandafter\def\csname PYG@tok@k\endcsname{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.00,0.44,0.13}{##1}}}
\expandafter\def\csname PYG@tok@ge\endcsname{\let\PYG@it=\textit}
\expandafter\def\csname PYG@tok@vi\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.73,0.38,0.84}{##1}}}
\expandafter\def\csname PYG@tok@cs\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.25,0.50,0.56}{##1}}\def\PYG@bc##1{\setlength{\fboxsep}{0pt}\colorbox[rgb]{1.00,0.94,0.94}{\strut ##1}}}
\expandafter\def\csname PYG@tok@nl\endcsname{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.00,0.13,0.44}{##1}}}
\expandafter\def\csname PYG@tok@nt\endcsname{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.02,0.16,0.45}{##1}}}
\expandafter\def\csname PYG@tok@gt\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.00,0.27,0.87}{##1}}}
\expandafter\def\csname PYG@tok@mf\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.13,0.50,0.31}{##1}}}
\expandafter\def\csname PYG@tok@nn\endcsname{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.05,0.52,0.71}{##1}}}
\expandafter\def\csname PYG@tok@kn\endcsname{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.00,0.44,0.13}{##1}}}
\expandafter\def\csname PYG@tok@ni\endcsname{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.84,0.33,0.22}{##1}}}
\expandafter\def\csname PYG@tok@ss\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.32,0.47,0.09}{##1}}}
\expandafter\def\csname PYG@tok@nd\endcsname{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.33,0.33,0.33}{##1}}}
\expandafter\def\csname PYG@tok@mo\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.13,0.50,0.31}{##1}}}
\expandafter\def\csname PYG@tok@nc\endcsname{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.05,0.52,0.71}{##1}}}
\expandafter\def\csname PYG@tok@s2\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.25,0.44,0.63}{##1}}}

\def\PYGZbs{\char`\\}
\def\PYGZus{\char`\_}
\def\PYGZob{\char`\{}
\def\PYGZcb{\char`\}}
\def\PYGZca{\char`\^}
\def\PYGZam{\char`\&}
\def\PYGZlt{\char`\<}
\def\PYGZgt{\char`\>}
\def\PYGZsh{\char`\#}
\def\PYGZpc{\char`\%}
\def\PYGZdl{\char`\$}
\def\PYGZhy{\char`\-}
\def\PYGZsq{\char`\'}
\def\PYGZdq{\char`\"}
\def\PYGZti{\char`\~}
% for compatibility with earlier versions
\def\PYGZat{@}
\def\PYGZlb{[}
\def\PYGZrb{]}
\makeatother

\begin{document}

\maketitle
\tableofcontents
\phantomsection\label{index::doc}

\begin{quote}\begin{description}
\item[{Release}] \leavevmode
0.3.0

\item[{Date}] \leavevmode
December 23, 2014

\item[{Authors}] \leavevmode
sdementen

\end{description}\end{quote}


\chapter{What's new}
\label{news::doc}\label{news:welcome-to-the-piecash-documentation}\label{news:what-s-new}

\section{Devel}
\label{news:devel}\begin{itemize}
\item {} 
refactor classes

\item {} 
add helper functions:
\begin{itemize}
\item {} 
{\hyperref[api/piecash.model_core.commodity:piecash.model_core.commodity.Commodity.create_currency_from_ISO]{\code{Commodity.create\_currency\_from\_ISO()}}}

\item {} 
{\hyperref[api/piecash.model_core.commodity:piecash.model_core.commodity.Commodity.create_stock_from_symbol]{\code{Commodity.create\_stock\_from\_symbol()}}}

\end{itemize}

\end{itemize}

Contents:


\chapter{Documentation}
\label{doc/doc:documentation}\label{doc/doc::doc}
This project provides a simple and pythonic interface to GnuCash files stored in SQL (sqlite3 and Postgres, not tested in MySQL).

It is a pure python package, tested on python 2.7 and 3.4, that can be used as an alternative to:
\begin{itemize}
\item {} 
the official python bindings (as long as no advanced book modifications and/or engine calculations are needed).
This is specially useful on Windows where the official python bindings may be tricky to install or if you want to work with
python 3.

\item {} 
XML parsing/reading of XML GnuCash files if you prefer python over XML/XLST manipulations.

\end{itemize}

piecash is built on the excellent SQLAlchemy library and does not require the installation of GnuCash itself.

piecash allows you to:
\begin{itemize}
\item {} 
create a GnuCash document from scratch or edit an existing one

\item {} 
create new accounts, transactions, etc or change (within some limits) existing objects.

\item {} 
read/browse all objects through an intuitive interface

\end{itemize}

A simple example of a piecash script:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{k}{with} \PYG{n}{open\PYGZus{}book}\PYG{p}{(}\PYG{l+s}{\PYGZdq{}}\PYG{l+s}{example.gnucash}\PYG{l+s}{\PYGZdq{}}\PYG{p}{)} \PYG{k}{as} \PYG{n}{s}\PYG{p}{:}
    \PYG{c}{\PYGZsh{} get default currency of book}
    \PYG{k}{print}\PYG{p}{(} \PYG{n}{s}\PYG{o}{.}\PYG{n}{book}\PYG{o}{.}\PYG{n}{root\PYGZus{}account}\PYG{o}{.}\PYG{n}{commodity} \PYG{p}{)}  \PYG{c}{\PYGZsh{} ==\PYGZgt{} Commodity\PYGZlt{}CURRENCY:EUR\PYGZgt{}}

    \PYG{c}{\PYGZsh{} iterating over all splits in all books and print the transaction description:}
    \PYG{k}{for} \PYG{n}{acc} \PYG{o+ow}{in} \PYG{n}{s}\PYG{o}{.}\PYG{n}{accounts}\PYG{p}{:}
        \PYG{k}{for} \PYG{n}{sp} \PYG{o+ow}{in} \PYG{n}{acc}\PYG{o}{.}\PYG{n}{splits}\PYG{p}{:}
            \PYG{k}{print}\PYG{p}{(}\PYG{n}{sp}\PYG{o}{.}\PYG{n}{transaction}\PYG{o}{.}\PYG{n}{description}\PYG{p}{)}
\end{Verbatim}

As piecash is essentially a SQLAlchemy layer, it could be reused by any web framework that has a SQLAlchemy interface to develop
REST API or classical websites. It can also be used for reporting purposes.

The project has reached beta stage. Knowledge of SQLAlchemy is at this stage not anymore required to use it and/or
to contribute to it. Some documentation for developers on the object model of GnuCash as understood by the author is
available {\hyperref[object_model::doc]{\emph{here}}}.

\begin{notice}{warning}{Warning:}\begin{enumerate}
\item {} 
Always do a backup of your gnucash file/DB before using piecash.

\item {} 
Test first your script by opening your file in readonly mode (which is the default mode)

\end{enumerate}
\end{notice}


\section{Installation}
\label{doc/doc:installation}
With pip:

\begin{Verbatim}[commandchars=\\\{\}]
\$ pip install piecash
\end{Verbatim}

or easy\_install:

\begin{Verbatim}[commandchars=\\\{\}]
\$ easy\_install piecash
\end{Verbatim}

Otherwise, you can install from the distribution using the setup.py script:

\begin{Verbatim}[commandchars=\\\{\}]
\$ python setup.py install
\end{Verbatim}

If you are on windows and not so familiar with python, we would suggest you to install the miniconda python distribution
available at \href{http://conda.pydata.org/miniconda.html}{http://conda.pydata.org/miniconda.html} (you can choose whatever version - 2.7 or 3.X - of python you would like)
and then:

\begin{Verbatim}[commandchars=\\\{\}]
\$ conda install pip sqlalchemy
\$ pip install piecash
\end{Verbatim}


\section{Quickstart}
\label{doc/doc:quickstart}
The simplest workflow to use piecash starts by opening a GnuCash file

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{k+kn}{import} \PYG{n+nn}{piecash}

\PYG{c}{\PYGZsh{} open a GnuCash Book}
\PYG{n}{session} \PYG{o}{=} \PYG{n}{piecash}\PYG{o}{.}\PYG{n}{open\PYGZus{}book}\PYG{p}{(}\PYG{l+s}{\PYGZdq{}}\PYG{l+s}{test.gnucash}\PYG{l+s}{\PYGZdq{}}\PYG{p}{,} \PYG{n}{readonly}\PYG{o}{=}\PYG{n+nb+bp}{True}\PYG{p}{)}
\end{Verbatim}

and then access GnuCash objects through the session, for example to query the stock prices

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{c}{\PYGZsh{} example 1, print all stock prices in the Book}
\PYG{c}{\PYGZsh{} display all prices}
\PYG{k}{for} \PYG{n}{price} \PYG{o+ow}{in} \PYG{n}{session}\PYG{o}{.}\PYG{n}{get}\PYG{p}{(}\PYG{n}{piecash}\PYG{o}{.}\PYG{n}{Price}\PYG{p}{)}\PYG{p}{:}
    \PYG{k}{print}\PYG{p}{(}\PYG{n}{price}\PYG{p}{)}
\end{Verbatim}

\begin{Verbatim}[commandchars=\\\{\}]
\textless{}Price 2014-12-22 : 0.702755 EUR/CAD\textgreater{}
\textless{}Price 2014-12-19 : 0.695658 EUR/CAD\textgreater{}
\textless{}Price 2014-12-18 : 0.689026 EUR/CAD\textgreater{}
\textless{}Price 2014-12-17 : 0.69005 EUR/CAD\textgreater{}
\textless{}Price 2014-12-16 : 0.693247 EUR/CAD\textgreater{}
\textless{}Price 2014-12-22 : 51.15 USD/YHOO\textgreater{}
\textless{}Price 2014-12-19 : 50.88 USD/YHOO\textgreater{}
\textless{}Price 2014-12-18 : 50.91 USD/YHOO\textgreater{}
\textless{}Price 2014-12-17 : 50.12 USD/YHOO\textgreater{}
\textless{}Price 2014-12-16 : 48.85 USD/YHOO\textgreater{}
...
\end{Verbatim}

or to query the accounts:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{k}{for} \PYG{n}{account} \PYG{o+ow}{in} \PYG{n}{session}\PYG{o}{.}\PYG{n}{accounts}\PYG{p}{:}
    \PYG{k}{print}\PYG{p}{(}\PYG{n}{account}\PYG{p}{)}
\end{Verbatim}

\begin{Verbatim}[commandchars=\\\{\}]
Account\textless{}[EUR]\textgreater{}
Account\textless{}Assets[EUR]\textgreater{}
Account\textless{}Assets:Current Assets[EUR]\textgreater{}
Account\textless{}Assets:Current Assets:Checking Account[EUR]\textgreater{}
Account\textless{}Assets:Current Assets:Savings Account[EUR]\textgreater{}
Account\textless{}Assets:Current Assets:Cash in Wallet[EUR]\textgreater{}
Account\textless{}Income[EUR]\textgreater{}
Account\textless{}Income:Bonus[EUR]\textgreater{}
Account\textless{}Income:Gifts Received[EUR]\textgreater{}
...
Account\textless{}Expenses[EUR]\textgreater{}
Account\textless{}Expenses:Commissions[EUR]\textgreater{}
Account\textless{}Expenses:Adjustment[EUR]\textgreater{}
Account\textless{}Expenses:Auto[EUR]\textgreater{}
Account\textless{}Expenses:Auto:Fees[EUR]\textgreater{}
...
Account\textless{}Liabilities[EUR]\textgreater{}
Account\textless{}Liabilities:Credit Card[EUR]\textgreater{}
Account\textless{}Equity[EUR]\textgreater{}
Account\textless{}Equity:Opening Balances[EUR]\textgreater{}
...
\end{Verbatim}

or to create a new expense account for utilities:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{c}{\PYGZsh{} retrieve currency}
\PYG{n}{EUR} \PYG{o}{=} \PYG{n}{session}\PYG{o}{.}\PYG{n}{commodities}\PYG{o}{.}\PYG{n}{get}\PYG{p}{(}\PYG{n}{mnemonic}\PYG{o}{=}\PYG{l+s}{\PYGZsq{}}\PYG{l+s}{EUR}\PYG{l+s}{\PYGZsq{}}\PYG{p}{)}

\PYG{c}{\PYGZsh{} retrieve parent account}
\PYG{n}{acc\PYGZus{}exp} \PYG{o}{=} \PYG{n}{session}\PYG{o}{.}\PYG{n}{accounts}\PYG{o}{.}\PYG{n}{get}\PYG{p}{(}\PYG{n}{fullname}\PYG{o}{=}\PYG{l+s}{\PYGZdq{}}\PYG{l+s}{Expenses:Utilities}\PYG{l+s}{\PYGZdq{}}\PYG{p}{)}

\PYG{c}{\PYGZsh{} add a new subaccount to this account of type EXPENSE with currency EUR}
\PYG{n}{new\PYGZus{}acc} \PYG{o}{=} \PYG{n}{piecash}\PYG{o}{.}\PYG{n}{Account}\PYG{p}{(}\PYG{n}{name}\PYG{o}{=}\PYG{l+s}{\PYGZdq{}}\PYG{l+s}{Cable}\PYG{l+s}{\PYGZdq{}}\PYG{p}{,} \PYG{n}{account\PYGZus{}type}\PYG{o}{=}\PYG{l+s}{\PYGZdq{}}\PYG{l+s}{EXPENSE}\PYG{l+s}{\PYGZdq{}}\PYG{p}{,} \PYG{n}{parent}\PYG{o}{=}\PYG{n}{acc\PYGZus{}exp}\PYG{p}{,} \PYG{n}{commodity}\PYG{o}{=}\PYG{n}{EUR}\PYG{p}{)}

\PYG{c}{\PYGZsh{} save changes (it should raise an exception if we opened the book as readonly)}
\PYG{n}{session}\PYG{o}{.}\PYG{n}{save}\PYG{p}{(}\PYG{p}{)}
\end{Verbatim}

Most basic objects used for personal finance are supported (Account, Split, Transaction, Price, ...).

For more information on how to use piecash, please refer to the {\hyperref[tutorial/index::doc]{\emph{Tutorials}}},
the {\hyperref[tutorial/examples::doc]{\emph{Example scripts}}} or the {\hyperref[api/piecash::doc]{\emph{package documentation}}}.


\chapter{Tutorials}
\label{tutorial/index::doc}\label{tutorial/index:tutorials}

\section{Creating a new Book}
\label{tutorial/create_book::doc}\label{tutorial/create_book:creating-a-new-book}
piecash can create a new GnuCash document (a {\hyperref[api/piecash.model_core.session:piecash.model_core.session.GncSession]{\code{GncSession}}}) from scratch through the {\hyperref[api/piecash.model_core.session:piecash.model_core.session.create_book]{\code{create\_book()}}} function.

To create a in-memory sqlite3 document (useful to test piecash for instance), a simple call is enough:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{k+kn}{import} \PYG{n+nn}{piecash}

\PYG{n}{s} \PYG{o}{=} \PYG{n}{piecash}\PYG{o}{.}\PYG{n}{create\PYGZus{}book}\PYG{p}{(}\PYG{p}{)}
\end{Verbatim}

To create a file-based sqlite3 document:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{n}{s} \PYG{o}{=} \PYG{n}{piecash}\PYG{o}{.}\PYG{n}{create\PYGZus{}book}\PYG{p}{(}\PYG{l+s}{\PYGZdq{}}\PYG{l+s}{example\PYGZus{}file.gnucash}\PYG{l+s}{\PYGZdq{}}\PYG{p}{)}
\PYG{c}{\PYGZsh{} or equivalently}
\PYG{n}{s} \PYG{o}{=} \PYG{n}{piecash}\PYG{o}{.}\PYG{n}{create\PYGZus{}book}\PYG{p}{(}\PYG{n}{sqlite\PYGZus{}file}\PYG{o}{=}\PYG{l+s}{\PYGZdq{}}\PYG{l+s}{example\PYGZus{}file.gnucash}\PYG{l+s}{\PYGZdq{}}\PYG{p}{)}
\PYG{c}{\PYGZsh{} or equivalently}
\PYG{n}{s} \PYG{o}{=} \PYG{n}{piecash}\PYG{o}{.}\PYG{n}{create\PYGZus{}book}\PYG{p}{(}\PYG{n}{uri\PYGZus{}conn}\PYG{o}{=}\PYG{l+s}{\PYGZdq{}}\PYG{l+s}{sqlite:///example\PYGZus{}file.gnucash}\PYG{l+s}{\PYGZdq{}}\PYG{p}{)}
\end{Verbatim}

and for a postgres document:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{n}{s} \PYG{o}{=} \PYG{n}{piecash}\PYG{o}{.}\PYG{n}{create\PYGZus{}book}\PYG{p}{(}\PYG{n}{uri\PYGZus{}conn}\PYG{o}{=}\PYG{l+s}{\PYGZdq{}}\PYG{l+s}{postgres://user:passwd@localhost/example\PYGZus{}gnucash\PYGZus{}db}\PYG{l+s}{\PYGZdq{}}\PYG{p}{)}
\end{Verbatim}

\begin{notice}{note}{Note:}
Specifying the default currency

Per default, the currency of the document is the euro (EUR) but you can specify any other currency through
its ISO symbol:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{n}{s} \PYG{o}{=} \PYG{n}{piecash}\PYG{o}{.}\PYG{n}{create\PYGZus{}book}\PYG{p}{(}\PYG{n}{sqlite\PYGZus{}file}\PYG{o}{=}\PYG{l+s}{\PYGZdq{}}\PYG{l+s}{example\PYGZus{}file.gnucash}\PYG{l+s}{\PYGZdq{}}\PYG{p}{,} \PYG{n}{currency}\PYG{o}{=}\PYG{l+s}{\PYGZdq{}}\PYG{l+s}{USD}\PYG{l+s}{\PYGZdq{}}\PYG{p}{)}
\end{Verbatim}
\end{notice}
\begin{description}
\item[{If the document already exists, piecash will raise an exception. You can force piecash to overwrite an existing file/database}] \leavevmode
(i.e. delete it and then recreate it) by passing the overwrite=True argument:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{n}{s} \PYG{o}{=} \PYG{n}{piecash}\PYG{o}{.}\PYG{n}{create\PYGZus{}book}\PYG{p}{(}\PYG{n}{sqlite\PYGZus{}file}\PYG{o}{=}\PYG{l+s}{\PYGZdq{}}\PYG{l+s}{example\PYGZus{}file.gnucash}\PYG{l+s}{\PYGZdq{}}\PYG{p}{)}
\PYG{n}{s} \PYG{o}{=} \PYG{n}{piecash}\PYG{o}{.}\PYG{n}{create\PYGZus{}book}\PYG{p}{(}\PYG{n}{sqlite\PYGZus{}file}\PYG{o}{=}\PYG{l+s}{\PYGZdq{}}\PYG{l+s}{example\PYGZus{}file.gnucash}\PYG{l+s}{\PYGZdq{}}\PYG{p}{,} \PYG{n}{overwrite}\PYG{o}{=}\PYG{n+nb+bp}{True}\PYG{p}{)}
\end{Verbatim}

\end{description}


\section{Opening an existing Book}
\label{tutorial/open_book::doc}\label{tutorial/open_book:opening-an-existing-book}
To open an existing GnuCash document (and get the related {\hyperref[api/piecash.model_core.session:piecash.model_core.session.GncSession]{\code{GncSession}}}), use the {\hyperref[api/piecash.model_core.session:piecash.model_core.session.open_book]{\code{open\_book()}}} function:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{k+kn}{import} \PYG{n+nn}{piecash}

\PYG{c}{\PYGZsh{} for a sqlite3 document}
\PYG{n}{s} \PYG{o}{=} \PYG{n}{piecash}\PYG{o}{.}\PYG{n}{open\PYGZus{}book}\PYG{p}{(}\PYG{l+s}{\PYGZdq{}}\PYG{l+s}{existing\PYGZus{}file.gnucash}\PYG{l+s}{\PYGZdq{}}\PYG{p}{)}

\PYG{c}{\PYGZsh{} or through an URI connection string for sqlite3}
\PYG{n}{s} \PYG{o}{=} \PYG{n}{piecash}\PYG{o}{.}\PYG{n}{open\PYGZus{}book}\PYG{p}{(}\PYG{n}{uri\PYGZus{}conn}\PYG{o}{=}\PYG{l+s}{\PYGZdq{}}\PYG{l+s}{sqlite:///existing\PYGZus{}file.gnucash}\PYG{l+s}{\PYGZdq{}}\PYG{p}{)}
\PYG{c}{\PYGZsh{} or for postgres}
\PYG{n}{s} \PYG{o}{=} \PYG{n}{piecash}\PYG{o}{.}\PYG{n}{open\PYGZus{}book}\PYG{p}{(}\PYG{n}{uri\PYGZus{}conn}\PYG{o}{=}\PYG{l+s}{\PYGZdq{}}\PYG{l+s}{postgres://user:passwd@localhost/existing\PYGZus{}gnucash\PYGZus{}db}\PYG{l+s}{\PYGZdq{}}\PYG{p}{)}
\end{Verbatim}

The documents are open as readonly per default. To allow RW access, specify explicitly readonly=False as:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{n}{s} \PYG{o}{=} \PYG{n}{piecash}\PYG{o}{.}\PYG{n}{open\PYGZus{}book}\PYG{p}{(}\PYG{l+s}{\PYGZdq{}}\PYG{l+s}{existing\PYGZus{}file.gnucash}\PYG{l+s}{\PYGZdq{}}\PYG{p}{,} \PYG{n}{readonly}\PYG{o}{=}\PYG{n+nb+bp}{False}\PYG{p}{)}
\end{Verbatim}

Per default, piecash will acquire a lock on the file (as GnuCash does). To avoid acquiring the lock, you can
set the acquire\_lock=False argument:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{n}{s} \PYG{o}{=} \PYG{n}{piecash}\PYG{o}{.}\PYG{n}{open\PYGZus{}book}\PYG{p}{(}\PYG{l+s}{\PYGZdq{}}\PYG{l+s}{existing\PYGZus{}file.gnucash}\PYG{l+s}{\PYGZdq{}}\PYG{p}{,} \PYG{n}{acquire\PYGZus{}lock}\PYG{o}{=}\PYG{n+nb+bp}{False}\PYG{p}{)}
\end{Verbatim}

To force opening the file even through there is a lock on it, use the open\_if\_lock=True argument:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{n}{s} \PYG{o}{=} \PYG{n}{piecash}\PYG{o}{.}\PYG{n}{open\PYGZus{}book}\PYG{p}{(}\PYG{l+s}{\PYGZdq{}}\PYG{l+s}{existing\PYGZus{}file.gnucash}\PYG{l+s}{\PYGZdq{}}\PYG{p}{,} \PYG{n}{open\PYGZus{}if\PYGZus{}lock}\PYG{o}{=}\PYG{n+nb+bp}{True}\PYG{p}{)}
\end{Verbatim}


\chapter{Examples of scripts}
\label{tutorial/examples::doc}\label{tutorial/examples:examples-of-scripts}
You can find examples for scripts (loosely based on the scripts for the official python bindings for gnucash or on
questions posted on the mailing list) in the examples subfolder.


\section{Filtered transaction reports}
\label{tutorial/examples:filtered-transaction-reports}
\begin{Verbatim}[commandchars=\\\{\}]
\PYG{k+kn}{from} \PYG{n+nn}{\PYGZus{}\PYGZus{}future\PYGZus{}\PYGZus{}} \PYG{k+kn}{import} \PYG{n}{print\PYGZus{}function}
\PYG{k+kn}{import} \PYG{n+nn}{datetime}
\PYG{k+kn}{import} \PYG{n+nn}{re}
\PYG{k+kn}{from} \PYG{n+nn}{piecash} \PYG{k+kn}{import} \PYG{n}{Transaction}\PYG{p}{,} \PYG{n}{open\PYGZus{}book}


\PYG{n}{s} \PYG{o}{=} \PYG{n}{open\PYGZus{}book}\PYG{p}{(}\PYG{l+s}{\PYGZdq{}}\PYG{l+s}{book.gnucash}\PYG{l+s}{\PYGZdq{}}\PYG{p}{,} \PYG{n}{open\PYGZus{}if\PYGZus{}lock}\PYG{o}{=}\PYG{n+nb+bp}{True}\PYG{p}{)}

\PYG{n}{regex} \PYG{o}{=} \PYG{n}{re}\PYG{o}{.}\PYG{n}{compile}\PYG{p}{(}\PYG{l+s}{\PYGZdq{}}\PYG{l+s}{\PYGZca{}/Rental/}\PYG{l+s}{\PYGZdq{}}\PYG{p}{)}

\PYG{c}{\PYGZsh{} retrieve relevant transactions}
\PYG{n}{transactions} \PYG{o}{=} \PYG{p}{[}\PYG{n}{tr} \PYG{k}{for} \PYG{n}{tr} \PYG{o+ow}{in} \PYG{n}{s}\PYG{o}{.}\PYG{n}{transactions}  \PYG{c}{\PYGZsh{} query all transactions in the book/session and filter them on}
                \PYG{k}{if} \PYG{p}{(}\PYG{n}{regex}\PYG{o}{.}\PYG{n}{search}\PYG{p}{(}\PYG{n}{tr}\PYG{o}{.}\PYG{n}{description}\PYG{p}{)}                            \PYG{c}{\PYGZsh{} description field matching regex}
                    \PYG{o+ow}{or} \PYG{n+nb}{any}\PYG{p}{(}\PYG{n}{regex}\PYG{o}{.}\PYG{n}{search}\PYG{p}{(}\PYG{n}{spl}\PYG{o}{.}\PYG{n}{memo}\PYG{p}{)} \PYG{k}{for} \PYG{n}{spl} \PYG{o+ow}{in} \PYG{n}{tr}\PYG{o}{.}\PYG{n}{splits}\PYG{p}{)}\PYG{p}{)}    \PYG{c}{\PYGZsh{} or memo field of any split of transaction}
                \PYG{o+ow}{and} \PYG{n}{tr}\PYG{o}{.}\PYG{n}{post\PYGZus{}date}\PYG{o}{.}\PYG{n}{date}\PYG{p}{(}\PYG{p}{)} \PYG{o}{\PYGZgt{}}\PYG{o}{=} \PYG{n}{datetime}\PYG{o}{.}\PYG{n}{date}\PYG{p}{(}\PYG{l+m+mi}{2014}\PYG{p}{,} \PYG{l+m+mi}{11}\PYG{p}{,} \PYG{l+m+mi}{1}\PYG{p}{)}\PYG{p}{]}      \PYG{c}{\PYGZsh{} and with post\PYGZus{}date no later than begin nov.}


\PYG{c}{\PYGZsh{} output report with simple \PYGZsq{}print\PYGZsq{}}
\PYG{k}{print}\PYG{p}{(}\PYG{l+s}{\PYGZdq{}}\PYG{l+s}{Here are the transactions for the search criteria }\PYG{l+s}{\PYGZsq{}}\PYG{l+s}{\PYGZob{}\PYGZcb{}}\PYG{l+s}{\PYGZsq{}}\PYG{l+s}{:}\PYG{l+s}{\PYGZdq{}}\PYG{o}{.}\PYG{n}{format}\PYG{p}{(}\PYG{n}{regex}\PYG{o}{.}\PYG{n}{pattern}\PYG{p}{)}\PYG{p}{)}
\PYG{k}{for} \PYG{n}{tr} \PYG{o+ow}{in} \PYG{n}{transactions}\PYG{p}{:}
    \PYG{k}{print}\PYG{p}{(}\PYG{l+s}{\PYGZdq{}}\PYG{l+s}{\PYGZhy{} \PYGZob{}:}\PYG{l+s}{\PYGZpc{}}\PYG{l+s}{Y/}\PYG{l+s}{\PYGZpc{}}\PYG{l+s}{m/}\PYG{l+s+si}{\PYGZpc{}d}\PYG{l+s}{\PYGZcb{} : \PYGZob{}\PYGZcb{}}\PYG{l+s}{\PYGZdq{}}\PYG{o}{.}\PYG{n}{format}\PYG{p}{(}\PYG{n}{tr}\PYG{o}{.}\PYG{n}{post\PYGZus{}date}\PYG{p}{,} \PYG{n}{tr}\PYG{o}{.}\PYG{n}{description}\PYG{p}{)}\PYG{p}{)}
    \PYG{k}{for} \PYG{n}{spl} \PYG{o+ow}{in} \PYG{n}{tr}\PYG{o}{.}\PYG{n}{splits}\PYG{p}{:}
        \PYG{k}{print}\PYG{p}{(}\PYG{l+s}{\PYGZdq{}}\PYG{l+s+se}{\PYGZbs{}t}\PYG{l+s}{\PYGZob{}amount\PYGZcb{}  \PYGZob{}direction\PYGZcb{}  \PYGZob{}account\PYGZcb{} : \PYGZob{}memo\PYGZcb{}}\PYG{l+s}{\PYGZdq{}}\PYG{o}{.}\PYG{n}{format}\PYG{p}{(}\PYG{n}{amount}\PYG{o}{=}\PYG{n+nb}{abs}\PYG{p}{(}\PYG{n}{spl}\PYG{o}{.}\PYG{n}{value}\PYG{p}{)}\PYG{p}{,}
                                                                 \PYG{n}{direction}\PYG{o}{=}\PYG{l+s}{\PYGZdq{}}\PYG{l+s}{\PYGZhy{}\PYGZhy{}\PYGZgt{}}\PYG{l+s}{\PYGZdq{}} \PYG{k}{if} \PYG{n}{spl}\PYG{o}{.}\PYG{n}{value} \PYG{o}{\PYGZgt{}} \PYG{l+m+mi}{0} \PYG{k}{else} \PYG{l+s}{\PYGZdq{}}\PYG{l+s}{\PYGZlt{}\PYGZhy{}\PYGZhy{}}\PYG{l+s}{\PYGZdq{}}\PYG{p}{,}
                                                                 \PYG{n}{account}\PYG{o}{=}\PYG{n}{spl}\PYG{o}{.}\PYG{n}{account}\PYG{o}{.}\PYG{n}{fullname}\PYG{p}{(}\PYG{p}{)}\PYG{p}{,}
                                                                 \PYG{n}{memo}\PYG{o}{=}\PYG{n}{spl}\PYG{o}{.}\PYG{n}{memo}\PYG{p}{)}\PYG{p}{)}

\PYG{c}{\PYGZsh{} same with jinja2 templates}
\PYG{k}{try}\PYG{p}{:}
    \PYG{k+kn}{import} \PYG{n+nn}{jinja2}
\PYG{k}{except} \PYG{n+ne}{ImportError}\PYG{p}{:}
    \PYG{k}{print}\PYG{p}{(}\PYG{l+s}{\PYGZdq{}}\PYG{l+s+se}{\PYGZbs{}n}\PYG{l+s+se}{\PYGZbs{}t}\PYG{l+s}{*** Install jinja2 (}\PYG{l+s}{\PYGZsq{}}\PYG{l+s}{pip install jinja2}\PYG{l+s}{\PYGZsq{}}\PYG{l+s}{) to test the jinja2 template version ***}\PYG{l+s+se}{\PYGZbs{}n}\PYG{l+s}{\PYGZdq{}}\PYG{p}{)}
    \PYG{n}{jinja2} \PYG{o}{=} \PYG{n+nb+bp}{None}

\PYG{k}{if} \PYG{n}{jinja2}\PYG{p}{:}
    \PYG{n}{env} \PYG{o}{=} \PYG{n}{jinja2}\PYG{o}{.}\PYG{n}{Environment}\PYG{p}{(}\PYG{n}{trim\PYGZus{}blocks}\PYG{o}{=}\PYG{n+nb+bp}{True}\PYG{p}{,} \PYG{n}{lstrip\PYGZus{}blocks}\PYG{o}{=}\PYG{n+nb+bp}{True}\PYG{p}{)}
    \PYG{k}{print}\PYG{p}{(}\PYG{n}{env}\PYG{o}{.}\PYG{n}{from\PYGZus{}string}\PYG{p}{(}\PYG{l+s}{\PYGZdq{}\PYGZdq{}\PYGZdq{}}
\PYG{l+s}{    Here are the transactions for the search criteria }\PYG{l+s}{\PYGZsq{}}\PYG{l+s}{\PYGZob{}\PYGZob{}regex.pattern\PYGZcb{}\PYGZcb{}}\PYG{l+s}{\PYGZsq{}}\PYG{l+s}{:}
\PYG{l+s}{    \PYGZob{}}\PYG{l+s+si}{\PYGZpc{} f}\PYG{l+s}{or tr in transactions }\PYG{l+s}{\PYGZpc{}}\PYG{l+s}{\PYGZcb{}}
\PYG{l+s}{    \PYGZhy{} \PYGZob{}\PYGZob{} tr.post\PYGZus{}date.strftime(}\PYG{l+s}{\PYGZdq{}}\PYG{l+s}{\PYGZpc{}}\PYG{l+s}{Y/}\PYG{l+s}{\PYGZpc{}}\PYG{l+s}{m/}\PYG{l+s+si}{\PYGZpc{}d}\PYG{l+s}{\PYGZdq{}}\PYG{l+s}{) \PYGZcb{}\PYGZcb{} : \PYGZob{}\PYGZob{} tr.description \PYGZcb{}\PYGZcb{}}
\PYG{l+s}{      \PYGZob{}}\PYG{l+s+si}{\PYGZpc{} f}\PYG{l+s}{or spl in tr.splits }\PYG{l+s}{\PYGZpc{}}\PYG{l+s}{\PYGZcb{}}
\PYG{l+s}{        \PYGZob{}\PYGZob{} spl.value.\PYGZus{}\PYGZus{}abs\PYGZus{}\PYGZus{}() \PYGZcb{}\PYGZcb{} \PYGZob{}}\PYG{l+s+si}{\PYGZpc{} i}\PYG{l+s}{f spl.value \PYGZlt{} 0 }\PYG{l+s}{\PYGZpc{}}\PYG{l+s}{\PYGZcb{} \PYGZhy{}\PYGZhy{}\PYGZgt{} \PYGZob{}}\PYG{l+s+si}{\PYGZpc{} e}\PYG{l+s}{lse }\PYG{l+s}{\PYGZpc{}}\PYG{l+s}{\PYGZcb{} \PYGZlt{}\PYGZhy{}\PYGZhy{} \PYGZob{}}\PYG{l+s+si}{\PYGZpc{} e}\PYG{l+s}{ndif }\PYG{l+s}{\PYGZpc{}}\PYG{l+s}{\PYGZcb{} \PYGZob{}\PYGZob{} spl.account.fullname() \PYGZcb{}\PYGZcb{} : \PYGZob{}\PYGZob{} spl.memo \PYGZcb{}\PYGZcb{}}
\PYG{l+s}{      \PYGZob{}}\PYG{l+s+si}{\PYGZpc{} e}\PYG{l+s}{ndfor }\PYG{l+s}{\PYGZpc{}}\PYG{l+s}{\PYGZcb{}}
\PYG{l+s}{    \PYGZob{}}\PYG{l+s+si}{\PYGZpc{} e}\PYG{l+s}{ndfor }\PYG{l+s}{\PYGZpc{}}\PYG{l+s}{\PYGZcb{}}
\PYG{l+s}{    }\PYG{l+s}{\PYGZdq{}\PYGZdq{}\PYGZdq{}}\PYG{p}{)}\PYG{o}{.}\PYG{n}{render}\PYG{p}{(}\PYG{n}{transactions}\PYG{o}{=}\PYG{n}{transactions}\PYG{p}{,}
                \PYG{n}{regex}\PYG{o}{=}\PYG{n}{regex}\PYG{p}{)}\PYG{p}{)}
\end{Verbatim}


\section{Simple changes on a newly created book}
\label{tutorial/examples:simple-changes-on-a-newly-created-book}
\begin{Verbatim}[commandchars=\\\{\}]
\PYG{k+kn}{from} \PYG{n+nn}{\PYGZus{}\PYGZus{}future\PYGZus{}\PYGZus{}} \PYG{k+kn}{import} \PYG{n}{print\PYGZus{}function}
\PYG{k+kn}{from} \PYG{n+nn}{piecash} \PYG{k+kn}{import} \PYG{n}{create\PYGZus{}book}

\PYG{c}{\PYGZsh{} create by default an in memory sqlite version}
\PYG{n}{ses} \PYG{o}{=} \PYG{n}{create\PYGZus{}book}\PYG{p}{(}\PYG{n}{echo}\PYG{o}{=}\PYG{n+nb+bp}{False}\PYG{p}{)}
\PYG{n}{book} \PYG{o}{=} \PYG{n}{ses}\PYG{o}{.}\PYG{n}{book}

\PYG{k}{print}\PYG{p}{(}\PYG{l+s}{\PYGZdq{}}\PYG{l+s}{Book is saved:}\PYG{l+s}{\PYGZdq{}}\PYG{p}{,} \PYG{n}{ses}\PYG{o}{.}\PYG{n}{is\PYGZus{}saved}\PYG{p}{,} \PYG{n}{end}\PYG{o}{=}\PYG{l+s}{\PYGZsq{}}\PYG{l+s}{ }\PYG{l+s}{\PYGZsq{}}\PYG{p}{)}
\PYG{k}{print}\PYG{p}{(}\PYG{l+s}{\PYGZdq{}}\PYG{l+s}{ ==\PYGZgt{} book description:}\PYG{l+s}{\PYGZdq{}}\PYG{p}{,} \PYG{n}{book}\PYG{o}{.}\PYG{n}{root\PYGZus{}account}\PYG{o}{.}\PYG{n}{description}\PYG{p}{)}

\PYG{k}{print}\PYG{p}{(}\PYG{l+s}{\PYGZdq{}}\PYG{l+s}{changing description...}\PYG{l+s}{\PYGZdq{}}\PYG{p}{)}
\PYG{n}{book}\PYG{o}{.}\PYG{n}{root\PYGZus{}account}\PYG{o}{.}\PYG{n}{description} \PYG{o}{=} \PYG{l+s}{\PYGZdq{}}\PYG{l+s}{hello, book}\PYG{l+s}{\PYGZdq{}}
\PYG{k}{print}\PYG{p}{(}\PYG{l+s}{\PYGZdq{}}\PYG{l+s}{Book is saved:}\PYG{l+s}{\PYGZdq{}}\PYG{p}{,} \PYG{n}{ses}\PYG{o}{.}\PYG{n}{is\PYGZus{}saved}\PYG{p}{,} \PYG{n}{end}\PYG{o}{=}\PYG{l+s}{\PYGZsq{}}\PYG{l+s}{ }\PYG{l+s}{\PYGZsq{}}\PYG{p}{)}
\PYG{k}{print}\PYG{p}{(}\PYG{l+s}{\PYGZdq{}}\PYG{l+s}{ ==\PYGZgt{} book description:}\PYG{l+s}{\PYGZdq{}}\PYG{p}{,} \PYG{n}{book}\PYG{o}{.}\PYG{n}{root\PYGZus{}account}\PYG{o}{.}\PYG{n}{description}\PYG{p}{)}

\PYG{k}{print}\PYG{p}{(}\PYG{l+s}{\PYGZdq{}}\PYG{l+s}{saving...}\PYG{l+s}{\PYGZdq{}}\PYG{p}{)}
\PYG{n}{ses}\PYG{o}{.}\PYG{n}{save}\PYG{p}{(}\PYG{p}{)}

\PYG{k}{print}\PYG{p}{(}\PYG{l+s}{\PYGZdq{}}\PYG{l+s}{Book is saved:}\PYG{l+s}{\PYGZdq{}}\PYG{p}{,} \PYG{n}{ses}\PYG{o}{.}\PYG{n}{is\PYGZus{}saved}\PYG{p}{,} \PYG{n}{end}\PYG{o}{=}\PYG{l+s}{\PYGZsq{}}\PYG{l+s}{ }\PYG{l+s}{\PYGZsq{}}\PYG{p}{)}
\PYG{k}{print}\PYG{p}{(}\PYG{l+s}{\PYGZdq{}}\PYG{l+s}{ ==\PYGZgt{} book description:}\PYG{l+s}{\PYGZdq{}}\PYG{p}{,} \PYG{n}{book}\PYG{o}{.}\PYG{n}{root\PYGZus{}account}\PYG{o}{.}\PYG{n}{description}\PYG{p}{)}

\PYG{k}{print}\PYG{p}{(}\PYG{l+s}{\PYGZdq{}}\PYG{l+s}{changing description...}\PYG{l+s}{\PYGZdq{}}\PYG{p}{)}
\PYG{n}{book}\PYG{o}{.}\PYG{n}{root\PYGZus{}account}\PYG{o}{.}\PYG{n}{description} \PYG{o}{=} \PYG{l+s}{\PYGZdq{}}\PYG{l+s}{nevermind, book}\PYG{l+s}{\PYGZdq{}}
\PYG{k}{print}\PYG{p}{(}\PYG{l+s}{\PYGZdq{}}\PYG{l+s}{Book is saved:}\PYG{l+s}{\PYGZdq{}}\PYG{p}{,} \PYG{n}{ses}\PYG{o}{.}\PYG{n}{is\PYGZus{}saved}\PYG{p}{,} \PYG{n}{end}\PYG{o}{=}\PYG{l+s}{\PYGZsq{}}\PYG{l+s}{ }\PYG{l+s}{\PYGZsq{}}\PYG{p}{)}
\PYG{k}{print}\PYG{p}{(}\PYG{l+s}{\PYGZdq{}}\PYG{l+s}{ ==\PYGZgt{} book description:}\PYG{l+s}{\PYGZdq{}}\PYG{p}{,} \PYG{n}{book}\PYG{o}{.}\PYG{n}{root\PYGZus{}account}\PYG{o}{.}\PYG{n}{description}\PYG{p}{)}

\PYG{k}{print}\PYG{p}{(}\PYG{l+s}{\PYGZdq{}}\PYG{l+s}{cancel...}\PYG{l+s}{\PYGZdq{}}\PYG{p}{)}
\PYG{n}{ses}\PYG{o}{.}\PYG{n}{cancel}\PYG{p}{(}\PYG{p}{)}

\PYG{k}{print}\PYG{p}{(}\PYG{l+s}{\PYGZdq{}}\PYG{l+s}{Book is saved:}\PYG{l+s}{\PYGZdq{}}\PYG{p}{,} \PYG{n}{ses}\PYG{o}{.}\PYG{n}{is\PYGZus{}saved}\PYG{p}{,} \PYG{n}{end}\PYG{o}{=}\PYG{l+s}{\PYGZsq{}}\PYG{l+s}{ }\PYG{l+s}{\PYGZsq{}}\PYG{p}{)}
\PYG{k}{print}\PYG{p}{(}\PYG{l+s}{\PYGZdq{}}\PYG{l+s}{ ==\PYGZgt{} book description:}\PYG{l+s}{\PYGZdq{}}\PYG{p}{,} \PYG{n}{book}\PYG{o}{.}\PYG{n}{root\PYGZus{}account}\PYG{o}{.}\PYG{n}{description}\PYG{p}{)}
\end{Verbatim}


\section{Creating and opening gnucash files}
\label{tutorial/examples:creating-and-opening-gnucash-files}
\begin{Verbatim}[commandchars=\\\{\}]
\PYG{k+kn}{from} \PYG{n+nn}{\PYGZus{}\PYGZus{}future\PYGZus{}\PYGZus{}} \PYG{k+kn}{import} \PYG{n}{print\PYGZus{}function}
\PYG{k+kn}{import} \PYG{n+nn}{os}

\PYG{k+kn}{from} \PYG{n+nn}{piecash} \PYG{k+kn}{import} \PYG{n}{open\PYGZus{}book}\PYG{p}{,} \PYG{n}{create\PYGZus{}book}\PYG{p}{,} \PYG{n}{GnucashException}


\PYG{n}{FILE\PYGZus{}1} \PYG{o}{=} \PYG{l+s}{\PYGZdq{}}\PYG{l+s}{/tmp/not\PYGZus{}there.xac}\PYG{l+s}{\PYGZdq{}}
\PYG{n}{FILE\PYGZus{}2} \PYG{o}{=} \PYG{l+s}{\PYGZdq{}}\PYG{l+s}{/tmp/example\PYGZus{}file.xac}\PYG{l+s}{\PYGZdq{}}

\PYG{c}{\PYGZsh{} open a file that isn\PYGZsq{}t there, detect the error}
\PYG{k}{try}\PYG{p}{:}
    \PYG{n}{session} \PYG{o}{=} \PYG{n}{open\PYGZus{}book}\PYG{p}{(}\PYG{n}{FILE\PYGZus{}1}\PYG{p}{)}
\PYG{k}{except} \PYG{n}{GnucashException} \PYG{k}{as} \PYG{n}{backend\PYGZus{}exception}\PYG{p}{:}
    \PYG{k}{print}\PYG{p}{(}\PYG{l+s}{\PYGZdq{}}\PYG{l+s}{OK}\PYG{l+s}{\PYGZdq{}}\PYG{p}{,} \PYG{n}{backend\PYGZus{}exception}\PYG{p}{)}

\PYG{c}{\PYGZsh{} create a new file, this requires a file type specification}
\PYG{k}{with} \PYG{n}{create\PYGZus{}book}\PYG{p}{(}\PYG{n}{FILE\PYGZus{}2}\PYG{p}{)} \PYG{k}{as} \PYG{n}{session}\PYG{p}{:}
    \PYG{k}{pass}

\PYG{c}{\PYGZsh{} open the new file, try to open it a second time, detect the lock}
\PYG{c}{\PYGZsh{} using the session as context manager automatically release the lock and close the session}
\PYG{k}{with} \PYG{n}{open\PYGZus{}book}\PYG{p}{(}\PYG{n}{FILE\PYGZus{}2}\PYG{p}{,}\PYG{n}{acquire\PYGZus{}lock}\PYG{o}{=}\PYG{n+nb+bp}{True}\PYG{p}{)} \PYG{k}{as} \PYG{n}{session}\PYG{p}{:}
    \PYG{k}{try}\PYG{p}{:}
        \PYG{n}{session\PYGZus{}2} \PYG{o}{=} \PYG{n}{open\PYGZus{}book}\PYG{p}{(}\PYG{n}{FILE\PYGZus{}2}\PYG{p}{)}
    \PYG{k}{except} \PYG{n}{GnucashException} \PYG{k}{as} \PYG{n}{backend\PYGZus{}exception}\PYG{p}{:}
        \PYG{k}{print}\PYG{p}{(}\PYG{l+s}{\PYGZdq{}}\PYG{l+s}{OK}\PYG{l+s}{\PYGZdq{}}\PYG{p}{,} \PYG{n}{backend\PYGZus{}exception}\PYG{p}{)}

\PYG{n}{os}\PYG{o}{.}\PYG{n}{remove}\PYG{p}{(}\PYG{n}{FILE\PYGZus{}2}\PYG{p}{)}
\end{Verbatim}


\section{Creating an account}
\label{tutorial/examples:creating-an-account}
\begin{Verbatim}[commandchars=\\\{\}]
\PYG{c}{\PYGZsh{}!/usr/bin/env python}
\PYG{c}{\PYGZsh{}\PYGZsh{}  @file}
\PYG{c}{\PYGZsh{}   @brief Example Script simple sqlite create}
\PYG{c}{\PYGZsh{}   @ingroup python\PYGZus{}bindings\PYGZus{}examples}

\PYG{k+kn}{from} \PYG{n+nn}{\PYGZus{}\PYGZus{}future\PYGZus{}\PYGZus{}} \PYG{k+kn}{import} \PYG{n}{print\PYGZus{}function}
\PYG{k+kn}{import} \PYG{n+nn}{os}
\PYG{k+kn}{from} \PYG{n+nn}{piecash} \PYG{k+kn}{import} \PYG{n}{create\PYGZus{}book}\PYG{p}{,} \PYG{n}{Account}\PYG{p}{,} \PYG{n}{Commodity}\PYG{p}{,} \PYG{n}{open\PYGZus{}book}

\PYG{n}{filename} \PYG{o}{=} \PYG{n}{os}\PYG{o}{.}\PYG{n}{path}\PYG{o}{.}\PYG{n}{abspath}\PYG{p}{(}\PYG{l+s}{\PYGZsq{}}\PYG{l+s}{test.blob}\PYG{l+s}{\PYGZsq{}}\PYG{p}{)}

\PYG{k}{with} \PYG{n}{create\PYGZus{}book}\PYG{p}{(}\PYG{n}{filename}\PYG{p}{)} \PYG{k}{as} \PYG{n}{s}\PYG{p}{:}
    \PYG{n}{a} \PYG{o}{=} \PYG{n}{Account}\PYG{p}{(}\PYG{n}{parent}\PYG{o}{=}\PYG{n}{s}\PYG{o}{.}\PYG{n}{book}\PYG{o}{.}\PYG{n}{root\PYGZus{}account}\PYG{p}{,}
                \PYG{n}{name}\PYG{o}{=}\PYG{l+s}{\PYGZdq{}}\PYG{l+s}{wow}\PYG{l+s}{\PYGZdq{}}\PYG{p}{,}
                \PYG{n}{account\PYGZus{}type}\PYG{o}{=}\PYG{l+s}{\PYGZdq{}}\PYG{l+s}{ASSET}\PYG{l+s}{\PYGZdq{}}\PYG{p}{,}
                \PYG{n}{commodity}\PYG{o}{=}\PYG{n}{Commodity}\PYG{o}{.}\PYG{n}{create\PYGZus{}currency\PYGZus{}from\PYGZus{}ISO}\PYG{p}{(}\PYG{l+s}{\PYGZdq{}}\PYG{l+s}{CAD}\PYG{l+s}{\PYGZdq{}}\PYG{p}{)}\PYG{p}{)}

    \PYG{n}{s}\PYG{o}{.}\PYG{n}{save}\PYG{p}{(}\PYG{p}{)}

\PYG{k}{with} \PYG{n}{open\PYGZus{}book}\PYG{p}{(}\PYG{n}{filename}\PYG{p}{)} \PYG{k}{as} \PYG{n}{s}\PYG{p}{:}
    \PYG{k}{print}\PYG{p}{(}\PYG{n}{s}\PYG{o}{.}\PYG{n}{book}\PYG{o}{.}\PYG{n}{root\PYGZus{}account}\PYG{o}{.}\PYG{n}{children}\PYG{p}{)}
    \PYG{k}{print}\PYG{p}{(}\PYG{n}{s}\PYG{o}{.}\PYG{n}{commodities}\PYG{o}{.}\PYG{n}{get}\PYG{p}{(}\PYG{n}{mnemonic}\PYG{o}{=}\PYG{l+s}{\PYGZdq{}}\PYG{l+s}{CAD}\PYG{l+s}{\PYGZdq{}}\PYG{p}{)}\PYG{p}{)}

\PYG{n}{os}\PYG{o}{.}\PYG{n}{remove}\PYG{p}{(}\PYG{n}{filename}\PYG{p}{)}
\end{Verbatim}


\section{Creating a transaction}
\label{tutorial/examples:creating-a-transaction}
\begin{Verbatim}[commandchars=\\\{\}]
\PYG{c}{\PYGZsh{}!/usr/bin/env python}
\PYG{c}{\PYGZsh{} \PYGZsh{} @file}
\PYG{c}{\PYGZsh{} @brief Creates a basic set of accounts and a couple of transactions}
\PYG{c}{\PYGZsh{} @ingroup python\PYGZus{}bindings\PYGZus{}examples}
\PYG{k+kn}{from} \PYG{n+nn}{decimal} \PYG{k+kn}{import} \PYG{n}{Decimal}

\PYG{k+kn}{from} \PYG{n+nn}{piecash} \PYG{k+kn}{import} \PYG{n}{create\PYGZus{}book}\PYG{p}{,} \PYG{n}{Account}\PYG{p}{,} \PYG{n}{Transaction}\PYG{p}{,} \PYG{n}{Split}\PYG{p}{,} \PYG{n}{Commodity}

\PYG{n}{FILE\PYGZus{}1} \PYG{o}{=} \PYG{l+s}{\PYGZdq{}}\PYG{l+s}{/tmp/example.gnucash}\PYG{l+s}{\PYGZdq{}}

\PYG{k}{with} \PYG{n}{create\PYGZus{}book}\PYG{p}{(}\PYG{n}{FILE\PYGZus{}1}\PYG{p}{,} \PYG{n}{overwrite}\PYG{o}{=}\PYG{n+nb+bp}{True}\PYG{p}{)} \PYG{k}{as} \PYG{n}{session}\PYG{p}{:}
    \PYG{n}{book} \PYG{o}{=} \PYG{n}{session}\PYG{o}{.}\PYG{n}{book}
    \PYG{n}{root\PYGZus{}acct} \PYG{o}{=} \PYG{n}{book}\PYG{o}{.}\PYG{n}{root\PYGZus{}account}
    \PYG{n}{cad} \PYG{o}{=} \PYG{n}{Commodity}\PYG{o}{.}\PYG{n}{create\PYGZus{}currency\PYGZus{}from\PYGZus{}ISO}\PYG{p}{(}\PYG{l+s}{\PYGZdq{}}\PYG{l+s}{CAD}\PYG{l+s}{\PYGZdq{}}\PYG{p}{)}
    \PYG{n}{expenses\PYGZus{}acct} \PYG{o}{=} \PYG{n}{Account}\PYG{p}{(}\PYG{n}{parent}\PYG{o}{=}\PYG{n}{root\PYGZus{}acct}\PYG{p}{,}
                            \PYG{n}{name}\PYG{o}{=}\PYG{l+s}{\PYGZdq{}}\PYG{l+s}{Expenses}\PYG{l+s}{\PYGZdq{}}\PYG{p}{,}
                            \PYG{n}{account\PYGZus{}type}\PYG{o}{=}\PYG{l+s}{\PYGZdq{}}\PYG{l+s}{EXPENSE}\PYG{l+s}{\PYGZdq{}}\PYG{p}{,}
                            \PYG{n}{commodity}\PYG{o}{=}\PYG{n}{cad}\PYG{p}{)}
    \PYG{n}{savings\PYGZus{}acct} \PYG{o}{=} \PYG{n}{Account}\PYG{p}{(}\PYG{n}{parent}\PYG{o}{=}\PYG{n}{root\PYGZus{}acct}\PYG{p}{,}
                           \PYG{n}{name}\PYG{o}{=}\PYG{l+s}{\PYGZdq{}}\PYG{l+s}{Savings}\PYG{l+s}{\PYGZdq{}}\PYG{p}{,}
                           \PYG{n}{account\PYGZus{}type}\PYG{o}{=}\PYG{l+s}{\PYGZdq{}}\PYG{l+s}{BANK}\PYG{l+s}{\PYGZdq{}}\PYG{p}{,}
                           \PYG{n}{commodity}\PYG{o}{=}\PYG{n}{cad}\PYG{p}{)}
    \PYG{n}{opening\PYGZus{}acct} \PYG{o}{=} \PYG{n}{Account}\PYG{p}{(}\PYG{n}{parent}\PYG{o}{=}\PYG{n}{root\PYGZus{}acct}\PYG{p}{,}
                           \PYG{n}{name}\PYG{o}{=}\PYG{l+s}{\PYGZdq{}}\PYG{l+s}{Opening Balance}\PYG{l+s}{\PYGZdq{}}\PYG{p}{,}
                           \PYG{n}{account\PYGZus{}type}\PYG{o}{=}\PYG{l+s}{\PYGZdq{}}\PYG{l+s}{EQUITY}\PYG{l+s}{\PYGZdq{}}\PYG{p}{,}
                           \PYG{n}{commodity}\PYG{o}{=}\PYG{n}{cad}\PYG{p}{)}
    \PYG{n}{num1} \PYG{o}{=} \PYG{n}{Decimal}\PYG{p}{(}\PYG{l+s}{\PYGZdq{}}\PYG{l+s}{4}\PYG{l+s}{\PYGZdq{}}\PYG{p}{)}
    \PYG{n}{num2} \PYG{o}{=} \PYG{n}{Decimal}\PYG{p}{(}\PYG{l+s}{\PYGZdq{}}\PYG{l+s}{100}\PYG{l+s}{\PYGZdq{}}\PYG{p}{)}
    \PYG{n}{num3} \PYG{o}{=} \PYG{n}{Decimal}\PYG{p}{(}\PYG{l+s}{\PYGZdq{}}\PYG{l+s}{15}\PYG{l+s}{\PYGZdq{}}\PYG{p}{)}

    \PYG{c}{\PYGZsh{} create transaction with core objects in one step}
    \PYG{n}{trans1} \PYG{o}{=} \PYG{n}{Transaction}\PYG{p}{(}\PYG{n}{currency}\PYG{o}{=}\PYG{n}{cad}\PYG{p}{,}
                         \PYG{n}{description}\PYG{o}{=}\PYG{l+s}{\PYGZdq{}}\PYG{l+s}{Groceries}\PYG{l+s}{\PYGZdq{}}\PYG{p}{,}
                         \PYG{n}{splits}\PYG{o}{=}\PYG{p}{[}
                             \PYG{n}{Split}\PYG{p}{(}\PYG{n}{value}\PYG{o}{=}\PYG{n}{num1}\PYG{p}{,} \PYG{n}{account}\PYG{o}{=}\PYG{n}{expenses\PYGZus{}acct}\PYG{p}{)}\PYG{p}{,}
                             \PYG{n}{Split}\PYG{p}{(}\PYG{n}{value}\PYG{o}{=}\PYG{o}{\PYGZhy{}}\PYG{n}{num1}\PYG{p}{,} \PYG{n}{account}\PYG{o}{=}\PYG{n}{savings\PYGZus{}acct}\PYG{p}{)}\PYG{p}{,}
                         \PYG{p}{]}\PYG{p}{)}

    \PYG{c}{\PYGZsh{} create transaction with core object in multiple steps}
    \PYG{n}{trans2} \PYG{o}{=} \PYG{n}{Transaction}\PYG{p}{(}\PYG{n}{currency}\PYG{o}{=}\PYG{n}{cad}\PYG{p}{,}
                         \PYG{n}{description}\PYG{o}{=}\PYG{l+s}{\PYGZdq{}}\PYG{l+s}{Opening Savings Balance}\PYG{l+s}{\PYGZdq{}}\PYG{p}{)}

    \PYG{n}{split3} \PYG{o}{=} \PYG{n}{Split}\PYG{p}{(}\PYG{n}{value}\PYG{o}{=}\PYG{n}{num2}\PYG{p}{,}
                   \PYG{n}{account}\PYG{o}{=}\PYG{n}{savings\PYGZus{}acct}\PYG{p}{,}
                   \PYG{n}{transaction}\PYG{o}{=}\PYG{n}{trans2}\PYG{p}{)}

    \PYG{n}{split4} \PYG{o}{=} \PYG{n}{Split}\PYG{p}{(}\PYG{n}{value}\PYG{o}{=}\PYG{o}{\PYGZhy{}}\PYG{n}{num2}\PYG{p}{,}
                   \PYG{n}{account}\PYG{o}{=}\PYG{n}{opening\PYGZus{}acct}\PYG{p}{,}
                   \PYG{n}{transaction}\PYG{o}{=}\PYG{n}{trans2}\PYG{p}{)}

    \PYG{c}{\PYGZsh{} create transaction with factory function}
    \PYG{n}{trans3} \PYG{o}{=} \PYG{n}{Transaction}\PYG{o}{.}\PYG{n}{single\PYGZus{}transaction}\PYG{p}{(}\PYG{n+nb+bp}{None}\PYG{p}{,}\PYG{n+nb+bp}{None}\PYG{p}{,}\PYG{l+s}{\PYGZdq{}}\PYG{l+s}{Pharmacy}\PYG{l+s}{\PYGZdq{}}\PYG{p}{,} \PYG{n}{num3}\PYG{p}{,} \PYG{n}{savings\PYGZus{}acct}\PYG{p}{,} \PYG{n}{expenses\PYGZus{}acct}\PYG{p}{)}

    \PYG{n}{session}\PYG{o}{.}\PYG{n}{save}\PYG{p}{(}\PYG{p}{)}
\end{Verbatim}


\chapter{For developers}
\label{index:for-developers}
The complete api documentation:


\section{piecash package}
\label{api/piecash::doc}\label{api/piecash:piecash-package}

\subsection{Subpackages}
\label{api/piecash:subpackages}

\subsubsection{piecash.model\_core package}
\label{api/piecash.model_core::doc}\label{api/piecash.model_core:piecash-model-core-package}

\paragraph{Submodules}
\label{api/piecash.model_core:submodules}

\subparagraph{piecash.model\_core.account module}
\label{api/piecash.model_core.account::doc}\label{api/piecash.model_core.account:module-piecash.model_core.account}\label{api/piecash.model_core.account:piecash-model-core-account-module}\index{piecash.model\_core.account (module)}\index{ACCOUNT\_TYPES (in module piecash.model\_core.account)}

\begin{fulllineitems}
\phantomsection\label{api/piecash.model_core.account:piecash.model_core.account.ACCOUNT_TYPES}\pysigline{\code{piecash.model\_core.account.}\bfcode{ACCOUNT\_TYPES}\strong{ = \{`ASSET', `INCOME', `RECEIVABLE', `EXPENSE', `CASH', `MUTUAL', `TRADING', `ROOT', `CREDIT', `STOCK', `EQUITY', `PAYABLE', `BANK', `LIABILITY'\}}}
the different types of accounts

\end{fulllineitems}

\index{Account (class in piecash.model\_core.account)}

\begin{fulllineitems}
\phantomsection\label{api/piecash.model_core.account:piecash.model_core.account.Account}\pysiglinewithargsret{\strong{class }\code{piecash.model\_core.account.}\bfcode{Account}}{\emph{name}, \emph{account\_type}, \emph{commodity}, \emph{parent=None}, \emph{description=None}, \emph{commodity\_scu=None}, \emph{hidden=0}, \emph{placeholder=0}, \emph{code=None}}{}
Bases: \code{piecash.model\_declbase.DeclarativeBaseGuid}

A GnuCash Account which is specified by its name, type and commodity.
\index{account\_type (piecash.model\_core.account.Account attribute)}

\begin{fulllineitems}
\phantomsection\label{api/piecash.model_core.account:piecash.model_core.account.Account.account_type}\pysigline{\bfcode{account\_type}}
\emph{str}

type of the Account

\end{fulllineitems}

\index{code (piecash.model\_core.account.Account attribute)}

\begin{fulllineitems}
\phantomsection\label{api/piecash.model_core.account:piecash.model_core.account.Account.code}\pysigline{\bfcode{code}}
\emph{str}

code of the Account

\end{fulllineitems}

\index{commodity (piecash.model\_core.account.Account attribute)}

\begin{fulllineitems}
\phantomsection\label{api/piecash.model_core.account:piecash.model_core.account.Account.commodity}\pysigline{\bfcode{commodity}}
{\hyperref[api/piecash.model_core.commodity:piecash.model_core.commodity.Commodity]{\code{piecash.model\_core.commodity.Commodity}}}

the commodity of the account

\end{fulllineitems}

\index{commodity\_scu (piecash.model\_core.account.Account attribute)}

\begin{fulllineitems}
\phantomsection\label{api/piecash.model_core.account:piecash.model_core.account.Account.commodity_scu}\pysigline{\bfcode{commodity\_scu}}
\emph{int}

smallest currency unit for the account

\end{fulllineitems}

\index{non\_std\_scu (piecash.model\_core.account.Account attribute)}

\begin{fulllineitems}
\phantomsection\label{api/piecash.model_core.account:piecash.model_core.account.Account.non_std_scu}\pysigline{\bfcode{non\_std\_scu}}
\emph{int}

1 if the scu of the account is NOT the same as the commodity

\end{fulllineitems}

\index{description (piecash.model\_core.account.Account attribute)}

\begin{fulllineitems}
\phantomsection\label{api/piecash.model_core.account:piecash.model_core.account.Account.description}\pysigline{\bfcode{description}}
\emph{str}

description of the account

\end{fulllineitems}

\index{name (piecash.model\_core.account.Account attribute)}

\begin{fulllineitems}
\phantomsection\label{api/piecash.model_core.account:piecash.model_core.account.Account.name}\pysigline{\bfcode{name}}
\emph{str}

name of the account

\end{fulllineitems}

\index{fullname (piecash.model\_core.account.Account attribute)}

\begin{fulllineitems}
\phantomsection\label{api/piecash.model_core.account:piecash.model_core.account.Account.fullname}\pysigline{\bfcode{fullname}}
\emph{str}

full name of the account (including name of parent accounts separated by `:')

\end{fulllineitems}

\index{placeholder (piecash.model\_core.account.Account attribute)}

\begin{fulllineitems}
\phantomsection\label{api/piecash.model_core.account:piecash.model_core.account.Account.placeholder}\pysigline{\bfcode{placeholder}}
\emph{int}

1 if the account is a placeholder (should not be involved in transactions)

\end{fulllineitems}

\index{hidden (piecash.model\_core.account.Account attribute)}

\begin{fulllineitems}
\phantomsection\label{api/piecash.model_core.account:piecash.model_core.account.Account.hidden}\pysigline{\bfcode{hidden}}
\emph{int}

1 if the account is hidden

\end{fulllineitems}

\index{parent (piecash.model\_core.account.Account attribute)}

\begin{fulllineitems}
\phantomsection\label{api/piecash.model_core.account:piecash.model_core.account.Account.parent}\pysigline{\bfcode{parent}}
{\hyperref[api/piecash.model_core.account:piecash.model_core.account.Account]{\code{Account}}}

the parent account of the account (None for the root account of a book)

\end{fulllineitems}

\index{children (piecash.model\_core.account.Account attribute)}

\begin{fulllineitems}
\phantomsection\label{api/piecash.model_core.account:piecash.model_core.account.Account.children}\pysigline{\bfcode{children}}
list of {\hyperref[api/piecash.model_core.account:piecash.model_core.account.Account]{\code{Account}}}

the list of the children accounts

\end{fulllineitems}

\index{validate\_account\_name() (piecash.model\_core.account.Account method)}

\begin{fulllineitems}
\phantomsection\label{api/piecash.model_core.account:piecash.model_core.account.Account.validate_account_name}\pysiglinewithargsret{\bfcode{validate\_account\_name}}{\emph{key}, \emph{value}}{}
Ensure the account name is unique amongst its sibling accounts

\end{fulllineitems}

\index{validate\_account\_type() (piecash.model\_core.account.Account method)}

\begin{fulllineitems}
\phantomsection\label{api/piecash.model_core.account:piecash.model_core.account.Account.validate_account_type}\pysiglinewithargsret{\bfcode{validate\_account\_type}}{\emph{key}, \emph{value}}{}
Ensure the account type is consistent

\end{fulllineitems}

\index{validate\_commodity() (piecash.model\_core.account.Account method)}

\begin{fulllineitems}
\phantomsection\label{api/piecash.model_core.account:piecash.model_core.account.Account.validate_commodity}\pysiglinewithargsret{\bfcode{validate\_commodity}}{\emph{key}, \emph{value}}{}
Ensure update of commodity\_scu when commodity is changed

\end{fulllineitems}


\end{fulllineitems}



\subparagraph{piecash.model\_core.book module}
\label{api/piecash.model_core.book::doc}\label{api/piecash.model_core.book:module-piecash.model_core.book}\label{api/piecash.model_core.book:piecash-model-core-book-module}\index{piecash.model\_core.book (module)}\index{Book (class in piecash.model\_core.book)}

\begin{fulllineitems}
\phantomsection\label{api/piecash.model_core.book:piecash.model_core.book.Book}\pysiglinewithargsret{\strong{class }\code{piecash.model\_core.book.}\bfcode{Book}}{\emph{*args}, \emph{**kwargs}}{}
Bases: \code{piecash.model\_declbase.DeclarativeBaseGuid}

A Book represents an accounting book. A new GnuCash document contains only a single Book .
\index{root\_account (piecash.model\_core.book.Book attribute)}

\begin{fulllineitems}
\phantomsection\label{api/piecash.model_core.book:piecash.model_core.book.Book.root_account}\pysigline{\bfcode{root\_account}}
the root account of the book

\end{fulllineitems}

\index{root\_template (piecash.model\_core.book.Book attribute)}

\begin{fulllineitems}
\phantomsection\label{api/piecash.model_core.book:piecash.model_core.book.Book.root_template}\pysigline{\bfcode{root\_template}}
the root template account of the book (usage not yet clear...)

\end{fulllineitems}


\end{fulllineitems}



\subparagraph{piecash.model\_core.commodity module}
\label{api/piecash.model_core.commodity::doc}\label{api/piecash.model_core.commodity:module-piecash.model_core.commodity}\label{api/piecash.model_core.commodity:piecash-model-core-commodity-module}\index{piecash.model\_core.commodity (module)}\index{quandl\_fx() (in module piecash.model\_core.commodity)}

\begin{fulllineitems}
\phantomsection\label{api/piecash.model_core.commodity:piecash.model_core.commodity.quandl_fx}\pysiglinewithargsret{\code{piecash.model\_core.commodity.}\bfcode{quandl\_fx}}{\emph{fx\_mnemonic}, \emph{base\_mnemonic}, \emph{start\_date}}{}
Retrieve exchange rate of commodity fx in function of base

\end{fulllineitems}

\index{Commodity (class in piecash.model\_core.commodity)}

\begin{fulllineitems}
\phantomsection\label{api/piecash.model_core.commodity:piecash.model_core.commodity.Commodity}\pysiglinewithargsret{\strong{class }\code{piecash.model\_core.commodity.}\bfcode{Commodity}}{\emph{*args}, \emph{**kwargs}}{}
Bases: \code{piecash.model\_declbase.DeclarativeBaseGuid}

A GnuCash Commodity.
\index{cusip (piecash.model\_core.commodity.Commodity attribute)}

\begin{fulllineitems}
\phantomsection\label{api/piecash.model_core.commodity:piecash.model_core.commodity.Commodity.cusip}\pysigline{\bfcode{cusip}}
\emph{str}

cusip code

\end{fulllineitems}

\index{fraction (piecash.model\_core.commodity.Commodity attribute)}

\begin{fulllineitems}
\phantomsection\label{api/piecash.model_core.commodity:piecash.model_core.commodity.Commodity.fraction}\pysigline{\bfcode{fraction}}
\emph{int}

minimal unit of the commodity (e.g. 100 for 1/100)

\end{fulllineitems}

\index{namespace (piecash.model\_core.commodity.Commodity attribute)}

\begin{fulllineitems}
\phantomsection\label{api/piecash.model_core.commodity:piecash.model_core.commodity.Commodity.namespace}\pysigline{\bfcode{namespace}}
\emph{str}

CURRENCY for currencies, otherwise any string to group multiple commodities together

\end{fulllineitems}

\index{mnemonic (piecash.model\_core.commodity.Commodity attribute)}

\begin{fulllineitems}
\phantomsection\label{api/piecash.model_core.commodity:piecash.model_core.commodity.Commodity.mnemonic}\pysigline{\bfcode{mnemonic}}
\emph{str}

the ISO symbol for a currency or the stock symbol for stocks (used for online quotes)

\end{fulllineitems}

\index{quote\_flag (piecash.model\_core.commodity.Commodity attribute)}

\begin{fulllineitems}
\phantomsection\label{api/piecash.model_core.commodity:piecash.model_core.commodity.Commodity.quote_flag}\pysigline{\bfcode{quote\_flag}}
\emph{int}

1 if piecash/GnuCash quotes will retrieve online quotes for the commodity

\end{fulllineitems}

\index{quote\_source (piecash.model\_core.commodity.Commodity attribute)}

\begin{fulllineitems}
\phantomsection\label{api/piecash.model_core.commodity:piecash.model_core.commodity.Commodity.quote_source}\pysigline{\bfcode{quote\_source}}
\emph{str}

the quote source for GnuCash (piecash always use yahoo for stock and quandl for currencies

\end{fulllineitems}

\index{quote\_tz (piecash.model\_core.commodity.Commodity attribute)}

\begin{fulllineitems}
\phantomsection\label{api/piecash.model_core.commodity:piecash.model_core.commodity.Commodity.quote_tz}\pysigline{\bfcode{quote\_tz}}
\emph{str}

the timezone to assign on the online quotes

\end{fulllineitems}

\index{base\_currency (piecash.model\_core.commodity.Commodity attribute)}

\begin{fulllineitems}
\phantomsection\label{api/piecash.model_core.commodity:piecash.model_core.commodity.Commodity.base_currency}\pysigline{\bfcode{base\_currency}}
{\hyperref[api/piecash.model_core.commodity:piecash.model_core.commodity.Commodity]{\code{Commodity}}}

The base\_currency for a commodity:
\begin{itemize}
\item {} 
if the commodity is a currency, returns the ``default currency'' of the book (ie the one of the root\_account)

\item {} 
if the commodity is not a currency, returns the currency encoded in the quoted\_currency slot

\end{itemize}

\end{fulllineitems}

\index{prices (piecash.model\_core.commodity.Commodity attribute)}

\begin{fulllineitems}
\phantomsection\label{api/piecash.model_core.commodity:piecash.model_core.commodity.Commodity.prices}\pysigline{\bfcode{prices}}
iterator of {\hyperref[api/piecash.model_core.commodity:piecash.model_core.commodity.Price]{\code{Price}}}

iterator on prices related to the commodity (it is a sqlalchemy query underneath)

\end{fulllineitems}

\index{create\_currency\_from\_ISO() (piecash.model\_core.commodity.Commodity class method)}

\begin{fulllineitems}
\phantomsection\label{api/piecash.model_core.commodity:piecash.model_core.commodity.Commodity.create_currency_from_ISO}\pysiglinewithargsret{\strong{classmethod }\bfcode{create\_currency\_from\_ISO}}{\emph{iso\_code}, \emph{from\_web=False}}{}
Factory function to create a new currency from its ISO code
\begin{quote}\begin{description}
\item[{Parameters}] \leavevmode\begin{itemize}
\item {} 
\textbf{iso\_code} (\href{http://docs.python.org/library/functions.html\#str}{\emph{str}}) -- the ISO code of the currency (e.g. EUR for the euro)

\item {} 
\textbf{from\_web} (\href{http://docs.python.org/library/functions.html\#bool}{\emph{bool}}) -- True to get the info from the website, False to get it from the hardcoded currency\_ISO module

\end{itemize}

\item[{Returns}] \leavevmode
{\hyperref[api/piecash.model_core.commodity:piecash.model_core.commodity.Commodity]{\code{Commodity}}}: the currency as a commodity object

\end{description}\end{quote}

\end{fulllineitems}

\index{create\_stock\_from\_symbol() (piecash.model\_core.commodity.Commodity class method)}

\begin{fulllineitems}
\phantomsection\label{api/piecash.model_core.commodity:piecash.model_core.commodity.Commodity.create_stock_from_symbol}\pysiglinewithargsret{\strong{classmethod }\bfcode{create\_stock\_from\_symbol}}{\emph{symbol}}{}
Factory function to create a new stock from its symbol. The ISO code of the quoted currency of the stock is
stored in the slot ``quoted\_currency''.
\begin{quote}\begin{description}
\item[{Parameters}] \leavevmode
\textbf{symbol} (\href{http://docs.python.org/library/functions.html\#str}{\emph{str}}) -- the symbol for the stock (e.g. YHOO for the Yahoo! stock)

\item[{Returns}] \leavevmode
{\hyperref[api/piecash.model_core.commodity:piecash.model_core.commodity.Commodity]{\code{Commodity}}}: the stock as a commodity object

\end{description}\end{quote}

\begin{notice}{note}{Note:}
The information is gathered from a yql query to the yahoo.finance.quotes
The default currency in which the quote is traded is stored as a slot
\end{notice}

\begin{notice}{note}{Todo}

use `select * from yahoo.finance.sectors' and `select * from yahoo.finance.industry where id =''sector\_id'''
to retrieve name of stocks and allow therefore the creation of a stock by giving its ``stock name'' (or part of it).
This could also be used to retrieve all symbols related to the same company
\end{notice}

\end{fulllineitems}

\index{update\_prices() (piecash.model\_core.commodity.Commodity method)}

\begin{fulllineitems}
\phantomsection\label{api/piecash.model_core.commodity:piecash.model_core.commodity.Commodity.update_prices}\pysiglinewithargsret{\bfcode{update\_prices}}{\emph{start\_date=None}}{}
Retrieve online prices for the commodity:
\begin{itemize}
\item {} 
for currencies, it will get from quandl the exchange rates between the currency and its base\_currency

\item {} 
for stocks, it will get from yahoo the daily closing prices expressed in its base\_currency

\end{itemize}
\begin{quote}\begin{description}
\item[{Parameters}] \leavevmode
\textbf{start\_date} (\href{http://docs.python.org/library/datetime.html\#datetime.date}{\code{datetime.date}}) -- prices will be updated as of the start\_date. If None, start\_date is today

\end{description}\end{quote}

\begin{notice}{note}{Note:}
if prices are already available in the GnuCash file, the function will only retrieve prices as of the
max(start\_date, last quoted price date)
\end{notice}

\begin{notice}{note}{Todo}

add some frequency to retrieve prices only every X (week, month, ...)
\end{notice}

\end{fulllineitems}

\index{create\_stock\_accounts() (piecash.model\_core.commodity.Commodity method)}

\begin{fulllineitems}
\phantomsection\label{api/piecash.model_core.commodity:piecash.model_core.commodity.Commodity.create_stock_accounts}\pysiglinewithargsret{\bfcode{create\_stock\_accounts}}{\emph{broker\_account}, \emph{income\_account=None}, \emph{income\_account\_types='D/CL/I'}}{}
Create the multiple accounts used to track a single stock, ie:
\begin{itemize}
\item {} 
broker\_account/stock.mnemonic

\end{itemize}

and the following accounts depending on the income\_account\_types argument
\begin{itemize}
\item {} 
D = Income/Dividends/stock.mnemonic

\item {} 
CL = Income/Cap Gain (Long)/stock.mnemonic

\item {} 
CS = Income/Cap Gain (Short)/stock.mnemonic

\item {} 
I = Income/Interest/stock.mnemonic

\end{itemize}
\begin{quote}\begin{description}
\item[{Parameters}] \leavevmode\begin{itemize}
\item {} 
\textbf{broker\_account} ({\hyperref[api/piecash.model_core.account:piecash.model_core.account.Account]{\code{piecash.model\_core.account.Account}}}) -- the broker account where the account holding

\item {} 
\textbf{income\_account} ({\hyperref[api/piecash.model_core.account:piecash.model_core.account.Account]{\code{piecash.model\_core.account.Account}}}) -- the income account where the accounts holding

\item {} 
\textbf{income\_account\_types} (\href{http://docs.python.org/library/functions.html\#str}{\emph{str}}) -- ``/'' separated codes to drive the creation of income accounts

\end{itemize}

\item[{Returns}] \leavevmode
{\hyperref[api/piecash.model_core.account:piecash.model_core.account.Account]{\code{piecash.model\_core.account.Account}}}: the account under the broker\_account where the stock is held.

\end{description}\end{quote}

\end{fulllineitems}


\end{fulllineitems}

\index{Price (class in piecash.model\_core.commodity)}

\begin{fulllineitems}
\phantomsection\label{api/piecash.model_core.commodity:piecash.model_core.commodity.Price}\pysiglinewithargsret{\strong{class }\code{piecash.model\_core.commodity.}\bfcode{Price}}{\emph{commodity}, \emph{currency}, \emph{date}, \emph{value}, \emph{type=None}, \emph{source='piecash'}}{}
Bases: \code{piecash.model\_declbase.DeclarativeBaseGuid}

A single Price for a commodity.
\index{commodity (piecash.model\_core.commodity.Price attribute)}

\begin{fulllineitems}
\phantomsection\label{api/piecash.model_core.commodity:piecash.model_core.commodity.Price.commodity}\pysigline{\bfcode{commodity}}
{\hyperref[api/piecash.model_core.commodity:piecash.model_core.commodity.Commodity]{\code{Commodity}}}

commodity to which the Price relates

\end{fulllineitems}

\index{currency (piecash.model\_core.commodity.Price attribute)}

\begin{fulllineitems}
\phantomsection\label{api/piecash.model_core.commodity:piecash.model_core.commodity.Price.currency}\pysigline{\bfcode{currency}}
{\hyperref[api/piecash.model_core.commodity:piecash.model_core.commodity.Commodity]{\code{Commodity}}}

currency in which the Price is expressed

\end{fulllineitems}

\index{date (piecash.model\_core.commodity.Price attribute)}

\begin{fulllineitems}
\phantomsection\label{api/piecash.model_core.commodity:piecash.model_core.commodity.Price.date}\pysigline{\bfcode{date}}
\href{http://docs.python.org/library/datetime.html\#datetime.datetime}{\code{datetime.datetime}}

datetime object representing the time at which the price is relevant

\end{fulllineitems}

\index{source (piecash.model\_core.commodity.Price attribute)}

\begin{fulllineitems}
\phantomsection\label{api/piecash.model_core.commodity:piecash.model_core.commodity.Price.source}\pysigline{\bfcode{source}}
\emph{str}

source of the price

\end{fulllineitems}

\index{type (piecash.model\_core.commodity.Price attribute)}

\begin{fulllineitems}
\phantomsection\label{api/piecash.model_core.commodity:piecash.model_core.commodity.Price.type}\pysigline{\bfcode{type}}
\emph{str}

last, ask, bid, unknown, nav

\end{fulllineitems}

\index{value (piecash.model\_core.commodity.Price attribute)}

\begin{fulllineitems}
\phantomsection\label{api/piecash.model_core.commodity:piecash.model_core.commodity.Price.value}\pysigline{\bfcode{value}}
\href{http://docs.python.org/library/decimal.html\#decimal.Decimal}{\code{decimal.Decimal}}

the price itself

\end{fulllineitems}


\end{fulllineitems}



\subparagraph{piecash.model\_core.currency\_ISO module}
\label{api/piecash.model_core.currency_ISO::doc}\label{api/piecash.model_core.currency_ISO:module-piecash.model_core.currency_ISO}\label{api/piecash.model_core.currency_ISO:piecash-model-core-currency-iso-module}\index{piecash.model\_core.currency\_ISO (module)}\index{ISO\_type (class in piecash.model\_core.currency\_ISO)}

\begin{fulllineitems}
\phantomsection\label{api/piecash.model_core.currency_ISO:piecash.model_core.currency_ISO.ISO_type}\pysigline{\strong{class }\code{piecash.model\_core.currency\_ISO.}\bfcode{ISO\_type}}
Bases: \code{builtins.tuple}

ISO\_type(country, currency, mnemonic, cusip, fraction)
\index{\_\_getnewargs\_\_() (piecash.model\_core.currency\_ISO.ISO\_type method)}

\begin{fulllineitems}
\phantomsection\label{api/piecash.model_core.currency_ISO:piecash.model_core.currency_ISO.ISO_type.__getnewargs__}\pysiglinewithargsret{\bfcode{\_\_getnewargs\_\_}}{}{}
Return self as a plain tuple.  Used by copy and pickle.

\end{fulllineitems}

\index{\_\_getstate\_\_() (piecash.model\_core.currency\_ISO.ISO\_type method)}

\begin{fulllineitems}
\phantomsection\label{api/piecash.model_core.currency_ISO:piecash.model_core.currency_ISO.ISO_type.__getstate__}\pysiglinewithargsret{\bfcode{\_\_getstate\_\_}}{}{}
Exclude the OrderedDict from pickling

\end{fulllineitems}

\index{\_\_new\_\_() (piecash.model\_core.currency\_ISO.ISO\_type static method)}

\begin{fulllineitems}
\phantomsection\label{api/piecash.model_core.currency_ISO:piecash.model_core.currency_ISO.ISO_type.__new__}\pysiglinewithargsret{\strong{static }\bfcode{\_\_new\_\_}}{\emph{\_cls}, \emph{country}, \emph{currency}, \emph{mnemonic}, \emph{cusip}, \emph{fraction}}{}
Create new instance of ISO\_type(country, currency, mnemonic, cusip, fraction)

\end{fulllineitems}

\index{\_\_repr\_\_() (piecash.model\_core.currency\_ISO.ISO\_type method)}

\begin{fulllineitems}
\phantomsection\label{api/piecash.model_core.currency_ISO:piecash.model_core.currency_ISO.ISO_type.__repr__}\pysiglinewithargsret{\bfcode{\_\_repr\_\_}}{}{}
Return a nicely formatted representation string

\end{fulllineitems}

\index{country (piecash.model\_core.currency\_ISO.ISO\_type attribute)}

\begin{fulllineitems}
\phantomsection\label{api/piecash.model_core.currency_ISO:piecash.model_core.currency_ISO.ISO_type.country}\pysigline{\bfcode{country}}
Alias for field number 0

\end{fulllineitems}

\index{currency (piecash.model\_core.currency\_ISO.ISO\_type attribute)}

\begin{fulllineitems}
\phantomsection\label{api/piecash.model_core.currency_ISO:piecash.model_core.currency_ISO.ISO_type.currency}\pysigline{\bfcode{currency}}
Alias for field number 1

\end{fulllineitems}

\index{cusip (piecash.model\_core.currency\_ISO.ISO\_type attribute)}

\begin{fulllineitems}
\phantomsection\label{api/piecash.model_core.currency_ISO:piecash.model_core.currency_ISO.ISO_type.cusip}\pysigline{\bfcode{cusip}}
Alias for field number 3

\end{fulllineitems}

\index{fraction (piecash.model\_core.currency\_ISO.ISO\_type attribute)}

\begin{fulllineitems}
\phantomsection\label{api/piecash.model_core.currency_ISO:piecash.model_core.currency_ISO.ISO_type.fraction}\pysigline{\bfcode{fraction}}
Alias for field number 4

\end{fulllineitems}

\index{mnemonic (piecash.model\_core.currency\_ISO.ISO\_type attribute)}

\begin{fulllineitems}
\phantomsection\label{api/piecash.model_core.currency_ISO:piecash.model_core.currency_ISO.ISO_type.mnemonic}\pysigline{\bfcode{mnemonic}}
Alias for field number 2

\end{fulllineitems}


\end{fulllineitems}



\subparagraph{piecash.model\_core.session module}
\label{api/piecash.model_core.session::doc}\label{api/piecash.model_core.session:module-piecash.model_core.session}\label{api/piecash.model_core.session:piecash-model-core-session-module}\index{piecash.model\_core.session (module)}\index{Version (class in piecash.model\_core.session)}

\begin{fulllineitems}
\phantomsection\label{api/piecash.model_core.session:piecash.model_core.session.Version}\pysiglinewithargsret{\strong{class }\code{piecash.model\_core.session.}\bfcode{Version}}{\emph{**kwargs}}{}
Bases: \code{sqlalchemy.ext.declarative.api.DeclarativeBase}

The declarative class for the `versions' table.
\index{table\_name (piecash.model\_core.session.Version attribute)}

\begin{fulllineitems}
\phantomsection\label{api/piecash.model_core.session:piecash.model_core.session.Version.table_name}\pysigline{\bfcode{table\_name}}
The name of the table

\end{fulllineitems}

\index{table\_version (piecash.model\_core.session.Version attribute)}

\begin{fulllineitems}
\phantomsection\label{api/piecash.model_core.session:piecash.model_core.session.Version.table_version}\pysigline{\bfcode{table\_version}}
The version for the table

\end{fulllineitems}


\end{fulllineitems}

\index{GncSession (class in piecash.model\_core.session)}

\begin{fulllineitems}
\phantomsection\label{api/piecash.model_core.session:piecash.model_core.session.GncSession}\pysiglinewithargsret{\strong{class }\code{piecash.model\_core.session.}\bfcode{GncSession}}{\emph{session}, \emph{acquire\_lock=False}}{}
Bases: \code{builtins.object}

The GncSession represents a session to a GnuCash document. It is created through one of the two factory functions
{\hyperref[api/piecash.model_core.session:piecash.model_core.session.create_book]{\code{create\_book()}}} and {\hyperref[api/piecash.model_core.session:piecash.model_core.session.open_book]{\code{open\_book()}}}.

Canonical use is as a context manager like (the session is automatically closed at the end of the with block):

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{k}{with} \PYG{n}{create\PYGZus{}book}\PYG{p}{(}\PYG{p}{)} \PYG{k}{as} \PYG{n}{s}\PYG{p}{:}
    \PYG{o}{.}\PYG{o}{.}\PYG{o}{.}
\end{Verbatim}

\begin{notice}{note}{Note:}
If you do not use the context manager, do not forget to close the session explicitly (\code{s.close()})
to release any lock on the file/DB.
\end{notice}

The session puts at disposal several attributes to access the main objects of the GnuCash document:

\begin{Verbatim}[commandchars=\\\{\}]
\# to get the book and the root\_account
ra = s.book.root\_account

\# to get the list of accounts, commodities or transactions
for acc in s.accounts:  \# or s.commodities or s.transactions
    \# do something with acc

\# to get a specific element of these lists
EUR = s.commodities(namespace="CURRENCY", mnemonic="EUR")

\# to get a list of all objects of some class (even non core classes)
budgets = s.get(Budget)
\# or a specific object
budget = s.get(Budget, name="my first budget")
\end{Verbatim}

You can check a session has changes (new, deleted, changed objects) by getting the \code{s.is\_saved} property.
To save or cancel changes, use \code{s.save()} or \code{s.cancel()}:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{c}{\PYGZsh{} save a session if it is no saved (saving a unchanged session is a no\PYGZhy{}op)}
\PYG{k}{if} \PYG{o+ow}{not} \PYG{n}{s}\PYG{o}{.}\PYG{n}{is\PYGZus{}saved}\PYG{p}{:}
    \PYG{n}{s}\PYG{o}{.}\PYG{n}{save}\PYG{p}{(}\PYG{p}{)}
\end{Verbatim}
\index{sa\_session (piecash.model\_core.session.GncSession attribute)}

\begin{fulllineitems}
\phantomsection\label{api/piecash.model_core.session:piecash.model_core.session.GncSession.sa_session}\pysigline{\bfcode{sa\_session}}
the underlying sqlalchemy session

\end{fulllineitems}

\index{save() (piecash.model\_core.session.GncSession method)}

\begin{fulllineitems}
\phantomsection\label{api/piecash.model_core.session:piecash.model_core.session.GncSession.save}\pysiglinewithargsret{\bfcode{save}}{}{}
Save the changes to the file/DB (=commit transaction)

\end{fulllineitems}

\index{cancel() (piecash.model\_core.session.GncSession method)}

\begin{fulllineitems}
\phantomsection\label{api/piecash.model_core.session:piecash.model_core.session.GncSession.cancel}\pysiglinewithargsret{\bfcode{cancel}}{}{}
Cancel all the changes that have not been saved (=rollback transaction)

\end{fulllineitems}

\index{close() (piecash.model\_core.session.GncSession method)}

\begin{fulllineitems}
\phantomsection\label{api/piecash.model_core.session:piecash.model_core.session.GncSession.close}\pysiglinewithargsret{\bfcode{close}}{}{}
Close a session. Any changes not yet saved are rolled back. Any lock on the file/DB is released.

\end{fulllineitems}

\index{is\_saved (piecash.model\_core.session.GncSession attribute)}

\begin{fulllineitems}
\phantomsection\label{api/piecash.model_core.session:piecash.model_core.session.GncSession.is_saved}\pysigline{\bfcode{is\_saved}}
True if nothing has yet been changed (False otherwise)

\end{fulllineitems}

\index{book (piecash.model\_core.session.GncSession attribute)}

\begin{fulllineitems}
\phantomsection\label{api/piecash.model_core.session:piecash.model_core.session.GncSession.book}\pysigline{\bfcode{book}}
the single {\hyperref[api/piecash.model_core.book:piecash.model_core.book.Book]{\code{piecash.model\_core.book.Book}}} within the GnuCash session.

\end{fulllineitems}

\index{transactions (piecash.model\_core.session.GncSession attribute)}

\begin{fulllineitems}
\phantomsection\label{api/piecash.model_core.session:piecash.model_core.session.GncSession.transactions}\pysigline{\bfcode{transactions}}
gives easy access to all transactions in the document through a {\hyperref[api/piecash.model_common:piecash.model_common.CallableList]{\code{piecash.model\_common.CallableList}}}
of \code{piecash.model\_core.transaction.Transaction}

\end{fulllineitems}

\index{accounts (piecash.model\_core.session.GncSession attribute)}

\begin{fulllineitems}
\phantomsection\label{api/piecash.model_core.session:piecash.model_core.session.GncSession.accounts}\pysigline{\bfcode{accounts}}
gives easy access to all accounts in the document through a {\hyperref[api/piecash.model_common:piecash.model_common.CallableList]{\code{piecash.model\_common.CallableList}}}
of {\hyperref[api/piecash.model_core.account:piecash.model_core.account.Account]{\code{piecash.model\_core.account.Account}}}

\end{fulllineitems}

\index{commodities (piecash.model\_core.session.GncSession attribute)}

\begin{fulllineitems}
\phantomsection\label{api/piecash.model_core.session:piecash.model_core.session.GncSession.commodities}\pysigline{\bfcode{commodities}}
gives easy access to all commodities in the document through a {\hyperref[api/piecash.model_common:piecash.model_common.CallableList]{\code{piecash.model\_common.CallableList}}}
of {\hyperref[api/piecash.model_core.commodity:piecash.model_core.commodity.Commodity]{\code{piecash.model\_core.commodity.Commodity}}}

\end{fulllineitems}

\index{query (piecash.model\_core.session.GncSession attribute)}

\begin{fulllineitems}
\phantomsection\label{api/piecash.model_core.session:piecash.model_core.session.GncSession.query}\pysigline{\bfcode{query}}
proxy for the query function of the underlying sqlalchemy session

\end{fulllineitems}

\index{add (piecash.model\_core.session.GncSession attribute)}

\begin{fulllineitems}
\phantomsection\label{api/piecash.model_core.session:piecash.model_core.session.GncSession.add}\pysigline{\bfcode{add}}
proxy for the add function of the underlying sqlalchemy session

\end{fulllineitems}

\index{get() (piecash.model\_core.session.GncSession method)}

\begin{fulllineitems}
\phantomsection\label{api/piecash.model_core.session:piecash.model_core.session.GncSession.get}\pysiglinewithargsret{\bfcode{get}}{\emph{cls}, \emph{**kwargs}}{}
Generic getter for a GnuCash object in the \emph{GncSession}. If no kwargs is given, it returns the list of all
objects of type cls (uses the sqlalchemy session.query(cls).all()).
Otherwise, it gets the unique object which attributes match the kwargs
(uses the sqlalchemy session.query(cls).filter\_by(**kwargs).one() underneath):
\begin{quote}

\# to get the first account with name=''Income''
inc\_account = session.get(Account, name=''Income'')

\# to get all accounts
accs = session.get(Account)
\end{quote}
\begin{quote}\begin{description}
\item[{Parameters}] \leavevmode\begin{itemize}
\item {} 
\textbf{cls} -- the class of the object to retrieve (Account, Price, Budget,...)

\item {} 
\textbf{kwargs} -- the attributes to filter on

\end{itemize}

\item[{Returns}] \leavevmode
the unique object if it exists, raises exceptions otherwise

\end{description}\end{quote}

\end{fulllineitems}


\end{fulllineitems}

\index{create\_book() (in module piecash.model\_core.session)}

\begin{fulllineitems}
\phantomsection\label{api/piecash.model_core.session:piecash.model_core.session.create_book}\pysiglinewithargsret{\code{piecash.model\_core.session.}\bfcode{create\_book}}{\emph{sqlite\_file=None}, \emph{uri\_conn=None}, \emph{currency='EUR'}, \emph{overwrite=False}, \emph{keep\_foreign\_keys=False}, \emph{**kwargs}}{}
Create a new empty GnuCash book. If both sqlite\_file and uri\_conn are None, then an ``in memory'' sqlite book is created.
\begin{quote}\begin{description}
\item[{Parameters}] \leavevmode\begin{itemize}
\item {} 
\textbf{sqlite\_file} (\href{http://docs.python.org/library/functions.html\#str}{\emph{str}}) -- a path to an sqlite3 file

\item {} 
\textbf{uri\_conn} (\href{http://docs.python.org/library/functions.html\#str}{\emph{str}}) -- a sqlalchemy connection string

\item {} 
\textbf{currency} (\href{http://docs.python.org/library/functions.html\#str}{\emph{str}}) -- the ISO symbol of the default currency of the book

\item {} 
\textbf{overwrite} (\href{http://docs.python.org/library/functions.html\#bool}{\emph{bool}}) -- True if book should be deleted and recreated if it exists already

\item {} 
\textbf{keep\_foreign\_keys} (\href{http://docs.python.org/library/functions.html\#bool}{\emph{bool}}) -- True if the foreign keys should be kept (may not work at all with GnuCash)

\end{itemize}

\item[{Returns}] \leavevmode
the document as a gnucash session

\item[{Return type}] \leavevmode
{\hyperref[api/piecash.model_core.session:piecash.model_core.session.GncSession]{\code{GncSession}}}

\item[{Raises GnucashException}] \leavevmode
if document already exists and overwrite is False

\end{description}\end{quote}

\end{fulllineitems}

\index{open\_book() (in module piecash.model\_core.session)}

\begin{fulllineitems}
\phantomsection\label{api/piecash.model_core.session:piecash.model_core.session.open_book}\pysiglinewithargsret{\code{piecash.model\_core.session.}\bfcode{open\_book}}{\emph{sqlite\_file=None}, \emph{uri\_conn=None}, \emph{acquire\_lock=True}, \emph{readonly=True}, \emph{open\_if\_lock=False}, \emph{**kwargs}}{}
Open an existing GnuCash book
\begin{quote}\begin{description}
\item[{Parameters}] \leavevmode\begin{itemize}
\item {} 
\textbf{sqlite\_file} (\href{http://docs.python.org/library/functions.html\#str}{\emph{str}}) -- a path to an sqlite3 file

\item {} 
\textbf{uri\_conn} (\href{http://docs.python.org/library/functions.html\#str}{\emph{str}}) -- a sqlalchemy connection string

\item {} 
\textbf{acquire\_lock} (\href{http://docs.python.org/library/functions.html\#bool}{\emph{bool}}) -- acquire a lock on the file

\item {} 
\textbf{readonly} (\href{http://docs.python.org/library/functions.html\#bool}{\emph{bool}}) -- open the file as readonly (useful to play with and avoid any unwanted save)

\item {} 
\textbf{open\_if\_lock} (\href{http://docs.python.org/library/functions.html\#bool}{\emph{bool}}) -- open the file even if it is locked by another user
(using open\_if\_lock=True with readonly=False is not recommended)

\end{itemize}

\item[{Returns}] \leavevmode
the document as a gnucash session

\item[{Return type}] \leavevmode
{\hyperref[api/piecash.model_core.session:piecash.model_core.session.GncSession]{\code{GncSession}}}

\item[{Raises}] \leavevmode\begin{itemize}
\item {} 
\textbf{GnucashException} -- if the document does not exist

\item {} 
\textbf{GnucashException} -- if there is a lock on the file and open\_if\_lock is False

\end{itemize}

\end{description}\end{quote}

\end{fulllineitems}



\subparagraph{piecash.model\_core.transaction module}
\label{api/piecash.model_core.transaction::doc}\label{api/piecash.model_core.transaction:module-piecash.model_core.transaction}\label{api/piecash.model_core.transaction:piecash-model-core-transaction-module}\index{piecash.model\_core.transaction (module)}

\paragraph{Module contents}
\label{api/piecash.model_core:module-contents}\label{api/piecash.model_core:module-piecash.model_core}\index{piecash.model\_core (module)}

\subsection{Submodules}
\label{api/piecash:submodules}

\subsubsection{piecash.kvp module}
\label{api/piecash.kvp::doc}\label{api/piecash.kvp:module-piecash.kvp}\label{api/piecash.kvp:piecash-kvp-module}\index{piecash.kvp (module)}\index{SlotType (class in piecash.kvp)}

\begin{fulllineitems}
\phantomsection\label{api/piecash.kvp:piecash.kvp.SlotType}\pysiglinewithargsret{\strong{class }\code{piecash.kvp.}\bfcode{SlotType}}{\emph{*args}, \emph{**kwargs}}{}
Bases: \code{sqlalchemy.sql.type\_api.TypeDecorator}

Used to customise the DateTime type for sqlite (ie without the separators as in gnucash
\index{impl (piecash.kvp.SlotType attribute)}

\begin{fulllineitems}
\phantomsection\label{api/piecash.kvp:piecash.kvp.SlotType.impl}\pysigline{\bfcode{impl}}
alias of \code{INTEGER}

\end{fulllineitems}


\end{fulllineitems}



\subsubsection{piecash.metadata module}
\label{api/piecash.metadata::doc}\label{api/piecash.metadata:module-piecash.metadata}\label{api/piecash.metadata:piecash-metadata-module}\index{piecash.metadata (module)}
Project metadata

Information describing the project.


\subsubsection{piecash.model\_budget module}
\label{api/piecash.model_budget:piecash-model-budget-module}\label{api/piecash.model_budget::doc}\label{api/piecash.model_budget:module-piecash.model_budget}\index{piecash.model\_budget (module)}

\subsubsection{piecash.model\_business module}
\label{api/piecash.model_business::doc}\label{api/piecash.model_business:piecash-model-business-module}\label{api/piecash.model_business:module-piecash.model_business}\index{piecash.model\_business (module)}\index{composite() (in module piecash.model\_business)}

\begin{fulllineitems}
\phantomsection\label{api/piecash.model_business:piecash.model_business.composite}\pysiglinewithargsret{\code{piecash.model\_business.}\bfcode{composite}}{\emph{class\_}, \emph{*attrs}, \emph{**kwargs}}{}
Return a composite column-based property for use with a Mapper.

See the mapping documentation section  for a
full usage example.

The \code{MapperProperty} returned by {\hyperref[api/piecash.model_business:piecash.model_business.composite]{\code{composite()}}}
is the \code{CompositeProperty}.
\begin{quote}\begin{description}
\item[{Parameters}] \leavevmode\begin{itemize}
\item {} 
\textbf{class\_} -- The ``composite type'' class.

\item {} 
\textbf{*cols} -- List of Column objects to be mapped.

\item {} 
\textbf{active\_history=False} -- 
When \code{True}, indicates that the ``previous'' value for a
scalar attribute should be loaded when replaced, if not
already loaded.  See the same flag on \code{column\_property()}.

\DUspan{versionmodified}{Changed in version 0.7: }This flag specifically becomes meaningful
- previously it was a placeholder.


\item {} 
\textbf{group} -- A group name for this property when marked as deferred.

\item {} 
\textbf{deferred} -- When True, the column property is ``deferred'', meaning that it does
not load immediately, and is instead loaded when the attribute is
first accessed on an instance.  See also
\code{deferred()}.

\item {} 
\textbf{comparator\_factory} -- a class which extends
\code{CompositeProperty.Comparator} which provides custom SQL
clause generation for comparison operations.

\item {} 
\textbf{doc} -- optional string that will be applied as the doc on the
class-bound descriptor.

\item {} 
\textbf{info} -- 
Optional data dictionary which will be populated into the
\code{MapperProperty.info} attribute of this object.

\DUspan{versionmodified}{New in version 0.8.}


\item {} 
\textbf{extension} -- an \code{AttributeExtension} instance,
or list of extensions, which will be prepended to the list of
attribute listeners for the resulting descriptor placed on the
class.  \textbf{Deprecated.}  Please see \code{AttributeEvents}.

\end{itemize}

\end{description}\end{quote}

\end{fulllineitems}



\subsubsection{piecash.model\_common module}
\label{api/piecash.model_common::doc}\label{api/piecash.model_common:piecash-model-common-module}\label{api/piecash.model_common:module-piecash.model_common}\index{piecash.model\_common (module)}\index{hybrid\_property\_gncnumeric() (in module piecash.model\_common)}

\begin{fulllineitems}
\phantomsection\label{api/piecash.model_common:piecash.model_common.hybrid_property_gncnumeric}\pysiglinewithargsret{\code{piecash.model\_common.}\bfcode{hybrid\_property\_gncnumeric}}{\emph{num\_col}, \emph{denom\_col}}{}
Return an hybrid\_property handling a Decimal represented by a numerator and a denominator column.
It assumes the python field related to the sqlcolumn is named as \_sqlcolumn.
\begin{quote}\begin{description}
\item[{Returns}] \leavevmode
sqlalchemy.ext.hybrid.hybrid\_property

\end{description}\end{quote}

\end{fulllineitems}

\index{CallableList (class in piecash.model\_common)}

\begin{fulllineitems}
\phantomsection\label{api/piecash.model_common:piecash.model_common.CallableList}\pysigline{\strong{class }\code{piecash.model\_common.}\bfcode{CallableList}}
Bases: \code{builtins.list}

A simple class (inherited from list) allowing to retrieve a given list element with a filter on an attribute.

It can be used as the collection\_class of a sqlalchemy relationship or to wrap any list (see examples
in {\hyperref[api/piecash.model_core.session:piecash.model_core.session.GncSession]{\code{piecash.model\_core.session.GncSession}}})
\index{get() (piecash.model\_common.CallableList method)}

\begin{fulllineitems}
\phantomsection\label{api/piecash.model_common:piecash.model_common.CallableList.get}\pysiglinewithargsret{\bfcode{get}}{\emph{**kwargs}}{}
Return the first element of the list that has attributes matching the kwargs dict.
To be used as:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{n}{l}\PYG{o}{.}\PYG{n}{get}\PYG{p}{(}\PYG{n}{mnemonic}\PYG{o}{=}\PYG{l+s}{\PYGZdq{}}\PYG{l+s}{EUR}\PYG{l+s}{\PYGZdq{}}\PYG{p}{,} \PYG{n}{namespace}\PYG{o}{=}\PYG{l+s}{\PYGZdq{}}\PYG{l+s}{CURRENCY}\PYG{l+s}{\PYGZdq{}}\PYG{p}{)}
\end{Verbatim}

\end{fulllineitems}


\end{fulllineitems}

\index{cast() (in module piecash.model\_common)}

\begin{fulllineitems}
\phantomsection\label{api/piecash.model_common:piecash.model_common.cast}\pysiglinewithargsret{\code{piecash.model\_common.}\bfcode{cast}}{\emph{expression}, \emph{type\_}}{}
Produce a \code{CAST} expression.

{\hyperref[api/piecash.model_common:piecash.model_common.cast]{\code{cast()}}} returns an instance of \code{Cast}.

E.g.:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{k+kn}{from} \PYG{n+nn}{sqlalchemy} \PYG{k+kn}{import} \PYG{n}{cast}\PYG{p}{,} \PYG{n}{Numeric}

\PYG{n}{stmt} \PYG{o}{=} \PYG{n}{select}\PYG{p}{(}\PYG{p}{[}
            \PYG{n}{cast}\PYG{p}{(}\PYG{n}{product\PYGZus{}table}\PYG{o}{.}\PYG{n}{c}\PYG{o}{.}\PYG{n}{unit\PYGZus{}price}\PYG{p}{,} \PYG{n}{Numeric}\PYG{p}{(}\PYG{l+m+mi}{10}\PYG{p}{,} \PYG{l+m+mi}{4}\PYG{p}{)}\PYG{p}{)}
        \PYG{p}{]}\PYG{p}{)}
\end{Verbatim}

The above statement will produce SQL resembling:

\begin{Verbatim}[commandchars=\\\{\}]
SELECT CAST(unit\_price AS NUMERIC(10, 4)) FROM product
\end{Verbatim}

The {\hyperref[api/piecash.model_common:piecash.model_common.cast]{\code{cast()}}} function performs two distinct functions when
used.  The first is that it renders the \code{CAST} expression within
the resulting SQL string.  The second is that it associates the given
type (e.g. \code{TypeEngine} class or instance) with the column
expression on the Python side, which means the expression will take
on the expression operator behavior associated with that type,
as well as the bound-value handling and result-row-handling behavior
of the type.

\DUspan{versionmodified}{Changed in version 0.9.0: }{\hyperref[api/piecash.model_common:piecash.model_common.cast]{\code{cast()}}} now applies the given type
to the expression such that it takes effect on the bound-value,
e.g. the Python-to-database direction, in addition to the
result handling, e.g. database-to-Python, direction.

An alternative to {\hyperref[api/piecash.model_common:piecash.model_common.cast]{\code{cast()}}} is the \code{type\_coerce()} function.
This function performs the second task of associating an expression
with a specific type, but does not render the \code{CAST} expression
in SQL.
\begin{quote}\begin{description}
\item[{Parameters}] \leavevmode\begin{itemize}
\item {} 
\textbf{expression} -- A SQL expression, such as a \code{ColumnElement}
expression or a Python string which will be coerced into a bound
literal value.

\item {} 
\textbf{type} -- A \code{TypeEngine} class or instance indicating
the type to which the \code{CAST} should apply.

\end{itemize}

\end{description}\end{quote}


\strong{See also:}


\code{type\_coerce()} - Python-side type coercion without emitting
CAST.



\end{fulllineitems}



\subsubsection{piecash.model\_declbase module}
\label{api/piecash.model_declbase:module-piecash.model_declbase}\label{api/piecash.model_declbase::doc}\label{api/piecash.model_declbase:piecash-model-declbase-module}\index{piecash.model\_declbase (module)}

\subsubsection{piecash.sa\_extra module}
\label{api/piecash.sa_extra::doc}\label{api/piecash.sa_extra:module-piecash.sa_extra}\label{api/piecash.sa_extra:piecash-sa-extra-module}\index{piecash.sa\_extra (module)}\index{mapped\_to\_slot\_property() (in module piecash.sa\_extra)}

\begin{fulllineitems}
\phantomsection\label{api/piecash.sa_extra:piecash.sa_extra.mapped_to_slot_property}\pysiglinewithargsret{\code{piecash.sa\_extra.}\bfcode{mapped\_to\_slot\_property}}{\emph{col}, \emph{slot\_name}, \emph{slot\_transform=\textless{}function \textless{}lambda\textgreater{} at 0xb6cdd14c\textgreater{}}}{}
Assume the attribute in the class as the same name as the table column with ``\_'' prepended

\end{fulllineitems}

\index{get\_foreign\_keys() (in module piecash.sa\_extra)}

\begin{fulllineitems}
\phantomsection\label{api/piecash.sa_extra:piecash.sa_extra.get_foreign_keys}\pysiglinewithargsret{\code{piecash.sa\_extra.}\bfcode{get\_foreign\_keys}}{\emph{metadata}, \emph{engine}}{}
Retrieve all foreign keys from metadata bound to an engine
:param metadata:
:param engine:
:return:

\end{fulllineitems}



\subsection{Module contents}
\label{api/piecash:module-contents}\label{api/piecash:module-piecash}\index{piecash (module)}
Python GnuCash SQL interface

with an overall view on the core objects in GnuCash:


\section{GnuCash SQL Object model and schema}
\label{object_model::doc}\label{object_model:gnucash-sql-object-model-and-schema}
A clear documentation of the SQL schema (tables, columns, relationships) and the implicit semantic (invariants that should
be always satisfied, logic to apply in ambiguous/corner cases) is critical for piecash to
\begin{enumerate}
\item {} 
ensure data integrity (when creating new objects and/or modifying/deleting existing objects)

\item {} 
ensure compatibility in semantic with the official GnuCash application

\end{enumerate}

\begin{notice}{warning}{Warning:}
This document explains what the author understands in these domains. It is not the reference documentation, please refer
to the official GnuCash documentation for this.
\end{notice}

\begin{notice}{warning}{Warning:}
Disclaimer : piecash primary focus is on reading GnuCash books and creating new {\hyperref[object_model:core-objects]{Core objects}}.
Creating other objects than the core objects, modifying existing objects attributes or relationships and deleting
objects can be done through piecash but at the user's own risk (backup your books before doing any of such modifications)
\end{notice}


\section{Core objects}
\label{object_model:core-objects}
There are 5 core objects in GnuCash  : {\hyperref[object_model:book]{Book}}, {\hyperref[object_model:commodity]{Commodity}}, {\hyperref[object_model:account]{Account}}, {\hyperref[object_model:transaction]{Transaction}}, {\hyperref[object_model:split]{Split}}.
An additional object, the {\hyperref[object_model:price]{Price}}, is strongly linked to the Commodity and is used in reports and for display (for instance, to convert all accounts balance
in the default currency). While not as core as the others, it is an essential piece of functionality for anyone using
GnuCash to track a stock portfolio value or multi-currency book.

\begin{notice}{note}{Note:}
A priori, all these objects are all ``create once, never change'' objects. Changing some fields of an object may lead to
complex renormalisation procedures. Deleting some objects may lead to complex cascade changes/renormalisation procedures.
In this respect, it is important to either avoid changes/deletions or to have clear invariants that should stay true at any time.
\end{notice}


\subsection{Book}
\label{object_model:book}
The Book is the object model representing a GnuCash document. It has a link to the root account, the account at the
root of the tree structure.


\subsubsection{Fields}
\label{object_model:fields}\begin{description}
\item[{root\_account (mandatory)}] \leavevmode
The account at the root of the tree structure

\item[{root\_template (???)}] \leavevmode
Use to be investigated...

\end{description}


\subsubsection{Invariant}
\label{object_model:invariant}\begin{itemize}
\item {} 
one (and only one) Book per GnuCash document

\end{itemize}


\subsubsection{Questions}
\label{object_model:questions}\begin{itemize}
\item {} 
in the XML version, the book encapsulates the whole XML structure. If we had two books in a single xml document,
they would not share the commodities. In the C api, the creation of a commodity requires a Book.

In the SQL version, the book only has a root\_account. It has no directly link to the other objects. If we had to have
two Books in a single document, they would de facto share the Commodity/Price/etc as there is no explicit link between
the Commodity/Price/etc and the book ?

\end{itemize}


\subsection{Commodity}
\label{object_model:commodity}
A Commodity is either a currency (\texteuro{}, \$, ...) or a commodity/stock that can be stored in/traded through an Account.

The Commodity object is used in two different (but related) contexts.
\begin{enumerate}
\item {} 
each Account should specify the Commodity it handles/stores. For usual accounts (Savings, Expenses, etc), the Commodity
is a currency. For trading accounts, the Commodity is usually a stock (AMZN, etc).
In this role, each commodity (be it a stock or a currency) can have Prices attached to it that give the value of the
commodity expressed in a given currency.

\item {} 
each Transaction should specify the Currency which is used to balance itself.

\end{enumerate}


\subsubsection{Fields}
\label{object_model:id1}\begin{description}
\item[{namespace (mandatory)}] \leavevmode
A string representing the group/class of the commodity. All commodities that are currencies should have `CURRENCY' as
namespace. Non currency commodities should have other groups.

\item[{mnemonic (mandatory)}] \leavevmode
The symbol/stock sticker of the commodity (relevant for online download of quotes)

\item[{fullname}] \leavevmode
The full name for the commodity. Besides the fullname, there is a ``calculated property'' unique\_name equal to ``namespace::mnemonic''

\item[{cusip}] \leavevmode
unique code for the commodity

\item[{fraction}] \leavevmode
The smallest unit that can be accounted for (for a currency, this is equivalent to the scu, the smallest currency unit)
This is essentially used for a) display and b) roundings

\item[{quote\_flag}] \leavevmode
True if Prices for the commodity should be retrieved for the given stock. This is used by the ``quote download'' functionnality.

\item[{quote\_source}] \leavevmode
The source for online download of quotes

\end{description}


\subsubsection{Invariant}
\label{object_model:id2}\begin{itemize}
\item {} 
a currency commodity has namespace=='CURRENCY'

\item {} 
only currencies referenced by accounts or commodities are stored in the table `commodities' (the complete list of
currencies is available within the GnuCash application)

\item {} 
a stock commodity has namespace!='CURRENCY'

\end{itemize}


\subsubsection{Questions}
\label{object_model:id3}\begin{itemize}
\item {} 
is the guid of a currency hardcoded in GnuCash (as is the full list of currencies) or can it be assigned freely ?
the guid of the currency can be assigned freely

\end{itemize}


\subsection{Account}
\label{object_model:account}
An account tracks some commodity for some business purpose. Changes in the commodity amounts are modelled through Splits
(see Transaction \& Splits).


\subsubsection{Fields}
\label{object_model:id4}\begin{description}
\item[{account\_type (mandatory)}] \leavevmode
the type of the account as string

\item[{commodity (mandatory)}] \leavevmode
The commodity that is handled by the account

\item[{parent (almost mandatory)}] \leavevmode
the parent account to which the account is attached. All accounts but the root\_account should have a parent account.

\item[{commodity\_scu (mandatory)}] \leavevmode
The smallest currency/commodity unit is similar to the fraction of a commodity. It is the smallest amount of the commodity
that is tracked in the account. If it is different than the fraction of the commodity to which the account is linked,
the field non\_std\_scu is set to 1 (otherwise the latter is set to 0).

\item[{name}] \leavevmode
self-explanatory

\item[{description}] \leavevmode
self-explanatory

\item[{placeholder}] \leavevmode
if True/1, the account cannot be involved in transactions through splits (ie it can only be the parent of other accounts).
if False/0, the account can have Splits referring to it (as well as be the parent of other accounts).
This field, if True, is also stored as a Slot under the key ``placeholder'' as a string ``true''.

\item[{hidden}] \leavevmode
to be investigated

\end{description}


\subsubsection{Invariant}
\label{object_model:id5}\begin{itemize}
\item {} 
if placeholder, no Splits can refer to account

\item {} 
only two accounts can have account\_type ROOT (the root\_account and the root\_template of the book)

\end{itemize}


\subsubsection{Questions}
\label{object_model:id6}\begin{itemize}
\item {} 
changing the placeholder status of an account with splits in gnucash does not trigger any warning, is it normal ?
is the placeholder flag just informative (or used for reporting)  ?

\item {} 
are there any constrains on the account\_type of an account wrt account\_type of its parent ?

\end{itemize}
\phantomsection\label{object_model:transaction}

\subsection{Transaction \& Splits}
\label{object_model:transaction-splits}\label{object_model:split}\label{object_model:transaction}
The transaction represents movement of money between accounts expressed in a given currency (the currency of the transaction).
The transaction is modelled through a set of Splits (2 or more).
Each Split is linked to an Account and gives the increase/decrease in units of the account commodity (quantity)
related to the transaction as well as the equivalent amount in currency (value).
For a given transaction, the sum of the split expressed in the currency (value) should be balanced.


\subsubsection{Fields for Transaction}
\label{object_model:fields-for-transaction}\begin{description}
\item[{currency (mandatory)}] \leavevmode
The currency of the transaction

\item[{num (optional)}] \leavevmode
A transaction number (only used for information ?)

\item[{post\_date (mandatory)}] \leavevmode
self-explanatory. This field is also stored as a slot under the date-posted key (as a date instead of a time)

\item[{enter\_date (mandatory)}] \leavevmode
self-explanatory

\item[{description (mandatory)}] \leavevmode
self-explanatory

\end{description}


\subsubsection{Fields for Split}
\label{object_model:fields-for-split}\begin{description}
\item[{tx (mandatory)}] \leavevmode
the transaction of the split

\item[{account (mandatory)}] \leavevmode
the account to which the split refers to

\item[{value (mandatory)}] \leavevmode
the value of the split expressed in the currency of the transaction

\item[{quantity (mandatory)}] \leavevmode
the change in quantity of the account expressed in the commodity of the account

\item[{reconcile information}] \leavevmode
to be filled

\item[{lot}] \leavevmode
reference to the lot (to be investigated)

\end{description}


\subsubsection{Invariant}
\label{object_model:id7}\begin{itemize}
\item {} 
the sum of the value on all splits in a transaction should = 0 (transaction is balanced). If it is not the case, the
GnuCash application create automatically an extra Split entry towards the Account Imbalance-XXX (with XXX the currency
of the transaction)

\item {} 
the value and quantity fields are expressed as numerator / denominator. The denominator of the value should be
the same as the fraction of the currency. The denominator of the quantity should be the same as the commodity\_scu of
the account.

\end{itemize}


\subsubsection{Questions}
\label{object_model:id8}\begin{itemize}
\item {} 
how is the currency of the transaction defined ? is the default currency (in gnucash preferences) ? No.
Is it the currency (if any) of the account into which the transaction is initiated in the gui ? Yes.
Can this be changed through the GUI ? No (AFAIK)

\item {} 
what happens to the splits of an account that is removed ? in GUI, splits are either moved to other account or deleted
with a corresponding entry created in the Imbalance-XXX account.

\item {} 
what happens to the splits when the currency of a transaction is changed ? the quantity and value do not change
(irrespective of any exchange rate) ?

\end{itemize}


\subsection{Price}
\label{object_model:price}
The Price represent the value of a commodity in a given currency at some time.

It is used for exchange rates and stock valuation.


\subsubsection{Fields}
\label{object_model:id9}\begin{description}
\item[{commodity (mandatory)}] \leavevmode
the commodity related to the Price

\item[{currency (mandatory)}] \leavevmode
The currency of the Price

\item[{datetime (mandatory)}] \leavevmode
self-explanatory (expressed in UTC)

\item[{value (mandatory)}] \leavevmode
the value in currency of the commodity

\end{description}


\subsubsection{Invariant}
\label{object_model:id10}\begin{itemize}
\item {} 
the value is expressed as numerator / denominator. The denominator of the value should be
the same as the fraction of the currency.

\end{itemize}


\subsubsection{Questions}
\label{object_model:id11}
None

The todo list:
\begin{itemize}
\item {} 
write more tests

\item {} 
review non core objects (model\_budget, model\_business)

\end{itemize}


\chapter{Indices and tables}
\label{index:indices-and-tables}\begin{itemize}
\item {} 
\emph{genindex}

\item {} 
\emph{modindex}

\item {} 
\emph{search}

\end{itemize}


\renewcommand{\indexname}{Python Module Index}
\begin{theindex}
\def\bigletter#1{{\Large\sffamily#1}\nopagebreak\vspace{1mm}}
\bigletter{p}
\item {\texttt{piecash}}, \pageref{api/piecash:module-piecash}
\item {\texttt{piecash.kvp}}, \pageref{api/piecash.kvp:module-piecash.kvp}
\item {\texttt{piecash.metadata}}, \pageref{api/piecash.metadata:module-piecash.metadata}
\item {\texttt{piecash.model\_budget}}, \pageref{api/piecash.model_budget:module-piecash.model_budget}
\item {\texttt{piecash.model\_business}}, \pageref{api/piecash.model_business:module-piecash.model_business}
\item {\texttt{piecash.model\_common}}, \pageref{api/piecash.model_common:module-piecash.model_common}
\item {\texttt{piecash.model\_core}}, \pageref{api/piecash.model_core:module-piecash.model_core}
\item {\texttt{piecash.model\_core.account}}, \pageref{api/piecash.model_core.account:module-piecash.model_core.account}
\item {\texttt{piecash.model\_core.book}}, \pageref{api/piecash.model_core.book:module-piecash.model_core.book}
\item {\texttt{piecash.model\_core.commodity}}, \pageref{api/piecash.model_core.commodity:module-piecash.model_core.commodity}
\item {\texttt{piecash.model\_core.currency\_ISO}}, \pageref{api/piecash.model_core.currency_ISO:module-piecash.model_core.currency_ISO}
\item {\texttt{piecash.model\_core.session}}, \pageref{api/piecash.model_core.session:module-piecash.model_core.session}
\item {\texttt{piecash.model\_core.transaction}}, \pageref{api/piecash.model_core.transaction:module-piecash.model_core.transaction}
\item {\texttt{piecash.model\_declbase}}, \pageref{api/piecash.model_declbase:module-piecash.model_declbase}
\item {\texttt{piecash.sa\_extra}}, \pageref{api/piecash.sa_extra:module-piecash.sa_extra}
\end{theindex}

\renewcommand{\indexname}{Index}
\printindex
\end{document}
