Add more documentation to XBlockUserStateClient interface

lms/djangoapps/courseware/user_state_client.py

@@ -29,19 +29,71 @@ class DjangoXBlockUserStateClient(DjangoXBlockUserStateClient):
         """
         pass
 
-    def get(username, block_key, scope=Scope.user_state):
-        return self.get_many(username, [block_key], scope)
+    def get(username, block_key, scope=Scope.user_state, fields=None):
+        """
+        Retrieve the stored XBlock state for a single xblock usage.
+
+        Arguments:
+            username: The name of the user whose state should be retrieved
+            block_key (UsageKey): The UsageKey identifying which xblock state to load.
+            scope (Scope): The scope to load data from
+            fields: A list of field values to retrieve. If None, retrieve all stored fields.
+
+        Returns:
+            dict: A dictionary mapping field names to values
+
+        Raises:
+            DoesNotExist if no entry is found.
+        """
+        try:
+            _usage_key, state = next(self.get_many(username, [block_key], scope, fields=fields))
+        except StopIteration:
+            raise self.DoesNotExist()
+
+        return state
 
     def set(username, block_key, state, scope=Scope.user_state):
+        """
+        Set fields for a particular XBlock.
+
+        Arguments:
+            username: The name of the user whose state should be retrieved
+            block_key (UsageKey): The UsageKey identifying which xblock state to load.
+            state (dict): A dictionary mapping field names to values
+            scope (Scope): The scope to load data from
+        """
         self.set_many(username, {block_key: state}, scope)
 
-    def get_many(username, block_keys, scope=Scope.user_state):
-        """Returns dict of block_id -> state."""
+    def get_many(username, block_keys, scope=Scope.user_state, fields=None):
+        """
+        Retrieve the stored XBlock state for a single xblock usage.
+
+        Arguments:
+            username: The name of the user whose state should be retrieved
+            block_keys ([UsageKey]): A list of UsageKeys identifying which xblock states to load.
+            scope (Scope): The scope to load data from
+            fields: A list of field values to retrieve. If None, retrieve all stored fields.
+
+        Yields:
+            (UsageKey, field_state) tuples for each specified UsageKey in block_keys.
+            field_state is a dict mapping field names to values.
+        """
         if scope != Scope.user_state:
             raise ValueError("Only Scope.user_state is supported")
         raise NotImplementedError()
 
     def set_many(username, block_keys_to_state, scope=Scope.user_state):
+        """
+        Set fields for a particular XBlock.
+
+        Arguments:
+            username: The name of the user whose state should be retrieved
+            block_keys_to_state (dict): A dict mapping UsageKeys to state dicts.
+                Each state dict maps field names to values. These state dicts
+                are overlaid over the stored state. To delete fields, use
+                :meth:`delete` or :meth:`delete_many`.
+            scope (Scope): The scope to load data from
+        """
         if scope != Scope.user_state:
             raise ValueError("Only Scope.user_state is supported")
         raise NotImplementedError()