sier2 0.23__tar.gz

sier2-0.23/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.23/PKG-INFO

@@ -0,0 +1,73 @@
+Metadata-Version: 2.1
+Name: sier2
+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
+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.19.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.23/README.rst

@@ -0,0 +1,50 @@
+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.23/pyproject.toml

@@ -0,0 +1,38 @@
+[tool.poetry]
+name = "sier2"
+version = "0.23"
+description = "Blocks of code that are executed in dags"
+authors = ["algol60 <algol60@users.noreply.github.com>"]
+readme = "README.rst"
+packages = [{include = "sier2", from = "src"}]
+classifiers = [
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Intended Audience :: Science/Research",
+    "Intended Audience :: Developers",
+    "Topic :: Scientific/Engineering",
+    "Topic :: Software Development :: Libraries"
+]
+
+[tool.poetry.dependencies]
+python = "^3.11"
+
+holoviews = ">=1.19.0"
+panel = ">=1.4.4"
+param = ">=2.1.0"
+
+[[tool.mypy.overrides]]
+module = [
+    "holoviews",
+    "param"
+]
+ignore_missing_imports = true
+
+[project.urls]
+Homepage = "https://github.com/algol60/sier2"
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"

sier2-0.23/src/sier2/__init__.py

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

sier2-0.23/src/sier2/__main__.py

@@ -0,0 +1,96 @@
+import argparse
+from importlib.metadata import version
+
+from sier2 import Library
+from ._library import _find_blocks, _find_dags, run_dag
+from ._util import block_doc_text, dag_doc_text
+
+BOLD = '' # '\x1b[1;37m'
+NORM = '' # '\x1b[0m'
+
+def _pkg(module):
+    return module.split('.')[0]
+
+def blocks_cmd(args):
+    """Display the blocks found via plugin entry points."""
+
+    seen = set()
+    curr_ep = None
+    for entry_point, gi in _find_blocks():
+        show = not args.block or gi.key.endswith(args.block)
+        if curr_ep is None or entry_point!=curr_ep:
+            if show:
+                pkg = _pkg(entry_point.module)
+                s = f'In {pkg} v{version(pkg)}'
+                u = '' # '\n' + '#' * len(s)
+                print(f'\n{BOLD}{s}{u}{NORM}')
+                # print(f'\x1b[1mIn {entry_point.module} v{version(entry_point.module)}:\x1b[0m')
+                curr_ep = entry_point
+
+        if show:
+            dup = f' (DUPLICATE)' if gi.key in seen else ''
+            print(f'  {BOLD}{gi.key}: {gi.doc}{NORM}{dup}')
+
+            if args.verbose:
+                block = Library.get_block(gi.key)
+                print(block_doc_text(block))
+                print()
+
+            seen.add(gi.key)
+
+def dags_cmd(args):
+    """Display the dags found via plugin entry points."""
+
+    seen = set()
+    curr_ep = None
+    for entry_point, gi in _find_dags():
+        show = not args.dag or gi.key.endswith(args.dag)
+        if curr_ep is None or entry_point!=curr_ep:
+            if show:
+                pkg = _pkg(entry_point.module)
+                s = f'In {pkg} v{version(pkg)}'
+                u = '' # '\n' + '#' * len(s)
+                print(f'\n{BOLD}{s}{u}{NORM}')
+                curr_ep = entry_point
+
+        if show:
+            dup = f' (DUPLICATE)' if gi.key in seen else ''
+            print(f'  {BOLD}{gi.key}: {gi.doc}{NORM}{dup}')
+
+            if args.verbose:
+                # We have to instantiate the dag to get the documentation.
+                #
+                dag = Library.get_dag(gi.key)
+                print(dag_doc_text(dag))
+
+            seen.add(gi.key)
+
+def run_cmd(args):
+    run_dag(args.dag)
+
+def main():
+    parser = argparse.ArgumentParser()
+    subparsers = parser.add_subparsers(help='sub-command help')
+
+    run = subparsers.add_parser('run', help='Run a dag')
+    run.add_argument('dag', type=str, help='A dag to run')
+    run.set_defaults(func=run_cmd)
+
+    blocks = subparsers.add_parser('blocks', help='Show available blocks')
+    blocks.add_argument('-v', '--verbose', action='store_true', help='Show help')
+    blocks.add_argument('block', nargs='?', help='Show all blocks ending with this string')
+    blocks.set_defaults(func=blocks_cmd)
+
+    dags = subparsers.add_parser('dags', help='Show available dags')
+    dags.add_argument('-v', '--verbose', action='store_true', help='Show help')
+    dags.add_argument('dag', nargs='?', help='Show all dags ending with this string')
+    dags.set_defaults(func=dags_cmd)
+
+    args = parser.parse_args()
+    if 'func' in args:
+        args.func(args)
+    else:
+        parser.print_help()
+
+if __name__=='__main__':
+    main()

sier2-0.23/src/sier2/_block.py

@@ -0,0 +1,194 @@
+from enum import StrEnum
+import inspect
+import param
+from typing import Any
+
+from . import _logger
+
+class BlockError(Exception):
+    """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
+
+class BlockState(StrEnum):
+    """The current state of a block; also used for logging."""
+
+    DAG = 'DAG'                 # Dag logging.
+    BLOCK = 'BLOCK'             # Block logging.
+    INPUT = 'INPUT'
+    READY = 'READY'
+    EXECUTING = 'EXECUTING'
+    WAITING = 'WAITING'
+    SUCCESSFUL = 'SUCCESSFUL'
+    INTERRUPTED = 'INTERRUPTED'
+    ERROR = 'ERROR'
+
+class Block(param.Parameterized):
+    """The base class for blocks.
+
+    A block is implemented as:
+
+    .. code-block:: python
+
+        class MyBlock(Block):
+            ...
+
+    A typical block will have at least one input parameter, and an ``execute()``
+    method that is called when an input parameter value changes.
+
+    .. code-block:: python
+
+        class MyBlock(Block):
+            value_in = param.String(label='Input Value')
+
+            def execute(self):
+                print(f'New value is {self.value_in}')
+    """
+
+    _block_state = param.String(default=BlockState.READY)
+
+    SIER2_KEY = '_sier2__key'
+
+    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.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".
+        # This is used by _block_event() to set the correct input parameter.
+        #
+        self._block_name_map: dict[tuple[str, str], str] = {}
+
+        # Record this block's output parameters.
+        # 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.
+        #
+        self._block_out_params = []
+
+        # self._block_context = _EmptyContext()
+
+        self._progress = None
+
+    @classmethod
+    def block_key(cls):
+        """The unique key of this block class.
+
+        Blocks require a unique key so they can be identified in the block library.
+        The default implementation should be sufficient, but can be overridden
+        in case of refactoring or name clashes.
+        """
+
+        im = inspect.getmodule(cls)
+
+        if hasattr(cls, Block.SIER2_KEY):
+            return getattr(cls, Block.SIER2_KEY)
+
+        return f'{im.__name__}.{cls.__qualname__}'
+
+    def execute(self, *_, **__):
+        """This method is called when one or more of the input parameters causes an event.
+
+        Override this method in a Block subclass.
+
+        The ``execute()`` method can have arguments. The arguments can be specified
+        in any order. It is not necessary to specify all, or any, arguments.
+        Arguments will not be passed via ``*args`` or ``**kwargs``.
+
+        * ``stopper`` - an indicator that the dag has been stopped. This may be
+            set while the block is executing, in which case the block should
+            stop executing as soon as possible.
+        * ``events`` - the param events that caused execute() to be called.
+        """
+
+        # print(f'** EXECUTE {self.__class__=}')
+        pass
+
+    def __panel__(self):
+        """A default Panel component.
+
+        When run in a Panel context, a block will typically implement
+        its own __panel__() method. If it doesn't, this method will be
+        used as a default. When a block without a __panel__() is wrapped
+        in a Card, self.progress will be assigned a pn.indicators.Progress()
+        widget which is returned here. The Panel context will make it active
+        before executing the block, and non-active after executing the block.
+        (Why not have a default Progress()? Because we don't want any
+        Panel-related code in the core implementation.)
+
+        If the block implements __panel__(), this will obviously be overridden.
+
+        When run in non-Panel context, this will remain unused.
+        """
+
+        return self._progress
+
+    def __call__(self, **kwargs) -> dict[str, Any]:
+        """Allow a block to be called directly."""
+
+        in_names = [name for name in self.__class__.param if name.startswith('in_')]
+        if len(kwargs)!=len(in_names) or any(name not in in_names for name in kwargs):
+            names = ', '.join(in_names)
+            raise BlockError(f'All input params must be specified: {names}')
+
+        for name, value in kwargs.items():
+            setattr(self, name, value)
+
+        self.execute()
+
+        out_names = [name for name in self.__class__.param if name.startswith('out_')]
+        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