document

API module/class for interacting with a document in a database.

class cloudant.document.Document(database, document_id=None, **kwargs)

Bases: dict

Encapsulates a JSON document. A Document object is instantiated with a reference to a database and used to manipulate document content in a CouchDB or Cloudant database instance.

In addition to basic CRUD style operations, a Document object also provides a convenient context manager. This context manager removes having to explicitly fetch() the document from the remote database before commencing work on it as well as explicitly having to save() the document once work is complete.

For example:

# Upon entry into the document context, fetches the document from the
# remote database, if it exists. Upon exit from the context, saves the
# document to the remote database with changes made within the context.
with Document(database, 'julia006') as document:
    # The document is fetched from the remote database
    # Changes are made locally
    document['name'] = 'Julia'
    document['age'] = 6
    # The document is saved to the remote database
Parameters:
  • database – A database instance used by the Document. Can be either a CouchDatabase or CloudantDatabase instance.
  • document_id (str) – Optional document id used to identify the document.
  • encoder (str) – Optional JSON encoder object (extending json.JSONEncoder).
  • decoder (str) – Optional JSON decoder object (extending json.JSONDecoder).
create()

Creates the current document in the remote database and if successful, updates the locally cached Document object with the _id and _rev returned as part of the successful response.

delete()

Removes the document from the remote database and clears the content of the locally cached Document object with the exception of the _id field. In order to successfully remove a document from the remote database, a _rev value must exist in the locally cached Document object.

delete_attachment(attachment, headers=None)

Removes an attachment from a remote document and refreshes the locally cached document object.

Parameters:
  • attachment (str) – Attachment file name used to identify the attachment.
  • headers (dict) – Optional, additional headers to be sent with request.
Returns:

Attachment deletion status in JSON format
document_url

Constructs and returns the document URL.

Returns:Document URL
exists()

Retrieves whether the document exists in the remote database or not.

Returns:True if the document exists in the remote database, otherwise False
fetch()

Retrieves the content of the current document from the remote database and populates the locally cached Document object with that content. A call to fetch will overwrite any dictionary content currently in the locally cached Document object.

static field_set(doc, field, value)

Sets or replaces a value for a field in a locally cached Document object. To remove the field set the value to None.

Parameters:
  • doc (Document) – Locally cached Document object that can be a Document, DesignDocument or dict.
  • field (str) – Name of the field to set.
  • value – Value to set the field to.
get_attachment(attachment, headers=None, write_to=None, attachment_type=None)

Retrieves a document’s attachment and optionally writes it to a file. If the content_type of the attachment is ‘application/json’ then the data returned will be in JSON format otherwise the response content will be returned as text or binary.

Parameters:
  • attachment (str) – Attachment file name used to identify the attachment.
  • headers (dict) – Optional, additional headers to be sent with request.
  • write_to (file) – Optional file handler to write the attachment to. The write_to file must be opened for writing prior to including it as an argument for this method.
  • attachment_type (str) – Optional setting to define how to handle the attachment when returning its contents from this method. Valid values are 'text', 'json', and 'binary' If omitted then the returned content will be based on the response Content-Type.
Returns:

The attachment content
json()

Retrieves the JSON string representation of the current locally cached document object, encoded by the encoder specified in the associated client object.

Returns:Encoded JSON string containing the document data
static list_field_append(doc, field, value)

Appends a value to a list field in a locally cached Document object. If a field does not exist it will be created first.

Parameters:
  • doc (Document) – Locally cached Document object that can be a Document, DesignDocument or dict.
  • field (str) – Name of the field list to append to.
  • value – Value to append to the field list.
static list_field_remove(doc, field, value)

Removes a value from a list field in a locally cached Document object.

Parameters:
  • doc (Document) – Locally cached Document object that can be a Document, DesignDocument or dict.
  • field (str) – Name of the field list to remove from.
  • value – Value to remove from the field list.
put_attachment(attachment, content_type, data, headers=None)

Adds a new attachment, or updates an existing attachment, to the remote document and refreshes the locally cached Document object accordingly.

Parameters:
  • attachment – Attachment file name used to identify the attachment.
  • content_type – The http Content-Type of the attachment used as an additional header.
  • data – Attachment data defining the attachment content.
  • headers – Optional, additional headers to be sent with request.
Returns:

Attachment addition/update status in JSON format
r_session

Returns the database instance r_session used by the document.

Returns:Client r_session
save()

Saves changes made to the locally cached Document object’s data structures to the remote database. If the document does not exist remotely then it is created in the remote database. If the object does exist remotely then the document is updated remotely. In either case the locally cached Document object is also updated accordingly based on the successful response of the operation.

update_field(action, field, value, max_tries=10)

Updates a field in the remote document. If a conflict exists, the document is re-fetched from the remote database and the update is retried. This is performed up to max_tries number of times.

Use this method when you want to update a single field in a document, and don’t want to risk clobbering other people’s changes to the document in other fields, but also don’t want the caller to implement logic to deal with conflicts.

For example:

# Append the string 'foo' to the 'words' list of Document doc.
doc.update_field(
    action=doc.list_field_append,
    field='words',
    value='foo'
)
Parameters:
  • action (callable) – A routine that takes a Document object, a field name, and a value. The routine should attempt to update a field in the locally cached Document object with the given value, using whatever logic is appropriate. Valid actions are list_field_append(), list_field_remove(), field_set()
  • field (str) – Name of the field to update
  • value – Value to update the field with
  • max_tries (int) – In the case of a conflict, the number of retries to attempt