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 existsReturns: a Database
instance
-
database
(name)¶ Get a database instance.
Parameters: name – database name Raises: NotFound
if a database does not existsReturns: 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 existsRaises: 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 successReturns: 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 existsReturns: 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
-