..	Copyright 2013-2014, Marten de Vries
..
..	Licensed under the Apache License, Version 2.0 (the "License");
..	you may not use this file except in compliance with the License.
..	You may obtain a copy of the License at
..
..	http://www.apache.org/licenses/LICENSE-2.0
..
..	Unless required by applicable law or agreed to in writing, software
..	distributed under the License is distributed on an "AS IS" BASIS,
..	WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
..	See the License for the specific language governing permissions and
..	limitations under the License.

==============
Python-PouchDB
==============

Python-PouchDB_ is a Python wrapper for the `PouchDB JavaScript
library`_.

.. _Python-PouchDB: http://python-pouchdb.marten-de-vries.nl/
.. _PouchDB JavaScript library: http://pouchdb.com/

If you just want to use PouchDB like in JavaScript, check out the
:doc:`documentation for the pouchdb package <pouchdb>`. It's all you
need when using Python-PouchDB normally.

If you want to store Python objects (for JSON-serializable objects you
don't need this!) in your PouchDB, you have two options:

- :doc:`objectstorage`: Pickles Python objects using ``jsonpickle``
  and stores them in PouchDB. Easy to use, but less useful when other
  programs need to access the same database.
- :doc:`mapping`: Like the `couchdb.mapping module`_, this module
  provides one-on-one mapping of PouchDB documents onto Python objects.
  Cleaner, but more work to set up.

.. _couchdb.mapping module: https://pythonhosted.org/CouchDB/mapping.html

Python-PouchDB uses Qt to wrap PouchDB. This means you need one of its
Python bindings: PySide, PyQt4 or PyQt5. When multiple are installed,
it uses the one which is already imported at the time the
:py:mod:`pouchdb` module is imported (or chooses one itself when none
are).

Table of Contents
=================
.. toctree::
   :maxdepth: 1

   pouchdb
   objectstorage
   mapping
   tests
   js-plugins

PouchDB Plug-ins
================

Python-PouchDB not only wraps PouchDB, but also quite a few of its
plug-ins. Their Python API is described in the documentation for the
:mod:`pouchdb` package. The included plug-ins are as follows:

**Third party plug-ins:**

- `GQL <https://github.com/pouchdb/GQL>`_ (`documentation <http://pouchdb.com/gql.html>`_)
- `PouchDB All DBs <https://github.com/nolanlawson/pouchdb-all-dbs>`_
- `PouchDB Authentication <https://github.com/nolanlawson/pouchdb-authentication>`_
- `PouchDB Search <https://github.com/pouchdb/pouchdb-search>`_
- `PouchDB Spatial <https://github.com/pouchdb/geopouch>`_

**Plug-ins developed alongside Python-PouchDB:**

- :ref:`PouchDB List <pouchdb-list-plug-in>`
- :ref:`PouchDB Rewrite <pouchdb-rewrite-plug-in>`
- :ref:`PouchDB Show <pouchdb-show-plug-in>`
- :ref:`PouchDB Update <pouchdb-update-plug-in>`
- :ref:`PouchDB Validation <pouchdb-validation-plug-in>`

JavaScript documentation for the plug-ins developed alongside
Python-PouchDB is available on their :doc:`js-plugins` page.

For more information on the plug-ins developed alongside Python-PouchDB,
and download links for their browser versions, see `their common
webpage`_.

.. _their common webpage: http://python-pouchdb.marten-de-vries.nl/plugins.html