The pouchdb package mostly mirrors the PouchDB JavaScript API.
There are two API versions: one asynchronous one, which almost directly maps functions to their JavaScript equivalents and supports both promises and callbacks in most cases, and a synchronous one, which doesn’t have a JavaScript equivalent, but is often easier to use.
Synchronous:
>>> environment = setup()
>>> db = environment.PouchDB('example')
>>> printjson(db.put({"_id": 'my_example_doc'}))
{"id": "my_example_doc", "ok": true, "rev": "1-..."}
>>> printjson(db.get('my_example_doc'))
{"_id": "my_example_doc", "_rev": "1-..."}
and (using dict-like syntax):
>>> db["my_example_doc"] = {}
>>> printjson(db["my_example_doc"])
{"_id": "my_example_doc", "_rev": "2-..."}
Asynchronous:
>>> def callback(err, resp):
... printjson(["inside callback:", resp])
...
>>> env = setup(async=True)
>>> db = env.PouchDB('example')
>>> promise = db.post({}, callback)
or db.post({}).then(callback), with the err argument removed from the callback function. Time to run the event loop. Normally, that’s done using e.g. QtGui.QApplication().exec_(), but for testing purposes like this the following can be used:
>>> env.context.waitUntilCalled(callback)
["inside callback:", {"id": "...", "ok": true, "rev": "1-..."}]
>>> promise2 = env.destroy('example')
For more examples, see the The pouchdb.tests package documentation page.
Since the asynchronous and synchronous api have the same methods, those methods are documented in abstract base classes: AbstractEnvironment and AbstractPouchDB. Their subclasses (AsyncEnvironment, SyncEnvironment, AsyncPouchDB and SyncPouchDB) are the ones actually exposed to you in the API.
The names in the JavaScript API of PouchDB are in camelCase. Python-PouchDB provides snake_case aliases where necessary, since that’s the preffered form according to the PEP 8 style guide.
As shown in the example, you can pass in dictionaries as documents. Additionally, Python-PouchDB allows passing in JSON strings. So, no need to convert if you already have a JSON string.
Sets up an environment which allows access to the rest of the API, which mostly consists out of wrappers around PouchDB’s functions. This environment is then returned to the user.
Depending on the async parameter, this is either an instance of SyncEnvironment or AsyncEnvironment.
The storageDir is created automatically if it doesn’t already exist. It can be relative, and should be a directory (not a file). It’s where databases are saved (or more specific: WebKit’s backend database files). When it is None (the default), a temporary directory is created by Python-PouchDB, which is also removed at process exit. This function can raise an EnvironmentError when a storageDir other than one used earlier is passed in as a parameter. (That’s a Qt restriction, unfortunately.)
In older versions of QtWebKit, the same-origin policy is a little too strict which makes it impossible to replicate with databases that aren’t on the same domain as baseUrl. In newer versions, as long as baseUrl is file:///, this problem doesn’t exist. When you need to support the older version, you can set this to a domain so you can at least replicate to one site.
Raised when something is wrong relating to the environment in which Python-PouchDB runs.
All error responses PouchDB would normally give you get raised in the form of this error class in Python-PouchDB. You can use get item syntax to access properties set on the error object. E.g.:
>>> try:
... setup().PouchDB('new-db').get('unexisting-doc')
... except pouchdb.PouchDBError as e:
... if e["status"] == 404:
... print("Not found")
... else:
... print("Unknown error")
...
Not found
Documentation on the functionality of all methods is available in the abstract base class AbstractEnvironment. While coding, you get an instance of one of its subclasses: SyncEnvironment or AsyncEnvironment.
The environment is an event emitter and will emit a ‘created’ event when a database is created. A ‘destroy’ event is emited when a database is destroyed.
Don’t instantiate this class or one of its subclasses yourself, use the setup() function instead.
A shortcut for the PouchDB attribute. The following two lines of code are, as you can see, equivalent:
>>> setup()["test"]
<pouchdb.SyncPouchDB object at 0x...>
>>> setup().PouchDB('test')
<pouchdb.SyncPouchDB object at 0x...>
The value of what is PouchDB.version in JavaScript, in other words, the version of PouchDB that Python-PouchDB wraps.
The PouchDB class that you can use to make a new database instance. You should always use this: never instantiate SyncPouchDB or AsyncPouchDB manually.
Adds a listener to the end of the listeners array for the specified event.
Alias for addListener().
Wraps the pouchdb-all-dbs plug-in. Returns a list of the names of all local databases.
Allows access to the internals of Python-Pouch; only useful for debugging purposes. E.g. context.inspect() and context.waitUntilCalled(). The last is used by the test suite.
Allows you to destroy a database without creating a new PouchDB instance first.
The name argument in PouchDB is called name_ in Python-PouchDB, to prevent a clash with the options["name"] argument. In JavaScript where there are no keyword arguments the problem doesn’t exist, in Python it does, hence the change.
Execute each of the listeners in order with the supplied args. Returns True if event had listeners, False otherwise.
Alias for addListener().
Adds a one time listener for the event. This listener is invoked only the next time the event is fired, after which it is removed.
Remove a listener from the listener array for the specified event. Caution: changes array indices in the listener array behind the listener.
Alias for removeAllListeners().
Alias for removeListener().
Replicate data from source to target. Both the source and target can be a string representing a CouchDB database url or the name a local PouchDB database. If live is true, then this will track future changes and also replicate them automatically.
Wraps the pouchdb-all-dbs plug-in. Destroys the separate allDbs database. You should never need to call this function.
Alias for resetAllDbs().
By default EventEmitters will print a warning if more than 10 listeners are added for a particular event. This is a useful default which helps finding memory leaks. Obviously not all Emitters should be limited to 10. This function allows that to be increased. Set to zero for unlimited.
Alias for setMaxListeners().
Bases: pouchdb.AbstractEnvironment, _abcoll.Mapping
This class is a Mapping, which means it can be used like a dict. (Except for setting values, in this case).
See for all the methods that being a Mapping offers, the docs about it.
>>> env = setup()
>>> env.keys()
[...]
A shortcut for the AbstractEnvironment.destroy() method. The last two of the following lines of code are equivalent:
>>> env = setup()
>>> del env["test"]
>>> env.destroy("test")
Bases: pouchdb.AbstractEnvironment
Documentation on the functionality of all methods is available in the abstract base class AbstractPouchDB. While coding, you get an instance of one of its subclasses: SyncPouchDB or AsyncPouchDB.
Never instantiate this class or one of its subclasses yourself. Create an environment using the setup() function instead, and then use its AbstractEnvironment.PouchDB attribute, with the arguments specified at __init__().
Extra (optional) options for all AbstractPouchDB.validating* methods compared to their normal AbstractPouchDB.* counterparts are:
secObj: e.g.:
{
"admins": {
"names": [],
"roles": []
},
"members": {
"names": [],
"roles": []
}
}
userCtx: e.g.:
{
"db": "test_db",
"name": "username",
"roles": [
"_admin"
]
}
checkHttp: Set this to True if you want to validate HTTP database documents offline too. Unnecessary for CouchDB, but handy for e.g. PouchDB-Server, which doesn’t validate itself.
This method creates a database or opens an existing one. If you use a URL like http://domain.com/dbname then Python-PouchDB will work as a client to an online CouchDB instance. Otherwise it will create a local database using the WebSQL backend.
Fetch multiple documents. Deleted documents are only included if keys is specified.
Modify, create or delete multiple documents. The docs argument is an object with property docs which is an array of documents. You can also specify a new_edits property on the docs object that when set to false allows you to post existing documents.
If you omit an _id parameter on a given document, the database will create a new document and assign the ID for you. To update a document, you must include both an _id parameter and a _rev parameter, which should match the ID and revision of the document on which to base your updates. Finally, to delete a document, include a _deleted parameter with the value True.
Alias for bulkDocs().
A list of changes made to documents in the database, in the order they were made. It returns an object with one method cancel, which you call if you don’t want to listen to new changes anymore. onChange will be be called for each change that is encountered.
Runs compaction of the database. Fires callback when compaction is done. If you use the http adapter and have specified a callback, Pouch will ping the remote database in regular intervals unless the compaction is finished.
Get attachment data. Returns a dictionary with the following format:
{
"data": b"Bytes as byte string",
"type": "text/plain"
}
Returns information about the current session. In other words, this tells you which user is currently logged in.
Returns the user document associated with a username. (CouchDB, in a pleasing show of consistency, stores users as JSON documents in the special _users database.) This is the primary way to get metadata about a user.
Alias for get_attachment().
Alias for getSession().
Uses the GQL PouchDB plug-in. Check out its documentation.
The Google Query Language (GQL) interface provides an alternative method for accessing data. The version of GQL implemented here is based on the Google Visualization API Query Language.
The syntax of GQL queries should be familiar to those who have used SQL, but the capabilities of GQL are much more limited.
Same as requesting _list in CouchDB. Wraps the list PouchDB plug-in.
Log in an existing user. Throws an error if the user doesn’t exist yet, the password is wrong, the HTTP server is unreachable, or a meteor struck your computer.
Logs out whichever user is currently logged in. If nobody’s logged in, it does nothing and just returns {"ok": True}.
Create a new document or update an existing document. If the document already exists, you must specify its revision _rev, otherwise a conflict will occur.
Attaches a binary object to a document. Most of Python-PouchDB’s API deals with JSON, but if you’re dealing with large binary data (such as PNGs), you may incur a performance or storage penalty if you simply include them as base64- or hex-encoded strings. In these cases, you can store the binary data as an attachment.
Be aware that the argument order is different than in PouchDB due to the rev argument being optional. Byte strings replace blobs in Python-PouchDB. (e.g. b"Hello World!")
Alias for putAttachment().
Retrieves a view, which allows you to perform more complex queries on Python-PouchDB. The CouchDB documentation for map/ reduce applies to Python-PouchDB.
Since views perform a full scan of all documents, this method may be slow, unless you first save your view in a design document.
Deletes the document. doc is required to be a document with at least an _id and a _rev property. Sending the full document will work as well.
Alias for remove_attachment().
A shorthand for AbstractEnvironment.replicate()
A shorthand for AbstractEnvironment.replicate()
Alias for replicateFrom().
Alias for replicateTo().
Given a set of document/revision IDs, returns the subset of those that do not correspond to revisions stored in the database. Primarily used in replication.
Alias for revsDiff().
Same as sending a request to _rewrite in CouchDB. Wraps the rewrite PouchDB plug-in. The url has the form designDocName/rewritePath. Keep in mind that you need to use options.query instead of appending a ?key=value string to the url.
options:
See rewrite(). Instead of returning the result of the function that the rewrite routes to, this returns a CouchDB request object that points to the resource the rewrite resolves to. See also the CouchDB documentation on the request object.
Same as requesting _show in CouchDB. Wraps the show PouchDB plug-in.
Sign up a new user who doesn’t exist yet. Throws an error if the user already exists or if the username is invalid, or if some network error occurred. CouchDB has some limitations on user names (e.g. they cannot contain the character ‘:’).
Note: Signing up does not automatically log in a user; you will need to call login() afterwards.
Options:
Same as requesting _spatial in CouchDB when GeoCouch is installed. Wraps the geopouch plug-in.
A shorthand for AbstractEnvironment.sync()
Same as sending a request to _update in CouchDB. Wraps the update PouchDB plug-in.
options:
Same as bulkDocs(), but validates like in CouchDB. Wraps the validation PouchDB plug-in.
Same as post(), but validates like in CouchDB. Wraps the validation PouchDB plug-in.
Same as put(), but validates like in CouchDB. Wraps the validation PouchDB plug-in.
Same as putAttachment(), but validates like in CouchDB. Wraps the validation PouchDB plug-in.
Same as remove(), but validates like in CouchDB. Wraps the validation PouchDB plug-in.
Same as removeAttachment(), but validates like in CouchDB. Wraps the validation PouchDB plug-in.
Alias for validatingBulkDocs().
Alias for validatingPost().
Alias for validatingPut().
Alias for validatingPutAttachment().
Alias for validatingRemove().
Alias for validatingRemoveAttachment().
Cleans up any stale map/reduce indexes.
As design docs are deleted or modified, their associated index files (in CouchDB) or companion databases (in local PouchDBs) continue to take up space on disk. viewCleanup() removes these unnecessary index files.
Alias for viewCleanup().
Bases: pouchdb.AbstractPouchDB, _abcoll.MutableMapping
This class is a MutableMapping, which means it can be used like a dict. For details on how that works with revisions, see the documentations on the following methods: __getitem__(), __setitem__() and __delitem__().
See for all the methods that being a MutableMapping offers, the docs about it.
>>> db = setup()["my-example"]
>>> db["mytest"] = {"test": "ok"}
>>> printjson(list(db))
["mytest"]
>>> len(db)
1
>>> "mytest" in db
True
>>> "abc" in db
False
A shortcut for the AbstractPouchDB.get() method.
Raises a KeyError in place of a PouchDBError if that error’s status is 404 Not Found.
>>> db = setup().PouchDB("example")
>>> db["abc"]
Traceback (most recent call last):
...
KeyError: '{"status":404,"name":"not_found","message":"missing"}'
A shortcut for the AbstractPouchDB.remove() method.
Raises a KeyError in place of a PouchDBError if that error’s status is 404 Not Found. Removes the current document from the database (in other words, the latest revision is taken from the database).
>>> db = setup()["example"]
>>> del db["abc"]
Traceback (most recent call last):
...
KeyError: '{"status":404,"name":"not_found","message":"missing"}'
Sets doc‘s _id to docId and saves the result. When no doc["_rev"] is defined, the one from the current document saved under that id is reused. That is a difference from the normal AbstractPouchDB.put() method. When succesful, doc["_rev"] will have been set to its new value.
When the live or continuous option is active, this method acts like its asynchronous equivalent.
Because MutableMapping.get is overwritten by the get() method, it’s aliased under this name.
>>> printjson(db.get_("abc", {"hello": "world"}))
{"hello": "world"}
When the live or continuous option is active, this method acts like its asynchronous equivalent.
Bases: pouchdb.AbstractPouchDB
The GQL plug-in only supports the callback interface, it doesn’t provide a promise.
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 impossible to fix this restriction, it’s just not something that has a very high priority. Patches welcome!
Other unsupported things: