This module consists of two different classes indicating query result, TrombiObject and TrombiError, first for the succesful API response and the latter for errorneus API response. All classes representing different data objects of CouchDB subclass TrombiObject.
A common error class indicating that an error has happened
Indicates that error happened. Always True.
Returned upon errorneus CouchDB API call. This is generally a call that results in other than 2xx response code.
Subclasses TrombiError.
Error number. Trombi error numbers are available in trombi.errors. Unless something really odd happened, it’s one of the following:
These map to HTTP error codes respectively.
A custom error code to distinct from overloaded errors.SERVER_ERROR. Means that the database name was invalid. Note: This can be returned without connecting to database, so your callback method might be called immediately without going back to the IOLoop.
Returned upon succesful CouchDB call. This is also superclass for all data object classes presented below.
Indicates succesful response, always False.
A generic result indicating a succesfull call. Used for example in Database.list(). Subclasses TrombiObject.
Contains the result of the query. The result format is not specified.
A special result object that represents a succesful view result. Subclasses TrombiObject and collections.Sequence.
Due to the subclassing of collections.Sequence, behaves kind of like a tuple. Supports len(), accessing items with dictionary like syntax and iterating over result rows using iter().
Total rows of the view as returned by CouchDB
Offset of the view as returned by CouchDB
A special result object for CouchDB’s bulk API responses. Subclasses TrombiObject and collections.Sequence.
Due to the subclassing of collections.Sequence, behaves kind of like a tuple. Supports len(), accessing items with dictionary like syntax and iterating over result iter().
The processed bulk API response content. Consists of instances of either BulkObject or BulkError.
A special result object for a single successful CouchDB’s bulk API response. Subclasses TrombiObject and collections.Mapping.
Due to the subclassing of collections.Mapping, behaves like a immutable dictionary. Can be converted to a dictionary object using built-in function dict().
Indicates a single error response from bulk API. Subclasses TrombiError.
The error type given by bulk API
The reason given by bulk API
In case of an error, if not otherwise mentioned, all the following methods call callback function with TrombiError as an argument.
Represents the connection to a CouchDB server. Subclass of TrombiObject.
Has one required argument baseurl which is an URI to CouchDB database. If the baseurl ends in a slash (/), it is removed.
To ease testing a custom tornado.ioloop.IOLoop instance can be passed as a keyword argument.
Indicates an error, always False.
Provides a way to pass in additional keyword arguments to the tornado’s AsyncHTTPClient.fetch() call. In particular, by passing in auth_username and auth_password as keyword arguments, we can now use CouchDB servers using HTTP Basic Authentication.
A custom json_encoder can be defined with parameter json_encoder. At this point, this encoder is only used when adding or modifying documents.
These additional arguments are directly passed to the AsyncHTTPClient() upon creation. This way the user can configure the underlying HTTP client, for example to allow more concurrent connections by passing max_simultaneous_connections keyword argument.
Creates a new database. Has two required arguments, the name of the new database and the callback function.
On success the callback function is called with newly created Database as an argument.
Tries to open database named name. Optional keyword argument create can be given to indicate that if the database does not exist, trombi tries to create it. As with create(), calls the callback with a Database on success.
Deletes a database named name. On success, calls callback with an empty TrombiObject as an argument.
Lists available databases. On success, calls callback with a generator object containing all databases.
In case of an error, if not otherwise mentioned, all the following methods call callback function with TrombiError as an argument.
Represents a CouchDB database. Has two required argument, server and name where server denotes the Server where database is and name is the name of the database.
Normally there’s no need to create Database objects as they are created via Server.create() and Server.get(). Subclass of TrombiObject.
Creates a new or modifies an existing document in the database. If called with three arguments, the first argument, doc_id is the document id of the new or existing document. If only two arguments are given the document id is generated by the database. data is the data to the document, either a Python dict or an instance of Document. doc_id can be omitted if data is an existing document.
This method makes distinction between creating a new document and updating an existing by inspecting the data argument. If data is a Document with attributes rev and id set, it tries to update existing document. Otherwise it tries to create a new document containing data.
Inline attachments can be passed to function with optional keyword argument attachments. attachments is a dict with a format somewhat similiar to CouchDB:
{<attachment_name>: (<content_type>, <data>)}
If content_type is None, text/plain is assumed.
On succesful creation or update the callback is called with Document as an argument.
Loads a document doc_id from the database. If optional keyword argument attachments is given the inline attachments of the document are loaded.
On success calls callback with Document as an argument.
Note: If there’s no document with document id doc_id this function calls callback with argument None. Implementer should always check for None before checking the error attribute of the result object.
Deletes a document in database. doc has to be a Document with rev and id set or the deletion will fail.
On success, calls callback with Database (i.e. self) as an argument.
Performs a bulk update on database. bulk_data is a list of Document or dict objects. If the upgrade was succesfull (i.e. returned with 2xx HTTP response code) calls callback with BulkResult as a parameter.
If all_or_nothing is True the operation is done with the all_or_nothing flag set to true. For more information, see CouchDB bulk document API.
Fetches view results from database. Both design_doc and viewname are string, which identify the view. Additional keyword arguments can be given and those are all sent as JSON encoded query parameters to CouchDB with one exception. If a keyword argument keys is given the query is transformed to POST and the payload will be JSON object {"keys": <keys>}. For more information, see CouchDB view API.
Note: trombi does not yet support creating views through any special mechanism. Views should be created using Database.set().
On success, a ViewResult object is passed to callback.
Fetches view, identified by design_doc and listname, results and filters them using the listname list function. Additional keyword arguments can be given and they are sent as query parameters to CouchDB.
On success, a TrombiResult object is passed to callback. Note that the response content is not defined in any way, it solely depends on the list function.
Additional keyword arguments can be given and those are all sent as JSON encoded query parameters to CouchDB.
Fetches the _changes feed for the database. Has two optional keyword arguments, timeout and feed_type. timeout is in seconds and defaults to 60 seconds, which is CouchDB’s default timeout for changes feed. feed_type is described in CouchDB database API. Additional keyword arguments are converted to query parameters for the changes feed. For possible keyword arguments, see CouchDB database API entry of changes feed.
If feed_type is continous, the callback is passed as both streaming and regular callback to the fetch function. The callback is called every time the changes feed sends a line of text that is JSON encoded. The argument to the callback is this line decoded. When the changes feed closes for some reason, the callback is called with None as an argument if the feed closed properly (ie. server closed the request with 200 OK). Otherwise the callback is called with the error object.
Generates a temporary view and on success calls callback with ViewResult as an argument. For more information on creating map function map_fun and reduce function reduce_fun see CouchDB view API.
Additional keyword arguments can be given and those are all sent as JSON encoded query parameters to CouchDB.
In case of an error, if not otherwise mentioned, all the following methods call callback function with TrombiError as an argument.
This class represents a CouchDB document. This subclasses both collections.MutableMapping and TrombiObject. Has two mandatory arguments, a Database intance db and data, which is a representation of document data as dict.
Normally there’s no need to create Document objects as they are received as results of several different Database operations.
Document behaves like a dict (not exactly, but not far anyway), as it implements an abstract base class collections.MutableMapping.
It supports len(), setting and getting values using the similiar notation as in dictionaries, e.g. doc[key] = val. It also implements __contains__() so the presence of a key can be inspected using in operator.
Creates a copy of this document under new document id new_id. This operation is atomic as it is implemented using the custom COPY method provided by CouchDB.
On success the callback function is called with a Document denoting the newly created copy.
Returns the document’s content as a raw dict, containing CouchDB’s internal variables like _id and _rev.
Creates an attachment of name name to the document. data is the content of the attachment. These attachments are not so called inline attachments. type defaults to text/plain.
On success, callback is called with this Document as an argument.
Loads an attachment named name. On success the callback is called with the attachment data as an argument.
Represents a pseudo-page of documents returned from a CouchDB view calculated from total_rows and offset as well as a user-defined page limit.
The one mandatory argument, db, is a Database instance.
Stores the given argument.
The number of documents returned for a given “page”
Stores the actual ViewResult instance.
The total_rows attribute returned from the CouchDB view
The document offset or position of the first item on the page.
The document offset or position of the last item on the page.
The total number of pages (total_rows of view / limit)
The current page number
The previous page number
The next page number
An ordered array of the documents for the current page
A Boolean member to determine if there is a next page
A Boolean member to determine if there is a previous page
A list of the number of pages
The Document ID of the first document on the page
The Document ID of the last document on the page
Fetches the limit specified number of CouchDB documents from the view.
key can be defined as a complex key by the calling function. If requesting a previous page, the key must be built using the first document on the current page. If requesting the next page, key must be built using the last document on the current page.
doc_id uses the same logic as the above key, but is used to specify start_doc_id or end_doc_id (depending on forward) in case the CouchDB view returns duplicate keys.
forward simply defines whether you are requesting to go to the next page or the previous page. If forward is False then it attempts to move backward from the key/doc_id given. If forward is True then it attempts to more forward.
Additional keyword arguments can be given and those are all sent as JSON encoded query parameters to CouchDB and can override default values such as descending = true.
On success, callback is called with this Paginator as an argument.