
Storage Backends
****************

To create a custom storage backend you will need to subclass the
"StorageBackend" class.  Then create an instance of the new class and
pass that as the *storage* keyword argument when you create the
"WebSupport" object:

   support = WebSupport(srcdir=srcdir,
                        builddir=builddir,
                        storage=MyStorage())

For more information about creating a custom storage backend, please
see the documentation of the "StorageBackend" class below.

class class sphinx.websupport.storage.StorageBackend

   Defines an interface for storage backends.


StorageBackend Methods
======================

StorageBackend.pre_build()

   Called immediately before the build process begins. Use this to
   prepare the StorageBackend for the addition of nodes.

StorageBackend.add_node(id, document, source)

   Add a node to the StorageBackend.

   Parameters:
      * **id** -- a unique id for the comment.

      * **document** -- the name of the document the node belongs to.

      * **source** -- the source files name.

StorageBackend.post_build()

   Called after a build has completed. Use this to finalize the
   addition of nodes if needed.

StorageBackend.add_comment(text, displayed, username, time, proposal, node_id, parent_id, moderator)

   Called when a comment is being added.

   Parameters:
      * **text** -- the text of the comment

      * **displayed** -- whether the comment should be displayed

      * **username** -- the name of the user adding the comment

      * **time** -- a date object with the time the comment was added

      * **proposal** -- the text of the proposal the user made

      * **node_id** -- the id of the node that the comment is being
        added to

      * **parent_id** -- the id of the comment's parent comment.

      * **moderator** -- whether the user adding the comment is a
        moderator

StorageBackend.delete_comment(comment_id, username, moderator)

   Delete a comment.

   Raises "UserNotAuthorizedError" if moderator is False and
   *username* doesn't match the username on the comment.

   Parameters:
      * **comment_id** -- The id of the comment being deleted.

      * **username** -- The username of the user requesting the
        deletion.

      * **moderator** -- Whether the user is a moderator.

StorageBackend.get_data(node_id, username, moderator)

   Called to retrieve all data for a node. This should return a dict
   with two keys, *source* and *comments* as described by
   "WebSupport"'s "get_data()" method.

   Parameters:
      * **node_id** -- The id of the node to get data for.

      * **username** -- The name of the user requesting the data.

      * **moderator** -- Whether the requestor is a moderator.

StorageBackend.process_vote(comment_id, username, value)

   Process a vote that is being cast. *value* will be either -1, 0, or
   1.

   Parameters:
      * **comment_id** -- The id of the comment being voted on.

      * **username** -- The username of the user casting the vote.

      * **value** -- The value of the vote being cast.

StorageBackend.update_username(old_username, new_username)

   If a user is allowed to change their username this method should be
   called so that there is not stagnate data in the storage system.

   Parameters:
      * **old_username** -- The username being changed.

      * **new_username** -- What the username is being changed to.

StorageBackend.accept_comment(comment_id)

   Called when a moderator accepts a comment. After the method is
   called the comment should be displayed to all users.

   Parameters:
      **comment_id** -- The id of the comment being accepted.
