access local redefinition of execute_command_list()

CHANGES.rst

@@ -6,6 +6,11 @@ Change History
 
 :1.1.7:  released *tba* (on or before 2019-07-01)
 
+	.. note:: DEPRECATION: 
+	   `apstools.plans.run_blocker_in_plan()` will be removed by 2019-12-31.
+	   `Do not write blocking code in bluesky plans.
+	   <https://github.com/BCDA-APS/apstools/issues/90#issuecomment-483405890>`_
+
     * `#175 <https://github.com/BCDA-APS/apstools/issues/175>`_
        move `plans.run_in_thread()` to `utils.run_in_thread()`
     * `#168 <https://github.com/BCDA-APS/apstools/issues/168>`_

apstools/plans.py

@@ -9,6 +9,7 @@
    ~nscan
    ~parse_Excel_command_file
    ~parse_text_command_file
+   ~register_command_handler
    ~run_blocker_in_plan
    ~run_command_file
    ~snapshot
@@ -115,6 +116,17 @@ def execute_command_list(filename, commands, md={}):
     raw_command: obj (str or list(str)
         contents from input file, such as:
         ``SAXS 0 0 0 blank``
+
+    SEE ALSO
+
+    .. autosummary::
+
+        ~execute_command_list
+        ~register_command_handler
+        ~run_command_file
+        ~summarize_command_file
+        ~parse_Excel_command_file
+        ~parse_text_command_file
     """
     full_filename = os.path.abspath(filename)
 
@@ -154,6 +166,19 @@ def execute_command_list(filename, commands, md={}):
 def get_command_list(filename):
     """
     return command list from either text or Excel file
+
+    SEE ALSO
+
+    .. autosummary::
+
+        ~execute_command_list
+        ~get_command_list
+        ~register_command_handler
+        ~run_command_file
+        ~summarize_command_file
+        ~parse_Excel_command_file
+        ~parse_text_command_file
+
     """
     full_filename = os.path.abspath(filename)
     if not os.path.exists(full_filename):
@@ -172,7 +197,9 @@ def get_command_list(filename):
 def run_blocker_in_plan(blocker, *args, _poll_s_=0.01, _timeout_s_=None, **kwargs):
     """
     plan: run blocking function ``blocker_(*args, **kwargs)`` from a Bluesky plan
-
+
+    .. warning: This plan is deprecated.  It will be removed by 2019-12-31.
+
     PARAMETERS
 
     blocker : func
@@ -198,6 +225,7 @@ def my_sleep(t=1.0):
         RE(my_sleep())
 
     """
+    logger.warning("This plan is deprecated.  It will be removed by 2019-12-31.")
     status = Status()
 
     @APS_utils.run_in_thread
@@ -338,6 +366,17 @@ def parse_Excel_command_file(filename):
     FileNotFoundError
         if file cannot be found
 
+    SEE ALSO
+
+    .. autosummary::
+
+        ~get_command_list
+        ~register_command_handler
+        ~run_command_file
+        ~summarize_command_file
+        ~parse_text_command_file
+
+
     """
     full_filename = os.path.abspath(filename)
     assert os.path.exists(full_filename)
@@ -406,6 +445,18 @@ def parse_text_command_file(filename):
 
     FileNotFoundError
         if file cannot be found
+
+    SEE ALSO
+
+    .. autosummary::
+
+        ~execute_command_list
+        ~get_command_list
+        ~register_command_handler
+        ~run_command_file
+        ~summarize_command_file
+        ~parse_Excel_command_file
+
     """
     full_filename = os.path.abspath(filename)
     assert os.path.exists(full_filename)
@@ -425,15 +476,60 @@ def parse_text_command_file(filename):
     return commands
 
 
+# internal use, allows redefinition of execute_command_list()
+_COMMAND_HANDLER_ = execute_command_list
+
+
+def register_command_handler(handler=None):
+    """
+    (re)define the function called to execute the command list
+
+    PARAMETERS
+
+    handler : obj
+        Reference of the ``execute_command_list`` function
+        to be used from :func:`~apstools.plans.run_command_file()`.
+        If ``None`` or not provided, 
+        will reset to :func:`~apstools.plans.execute_command_list()`,
+        which is also the initial setting.
+
+    SEE ALSO
+
+    .. autosummary::
+
+        ~execute_command_list
+        ~get_command_list
+        ~register_command_handler
+        ~summarize_command_file
+        ~parse_Excel_command_file
+        ~parse_text_command_file
+
+    """
+    global _COMMAND_HANDLER_
+    _COMMAND_HANDLER_ = handler or execute_command_list
+
+
 def run_command_file(filename, md={}):
     """
     plan: execute a list of commands from a text or Excel file
 
     * Parse the file into a command list
     * yield the command list to the RunEngine (or other)
+
+    SEE ALSO
+
+    .. autosummary::
+
+        ~execute_command_list
+        ~get_command_list
+        ~register_command_handler
+        ~summarize_command_file
+        ~parse_Excel_command_file
+        ~parse_text_command_file
+
     """
     commands = get_command_list(filename)
-    yield from execute_command_list(filename, commands)
+    yield from _COMMAND_HANDLER_(filename, commands)
 
 
 def snapshot(obj_list, stream="primary", md=None):
@@ -510,6 +606,17 @@ def _snap(md=None):
 def summarize_command_file(filename):
     """
     print the command list from a text or Excel file
+
+    SEE ALSO
+
+    .. autosummary::
+
+        ~execute_command_list
+        ~get_command_list
+        ~run_command_file
+        ~parse_Excel_command_file
+        ~parse_text_command_file
+
     """
     commands = get_command_list(filename)
     print(f"Command file: {filename}")
@@ -719,6 +826,12 @@ class TuneAxis(object):
        ~tune
        ~multi_pass_tune
        ~peak_detected
+
+    SEE ALSO
+
+    .. autosummary::
+
+       ~tune_axes
 
     """
 
@@ -978,6 +1091,12 @@ def tune_axes(axes):
     Sequentially, tune a list of preconfigured axes::
 
         RE(tune_axes([mr, m2r, ar, a2r])
+
+    SEE ALSO
+
+    .. autosummary::
+
+       ~TuneAxis
     """
     for axis in axes:
         yield from axis.tune()

apstools/utils.py

@@ -587,7 +587,7 @@ class ExcelDatabaseFileGeneric(ExcelDatabaseFileBase):
 
     EXAMPLE
 
-    See section :ref:`example_Excel_scan` for more examples.
+    See section :ref:`example_run_command_file` for more examples.
 
     (See also :ref:`example screen shot <excel_plan_spreadsheet_screen>`.)
     Table (on Sheet 1) begins on row 4 in first column::

docs/source/applications/index.rst

@@ -0,0 +1,19 @@
+
+Applications
+------------
+
+.. toctree::
+   :hidden:
+   :maxdepth: 2
+   :glob:
+
+   snapshot
+
+There are two command-line applications provided by apstools:
+
+=====================================================   =================================
+application                                             purpose
+=====================================================   =================================
+:ref:`apstools_plan_catalog <example_plan_catalog>`     summary list of all scans in the databroker 
+:ref:`bluesky_snapshot`                                 Take a snapshot of a list of EPICS PVs and record it in the databroker.
+=====================================================   =================================

docs/source/snapshot.rst → docs/source/applications/snapshot.rst

@@ -176,7 +176,7 @@ This is a GUI program started with the command: `bluesky_snapshot_viewer`
 Internally, this tool calls :class:`apstools.callbacks.SnapshotReport` to 
 make the report.  There are no command line options or command line help.
 
-.. figure:: resources/bsv1.jpg
+.. figure:: ../resources/bsv1.jpg
    :width: 95%
 
    Screen shot of `bluesky_snapshot_viewer` GUI.

docs/source/conf.py

@@ -35,8 +35,9 @@
 extensions = [
     'sphinx.ext.autodoc',
     'sphinx.ext.autosummary',
-    'sphinx.ext.todo',
+    'sphinx.ext.coverage',
     'sphinx.ext.mathjax',
+    'sphinx.ext.todo',
     'sphinx.ext.viewcode',
     ]