sier2 0.17__py3-none-any.whl

sier2/panel/_panel.py

@@ -0,0 +1,320 @@
+import ctypes
+from datetime import datetime
+import panel as pn
+import sys
+import threading
+
+from sier2 import Block, BlockState, Dag, BlockError
+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>
+'''
+
+pn.extension('floatpanel', inline=True, nthreads=NTHREADS, loading_spinner='bar')
+
+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.user_input 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
+            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 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
+
+        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 _show_dag(dag: Dag):
+    """Display the dag in a panel template."""
+
+    # 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'
+    )
+
+    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)
+        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,
+            fp_holder
+        )
+    )
+
+    pn.state.on_session_destroyed(_quit)
+
+    template.show(threaded=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.
+        #
+        # Instead, we want to display an indefinite progress bar.
+        # The Panel context manager will activate and deactivate it.
+        #
+        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
+            )
+
+        if w.user_input:
+            # This is a user_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.
+                #
+                w.param.trigger(*w._block_out_params)
+                parent_template.main[0].loading = True
+                try:
+                    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)
+                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)
+
+            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)

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.17.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.17.dist-info/METADATA

@@ -0,0 +1,72 @@
+Metadata-Version: 2.1
+Name: sier2
+Version: 0.17
+Summary: Block code 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: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+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: panel (>=1.4.4)
+Requires-Dist: param (>=2.1.0)
+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.17.dist-info/RECORD

@@ -0,0 +1,16 @@
+sier2/__init__.py,sha256=evhmBhh3aIfP-yu72pBZbv-3ZwillUHLxqip74zdvBg,154
+sier2/__main__.py,sha256=HZfzJLaD2_JOyKFkFYTD2vs-UARxNMjP4D7ZdJg405A,3140
+sier2/_block.py,sha256=JEfjrMydPKBHZBgzjfkLYkW30r5ZeTH3leFg6RoAx0g,4955
+sier2/_dag.py,sha256=1zOdaVInZVFkttETWBwbq_L7ii7YeO5qH_mNF7BYQx4,18668
+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_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.17.dist-info/WHEEL

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