sier2 0.29__py2.py3-none-any.whl

sier2/panel/_panel.py

@@ -0,0 +1,412 @@
+import ctypes
+from datetime import datetime
+import html
+import panel as pn
+import sys
+import threading
+from typing import Callable
+
+from sier2 import Block, BlockValidateError, BlockState, Dag, BlockError
+from .._dag import _InputValues
+from ._feedlogger import getDagPanelLogger, getBlockPanelLogger
+from ._panel_util import _get_state_color, dag_doc
+
+NTHREADS = 2
+
+# From https://tabler.io/icons/icon/info-circle
+#
+INFO_SVG = '''<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+  <path stroke="none" d="M0 0h24v24H0z" fill="none" />
+  <path d="M3 12a9 9 0 1 0 18 0a9 9 0 0 0 -18 0" />
+  <path d="M12 9h.01" />
+  <path d="M11 12h1v4h1" />
+</svg>
+'''
+
+if '_pyodide' in sys.modules:
+    # Pyodide (to be specific, WASM) doesn't allow threads.
+    # Specifying one thread for panel for some reason tries to start one, so we need to rely on the default.
+    #
+    pn.extension(
+        'floatpanel',
+        inline=True,
+        loading_spinner='bar',
+        notifications=True,
+    )
+else:
+    pn.extension(
+        'floatpanel',
+        inline=True,
+        nthreads=NTHREADS,
+        loading_spinner='bar',
+        notifications=True,
+    )
+
+
+
+def _hms(sec):
+    h, sec = divmod(int(sec), 3600)
+    m, sec = divmod(sec, 60)
+
+    return f'{h:02}:{m:02}:{sec:02}'
+
+class _PanelContext:
+    """A context manager to wrap the execution of a block within a dag.
+
+    This default context manager handles the block state, the stopper,
+    and converts block execution errors to GimzoError exceptions.
+
+    It also uses the panel UI to provide extra information to the user.
+    """
+
+    def __init__(self, *, block: Block, dag: Dag, dag_logger=None):
+        self.block = block
+        self.dag = dag
+        self.dag_logger = dag_logger
+
+    def __enter__(self):
+        state = BlockState.EXECUTING
+        self.block._block_state = state
+        self.t0 = datetime.now()
+        if self.dag_logger:
+            self.dag_logger.info('Execute', block_name=self.block.name, block_state=state)
+
+        block_logger = getBlockPanelLogger(self.block.name)
+        self.block.logger = block_logger
+
+        # if self.block._progress:
+        #     self.block._progress.active = True
+
+        return self.block
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        delta = (datetime.now() - self.t0).total_seconds()
+
+        # if self.block._progress:
+        #     self.block._progress.active = False
+
+        if exc_type is None:
+            state = BlockState.WAITING if self.block.block_pause_execution 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)
+        elif isinstance(exc_type, KeyboardInterrupt):
+            state = BlockState.INTERRUPTED
+            self.block_state._block_state = state
+            if not self.dag._is_pyodide:
+                self.dag._stopper.event.set()
+            if self.dag_logger:
+                self.dag_logger.exception(f'KEYBOARD INTERRUPT after {_hms(delta)}', block_name=self.block.name, block_state=state)
+        else:
+            state = BlockState.ERROR
+            self.block._block_state = state
+            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}'
+                if not self.dag._is_pyodide:
+                    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
+
+def _quit(session_context):
+    print(session_context)
+    sys.exit()
+
+def interrupt_thread(tid, exctype):
+    """Raise exception exctype in thread tid."""
+
+    r = ctypes.pythonapi.PyThreadState_SetAsyncExc(
+        ctypes.c_ulong(tid),
+        ctypes.py_object(exctype)
+    )
+    if r==0:
+        raise ValueError('Invalid thread id')
+    elif r!=1:
+        # "if it returns a number greater than one, you're in trouble,
+        # and you should call it again with exc=NULL to revert the effect"
+        #
+        ctypes.pythonapi.PyThreadState_SetAsyncExc(ctypes.c_ulong(tid), None)
+        raise SystemError('PyThreadState_SetAsyncExc failed')
+
+def _prepare_to_show(dag: Dag):
+    # Replace the default text-based context with the panel-based context.
+    #
+    dag._block_context = _PanelContext
+
+    info_button = pn.widgets.ButtonIcon(
+        icon=INFO_SVG,
+        active_icon=INFO_SVG,
+        description='Dag Help',
+        align='center'
+    )
+
+    # 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(
+        site=dag.site,
+        title=dag.title,
+        theme='dark',
+        sidebar=pn.Column(sidebar_title),
+        collapsed_sidebar=True,
+        sidebar_width=440
+    )
+
+    def display_info(_event):
+        """Display a FloatPanel containing help for the dag and blocks."""
+
+        text = dag_doc(dag)
+        config = {
+            'headerControls': {'maximize': 'remove'},
+            'contentOverflow': 'scroll'
+        }
+        fp = pn.layout.FloatPanel(text, name=dag.title, width=550, height=450, contained=False, position='center', theme='dark filleddark', config=config)
+        info_fp_holder[:] = [fp]
+
+    info_button.on_click(display_info)
+
+    switch = pn.widgets.Switch(name='Stop')
+
+    def on_switch(event):
+        if switch.value:
+            dag.stop()
+            reset()
+
+            # Which thread are we running on?
+            #
+            current_tid = threading.current_thread().ident
+
+            # What other threads are running?
+            # There are multiple threads running, including the main thread
+            # and the bokeh server thread. We need to find the panel threads.
+            # Unfortunately, there is nothing special about them.
+            #
+            print('THREADS', current_tid, [t for t in threading.enumerate()])
+            all_threads = [t for t in threading.enumerate() if t.name.startswith('ThreadPoolExecutor')]
+            assert len(all_threads)<=NTHREADS, f'{all_threads=}'
+            other_thread = [t for t in all_threads if t.ident!=current_tid]
+
+            # It's possible that since the user might not have done anything yet,
+            # another thread hasn't spun up.
+            #
+            if other_thread:
+                interrupt_thread(other_thread[0].ident, KeyboardInterrupt)
+        else:
+            dag.unstop()
+            # TODO reset status for each card
+
+    pn.bind(on_switch, switch, watch=True)
+
+    def reset():
+        """Experiment."""
+        col = template.main.objects[0]
+        for card in col:
+            status = card.header[0]
+
+    # We use a Panel Feed widget to display log messages.
+    #
+    log_feed = pn.Feed(
+        view_latest=True,
+        scroll_button_threshold=20,
+        auto_scroll_limit=1,
+        sizing_mode='stretch_width'
+    )
+    dag_logger = getDagPanelLogger(log_feed)
+
+    template.main.append(
+        pn.Column(
+            *(BlockCard(parent_template=template, dag=dag, w=gw, dag_logger=dag_logger) for gw in dag.get_sorted())
+        )
+    )
+    template.sidebar.append(
+        pn.Column(
+            switch,
+            pn.panel(dag.hv_graph().opts(invert_yaxis=True, xaxis=None, yaxis=None)),
+            log_feed,
+            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)
+
+    # Execute the dag.
+    # Since this is a panel dag, we expect the first block to be an input nlock.
+    # This ensures that the first block's prepare() method is called.
+    # If the first block is not an input block, it must be primed, just like a plain dag.
+    #
+    dag.execute()
+
+    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)
+
+    # Execute the dag.
+    # Since this is a panel dag, we expect the first block to be an input nlock.
+    # This ensures that the first block's prepare() method is called.
+    # If the first block is not an input block, it must be primed, just like a plain dag.
+    #
+    dag.execute()
+
+    template.servable()
+
+def _default_panel(self) -> Callable[[Block], pn.Param]:
+    """Provide a default __panel__() implementation for blocks that don't have one.
+
+    This default will display the in_ parameters.
+    """
+
+    in_names = [name for name in self.param.values() if name.startswith('in_')]
+
+    return pn.Param(self, parameters=in_names, show_name=False)
+
+class BlockCard(pn.Card):
+    """A custom card to wrap around a block.
+
+    This adds the block title and a status light to the card header.
+    The light updates to match the block state.
+    """
+
+    @staticmethod
+    def _get_state_light(color: str) -> pn.Spacer:
+        return pn.Spacer(
+            margin=(8, 0, 0, 0),
+            styles={'width':'20px', 'height':'20px', 'background':color, 'border-radius': '10px'}
+        )
+
+    # def ui(self, message):
+    #     """TODO connect this to the template"""
+    #     print(message)
+
+    def __init__(self, *args, parent_template, dag: Dag, w: Block, dag_logger=None, **kwargs):
+        # Make this look like <h3> (the default Card header text).
+        #
+        name_text = pn.widgets.StaticText(
+            value=w.name,
+            css_classes=['card-title'],
+            styles={'font-size':'1.17em', 'font-weight':'bold'}
+        )
+        spacer = pn.HSpacer(
+            styles=dict(
+                min_width='1px', min_height='1px'
+            )
+        )
+
+        # If a block has no __panel__() method, Panel will by default
+        # inspect the class and display the param attributes.
+        # This is obviously not what we want.
+        #
+        # We just want to display the in_ params.
+        #
+        has_panel = '__panel__' in w.__class__.__dict__
+        if not has_panel:
+            # w._progress = pn.indicators.Progress(
+            #     name='Block progress',
+            #     bar_color='primary',
+            #     active=False,
+            #     value=-1
+            # )
+
+            # Go go gadget descriptor protocol.
+            #
+            w.__panel__ = _default_panel.__get__(w)
+
+        if w.block_pause_execution:
+            # 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,
+                # so there won't be anything on the block queue.
+                # Therefore, we trigger the output params to put their
+                # current values on the queue.
+                # If their values are already there, it doesn't matter.
+                #
+                parent_template.main[0].loading = True
+                w.param.trigger(*w._block_out_params)
+
+                try:
+                    if dag_logger:
+                        dag_logger.info('', block_name=None, block_state=None)
+                        dag_logger.info('Execute dag', block_name='', block_state=BlockState.DAG)
+
+                    # 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=w.continue_label, button_type='primary')
+            c_button.on_click(on_continue)
+
+            w_ = pn.Column(
+                w,
+                pn.Row(c_button, align='end'),
+               sizing_mode='scale_width'
+            )
+        else:
+            w_ = w
+
+        super().__init__(w_, *args, sizing_mode='stretch_width', **kwargs)
+
+        self.header = pn.Row(
+            name_text,
+            pn.VSpacer(),
+            spacer,
+            self._get_state_light(_get_state_color(w._block_state))
+        )
+
+        # Watch the block state so we can update the staus light.
+        #
+        w.param.watch_values(self.state_change, '_block_state')
+
+    def state_change(self, _block_state: BlockState):
+        """Watcher for the block state.
+
+        Updates the state light.
+        """
+
+        self.header[-1] = self._get_state_light(_get_state_color(_block_state))
+
+class PanelDag(Dag):
+    def __init__(self, *, site: str='Panel Dag', title: str, doc: str):
+        super().__init__(site=site, title=title, doc=doc)
+
+    def show(self):
+        _show_dag(self)
+
+    def servable(self):
+        _serveable_dag(self)

sier2/panel/_panel_util.py

@@ -0,0 +1,83 @@
+import sys
+from .._block import BlockState
+from .._util import trim
+
+def _get_state_color(gs: BlockState) -> str:
+    """Convert a block state (as logged by the dag) to a color.
+
+    The colors are arbitrary, except for BLOCK. When a block logs a message,
+    it is executing by definition, so no color is required.
+    """
+
+    match gs:
+        case BlockState.BLOCK:
+            color = 'var(--panel-background-color)'
+        case BlockState.DAG:
+            color = 'grey'
+        case BlockState.INPUT:
+            color = '#f0c820'
+        case BlockState.READY:
+            color='white'
+        case BlockState.EXECUTING:
+            color='steelblue'
+        case BlockState.WAITING:
+            color='yellow'
+        case BlockState.SUCCESSFUL:
+            color = 'green'
+        case BlockState.INTERRUPTED:
+            color= 'orange'
+        case BlockState.ERROR:
+            color = 'red'
+        case _:
+            color = 'magenta'
+
+    return color
+
+########
+# Documentation utilities
+########
+
+def block_doc(block):
+    """Generate Markdown documentation for a block.
+
+    The documentation is taken from the docstring of the block class
+    and the doc of each 'in_' and 'out_' param.
+    """
+
+    # Force the first line of the block docstring to have a level 2 header.
+    #
+    b_doc = '## ' + trim(block.__doc__).lstrip(' #')
+
+    params = []
+    for name, p in block.param.objects().items():
+        if name.startswith(('in_', 'out_')):
+            doc = p.doc if p.doc else ''
+            params.append((name, doc.strip()))
+
+    params.sort()
+    text = ['| Name | Description |', '| ---- | ---- |']
+    for name, doc in params:
+        text.append(f'| {name} | {doc}')
+
+    return '---\n' + b_doc + '\n### Params\n' + '\n'.join(text)
+
+def dag_doc(dag):
+    """Generate Markdown documentation for a dag and its blocks."""
+
+    # A Block may be in the dag more than once.
+    # Don't include the documentation for such blocks more than once.
+    #
+    blocks = dag.get_sorted()
+    uniq_blocks = []
+    seen_blocks = set()
+    for b in blocks:
+        if type(b) not in seen_blocks:
+            uniq_blocks.append(b)
+            seen_blocks.add(type(b))
+    block_docs = '\n\n'.join(block_doc(block) for block in uniq_blocks)
+
+    # Force the first line of the dag doc to have a level 1 header.
+    #
+    dag_text =f'# {dag.site} - {dag.title}\n\n# ' + trim(dag.doc).lstrip(' #')
+
+    return f'{dag_text}\n\n{block_docs}'

sier2-0.29.dist-info/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Algol60
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

sier2-0.29.dist-info/METADATA

@@ -0,0 +1,68 @@
+Metadata-Version: 2.3
+Name: sier2
+Version: 0.29
+Summary: Blocks of code that are executed in dags
+Author: Algol60
+Author-email: algol60 <algol60@users.noreply.github.com>
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Software Development :: Libraries
+Project-URL: Homepage, https://github.com/algol60/sier2
+Description-Content-Type: text/x-rst
+
+Sier2
+======
+
+Connect modular pieces of Python code ("blocks") into
+a processing dag pipeline. Blocks are an improvement on libraries;
+if you have a library, you still need to build an application.
+Blocks are pieces of an application, you just have to connect them.
+
+See the ``examples`` directory for examples.
+
+Description
+-----------
+
+A ``block`` is a self-contained piece of code with input and output parameters.
+Blocks can be connected to each other using a ``Dag`` to create
+a dag of blocks.
+
+More precisely, output parameters in one block can be connected to input parameters
+in another block. The connections need not be one-to-one: parameters in multiple blocks
+can be connected to parameters in a single block; conversely, parameters in a single block
+can be connected to parameters in multiple blocks.
+
+Block parameters use `param <https://param.holoviz.org/>`_, which not only implement
+triggering and watching of events, but allow parameters to be named and documented.
+
+A typical block implementation looks like this.
+
+.. code-block:: python
+
+    from sier2 import Block
+
+    class Increment(Block):
+        """A block that adds one to the input value."""
+
+        int_in = param.Integer(label='The input', doc='An integer')
+        int_out = param.Integer(label='The output', doc='The incremented value')
+
+        def execute(self):
+            self.int_out = self.int_in + 1
+
+See the examples in ``examples`` (Python scripts) and ``examples-panel`` (scripts that use `Panel <https://panel.holoviz.org/>`_ as a UI).
+
+Documentation
+-------------
+
+To build the documentation from the repository root directory:
+
+.. code-block:: powershell
+
+    docs/make html
+

sier2-0.29.dist-info/RECORD

@@ -0,0 +1,16 @@
+sier2/__init__.py,sha256=_JNRxOnwTgKfuaNEF1P9iRgBNX2P8i-GuibUG0KVdS8,174
+sier2/__main__.py,sha256=HZfzJLaD2_JOyKFkFYTD2vs-UARxNMjP4D7ZdJg405A,3140
+sier2/_block.py,sha256=_0aBr84mikRoP_FfEcpg92JTqOdoB9kObu6Y0u8KeKc,7716
+sier2/_dag.py,sha256=BPB22UEScfS1lYL8fzpGTx7IOqvnyTcFsz9QgFI4Fn4,23976
+sier2/_library.py,sha256=BGEG78AH16IAhI7NEDL-3CrEwNYXFUo4K-XFfHgKn70,8011
+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=_0BZRebzFFTnyX-Qr4pgbAbf09QzKXSsZG6JFU1DOWI,13913
+sier2/panel/_panel_util.py,sha256=omcLO0OIHhH00l9YXv09Qv8lnaY6VKsQ1F0qbsrs3vk,2450
+sier2-0.29.dist-info/LICENSE,sha256=2AKq0yxLLDdGsj6xQuNjDPG5d2IbFWFGiB_cnCBtMp4,1064
+sier2-0.29.dist-info/METADATA,sha256=ARQRzlQc-1_QSNseo6sgQ1da5uufFWPeQtm0AWolrqo,2332
+sier2-0.29.dist-info/WHEEL,sha256=aiTauIPAnqOMBuVimVqk4bevIILHLWXNdkzTocSR-tg,92
+sier2-0.29.dist-info/RECORD,,

sier2-0.29.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: poetry-core 2.1.1
+Root-Is-Purelib: true
+Tag: py2.py3-none-any