Developer Interface

This part of documentation covers a main developer interface. All py-couchdb functionality can be accessed by these classes:

Server

class pycouchdb.client.Server(base_url='http://localhost:5984/', full_commit=True, authmethod='basic', verify=False)

Class that represents a couchdb connection.

Parameters:
  • verify – setup ssl verification.
  • base_url – a full url to couchdb (can contain auth data).
  • full_commit – If False, couchdb not commits all data on a request is finished.
  • authmethod – specify a authentication method. By default “basic” method is used but also exists “session” (that requires some server configuration changes).
changes_feed(feed_reader, **kwargs)

Subscribe to changes feed of the whole CouchDB server.

Note: this method is blocking.

Parameters:feed_reader – callable or BaseFeedReader instance
[Ref]http://docs.couchdb.org/en/1.6.1/api/server/common.html#db-updates
create(name)

Create a database.

Parameters:name – database name
Raises:Conflict if a database already exists
Returns:a Database instance
database(name)

Get a database instance.

Parameters:name – database name
Raises:NotFound if a database does not exists
Returns:a Database instance
delete(name)

Delete some database.

Parameters:name – database name
Raises:NotFound if a database does not exists
info()

Get server info.

Returns:dict with all data that couchdb returns.
Return type:dict
replicate(source, target, **kwargs)

Replicate the source database to the target one.

New in version 1.3.

Parameters:
  • source – full URL to the source database
  • target – full URL to the target database
version()

Get the current version of a couchdb server.

Database

class pycouchdb.client.Database(resource, name)

Class that represents a couchdb database.

all(wrapper=None, flat=None, as_list=False, **kwargs)

Execute a builtin view for get all documents.

Parameters:
  • wrapper – wrap result into a specific class.
  • as_list – return a list of results instead of a default lazy generator.
  • flat – get a specific field from a object instead of a complete object.
Returns:generator object
changes_feed(feed_reader, **kwargs)

Subscribe to changes feed of couchdb database.

Note: this method is blocking.

Parameters:feed_reader – callable or BaseFeedReader instance
changes_list(**kwargs)

Obtain a list of changes from couchdb.

cleanup()

Execute a cleanup operation.

commit()

Send commit message to server.

compact()

Send compact message to server. Compacting write-heavy databases should be avoided, otherwise the process may not catch up with the writes. Read load has no effect.

compact_view(ddoc)

Execute compact over design view.

Raises:NotFound if a view does not exists.
config()

Get database status data such as document count, update sequence etc. :return: dict

delete(doc_or_id)

Delete document by id.

Changed in version 1.2: Accept document or id.

Parameters:doc_or_id – document or id
Raises:NotFound if a document not exists
Raises:Conflict if delete with wrong revision.
delete_attachment(doc, filename)

Delete attachment by filename from document.

Changed in version 1.2: Now returns a new document instead of modify the original.

Parameters:
  • doc – document dict
  • filename – name of attachment.
Raises:

Conflict if save with wrong revision.
Returns:

doc
delete_bulk(docs, transaction=True)

Delete a bulk of documents.

New in version 1.2.

Parameters:docs – list of docs
Raises:Conflict if a delete is not success
Returns:raw results from server
get(doc_id, params=None, **kwargs)

Get a document by id.

Parameters:doc_id – document id
Raises:NotFound if a document not exists
Returns:document (dict)
get_attachment(doc, filename, stream=False, **kwargs)

Get attachment by filename from document.

Parameters:
  • doc – document dict
  • filename – attachment file name.
  • stream – setup streaming output (default: False)
Returns:binary data or
one(name, flat=None, wrapper=None, **kwargs)

Execute a design document view query and returns a first result.

Parameters:
  • name – name of the view (eg: docidname/viewname).
  • wrapper – wrap result into a specific class.
  • flat – get a specific field from a object instead of a complete object.
Returns:object or None
put_attachment(doc, content, filename=None, content_type=None)

Put a attachment to a document.

Changed in version 1.2: Now returns a new document instead of modify the original.

Parameters:
  • doc – document dict.
  • content – the content to upload, either a file-like object or bytes
  • filename – the name of the attachment file; if omitted, this function tries to get the filename from the file-like object passed as the content argument value
Raises:

Conflict if save with wrong revision.
Raises:

ValueError
Returns:

doc
query(name, wrapper=None, flat=None, as_list=False, **kwargs)

Execute a design document view query.

Parameters:
  • name – name of the view (eg: docidname/viewname).
  • wrapper – wrap result into a specific class.
  • as_list – return a list of results instead of a default lazy generator.
  • flat – get a specific field from a object instead of a complete object.
Returns:generator object
revisions(doc_id, status='available', params=None, **kwargs)

Get all revisions of one document.

Parameters:
  • doc_id – document id
  • status – filter of revision status, set empty to list all
Raises:

NotFound if a view does not exists.
Returns:

generator object
save(doc, batch=False)

Save or update a document.

Changed in version 1.2: Now returns a new document instead of modify the original.

Parameters:
  • doc – document
  • batch – allow batch=ok inserts (default False)
Raises:

Conflict if save with wrong revision.
Returns:

doc
save_bulk(docs, try_setting_ids=True, transaction=True)

Save a bulk of documents.

Changed in version 1.2: Now returns a new document list instead of modify the original.

Parameters:
  • docs – list of docs
  • try_setting_ids – if True, we loop through docs and generate/set an id in each doc if none exists
  • transaction – if True, couchdb do a insert in transaction model.
Returns:

docs