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


\title{Momoko Documentation}
\date{January 28, 2013}
\release{1.0.0}
\author{Frank Smit}
\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@go\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.20,0.20,0.20}{##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@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@ge\endcsname{\let\PYG@it=\textit}
\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@kt\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.56,0.13,0.00}{##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@cp\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.00,0.44,0.13}{##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@kn\endcsname{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.00,0.44,0.13}{##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@gu\endcsname{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.50,0.00,0.50}{##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@kc\endcsname{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.00,0.44,0.13}{##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@gr\endcsname{\def\PYG@tc##1{\textcolor[rgb]{1.00,0.00,0.00}{##1}}}
\expandafter\def\csname PYG@tok@gs\endcsname{\let\PYG@bf=\textbf}
\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@sr\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.14,0.33,0.53}{##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@mo\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.13,0.50,0.31}{##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@mi\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.13,0.50,0.31}{##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@kd\endcsname{\let\PYG@bf=\textbf\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@il\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.13,0.50,0.31}{##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@s\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.25,0.44,0.63}{##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@sc\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.25,0.44,0.63}{##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@w\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.73,0.73,0.73}{##1}}}
\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@si\endcsname{\let\PYG@it=\textit\def\PYG@tc##1{\textcolor[rgb]{0.44,0.63,0.82}{##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@s1\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.25,0.44,0.63}{##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@c1\endcsname{\let\PYG@it=\textit\def\PYG@tc##1{\textcolor[rgb]{0.25,0.50,0.56}{##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@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@nf\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.02,0.16,0.49}{##1}}}
\expandafter\def\csname PYG@tok@s2\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.25,0.44,0.63}{##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@nc\endcsname{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.05,0.52,0.71}{##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@na\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.25,0.44,0.63}{##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@nn\endcsname{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.05,0.52,0.71}{##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@nl\endcsname{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.00,0.13,0.44}{##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@nv\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.73,0.38,0.84}{##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@vi\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.73,0.38,0.84}{##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@vg\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.73,0.38,0.84}{##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@vc\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.73,0.38,0.84}{##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}


Wraps (asynchronous) Psycopg2 for Tornado.

Momoko wraps Psycopg2 to make it suitable for use in Tornado using Psycopg2's
support for asynchronous connections. Momoko's API is geared towards use with
Tornado's \href{http://www.tornadoweb.org/documentation/gen.html}{gen} module, but also works fine without it.

Contents:


\chapter{Changelog}
\label{changelog:id1}\label{changelog:overview}\label{changelog:momoko}\label{changelog:changelog}\label{changelog::doc}

\section{1.0.0b2 (2013-01-??)}
\label{changelog:b2-2013-01}\begin{itemize}
\item {} 
Add and remove a database connection to and from the IOLoop for each operation.
See \href{https://github.com/FSX/momoko/pull/38}{pull request 38} and commits \href{https://github.com/FSX/momoko/commit/189323211bcb44ea158f41ddf87d4240c0e657d6}{189323211b} and \href{https://github.com/FSX/momoko/commit/92940db0a0f6d780724f42d3d66f1b75a78430ff}{92940db0a0} for more information.

\item {} 
Add support for \href{http://www.postgresql.org/docs/9.2/static/hstore.html}{hstore}.

\end{itemize}


\section{1.0.0b1 (2012-12-16)}
\label{changelog:hstore}\label{changelog:b1-2012-12-16}
This is a beta release. It means that the code has not been tested thoroughly
yet. This first beta release is meant to provide all the functionality of the
previous version plus a few additions.
\begin{itemize}
\item {} 
Most of the code has been rewritten.

\item {} 
The \href{http://initd.org/psycopg/docs/cursor.html\#cursor.mogrify}{mogrify} method has been added.

\item {} 
Added support for transactions.

\item {} 
The query chain and batch have been removed, because \code{tornado.gen} can be used instead.

\item {} 
Error reporting has bee improved by passing the raised exception to the callback.
A callback accepts two arguments: the cursor and the error.

\item {} 
\code{Op}, \code{WaitOp} and \code{WaitAllOps} in \code{momoko.utils} are wrappers for
classes in \code{tornado.gen} which raise the error again when one occurs.
And the user can capture the exception in the request handler.

\item {} 
A complete set of tests has been added in the \code{momoko} module: \code{momoko.tests}.
These can be run with \code{python setup.py test}.

\end{itemize}


\section{0.5.0 (2012-07-30)}
\label{changelog:id2}\label{changelog:mogrify}\begin{itemize}
\item {} 
Removed all Adisp related code.

\item {} 
Refactored connection pool and connection polling.

\item {} 
Just pass all unspecified arguments to \code{BlockingPool} and \code{AsyncPool}. So
\code{connection\_factory} can be used again.

\end{itemize}


\section{0.4.0 (2011-12-15)}
\label{changelog:id3}\begin{itemize}
\item {} 
Reorganized classes and files.

\item {} 
Renamed \code{momoko.Client} to \code{momoko.AsyncClient}.

\item {} 
Renamed \code{momoko.Pool} to \code{momoko.AsyncPool}.

\item {} 
Added a client and pool for blocking connections, \code{momoko.BlockingClient}
and \code{momoko.BlockingPool}.

\item {} 
Added \code{PoolError} to the import list in \code{\_\_init\_\_.py}.

\item {} 
Added an example that uses Tornado's \href{http://www.tornadoweb.org/documentation/gen.html}{gen} module and \href{http://code.naeseth.com/swirl/}{Swift}.

\item {} 
Callbacks are now optional for \code{AsyncClient}.

\item {} 
\code{AsyncPool} and \code{Poller} now accept a ioloop argument. {[}\href{https://github.com/fzzbt}{fzzbt}{]}

\item {} 
Unit tests have been added. {[}\href{https://github.com/fzzbt}{fzzbt}{]}

\end{itemize}


\section{0.3.0 (2011-08-07)}
\label{changelog:id4}\label{changelog:fzzbt}\begin{itemize}
\item {} 
Renamed \code{momoko.Momoko} to \code{momoko.Client}.

\item {} 
Programming in blocking-style is now possible with \code{AdispClient}.

\item {} 
Support for Python 3 has been added.

\item {} 
The batch and chain fucntion now accepts different arguments. See the
documentation for details.

\end{itemize}


\section{0.2.0 (2011-04-30)}
\label{changelog:id5}\begin{itemize}
\item {} 
Removed \code{executemany} from \code{Momoko}, because it can not be used in asynchronous mode.

\item {} 
Added a wrapper class, \code{Momoko}, for \code{Pool}, \code{BatchQuery} and \code{QueryChain}.

\item {} 
Added the \code{QueryChain} class for executing a chain of queries (and callables)
in a certain order.

\item {} 
Added the \code{BatchQuery} class for executing batches of queries at the same time.

\item {} 
Improved \code{Pool.\_clean\_pool}. It threw an \code{IndexError} when more than one
connection needed to be closed.

\end{itemize}


\section{0.1.0 (2011-03-13)}
\label{changelog:id6}\begin{itemize}
\item {} 
Initial release.

\end{itemize}


\chapter{Installation}
\label{installation:installation}\label{installation:id1}\label{installation::doc}
Momoko supports Python 2 and 3 and PyPy with \href{http://pypi.python.org/pypi/psycopg2ct}{psycopg2ct} or \href{http://pypi.python.org/pypi/psycopg2cffi}{psycopg2cffi}.
And the only dependencies are \href{http://www.tornadoweb.org/}{Tornado} and \href{http://initd.org/psycopg/}{Psycopg2} (or \href{http://pypi.python.org/pypi/psycopg2ct}{psycopg2ct}/\href{http://pypi.python.org/pypi/psycopg2cffi}{psycopg2cffi}).
Installation is easy using \emph{easy\_install} or \href{http://www.pip-installer.org/}{pip}:

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

The lastest source code can always be cloned from the \href{https://github.com/FSX/momoko}{Github repository} with:

\begin{Verbatim}[commandchars=\\\{\}]
git clone git://github.com/FSX/momoko.git
cd momoko
python setup.py install
\end{Verbatim}

Psycopg2 is used by default when installing Momoko, but psycopg2ct or psycopg2cffi
can also be used by setting the \code{MOMOKO\_PSYCOPG2\_IMPL} environment variable to
\code{psycopg2ct} or \code{psycopg2cffi} before running \code{setup.py}. For example:

\begin{Verbatim}[commandchars=\\\{\}]
\# 'psycopg2', 'psycopg2ct' or 'psycopg2cffi'
export MOMOKO\_PSYCOPG2\_IMPL='psycopg2cffi'
\end{Verbatim}

The unit tests als use this variable. It needs to be set if something else is used
instead of Psycopg2 when running the unit tests. Besides \code{MOMOKO\_PSYCOPG2\_IMPL}
there are also other variables that need to be set for the unit tests.

Here's an example for the environment variables:

\begin{Verbatim}[commandchars=\\\{\}]
export MOMOKO\_TEST\_DB='your\_db'  \# Default: momoko\_test
export MOMOKO\_TEST\_USER='your\_user'  \# Default: postgres
export MOMOKO\_TEST\_PASSWORD='your\_password'  \# Empty de default
export MOMOKO\_TEST\_HOST='localhost'  \# Empty de default
export MOMOKO\_TEST\_PORT='5432'  \# Default: 5432

\# Set to '0' if hstore extension isn't enabled
export MOMOKO\_TEST\_HSTORE='1'  \# Default: 0
\end{Verbatim}

And running the tests is easy:

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


\chapter{Tutorial}
\label{tutorial:github-repository}\label{tutorial:id1}\label{tutorial:tutorial}\label{tutorial::doc}
How does stuff work?
\begin{itemize}
\item {} 
Settings things up

\item {} 
Connecting

\item {} 
One simple query

\item {} 
Callproc and mogrify

\item {} 
Using tornado.gen

\item {} 
Simulating a batch (with a list of gen.Task), WaitOp, WaitAll

\item {} 
Difference betweens Momoko's utilities and Tornado's gen module.

\item {} 
Handling errors

\end{itemize}


\chapter{Testing}
\label{testing:id1}\label{testing:testing}\label{testing::doc}
Stuff about unit tests.
\phantomsection\label{api:api}\phantomsection\label{api:module-momoko}\phantomsection\label{api:api}\index{momoko (module)}

\chapter{API}
\label{api:id1}\label{api::doc}
Classes, methods and stuff.


\section{Connections}
\label{api:connections}\index{Pool (class in momoko)}

\begin{fulllineitems}
\phantomsection\label{api:momoko.Pool}\pysiglinewithargsret{\strong{class }\code{momoko.}\bfcode{Pool}}{\emph{dsn}, \emph{connection\_factory=None}, \emph{register\_hstore=False}, \emph{minconn=1}, \emph{maxconn=5}, \emph{cleanup\_timeout=10}, \emph{callback=None}, \emph{ioloop=None}}{}
Asynchronous connection pool.

The pool manages database connections and passes operations to connections.

See {\hyperref[api:momoko.Connection]{\code{momoko.Connection}}} for documentation about the \code{dsn} and
\code{connection\_factory} parameters. These are used by the connection pool when
a new connection is created.
\begin{quote}\begin{description}
\item[{Parameters}] \leavevmode\begin{itemize}
\item {} 
\textbf{register\_hstore} (\emph{boolean}) -- Register adapter and typecaster for \code{dict-hstore} conversions.

\item {} 
\textbf{minconn} (\emph{integer}) -- Amount of connections created upon initialization. Defaults to \code{1}.

\item {} 
\textbf{maxconn} (\emph{integer}) -- Maximum amount of connections allowed by the pool. Defaults to \code{5}.

\item {} 
\textbf{cleanup\_timeout} (\emph{integer}) -- Time in seconds between pool cleanups. Unused connections are closed and
removed from the pool until only \code{minconn} are left. When an integer
below \code{1}, like \code{-1} is used the pool cleaner will be disabled.
Defaults to \code{10}.

\item {} 
\textbf{callback} (\emph{callable}) -- A callable that's called after all the connections are created. Defaults to \code{None}.

\item {} 
\textbf{ioloop} -- An instance of Tornado's IOLoop. Defaults to \code{None}.

\end{itemize}

\end{description}\end{quote}
\index{callproc() (momoko.Pool method)}

\begin{fulllineitems}
\phantomsection\label{api:momoko.Pool.callproc}\pysiglinewithargsret{\bfcode{callproc}}{\emph{procname}, \emph{parameters=()}, \emph{cursor\_factory=None}, \emph{callback=None}, \emph{connection=None}}{}
Call a stored database procedure with the given name.

See {\hyperref[api:momoko.Connection.callproc]{\code{momoko.Connection.callproc()}}} for documentation about the
parameters. The \code{connection} parameter is for internal use.

\end{fulllineitems}

\index{close() (momoko.Pool method)}

\begin{fulllineitems}
\phantomsection\label{api:momoko.Pool.close}\pysiglinewithargsret{\bfcode{close}}{}{}
Close the connection pool.

\end{fulllineitems}

\index{execute() (momoko.Pool method)}

\begin{fulllineitems}
\phantomsection\label{api:momoko.Pool.execute}\pysiglinewithargsret{\bfcode{execute}}{\emph{operation}, \emph{parameters=()}, \emph{cursor\_factory=None}, \emph{callback=None}, \emph{connection=None}}{}
Prepare and execute a database operation (query or command).

See {\hyperref[api:momoko.Connection.execute]{\code{momoko.Connection.execute()}}} for documentation about the
parameters. The \code{connection} parameter is for internal use.

\end{fulllineitems}

\index{mogrify() (momoko.Pool method)}

\begin{fulllineitems}
\phantomsection\label{api:momoko.Pool.mogrify}\pysiglinewithargsret{\bfcode{mogrify}}{\emph{operation}, \emph{parameters=()}, \emph{callback=None}, \emph{connection=None}}{}
Return a query string after arguments binding.

See {\hyperref[api:momoko.Connection.mogrify]{\code{momoko.Connection.mogrify()}}} for documentation about the
parameters. The \code{connection} parameter is for internal use.

\end{fulllineitems}

\index{new() (momoko.Pool method)}

\begin{fulllineitems}
\phantomsection\label{api:momoko.Pool.new}\pysiglinewithargsret{\bfcode{new}}{\emph{callback=None}}{}
Create a new connection and add it to the pool.
\begin{quote}\begin{description}
\item[{Parameters}] \leavevmode
\textbf{callback} (\emph{callable}) -- A callable that's called after the connection is created. It accepts
one paramater: an instance of {\hyperref[api:momoko.Connection]{\code{momoko.Connection}}}. Defaults to \code{None}.

\end{description}\end{quote}

\end{fulllineitems}

\index{transaction() (momoko.Pool method)}

\begin{fulllineitems}
\phantomsection\label{api:momoko.Pool.transaction}\pysiglinewithargsret{\bfcode{transaction}}{\emph{statements}, \emph{cursor\_factory=None}, \emph{callback=None}, \emph{connection=None}}{}
Run a sequence of SQL queries in a database transaction.

See {\hyperref[api:momoko.Connection.transaction]{\code{momoko.Connection.transaction()}}} for documentation about the
parameters. The \code{connection} parameter is for internal use.

\end{fulllineitems}


\end{fulllineitems}

\index{Connection (class in momoko)}

\begin{fulllineitems}
\phantomsection\label{api:momoko.Connection}\pysiglinewithargsret{\strong{class }\code{momoko.}\bfcode{Connection}}{\emph{dsn}, \emph{connection\_factory=None}, \emph{callback=None}, \emph{ioloop=None}}{}
Create an asynchronous connection.
\begin{quote}\begin{description}
\item[{Parameters}] \leavevmode\begin{itemize}
\item {} 
\textbf{dsn} (\emph{string}) -- 
A \href{http://en.wikipedia.org/wiki/Data\_Source\_Name}{Data Source Name} string containing one of the following values:
\begin{itemize}
\item {} 
\textbf{dbname} - the database name

\item {} 
\textbf{user} - user name used to authenticate

\item {} 
\textbf{password} - password used to authenticate

\item {} 
\textbf{host} - database host address (defaults to UNIX socket if not provided)

\item {} 
\textbf{port} - connection port number (defaults to 5432 if not provided)

\end{itemize}

Or any other parameter supported by PostgreSQL. See the PostgreSQL
documentation for a complete list of supported \href{http://www.postgresql.org/docs/current/static/libpq-connect.html\#LIBPQ-PQCONNECTDBPARAMS}{parameters}.


\item {} 
\textbf{connection\_factory} -- The \code{connection\_factory} argument can be used to create non-standard
connections. The class returned should be a subclass of \href{http://initd.org/psycopg/docs/connection.html\#connection}{psycopg2.extensions.connection}.
See \href{http://initd.org/psycopg/docs/advanced.html\#subclassing-cursor}{Connection and cursor factories} for details. Defaults to \code{None}.

\item {} 
\textbf{callback} (\emph{callable}) -- A callable that's called after the connection is created. It accepts one
paramater: an instance of {\hyperref[api:momoko.Connection]{\code{momoko.Connection}}}. Defaults to \code{None}.

\item {} 
\textbf{ioloop} -- An instance of Tornado's IOLoop. Defaults to \code{None}.

\end{itemize}

\end{description}\end{quote}
\index{busy() (momoko.Connection method)}

\begin{fulllineitems}
\phantomsection\label{api:momoko.Connection.busy}\pysiglinewithargsret{\bfcode{busy}}{}{}
Check if the connection is busy or not.

\end{fulllineitems}

\index{callproc() (momoko.Connection method)}

\begin{fulllineitems}
\phantomsection\label{api:momoko.Connection.callproc}\pysiglinewithargsret{\bfcode{callproc}}{\emph{procname}, \emph{parameters=()}, \emph{cursor\_factory=None}, \emph{callback=None}}{}
Call a stored database procedure with the given name.

The sequence of parameters must contain one entry for each argument that
the procedure expects. The result of the call is returned as modified copy
of the input sequence. Input parameters are left untouched, output and
input/output parameters replaced with possibly new values.

The procedure may also provide a result set as output. This must then be
made available through the standard \href{http://initd.org/psycopg/docs/cursor.html\#fetch}{fetch*()} methods.
\begin{quote}\begin{description}
\item[{Parameters}] \leavevmode\begin{itemize}
\item {} 
\textbf{operation} (\emph{string}) -- The name of the database procedure.

\item {} 
\textbf{parameters} (\emph{tuple/list}) -- A list or tuple with query parameters. See \href{http://initd.org/psycopg/docs/usage.html\#query-parameters}{Passing parameters to SQL queries}
for more information. Defaults to an empty tuple.

\item {} 
\textbf{cursor\_factory} -- The \code{cursor\_factory} argument can be used to create non-standard cursors.
The class returned must be a subclass of \href{http://initd.org/psycopg/docs/extensions.html\#psycopg2.extensions.cursor}{psycopg2.extensions.cursor}.
See \href{http://initd.org/psycopg/docs/advanced.html\#subclassing-cursor}{Connection and cursor factories} for details. Defaults to \code{None}.

\item {} 
\textbf{callback} (\emph{callable}) -- A callable that is executed when the query has finished. It must accept
two positional parameters. The first one being the cursor and the second
one \code{None} or an instance of an exception if an error has occurred,
in that case the first parameter will be \code{None}. Defaults to \code{None}.

\end{itemize}

\end{description}\end{quote}

\end{fulllineitems}

\index{close() (momoko.Connection method)}

\begin{fulllineitems}
\phantomsection\label{api:momoko.Connection.close}\pysiglinewithargsret{\bfcode{close}}{}{}
Remove the connection from the IO loop and close it.

\end{fulllineitems}

\index{closed (momoko.Connection attribute)}

\begin{fulllineitems}
\phantomsection\label{api:momoko.Connection.closed}\pysigline{\bfcode{closed}}
Indicates whether the connection is closed or not.

\end{fulllineitems}

\index{execute() (momoko.Connection method)}

\begin{fulllineitems}
\phantomsection\label{api:momoko.Connection.execute}\pysiglinewithargsret{\bfcode{execute}}{\emph{operation}, \emph{parameters=()}, \emph{cursor\_factory=None}, \emph{callback=None}}{}
Prepare and execute a database operation (query or command).
\begin{quote}\begin{description}
\item[{Parameters}] \leavevmode\begin{itemize}
\item {} 
\textbf{operation} (\emph{string}) -- An SQL query.

\item {} 
\textbf{parameters} (\emph{tuple/list}) -- A list or tuple with query parameters. See \href{http://initd.org/psycopg/docs/usage.html\#query-parameters}{Passing parameters to SQL queries}
for more information. Defaults to an empty tuple.

\item {} 
\textbf{cursor\_factory} -- The \code{cursor\_factory} argument can be used to create non-standard cursors.
The class returned must be a subclass of \href{http://initd.org/psycopg/docs/extensions.html\#psycopg2.extensions.cursor}{psycopg2.extensions.cursor}.
See \href{http://initd.org/psycopg/docs/advanced.html\#subclassing-cursor}{Connection and cursor factories} for details. Defaults to \code{None}.

\item {} 
\textbf{callback} (\emph{callable}) -- A callable that is executed when the query has finished. It must accept
two positional parameters. The first one being the cursor and the second
one \code{None} or an instance of an exception if an error has occurred,
in that case the first parameter will be \code{None}. Defaults to \code{None}.

\end{itemize}

\end{description}\end{quote}

\end{fulllineitems}

\index{mogrify() (momoko.Connection method)}

\begin{fulllineitems}
\phantomsection\label{api:momoko.Connection.mogrify}\pysiglinewithargsret{\bfcode{mogrify}}{\emph{operation}, \emph{parameters=()}, \emph{callback=None}}{}
Return a query string after arguments binding.

The string returned is exactly the one that would be sent to the database
running the execute() method or similar.
\begin{quote}\begin{description}
\item[{Parameters}] \leavevmode\begin{itemize}
\item {} 
\textbf{operation} (\emph{string}) -- An SQL query.

\item {} 
\textbf{parameters} (\emph{tuple/list}) -- A list or tuple with query parameters. See \href{http://initd.org/psycopg/docs/usage.html\#query-parameters}{Passing parameters to SQL queries}
for more information. Defaults to an empty tuple.

\item {} 
\textbf{callback} (\emph{callable}) -- A callable that is executed when the query has finished. It must accept
two positional parameters. The first one being the resulting query as
a byte string and the second one \code{None} or an instance of an exception
if an error has occurred. Defaults to \code{None}.

\end{itemize}

\end{description}\end{quote}

\end{fulllineitems}

\index{transaction() (momoko.Connection method)}

\begin{fulllineitems}
\phantomsection\label{api:momoko.Connection.transaction}\pysiglinewithargsret{\bfcode{transaction}}{\emph{statements}, \emph{cursor\_factory=None}, \emph{callback=None}}{}
Run a sequence of SQL queries in a database transaction.
\begin{quote}\begin{description}
\item[{Parameters}] \leavevmode\begin{itemize}
\item {} 
\textbf{statements} (\emph{tuple/list}) -- 
List or tuple containing SQL queries with or without parameters. An item
can be a string (SQL query without parameters) or a tuple/list with two items,
an SQL query and a tuple/list wuth parameters. An example:

See \href{http://initd.org/psycopg/docs/usage.html\#query-parameters}{Passing parameters to SQL queries} for more information.


\item {} 
\textbf{cursor\_factory} -- The \code{cursor\_factory} argument can be used to create non-standard cursors.
The class returned must be a subclass of \href{http://initd.org/psycopg/docs/extensions.html\#psycopg2.extensions.cursor}{psycopg2.extensions.cursor}.
See \href{http://initd.org/psycopg/docs/advanced.html\#subclassing-cursor}{Connection and cursor factories} for details. Defaults to \code{None}.

\item {} 
\textbf{callback} (\emph{callable}) -- A callable that is executed when the transaction has finished. It must accept
two positional parameters. The first one being a list of cursors in the same
order as the given statements and the second one \code{None} or an instance of
an exception if an error has occurred, in that case the first parameter is
an empty list. Defaults to \code{None}.

\end{itemize}

\end{description}\end{quote}

\end{fulllineitems}


\end{fulllineitems}



\section{Utilities}
\label{api:utilities}\index{Op (class in momoko)}

\begin{fulllineitems}
\phantomsection\label{api:momoko.Op}\pysiglinewithargsret{\strong{class }\code{momoko.}\bfcode{Op}}{\emph{func}, \emph{*args}, \emph{**kwargs}}{}
Run a single asynchronous operation.

Behaves like \href{http://www.tornadoweb.org/documentation/gen.html\#tornado.gen.Task}{tornado.gen.Task}, but raises an exception (one of Psycop2's
\href{http://initd.org/psycopg/docs/module.html\#exceptions}{exceptions}) when an error occurs related to Psycopg2 or PostgreSQL.

\end{fulllineitems}

\index{WaitOp (class in momoko)}

\begin{fulllineitems}
\phantomsection\label{api:momoko.WaitOp}\pysiglinewithargsret{\strong{class }\code{momoko.}\bfcode{WaitOp}}{\emph{key}}{}
Return the argument passed to the result of a previous \href{http://www.tornadoweb.org/documentation/gen.html\#tornado.gen.Callback}{tornado.gen.Callback}.

Behaves like \href{http://www.tornadoweb.org/documentation/gen.html\#tornado.gen.Wait}{tornado.gen.Wait}, but raises an exception (one of Psycop2's
\href{http://initd.org/psycopg/docs/module.html\#exceptions}{exceptions}) when an error occurs related to Psycopg2 or PostgreSQL.

\end{fulllineitems}

\index{WaitAllOps (class in momoko)}

\begin{fulllineitems}
\phantomsection\label{api:momoko.WaitAllOps}\pysiglinewithargsret{\strong{class }\code{momoko.}\bfcode{WaitAllOps}}{\emph{keys}}{}
Return the results of multiple previous \href{http://www.tornadoweb.org/documentation/gen.html\#tornado.gen.Callback}{tornado.gen.Callback}.

Behaves like \href{http://www.tornadoweb.org/documentation/gen.html\#tornado.gen.WaitAll}{tornado.gen.WaitAll}, but raises an exception (one of Psycop2's
\href{http://initd.org/psycopg/docs/module.html\#exceptions}{exceptions}) when an error occurs related to Psycopg2 or PostgreSQL.

\end{fulllineitems}



\section{Exceptions}
\label{api:id14}\index{PoolError (class in momoko)}

\begin{fulllineitems}
\phantomsection\label{api:momoko.PoolError}\pysigline{\strong{class }\code{momoko.}\bfcode{PoolError}}
The \code{PoolError} exception is raised when something goes wrong in the connection
pool. When the maximum amount is exceeded for example.

\end{fulllineitems}



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

\item {} 
\emph{search}

\end{itemize}


\renewcommand{\indexname}{Python Module Index}
\begin{theindex}
\def\bigletter#1{{\Large\sffamily#1}\nopagebreak\vspace{1mm}}
\bigletter{m}
\item {\texttt{momoko}}, \pageref{api:module-momoko}
\end{theindex}

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