sier2 0.17__py3-none-any.whl → 0.23__py3-none-any.whl

sier2/__init__.py

@@ -1,4 +1,4 @@
-from ._block import Block, BlockError
+from ._block import Block, InputBlock, BlockError, BlockValidateError
 from ._dag import Connection, Dag, BlockState
 from ._library import Library, Info
 from ._version import __version__

sier2/_block.py

@@ -1,13 +1,16 @@
 from enum import StrEnum
 import inspect
 import param
-from typing import Any, Callable
-from collections import defaultdict
+from typing import Any
 
 from . import _logger
 
 class BlockError(Exception):
-    """Raised if a Block configuration is invalid."""
+    """Raised if a Block configuration is invalid.
+
+    If this exception is raised, the executing dag sets its stop
+    flag (which must be manually reset), and displays a stacktrace.
+    """
 
     pass
 
@@ -50,14 +53,14 @@ class Block(param.Parameterized):
 
     SIER2_KEY = '_sier2__key'
 
-    def __init__(self, *args, user_input=False, **kwargs):
+    def __init__(self, *args, continue_label='Continue', **kwargs):
         super().__init__(*args, **kwargs)
 
         if not self.__doc__:
             raise BlockError(f'Class {self.__class__} must have a docstring')
 
-        self.user_input = user_input
-        self._block_state = BlockState.INPUT if user_input else BlockState.READY
+        self.continue_label = continue_label
+        # self._block_state = BlockState.READY
         self.logger = _logger.get_logger(self.name)
 
         # Maintain a map of "block+output parameter being watched" -> "input parameter".
@@ -66,7 +69,7 @@ class Block(param.Parameterized):
         self._block_name_map: dict[tuple[str, str], str] = {}
 
         # Record this block's output parameters.
-        # If this is a user_input block, we need to trigger
+        # If this is an input block, we need to trigger
         # the output values before executing the next block,
         # in case the user didn't change anything.
         #
@@ -146,3 +149,46 @@ class Block(param.Parameterized):
         result = {name: getattr(self, name) for name in out_names}
 
         return result
+
+class InputBlock(Block):
+    """A ``Block`` that accepts user input.
+
+    An ``InputBlock`` executes in two steps().
+
+    When the block is executed by a dag, the dag first sets the input
+     params, then calls ``prepare()``. Execution of the dag then stops.
+
+    The dag is then restarted using ``dag.execute_after_input(input_block)``.
+    (An input block must be specified because it is not required that the
+    same input block be used immediately.) This causes the block's
+    ``execute()`` method to be called without resetting the input params.
+
+    Dag execution then continues as normal.
+    """
+
+    def __init__(self, *args, continue_label='Continue', **kwargs):
+        super().__init__(*args, continue_label=continue_label, **kwargs)
+        self._block_state = BlockState.INPUT
+
+    def prepare(self):
+        """Called by a dag before calling ``execute()```.
+
+        This gives the block author an opportunity to validate the
+        input params and set up a user inteface.
+
+        After the dag restarts on this block, ``execute()`` will be called.
+        """
+
+        pass
+
+class BlockValidateError(BlockError):
+    """Raised if ``InputBlock.prepare()`` or ``Block.execute()`` determines that input data is invalid.
+
+    If this exception is raised, it will be caught by the executing dag.
+    The dag will not set its stop flag, no stacktrace will be displayed,
+    and the error message will be displayed.
+    """
+
+    def __init__(self, block_name: str, error: str):
+        super().__init__(error)
+        self.block_name = block_name

sier2/_dag.py

@@ -1,4 +1,4 @@
-from ._block import Block, BlockError, BlockState
+from ._block import Block, InputBlock, BlockError, BlockValidateError, BlockState
 from dataclasses import dataclass, field #, KW_ONLY, field
 from collections import defaultdict, deque
 import holoviews as hv
@@ -28,7 +28,8 @@ class _InputValues:
     """Record a param value change.
 
     When a block updates an output param, the update is queued until
-    the block finishes executing. This class is what is queued.
+    the block finishes executing. Instances of this class are
+    what is queued.
     """
 
     # The block to be updated.
@@ -36,6 +37,9 @@ class _InputValues:
     dst: Block
 
     # The values to be set before the block executes.
+    # For a normal block, values will be non-empty when execute() is called.
+    # For an input block, if values is non-empty, prepare()
+    # will be called, else execute() will be called
     #
     values: dict[str, Any] = field(default_factory=dict)
 
@@ -63,21 +67,35 @@ class _BlockContext:
 
     def __exit__(self, exc_type, exc_val, exc_tb):
         if exc_type is None:
-            self.block._block_state = BlockState.WAITING if self.block.user_input else BlockState.SUCCESSFUL
-        elif isinstance(exc_type, KeyboardInterrupt):
+            self.block._block_state = BlockState.WAITING if isinstance(self.block, InputBlock) else BlockState.SUCCESSFUL
+        elif exc_type is KeyboardInterrupt:
             self.block_state._block_state = BlockState.INTERRUPTED
             self.dag._stopper.event.set()
             print(f'KEYBOARD INTERRUPT IN BLOCK {self.name}')
         else:
-            self.block._block_state = BlockState.ERROR
-            msg = f'While in {self.block.name}.execute(): {exc_val}'
-            # LOGGER.exception(msg)
-            self.dag._stopper.event.set()
-
-            # Convert the error in the block to a BlockError.
-            #
-            raise BlockError(f'Block {self.block.name}: {str(exc_val)}') from exc_val
-
+            state = BlockState.ERROR
+            self.block._block_state = state
+            if exc_type is not BlockValidateError:
+                # Validation errors don't set the stopper;
+                # they just stop execution.
+                #
+                if self.dag_logger:
+                    self.dag_logger.exception(
+                        block_name=self.block.name,
+                        block_state=state
+                    )
+
+                # msg = f'While in {self.block.name}.execute(): {exc_val}'
+                # LOGGER.exception(msg)
+                self.dag._stopper.event.set()
+
+                if not issubclass(exc_type, BlockError):
+                    # Convert non-BlockErrors in the block to a BlockError.
+                    #
+                    raise BlockError(f'Block {self.block.name}: {str(exc_val)}') from exc_val
+
+        # Don't suppress the original exception.
+        #
         return False
 
 class _Stopper:
@@ -213,21 +231,52 @@ class Dag:
                 item.values[inp] = new
                 self._block_queue.append(item)
 
+    def execute_after_input(self, block: InputBlock, *, dag_logger=None):
+        """Execute the dag after running ``prepare()`` in an input block.
+
+        After prepare() executes, and the user has possibly
+        provided input, the dag must continue with execute() in the
+        same block.
+
+        This method will prime the block queue with the specified block's
+        output, and call execute().
+
+        Parameters
+        ----------
+        block: InputBlock
+            The block to restart the dag at.
+        dag_logger:
+            A logger adapter that will accept log messages.
+        """
+
+        if not isinstance(block, InputBlock):
+            raise BlockError(f'A dag can only restart an InputBlock, not {block.name}')
+
+        # Prime the block queue, using an empty input param values dict
+        # to indicate that this is a restart, and Block.execute()
+        # must be called.
+        #
+        self._block_queue.appendleft(_InputValues(block, {}))
+        self.execute(dag_logger=dag_logger)
+
     def execute(self, *, dag_logger=None):
         """Execute the dag.
 
-        The dag is executed by iterating through the block events queue
+        The dag is executed by iterating through the block event queue
         and popping events from the head of the queue. For each event,
         update the destination block's input parameters and call
         that block's execute() method.
 
-        If the current destination block has user_flag True,
-        the loop will continue to set param values until the queue is empty,
-        but no execute() method will be called.
+        If the current destination block is an ``InputBlock``,
+        the loop will call ``block.prepare()` instead of ``block.execute()``,
+        then stop. The dag can then be restarted with
+        ``dag.execute_after_input()``.
 
-        To start (or restart) the dag, there must be something in the event queue.
-        The first (or current) user_input block must have updated at least one
-        output param before the dag's execute() is called.
+        To start the dag, there must be something in the event queue -
+        the dag must be "primed". A block must have updated at least one
+        output param before the dag's execute() is called. Calling
+        ``dag.execute()`` will then execute the dag starting with
+        the blocks connected to the first block.
         """
 
         if not self._block_queue:
@@ -252,15 +301,32 @@ class Dag:
                 self._stopper.event.set()
                 raise BlockError(msg) from e
 
+            # Execute the block.
+            # Don't execute input blocks when we get to them,
+            # unless this is after the user has selected the "Continue"
+            # button.
+            #
+            is_input_block = isinstance(item.dst, InputBlock)
             if can_execute:
                 with self._block_context(block=item.dst, dag=self, dag_logger=dag_logger) as g:
-                    g.execute()
-
-            if item.dst.user_input:
+                    # If this is an input block, and there are input
+                    # values, call prepare() if it exists.
+                    #
+                    if is_input_block and item.values:
+                        g.prepare()
+                    else:
+                        g.execute()
+
+            if is_input_block and item.values:
                 # If the current destination block requires user input,
-                # continue to set params, but don't execute anything.
+                # stop executing the dag immediately, because we don't
+                # want to be setting the input params of further blocks
+                # and causing them to do things.
                 #
-                can_execute = False
+                # This possibly leaves items on the queue, which will be
+                # executed on the next call to execute().
+                #
+                break
 
     def disconnect(self, g: Block) -> None:
         """Disconnect block g from other blocks.
@@ -373,10 +439,6 @@ class Dag:
                 if hasattr(g, var):
                     args[var] = getattr(g, var)
 
-            # TODO is there a better way of checking for user_input?
-            if hasattr(g, 'user_input'):
-                args['user_input'] = getattr(g, 'user_input')
-
             block = {
                 'block': g.block_key(),
                 'instance': i,

sier2/panel/_panel.py

@@ -1,10 +1,12 @@
 import ctypes
 from datetime import datetime
+import html
 import panel as pn
 import sys
 import threading
 
-from sier2 import Block, BlockState, Dag, BlockError
+from sier2 import Block, InputBlock, BlockValidateError, BlockState, Dag, BlockError
+from .._dag import _InputValues
 from ._feedlogger import getDagPanelLogger, getBlockPanelLogger
 from ._panel_util import _get_state_color, dag_doc
 
@@ -20,7 +22,7 @@ INFO_SVG = '''<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" vie
 </svg>
 '''
 
-pn.extension('floatpanel', inline=True, nthreads=NTHREADS, loading_spinner='bar')
+pn.extension('floatpanel', inline=True, nthreads=NTHREADS, loading_spinner='bar', notifications=True)
 
 def _hms(sec):
     h, sec = divmod(int(sec), 3600)
@@ -64,7 +66,7 @@ class _PanelContext:
             self.block._progress.active = False
 
         if exc_type is None:
-            state = BlockState.WAITING if self.block.user_input else BlockState.SUCCESSFUL
+            state = BlockState.WAITING if isinstance(self.block, InputBlock) else BlockState.SUCCESSFUL
             self.block._block_state = state
             if self.dag_logger:
                 self.dag_logger.info(f'after {_hms(delta)}', block_name=self.block.name, block_state=state.value)
@@ -77,14 +79,21 @@ class _PanelContext:
         else:
             state = BlockState.ERROR
             self.block._block_state = state
-            if self.dag_logger:
-                self.dag_logger.exception(f'after {_hms(delta)}', block_name=self.block.name, block_state=state)
-            msg = f'While in {self.block.name}.execute(): {exc_val}'
-            self.dag._stopper.event.set()
-
-            # Convert the error in the block to a BlockError.
-            #
-            raise BlockError(f'Block {self.block.name}: {str(exc_val)}') from exc_val
+            if exc_type is not BlockValidateError:
+                if self.dag_logger:
+                    self.dag_logger.exception(
+                        f'after {_hms(delta)}',
+                        block_name=self.block.name,
+                        block_state=state
+                    )
+
+                # msg = f'While in {self.block.name}.execute(): {exc_val}'
+                self.dag._stopper.event.set()
+
+                if not issubclass(exc_type, BlockError):
+                    # Convert the error in the block to a BlockError.
+                    #
+                    raise BlockError(f'Block {self.block.name}: {str(exc_val)}') from exc_val
 
         return False
 
@@ -107,10 +116,8 @@ def interrupt_thread(tid, exctype):
         #
         ctypes.pythonapi.PyThreadState_SetAsyncExc(ctypes.c_ulong(tid), None)
         raise SystemError('PyThreadState_SetAsyncExc failed')
-
-def _show_dag(dag: Dag):
-    """Display the dag in a panel template."""
-
+        
+def _prepare_to_show(dag: Dag):
     # Replace the default text-based context with the panel-based context.
     #
     dag._block_context = _PanelContext
@@ -122,7 +129,9 @@ def _show_dag(dag: Dag):
         align='center'
     )
 
-    fp_holder = pn.Column(visible=False)
+    # A place to stash the info FloatPanel.
+    #
+    info_fp_holder = pn.Column(visible=False)
 
     sidebar_title = pn.Row(info_button, '## Blocks')
     template = pn.template.BootstrapTemplate(
@@ -143,7 +152,8 @@ def _show_dag(dag: Dag):
             'contentOverflow': 'scroll'
         }
         fp = pn.layout.FloatPanel(text, name=dag.title, width=550, height=450, contained=False, position='center', theme='dark filleddark', config=config)
-        fp_holder[:] = [fp]
+        info_fp_holder[:] = [fp]
+
     info_button.on_click(display_info)
 
     switch = pn.widgets.Switch(name='Stop')
@@ -204,14 +214,30 @@ def _show_dag(dag: Dag):
             switch,
             pn.panel(dag.hv_graph().opts(invert_yaxis=True, xaxis=None, yaxis=None)),
             log_feed,
-            fp_holder
+            info_fp_holder
         )
     )
 
+    return template
+
+def _show_dag(dag: Dag):
+    """Display the dag in a panel template."""
+
+    template = _prepare_to_show(dag)
+
     pn.state.on_session_destroyed(_quit)
 
     template.show(threaded=False)
 
+def _serveable_dag(dag: Dag):
+    """Serve the dag in a panel template."""
+
+    template = _prepare_to_show(dag)
+
+    pn.state.on_session_destroyed(_quit)
+
+    template.servable()
+
 class BlockCard(pn.Card):
     """A custom card to wrap around a block.
 
@@ -260,8 +286,8 @@ class BlockCard(pn.Card):
                 value=-1
             )
 
-        if w.user_input:
-            # This is a user_input block, so add a 'Continue' button.
+        if isinstance(w, InputBlock):
+            # This is an input block, so add a 'Continue' button.
             #
             def on_continue(_event):
                 # The user may not have changed anything from the default values,
@@ -276,12 +302,27 @@ class BlockCard(pn.Card):
                     if dag_logger:
                         dag_logger.info('', block_name=None, block_state=None)
                         dag_logger.info('Execute dag', block_name='', block_state=BlockState.DAG)
-                    dag.execute(dag_logger=dag_logger)
+
+                    # We want this block's execute() method to run first
+                    # after the user clicks the "Continue" button.
+                    # We make this happen by pushing this block on the head
+                    # of the queue, but without any values - we don't want
+                    # to trigger any param changes.
+                    #
+                    try:
+                        dag.execute_after_input(w, dag_logger=dag_logger)
+                    except BlockValidateError as e:
+                        # Display the error as a notification.
+                        #
+                        block_name = html.escape(e.block_name)
+                        error = html.escape(str(e))
+                        notif = f'<b>{block_name}</b>:<br>{error}'
+                        pn.state.notifications.error(notif, duration=0)
                 finally:
                     parent_template.main[0].loading = False
 
-            c_button = pn.widgets.Button(name='Continue', button_type='primary')
-            pn.bind(on_continue, c_button, watch=True)
+            c_button = pn.widgets.Button(name=w.continue_label, button_type='primary')
+            c_button.on_click(on_continue)
 
             w_ = pn.Column(
                 w,
@@ -318,3 +359,6 @@ class PanelDag(Dag):
 
     def show(self):
         _show_dag(self)
+
+    def servable(self):
+        _serveable_dag(self)

{sier2-0.17.dist-info → sier2-0.23.dist-info}/METADATA

@@ -1,12 +1,13 @@
 Metadata-Version: 2.1
 Name: sier2
-Version: 0.17
-Summary: Block code dags
+Version: 0.23
+Summary: Blocks of code that are executed in dags
 Author: algol60
 Author-email: algol60@users.noreply.github.com
 Requires-Python: >=3.11,<4.0
 Classifier: Intended Audience :: Developers
 Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.11
@@ -14,7 +15,7 @@ Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Scientific/Engineering
 Classifier: Topic :: Software Development :: Libraries
-Requires-Dist: holoviews (>=1.18.3,<2.0.0)
+Requires-Dist: holoviews (>=1.19.0)
 Requires-Dist: panel (>=1.4.4)
 Requires-Dist: param (>=2.1.0)
 Description-Content-Type: text/x-rst

{sier2-0.17.dist-info → sier2-0.23.dist-info}/RECORD

@@ -1,16 +1,16 @@
-sier2/__init__.py,sha256=evhmBhh3aIfP-yu72pBZbv-3ZwillUHLxqip74zdvBg,154
+sier2/__init__.py,sha256=t1dLAlWzyhcRxkH-lcmN4NmPFs1Z57iQ93HBO8Fcpmo,186
 sier2/__main__.py,sha256=HZfzJLaD2_JOyKFkFYTD2vs-UARxNMjP4D7ZdJg405A,3140
-sier2/_block.py,sha256=JEfjrMydPKBHZBgzjfkLYkW30r5ZeTH3leFg6RoAx0g,4955
-sier2/_dag.py,sha256=1zOdaVInZVFkttETWBwbq_L7ii7YeO5qH_mNF7BYQx4,18668
+sier2/_block.py,sha256=wEXIk5UtV7utYSUNzQuXshgkKg6dVb7SGm4E6tfoTmM,6590
+sier2/_dag.py,sha256=KlLvGImFZoJfzgjRHJ7l-mpkUtPUdiyFgAbdz8WJF-Y,21278
 sier2/_library.py,sha256=aG1f6xHE2qtzvlFCgIp0cMXd6OKlkW_OvbQQb-b2l_8,7536
 sier2/_logger.py,sha256=lwRmYjXMkP7TyURo5gvOf266vwGDFkLGau-EXpo5eEw,2379
 sier2/_util.py,sha256=NmXI7QMSdkoSMe6EYJ-q8zI9iGJeMUto3g4314UVoM8,1932
 sier2/_version.py,sha256=K5EdVMOTOHqhr-mIMjXhh84WHTSES2K-MJ_b--KryBM,71
 sier2/panel/__init__.py,sha256=wDEf_v859flQX4udAVYZW1m79sfB1NIrI3pyNIpNiEM,29
 sier2/panel/_feedlogger.py,sha256=tsrA8R2FZUecVY2egifVu2qosRfjccgvGRE0lLZSXZY,5270
-sier2/panel/_panel.py,sha256=g68zXfyqzcTiBlaC9n_UXTlWtJDdDNCIwLqmJEjgyTQ,10890
+sier2/panel/_panel.py,sha256=Q3a5Y1TTkhKzU5n0ZpmKH5MkSDOJAlidVz2Sq3F_cvc,12451
 sier2/panel/_panel_util.py,sha256=omcLO0OIHhH00l9YXv09Qv8lnaY6VKsQ1F0qbsrs3vk,2450
-sier2-0.17.dist-info/LICENSE,sha256=2AKq0yxLLDdGsj6xQuNjDPG5d2IbFWFGiB_cnCBtMp4,1064
-sier2-0.17.dist-info/METADATA,sha256=TBbD_gpxkuM0dHoOZEeYScUy_xtD-rn7SqWs-33hk9Y,2423
-sier2-0.17.dist-info/WHEEL,sha256=Nq82e9rUAnEjt98J6MlVmMCZb-t9cYE2Ir1kpBmnWfs,88
-sier2-0.17.dist-info/RECORD,,
+sier2-0.23.dist-info/LICENSE,sha256=2AKq0yxLLDdGsj6xQuNjDPG5d2IbFWFGiB_cnCBtMp4,1064
+sier2-0.23.dist-info/METADATA,sha256=ak30FoB2FhtDAuby3K97gbjc7NZkUgNXOPwCAlzYGNI,2492
+sier2-0.23.dist-info/WHEEL,sha256=Nq82e9rUAnEjt98J6MlVmMCZb-t9cYE2Ir1kpBmnWfs,88
+sier2-0.23.dist-info/RECORD,,