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

class cloudant.security_document.SecurityDocument(database)

Bases: dict

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

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

For example:

# Upon entry into the security document context, fetches the security
# document from the remote database, if it exists. Upon exit from the
# context, saves the security document to the remote database with
# changes made within the context.
with SecurityDocument(database) as security_document:
    # The security document is fetched from the remote database
    # Changes are made locally
    security_document['Cloudant']['julia'] = ['_reader', '_writer']
    security_document['Cloudant']['ruby'] = ['_admin', '_replicator']
    # The security document is saved to the remote database
Parameters:database – A database instance used by the SecurityDocument. Can be either a CouchDatabase or CloudantDatabase instance.

Constructs and returns the security document URL.

Returns:Security document URL

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


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

Returns:Encoded JSON string containing the security document data

Returns the Python requests session used by the security document.

Returns:The Python requests session

Saves changes made to the locally cached SecurityDocument object’s data structures to the remote database.