docs: partial session.data documentation consolidation

Consolitdate some redundant docs, and do some cross-linking for the
various places that mention session.data.

docs/developer/clients.rst

@@ -190,11 +190,12 @@ Client example would be::
 Replies from Operation methods
 ------------------------------
 
-The responses from Operation methods is a tuple, (status, message,
-session).  The elements of the tuple are:
+The response from Operation methods is a tuple, ``(status, message,
+session)``.  The elements of the tuple are:
 
   ``status``
-    An integer value equal to ocs.OK, ocs.ERROR, or ocs.TIMEOUT.
+    An integer value equal to ocs.OK, ocs.ERROR, or ocs.TIMEOUT (see
+    :class:`ocs.base.ResponseCode`).
 
   ``message``
     A string providing a brief description of the result (this is
@@ -205,8 +206,8 @@ session).  The elements of the tuple are:
     The session information... see below.
 
 Responses obtained from MatchedClient calls are lightly wrapped by
-class ``OCSReply`` so that ``__repr__`` produces a nicely formatted
-description of the result.  For example::
+class :class:`ocs.matched_client.OCSReply` so that ``__repr__``
+produces a nicely formatted description of the result.  For example::
 
   >>> c.set_autoscan.wait()
   OCSReply: OK : Operation "set_autoscan" just exited.
@@ -220,43 +221,16 @@ description of the result.  For example::
 
 
 The ``session`` portion of the reply is dictionary containing a bunch
-of potentially useful information.  This information corresponds to
-the OpSession maintained by the OCSAgent class for each run of an
-Agent's Operation (see OpSession in ocs/ocs_agent.py):
-
-  ``'session_id'``
-    An integer identifying this run of the Operation.  If an Op ends
-    and is started again, ``session_id`` will be different.
-
-  ``'op_name'``
-    The operation name.  You probably already know this.
-
-  ``'status'``
-    A string representing the state of the operation.  The possible
-    values are 'starting', 'running', 'done'.
-
-  ``'start_time'``
-    The timestamp corresponding to when this run was started.
-
-  ``'end_time'``
-    If ``status`` == ``'done'``, then this is the timestamp at which
-    the run completed.  Otherwise it will be None.
-
-  ``'success'``
-    If ``status`` == ``'done'``, then this is a boolean indicating
-    whether the operation reported that it completed successfully
-    (rather than with an error).
-
-  ``'data'``
-    Agent-specific data that might of interest to a user.  This may be
-    updated while an Operation is running, but once ``status`` becomes
-    ``'done'`` then ``data`` should not change any more.  A typical
-    use case here would be for a Process that is monitoring some
-    system to report the current values of key parametrs.  This should
-    not be used as an alternative to providing a data feed... rather
-    it should provide current values to answer immediate questions.
-
-  ``'messages'``
-    A list of Operation log messages.  Each entry in the list is a
-    tuple, (timestamp, text).
+of potentially useful information, such as timestamps for the
+Operation run's start and end, a success code, and a custom data
+structure populated by the Agent.
 
+The information can be accessed through the OCSReply, for example::
+
+  >>> reply = c.set_autoscan.status()
+  >>> reply.session['start_time']
+  1585667844.423
+
+For more information on the contents of ``.session``, see the
+docstring for :func:`ocs.ocs_agent.OpSession.encoded`, and the Data
+Access section on :ref:`session_data`.

docs/developer/session-data.rst

@@ -1,11 +1,14 @@
+.. _session_data:
+
 session.data
 ============
 
 Data Feeds make use of the crossbar Pub/Sub functionality to pass data around
 the network, however, sometimes you might not want to receive all data, just
-the most recent values. For this purpose there is the OpSession data attribute.
-This is per OCS operation location to store recent data of interest to OCS
-Agent users.
+the most recent values. For this purpose there is the ``session.data`` attribute.
+This is a per OCS operation location to store recent data of interest to OCS
+Agent users.  The ``session`` argument passed to each Operation function is an
+object of class :class:`ocs.ocs_agent.OpSession`.
 
 Often this is used to store the most recent values that are queried by the
 Agent, for example the temperature of thermometers on a Lakeshore device. This

ocs/ocs_agent.py

@@ -832,38 +832,69 @@ def encoded(self):
         Returns
         -------
         session_id : int
-          A unique identifier for a single session.
-          When an Operation is initiated, a new session object is
-          created and can be distinguished from other times the
-          Operation has been run using this id.
+          A unique identifier for a single session (a single "run" of
+          the Operation).  When an Operation is initiated, a new
+          session object is created and can be distinguished from
+          other times the Operation has been run using this id.
         op_name : str
           The OCS Operation name.
         op_code : int
           The OpCode, which combines information from status and
-          success; see `ocs.base.ResponseCode`.
+          success; see :class:`ocs.base.ResponseCode`.
         status : str
           The Operation run status (e.g. 'starting', 'done', ...).
-          See SESSION_STATUS_CODES.
+          See :ref:`ocs.ocs_agent.SESSION_STATUS_CODES`.
         success : bool or None
-          If the Operation Session has completed, this indicates that
-          the Operation was deemed successful.  Prior to the
-          completion of the operation, the value is None.
+          If the Operation Session has completed (`status == 'done'`),
+          this indicates that the Operation was deemed successful.
+          Prior to the completion of the operation, the value is None.
+          The value could be False if the Operation reported failure,
+          or if it crashed and failure was marked by the encapsulating
+          OCS code.
         start_time : float
           The time the Operation Session started, as a unix timestamp.
         end_time : float or None
           The time the Operation Session ended, as a unix timestamp.
           While the Session is still on-going, this is None.
         data : dict
+
           This is an area for the Operation code to store custom
-          information that might be of interest to a Control Client,
-          such as the most recent data readings from a device,
-          structured information about the configuration and progress
-          of the Operation, or diagnostics.
+          information that might be of interest to a Control Client
+          (the user), such as the most recent data readings from a
+          device, structured information about the configuration and
+          progress of the Operation, or diagnostics.
+
         messages : list
           A buffer of messages posted by the Operation.  Each element
           of the list is a tuple, (timestamp, message) where timestamp
           is a unix timestamp and message is a string.
 
+        Notes
+        -----
+        This ``data`` field may be used by Agent code to provide data
+        that might be of interest to a user (whether human or
+        automated), such as the most recent readings from a device,
+        structured information about the configuration and progress of
+        the Operation, or diagnostics.
+
+        The structure of the ``data`` entry is not strictly defined,
+        but please observe the following:
+
+        - Document your ``data`` structure in the Operation docstring.
+        - Provide a `timestamp` with the readings, or with each group
+          of readings, so that the consumer can confirm they're
+          recent.
+        - The session data is passed to clients with every API
+          response, so avoid storing a lot of data in there (as a rule
+          of thumb, try to keep it < 100 kB).
+        - Fight the urge to store timestreams (i.e. a history of
+          recent readings) -- try to use data feeds for that.
+        - When data are so useful that they are used by other clients
+          / control scripts to make decisions in automated contexts,
+          then they should also be pushed out to a data feed, so that
+          there is an archive of all variables that were affecting
+          system behavior.
+
         """
         return {'session_id': self.session_id,
                 'op_name': self.op_name,