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: str = 'http://localhost:5984/', full_commit: bool = True, authmethod: str = 'basic', verify: bool = False, timeout: float | None = None)¶

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: Callable[[Dict[str, Any]], None] | BaseFeedReader, **kwargs: Any) → None¶

Subscribe to changes feed of the whole CouchDB server.

Note: this method is blocking.

Parameters:: feed_reader – callable or BaseFeedReader instance

Database¶

class pycouchdb.client.Database(resource: Resource, name: str)¶

Class that represents a couchdb database.

all(wrapper: Callable[[Any], Any] | None = None, flat: str | None = None, as_list: bool = False, **kwargs: Any) → Iterator[Any] | List[Any]¶

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() → Dict[str, Any]¶: Execute a cleanup operation.

commit() → Dict[str, Any]¶: Send commit message to server.

compact() → Dict[str, Any]¶: 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: str) → Dict[str, Any]¶

Execute compact over design view.

Raises:: NotFound if a view does not exists.

config() → DatabaseInfo¶: Get database status data such as document count, update sequence etc. :return: dict

delete(doc_or_id: Dict[str, Any] | str) → None¶

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: Dict[str, Any], filename: str) → Dict[str, Any]¶

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: List[Dict[str, Any]], transaction: bool = True) → List[BulkItem]¶

Delete a bulk of documents.

Added in version 1.2.

Parameters:: docs – list of docs
Raises:: Conflict if a delete is not success
Returns:: raw results from server

design_info(ddoc: str) → Dict[str, Any]¶

Get design document information, including view index state.

Parameters:: ddoc – design document name or _design/<name> identifier.
Raises:: NotFound if a design document does not exist.

find(selector: Dict[str, Any], **kwargs: Any) → Iterator[Dict[str, Any]]¶

Execute a Mango query using the _find endpoint.

Parameters:

selector – Mango query selector
kwargs – Additional query parameters (limit, bookmark, etc.)

Returns:

Iterator of documents matching the selector

get(doc_id: str, params: Dict[str, Any] | None = None, **kwargs: Any) → Dict[str, Any]¶

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

mango_pages(selector: Dict[str, Any], page_size: int, params: Dict[str, Any] | None = None) → Iterator[List[Dict[str, Any]]]¶

Paginate through Mango query results with automatic bookmark management.

This method provides convenient pagination for Mango queries without manual bookmark parameter management. It automatically handles the bookmark cursor for stable pagination.

Parameters:

selector – Mango query selector
page_size – Number of documents per page
params – Additional query parameters

Returns:

Iterator yielding lists of documents for each page

Added in version 1.17.

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, pagesize=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.
pagesize – Paginate the query response with pagesize rows per page.

Returns:: generator object

revisions(doc_id: str, status: str = 'available', params: Dict[str, Any] | None = None, **kwargs: Any) → Iterator[Dict[str, Any]]¶

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: Dict[str, Any], batch: bool = False) → Dict[str, Any]¶

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: List[Dict[str, Any]], try_setting_ids: bool = True, transaction: bool = True) → List[Dict[str, Any]]¶

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

view_pages(design_and_view: str, page_size: int, params: Dict[str, Any] | None = None) → Iterator[List[Row]]¶

Paginate through CouchDB view results with automatic cursor management.

This method provides convenient pagination for view queries without manual skip parameter management. It automatically handles startkey and startkey_docid for stable pagination.

Parameters:

design_and_view – View name (e.g., “design/view”)
page_size – Number of rows per page
params – Additional query parameters

Returns:

Iterator yielding lists of rows for each page

Added in version 1.17.

Developer Interface¶

Server¶

Database¶

py-couchdb

Navigation

Related Topics