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

===================
The pouchdb package
===================

.. automodule:: pouchdb

API access point
================

.. autofunction:: setup

Errors
======

.. autoexception:: BaseError
.. autoexception:: EnvironmentError
.. autoexception:: PouchDBError

Environment
===========

Documentation on the functionality of all methods is available in the
abstract base class :py:class:`AbstractEnvironment`. While coding, you
get an instance of one of its subclasses: :py:class:`SyncEnvironment` or
:py:class:`AsyncEnvironment`.

Abstract
--------

.. autoclass:: AbstractEnvironment()
   :members:
   :undoc-members:

   .. automethod:: __getitem__

Implementations
---------------

.. autoclass:: SyncEnvironment()
   :members:
   :show-inheritance:

   .. automethod:: __delitem__

.. autoclass:: AsyncEnvironment()
   :members:
   :show-inheritance:

Database instance
=================

Documentation on the functionality of all methods is available in the
abstract base class :py:class:`AbstractPouchDB`. While coding, you get
an instance of one of its subclasses: :py:class:`SyncPouchDB` or
:py:class:`AsyncPouchDB`.

Abstract
--------

.. autoclass:: AbstractPouchDB()
   :members:
   :undoc-members:

   .. automethod:: __init__(name, **options)

Implementations
---------------

.. autoclass:: SyncPouchDB()
   :members:
   :show-inheritance:

   .. automethod:: __getitem__
   .. automethod:: __delitem__
   .. automethod:: __setitem__

.. autoclass:: AsyncPouchDB()
   :members:
   :show-inheritance:

Unsupported PouchDB APIs
========================

The wrapper that wraps Python-PouchDB isn't advanced enough to get a
return value of a Python function called from JavaScript. In most cases
this is no problem, but this prevents three things that you might expect
to work.

- It's not possible to pass a Python function reference as argument in
  the :meth:`AbstractPouchDB.query`. JavaScript functions and design doc
  paths are of course fine.
- It's not possible to pass database objects into the replicate
  functions. :meth:`AbstractPouchDB.replicate_from` and
  :meth:`AbstractPouchDB.replicate_to` allow you to use at least one
  :class:`AbstractPouchDB` object though, so you shouldn't have any
  problems because of this.
- It's not possible to write a PouchDB plug-in in Python. In other
  words, ``PouchDB.plug-in`` isn't implemented. But seriously, why would
  you ever want to do that anyway?

It's not impossible to fix this restriction, it's just not something
that has a very high priority. Patches welcome!

Other unsupported things:

- Accessing ``PouchDB.prefix``: Python-PouchDB is run in an isolated
  environment, accessing/changing it makes no sense. The value for the
  property is set by Python-PouchDB to be an empty string. (No _pouch_!)