Documents

A key role in aiocouch takes the Document class. Every data send and retrieved from the server is represented by an instance of that class. There are no other ways in aiocouch to interact with documents.

Getting a Document instance

While the constructor can be used to get an instance representing a specific document, the canonical way is the usage of member functions of instances of the Database class.

butterfly_doc = await database["butterfly"]
wolpertinger = await database.get("wolpertinger")

These methods create a Document and fetch the data from the server. For some cases, though, a precise control other the performed requests are required. The above code snippet is equivalent to this:

butterfly_doc = Document(database, "butterly")
await butterfly_doc.fetch()

Creating new Documents

The creation of a new document on the server consists of three steps. First, you need a local document handle, i.e., an Document instance. Then you set the contents of the document. And finally, the local document is saved to the server.

# get an Document instance
doc = await database.create["new_doc"]

# set the document content
doc["name"] = "The new document"

# actually perform the request to save the document on the server
await doc.save()

Modify existing documents

The modification of an existing document works very similarly to the creation. Retrieving the document, updating its contents, and finally saving the modified data to the server.

# get an Document instance
doc = await database["existing_doc"]

# update the document content
doc["name"] = "The modified document"

# actually perform the request to save the modification to the server
await doc.save()

Conflict handling

Whenever, two or more different Document instances want to save the same document on the server, a ConflictError can occur. To cope with conflicts, there are a set of different strategies, which can be used.

One trivial solution is to simply ignore conflicts.This is a viable strategy if only the existance of the document matters.

with contextlib.suppress(aiocouch.ConflictError):
    await doc.save()

Another straight-forward solution is to override the contents of the existing document.

try:
    await doc.save()
except aiocouch.ConflictError:
    info = await doc.info()
    doc.rev = info["rev"]
    await doc.save()

Other use cases may require a more sophisticated merging of documents. However, there isn’t a generic solution to such an approach. Thus, we forego to show example code here.

Reference

class aiocouch.document.Document(database, id, data=None)

A local representation for the referenced CouchDB document

An instance of this class represents a local copy of the document data on the server. This class behaves like a dict containing the document data and allows to fetch() and save() documents. For details about the dict-like interface, please refer to the Python manual.

Constructing an instance of this class does not cause any network requests.

Variables

id – the id of the document

Parameters
  • database (Database) – The database of the document

  • id (str) – the id of the document

  • data (Optional[dict]) – the inital data used to set the body of the document

attachment(id)

Returns the attachment object

The attachment object is returned, but this method doesn’t actually fetch any data from the server. Use fetch() and save(), respectively.

Parameters

id (str) – the id of the attachment

Return type

Attachment

Returns

Returns the attachment object

await copy(new_id)

Create a copy of the document on the server

Creates a new document with the data currently stored on the server.

Parameters

new_id (str) – the id of the new document

Return type

Document

Returns

an instance for the new document after it was copied

data

Returns the local copy of the document as a dict

If the document doesn’t exist on the server, this function returns None.

This method does not perform a network request.

Return type

dict

Returns

Returns the data of the document or None

await delete(discard_changes=False)

Deletes the document from the server

Calling this method deltes the local data and the document on the server. Afterwards, the instance can be filled with new data and call save() again.

Raises
  • ConflictError – if the local data has changed without saving

  • ConflictError – if the local revision is different from the server. See TODO.

exists

Denotes whether the document exists

A document exists, if it was fetch() ed from the server and wasn’t deleted on the server.

This method does not perform a network request.

Return type

bool

Returns

True if the document exists, False overwise

await fetch(discard_changes=False)

Retrieves the document data from the server

Fetching the document will retrieve the data from the server using a network request and update the local data.

Raises

ConflictError – if the local data has changed without saving

Parameters

discard_changes (bool) – If set to True, the local data object will the overridden with the retrieved content. If the local data was changed, no exception will be raised.

await info()

Returns a short information about the document.

This method sends a request to the server to retrieve the current status.

Raises

NotFoundError – if the document does not exist on the server

Return type

dict

Returns

A dict containing the id and revision of the document on the server

rev

Allows to set and get the local revision

If the local document wasn’t fetched or saved, this is None.

Return type

str

await save()

Saves the current state to the CouchDB server

Raises

ConflictError – if the local revision is different from the server. See TODO.