sier2 0.29__tar.gz → 0.35__tar.gz

{sier2-0.29 → sier2-0.35}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: sier2
-Version: 0.29
+Version: 0.35
 Summary: Blocks of code that are executed in dags
 Author: Algol60
 Author-email: algol60 <algol60@users.noreply.github.com>

{sier2-0.29 → sier2-0.35}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sier2"
-version = "0.29"
+version = "0.35"
 description = "Blocks of code that are executed in dags"
 authors = [
     {name="Algol60", email="algol60 <algol60@users.noreply.github.com>"}

{sier2-0.29 → sier2-0.35}/src/sier2/__init__.py

@@ -1,4 +1,6 @@
 from ._block import Block, BlockError, BlockValidateError
+from ._config import Config
 from ._dag import Connection, Dag, BlockState
 from ._library import Library, Info
 from ._version import __version__
+from ._util import get_block_config

{sier2-0.29 → sier2-0.35}/src/sier2/__main__.py

@@ -1,7 +1,7 @@
 import argparse
 from importlib.metadata import version
 
-from sier2 import Library
+from sier2 import Library, Config
 from ._library import _find_blocks, _find_dags, run_dag
 from ._util import block_doc_text, dag_doc_text
 
@@ -66,6 +66,19 @@ def dags_cmd(args):
             seen.add(gi.key)
 
 def run_cmd(args):
+    if args.update_config:
+        args = args.update_config.split(',')
+        block_name = args[0]
+        update_arg = ','.join(args[1:])
+        write_to_file = True
+    else:
+        block_name = None
+        update_arg = None
+        write_to_file = False
+
+    if args.config or args.update_config:
+        Config.update(location=args.config, config_block=block_name, update_arg=update_arg, write_to_file=write_to_file)
+
     run_dag(args.dag)
 
 def main():
@@ -74,6 +87,8 @@ def main():
 
     run = subparsers.add_parser('run', help='Run a dag')
     run.add_argument('dag', type=str, help='A dag to run')
+    run.add_argument('-C', '--config', default=None, help='Use this config file (default to personal config file)')
+    run.add_argument('-U', '--update_config', default=None, help='A block that provides a config that updates the personal config file')
     run.set_defaults(func=run_cmd)
 
     blocks = subparsers.add_parser('blocks', help='Show available blocks')

{sier2-0.29 → sier2-0.35}/src/sier2/_block.py

@@ -4,6 +4,7 @@ import param
 from typing import Any
 
 from . import _logger
+from ._config import Config
 
 class BlockError(Exception):
     """Raised if a Block configuration is invalid.
@@ -50,16 +51,34 @@ class Block(param.Parameterized):
         class MyBlock(Block):
             ...
 
+    The ``Block`` class inherits from ``param.Parameterized``, and uses parameters
+    as described at https://param.holoviz.org/user_guide/Parameters.html.
+    There are three kinds of parameters:
+    * Input parameters start with ``in_``. These parameters are set before a block is executed.
+    * Output parameters start with ``out_``. The block sets these in its ``execute()`` method.
+    * Block parameters start with ``block_``. THese are reserved for use by blocks.
+
     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')
+            in_value = param.String(label='Input Value')
+            out_upper = param.String(label='Output value)
 
             def execute(self):
-                print(f'New value is {self.value_in}')
+                self.out_value = self.in_value.upper()
+                print(f'New value is {self.out_value}')
+
+    The block parameter ``block_pause_execution`` allows a block to act as an "input" block,
+    particularly when the block hsa a GUI interface. When set to True and dag execution
+    reaches this block, the block's ``prepare()`` method is called, then the dag stops executing.
+    This allows the user to interact with a user interface.
+
+    The dag is then restarted using ``dag.execute_after_input(input_block)`` (typically by
+    a "Continue" button in the GUI.) When the dag is continued at this block,
+    the block's ``execute()`` method is called, and dag execution continues.
     """
 
     block_pause_execution = param.Boolean(default=False, label='Pause execution', doc=_PAUSE_EXECUTION_DOC)
@@ -68,13 +87,22 @@ class Block(param.Parameterized):
 
     SIER2_KEY = '_sier2__key'
 
-    def __init__(self, *args, block_pause_execution=False, continue_label='Continue', **kwargs):
+    def __init__(self, *args, block_pause_execution: bool=False, block_doc: str|None=None, continue_label='Continue', **kwargs):
+        """
+        Parameters
+        ----------
+        block_pause_execution: bool
+            If True, ``prepare()`` is called and dag execution stops.
+        block_doc: str|None
+            Markdown documentation that may displayed in the user interface.
+        """
         super().__init__(*args, **kwargs)
 
         if not self.__doc__:
             raise BlockError(f'Class {self.__class__} must have a docstring')
 
         self.block_pause_execution = block_pause_execution
+        self.block_doc = block_doc
         self.continue_label = continue_label
         # self._block_state = BlockState.READY
         self.logger = _logger.get_logger(self.name)
@@ -111,6 +139,66 @@ class Block(param.Parameterized):
 
         return f'{im.__name__}.{cls.__qualname__}'
 
+    def get_config(self, *, block: 'Block'=None):
+        """Return a dictionary containing keys and values from the section specified by
+        the block in the sier2 config file.
+
+        The config file has the format described by the Python ``configparser`` module,
+        with the added feature that values are evaluated using :func:`ast.literal_eval`,
+        and therefore must be syntactically correct Python literals.
+
+        They keys and values are read from the section ``[block.name]``, where ``name`` is
+        this block's unique key as specified by :func:`sier2.Block.block_key`.
+        If the ``block`` parameter is unspecified, the calling block is used by default.
+
+        If the section is not present in the config file, an empty dictionary is returned.
+
+        The default config file is looked for at
+        (the default user config directory) / 'sier2sier2.ini'.
+        On Windows, the config directory is ``$ENV:APPDATA``; on Linux, ``$XDG_CONFIG_HOME``
+        or ``$HOME/.config``.
+
+        An alternative config file can be specified by setting ``Config.location`` before
+        any dag or block is executed. THis can be done from a command line using
+        the ``--config`` option.
+
+        Parameters
+        ----------
+        block: Block
+            The specified block's config section will be returned. Defaults to ``self``.
+
+        Returns
+        -------
+        A dictionary containing the section's keys and values.
+        """
+
+        b = block if block is not None else self
+        name = f'block.{b.block_key()}'
+
+        return Config[name]
+
+    def get_config_value(self, key: str, default: Any=None, *, block: 'Block'=None):
+        """Return an individual value from the section specified by
+        the block in the sier2 config file.
+
+        See :func:`sier2.Block.get_config` for more details.
+
+        Parameters
+        ----------
+        key: str
+            The key of the value to be returned.
+        default: Any
+            The default value to return if the section or key are not present in the config file.
+        block: Block
+            The specified block's config section will be returned. Defaults to ``self``.
+        """
+
+        b = block if block is not None else self
+        name = f'block.{b.block_key()}'
+        value = Config[name, key]
+
+        return value if value is not None else default
+
     def prepare(self):
         """If blockpause_execution is True, called by a dag before calling ``execute()```.
 
@@ -140,25 +228,6 @@ class Block(param.Parameterized):
         # 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."""
 
@@ -177,37 +246,6 @@ class Block(param.Parameterized):
 
         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 ``Block.prepare()`` or ``Block.execute()`` determines that input data is invalid.
 

sier2-0.35/src/sier2/_config.py

@@ -0,0 +1,223 @@
+# A configuration module.
+#
+
+import ast
+import configparser
+import os
+from pathlib import Path
+from typing import Any
+
+# If this key exists in a section and has the value False,
+# this section will not be updated.
+#
+CONFIG_UPDATE = 'config_update'
+
+def _default_config_file():
+    if os.name=='nt':
+        prdir = Path(os.environ['APPDATA']) / 'sier2'
+    else:
+        prdir = os.environ.get('XDG_CONFIG_HOME', None)
+        if prdir:
+            prdir = Path(prdir)
+        else:
+            prdir = Path.home() / '.config'
+
+        prdir = prdir / 'sier2'
+
+    if not prdir.exists():
+        prdir.mkdir(parents=True)
+
+    return prdir / 'sier2.ini'
+
+class _Config:
+    """This class is for internal use.
+
+    A single instance of this class is exposed publicly as ``Config``.
+    """
+
+    def __init__(self):
+        self._clear()
+
+    @staticmethod
+    def update(*, location: Path|str|None=None, config_block: str|None=None, update_arg: str|None=None, write_to_file: bool=False):
+        """Update the config.
+
+        If ``location`` has a value, that config file will be used instead of the default.
+
+        If config_block has a value, it must be the name of a block that has
+        an ``out_config`` param. The ``out_config`` param must contain a string that is
+        the content of a sier2 ini file. If ``update_arg`` is specified and the block has
+        an ``in_arg`` param, ``in_arg`` is set to ``update_arg``.
+
+        Parameters
+        ----------
+        location: Path|str|None
+            The location of a config file that will be loaded when a config is read.
+        config_block: str|None
+            A sier2 block that returns the contents of a config file in ``out_config``.
+        update_arg: str|None
+            A string that is passed to the ``config_block`` block is it has an ``in_arg`` param.
+        write_to_file: bool
+            If True, the config file at ``location`` is overwritten with the merged config.
+        """
+
+        if location:
+            Config.location = location
+
+        if config_block:
+            # Import here, otherwise there's a circular dependency Library -> Config -> Library.
+            # Config blocks better not have any config.
+            #
+            from sier2 import Library
+
+            block = Library.get_block(config_block)()
+
+            if not hasattr(block, 'out_config'):
+                raise ValueError('config block does not have out param "out_config"')
+
+            if hasattr(block, 'in_arg'):
+                block.in_arg = update_arg
+
+            block.execute()
+            Config._update(block.out_config, write_to_file=write_to_file)
+
+    def _clear(self):
+        self._location = _default_config_file()
+        self._config = {}
+        self._loaded = False
+
+    @property
+    def location(self) -> Path:
+        """Get or set the config file location.
+
+        By default, this is `$ENV:APPDATA/sier2/sier2.ini` on Window,
+        and `$XDG_CONFIG_HOME/sier2/sier2.ini` on Linux.
+
+        The location cannot be set if the config file has already been loaded.
+        """
+
+        return self._location
+
+    @location.setter
+    def location(self, config_file: Path|str):
+        if self._loaded:
+            raise ValueError('Config is already loaded')
+
+        if not isinstance(config_file, Path):
+            config_file = Path(config_file)
+
+        self._location = config_file
+
+    def _update(self, ini: str, write_to_file: bool=False):
+        """Update the config file using ini, which contains the contents of another config file.
+
+        The current config is also updated.
+
+        The config file cannot be updated if it has already been loaded.
+        """
+
+        if self._loaded:
+            raise ValueError('Config is already loaded')
+
+        new_config = configparser.ConfigParser()
+        new_config.read_string(ini)
+
+        config = configparser.ConfigParser()
+        if self._location.is_file():
+            config.read(self._location)
+
+        for section_name in new_config.sections():
+            if not config.has_section(section_name):
+                config.add_section(section_name)
+                config[section_name].update(new_config[section_name])
+            else:
+                update_section = True
+                if CONFIG_UPDATE in config[section_name]:
+                    update_section = ast.literal_eval(config[section_name][CONFIG_UPDATE])
+                    if not isinstance(update_section, bool):
+                        raise ValueError(f'Value of [{section_name}].{CONFIG_UPDATE} is not a bool')
+
+                if update_section:
+                    config[section_name].update(new_config[section_name])
+                    # for k, v in new_config[section_name].items():
+                    #     config[section_name][k] = new_config[section_name][k]
+
+        if write_to_file:
+            with open(self._location, 'w', encoding='utf-8') as f:
+                config.write(f)
+
+        self._config = config
+        self._loaded = True
+
+    def _load(self):
+        """Load the config.
+
+        Overwrites any previous config. If the location does not exist, the config will be empty.
+        """
+
+        self._config = configparser.ConfigParser()
+        if self._location.is_file():
+            self._config.read(self._location)
+
+        # The config has been loaded, even if the file didn't exist.
+        #
+        self._loaded = True
+
+    def _load_string(self, sconfig):
+        """For testing."""
+
+        self._config = configparser.ConfigParser()
+        self._config.read_string(sconfig)
+        self._loaded = True
+
+    def __getitem__(self, section_name: str|tuple[str, str]) -> Any|dict[str, Any]:
+        """If section_name is a string, get the config values for the given section name.
+
+        The config file is lazily loaded. Non-existence of the file is normal.
+        The keys and values for the specified section are loaded into a new dictionary,
+        which is returned.
+
+        Since configparser always returns values as strings, the values are evaluated
+        using :func:`ast.literal_eval` to be correctly typed. This means that strings in the
+        .ini file must be surrounded by quotes.
+
+        A section name for a block is of the form 'block.block_key_name'.
+
+        The name need not to exist; if it doesn't, an empty dictionary is returned.
+
+        If section_name is a tuple, it is interpreted as (section_name, key). If the
+        section_name and key exist, the value of the key is returned, else None is returned.
+        Only that single value is evaluated.
+        """
+
+        if not self._loaded:
+            self._load()
+
+        if isinstance(section_name, tuple):
+            section_name, key = section_name
+            if section_name not in self._config:
+                return None
+
+            section = self._config[section_name]
+            if key not in section:
+                return None
+
+            try:
+                v = section[key]
+                return ast.literal_eval(v)
+            except ValueError:
+                raise ValueError(f'Cannot eval section [{section_name}], key {key}, value {v}')
+
+        if section_name not in self._config:
+            return {}
+
+        c = {}
+        for key, v in self._config[section_name].items():
+            try:
+                c[key] = ast.literal_eval(v)
+            except ValueError:
+                raise ValueError(f'Cannot eval section [{section_name}], key {key}, value {v}')
+
+        return c
+
+Config = _Config()

{sier2-0.29 → sier2-0.35}/src/sier2/_dag.py

@@ -144,12 +144,29 @@ _RESTART = ':restart:'
 class Dag:
     """A directed acyclic graph of blocks."""
 
-    def __init__(self, *, site: str='Block', title: str, doc: str, author: dict[str, str]=None):
+    def __init__(self, *, site: str='Block', title: str, doc: str, author: dict[str, str]=None, show_doc: bool=True):
+        """A new dag.
+
+        Parameters
+        ----------
+        site: str
+            Name of the site.
+        title: str
+            A title to show in the header.
+        doc: str
+            Dag documentation.
+        author: str
+            The dag author.
+        show_doc: bool
+            Show the dag docstring if True.
+        """
+
         self._block_pairs: list[tuple[Block, Block]] = []
 
         self.site = site
         self.title = title
         self.doc = doc
+        self.show_doc = show_doc
 
         if author is not None:
             if 'name' in author and 'email' in author:

{sier2-0.29 → sier2-0.35}/src/sier2/_library.py

@@ -7,6 +7,7 @@ import warnings
 
 from sier2 import Block, Dag, Connection, BlockError
 from sier2.panel import PanelDag
+from ._util import _import_item
 
 # Store a mapping from a unique key to a Block class.
 # When plugins are initially scanned, the classes are not loaded.
@@ -24,29 +25,6 @@ def docstring(func) -> str:
 
     return doc.split('\n')[0].strip()
 
-def _import_item(key):
-    """Look up an object by key.
-
-    The returned object may be a class (if a Block key) or a function (if a dag key).
-
-    See the Entry points specification at
-    https://packaging.python.org/en/latest/specifications/entry-points/#entry-points.
-    """
-
-    modname, qualname_separator, qualname = key.partition(':')
-    try:
-        obj = importlib.import_module(modname)
-        if qualname_separator:
-            for attr in qualname.split('.'):
-                obj = getattr(obj, attr)
-
-        return obj
-    except ModuleNotFoundError as e:
-        msg = str(e)
-        if not qualname_separator:
-            msg = f'{msg}. Is there a \':\' missing?'
-        raise BlockError(msg)
-
 def _find_blocks():
     yield from _find('blocks')
 
@@ -56,11 +34,15 @@ def _find_dags():
 def run_dag(dag_name):
     """Run the named dag."""
 
+    # TODO refactor this to allow specifying just the simple name when the re are no dups,
+    # but more of the qualified name where there are dups.
+    #
+
     ix = dag_name.rfind('.')
     if ix==-1:
         found_dag = None
         for _, d in _find_dags():
-            dparts = d.key.split('.')
+            dparts = d.key.replace(':', '.').split('.')
             if dparts[-1]==dag_name:
                 if found_dag:
                     raise BlockError(f'Found duplicate: {dag_name}, d')
@@ -73,10 +55,12 @@ def run_dag(dag_name):
         dag_name = found_dag.key
         ix = dag_name.rfind('.')
 
-    m = importlib.import_module(dag_name[:ix])
-    func = getattr(m, dag_name[ix+1:])
-    # if not issubclass(cls, Block):
-    #     raise BlockError(f'{key} is not a block')
+    # m = importlib.import_module(dag_name[:ix])
+    # func = getattr(m, dag_name[ix+1:])
+    # # if not issubclass(cls, Block):
+    # #     raise BlockError(f'{key} is not a block')
+
+    func = _import_item(found_dag.key)
 
     dag = func()
     if not hasattr(dag, 'show'):
@@ -159,7 +143,7 @@ class Library:
         block_class: type[Block]
             The Block's class.
         key: str
-            The Block's unique key string. By default, the block's block_key()
+            The Block's unique key string. By default, the block's :func:`sier2.Block.block_key`
             class method will be used to obtain the key.
         """
 
@@ -175,6 +159,22 @@ class Library:
 
     @staticmethod
     def get_block(key: str) -> type[Block]:
+        """Return the block class specified by the key.
+
+        Note that this is a ``Block`` sub-class, not an instance of a block.
+        The class can be used to instantiate one or more blocks.
+
+        Parameters
+        ----------
+        key: str
+            The unique name of the block class to be returned.
+
+        Returns
+        -------
+        type[Block]
+            A block class.
+        """
+
         if not _block_library:
             Library.collect_blocks()
 
@@ -199,7 +199,20 @@ class Library:
         return cast(type[Block], _block_library[key])
 
     @staticmethod
-    def get_dag(key: str) -> type[Dag]:
+    def get_dag(key: str) -> Dag:
+        """Return the dag specified by the key.
+
+        Parameters
+        ----------
+        key: str
+            The unique name of the dag to be returned.
+
+        Returns
+        -------
+        Dag
+            A dag.
+        """
+
         if not _dag_library:
             Library.collect_dags()
 

sier2-0.35/src/sier2/_util.py

@@ -0,0 +1,127 @@
+from functools import cache
+import importlib
+from importlib.metadata import entry_points
+import sys
+import warnings
+
+from sier2 import BlockError
+
+def _import_item(key):
+    """Look up an object by key.
+
+    The returned object may be a class (if a Block key) or a function (if a dag key).
+
+    See the Entry points specification at
+    https://packaging.python.org/en/latest/specifications/entry-points/#entry-points.
+    """
+
+    modname, qualname_separator, qualname = key.partition(':')
+    try:
+        obj = importlib.import_module(modname)
+        if qualname_separator:
+            for attr in qualname.split('.'):
+                obj = getattr(obj, attr)
+
+        return obj
+    except ModuleNotFoundError as e:
+        msg = str(e)
+        if not qualname_separator:
+            msg = f'{msg}. Is there a \':\' missing?'
+        raise BlockError(msg)
+
+@cache
+def get_block_config():
+    """A convenience function to get block configuration data.
+
+    Block can run in different environments; for example, a block that has access to the
+    Internet may use a different configuration to the same block running in a corporate
+    environment.
+
+    This function looks up a block configuration provider using the ``sier2.config`` entry point,
+    which has the form `module-name:function-name`.
+
+    If no config package is found, or more than one config package is found,
+    a warning will be produced (using `warnings.warn()`), and a default config will be returned,
+    with the ``'config'`` key having the value ``None``.
+
+    See the `sier2-blocks-config` package for an example.
+    """
+
+    eps = list(entry_points(group='sier2.config'))
+    if len(eps)==1:
+        ep = eps[0].value
+        config_func = _import_item(ep)
+        config = config_func()
+    else:
+        msg = 'No block configuration found' if not eps else 'Multiple configs found'
+        warnings.warn(f'{msg}: returning config None')
+        config = {'config': None}
+
+    if 'config' not in config:
+        raise BlockError('config dictionary does not contain "config" key')
+
+    return config
+
+########
+# Documentation utilities
+########
+
+def trim(docstring):
+    """From PEP-257: Fix docstring indentation"""
+
+    if not docstring:
+        return ''
+    # Convert tabs to spaces (following the normal Python rules)
+    # and split into a list of lines:
+    lines = docstring.expandtabs().splitlines()
+    # Determine minimum indentation (first line doesn't count):
+    indent = sys.maxsize
+    for line in lines[1:]:
+        stripped = line.lstrip()
+        if stripped:
+            indent = min(indent, len(line) - len(stripped))
+    # Remove indentation (first line is special):
+    trimmed = [lines[0].strip()]
+    if indent < sys.maxsize:
+        for line in lines[1:]:
+            trimmed.append(line[indent:].rstrip())
+    # Strip off trailing and leading blank lines:
+    while trimmed and not trimmed[-1]:
+        trimmed.pop()
+    while trimmed and not trimmed[0]:
+        trimmed.pop(0)
+    # Return a single string:
+    return '\n'.join(trimmed)
+
+def block_doc_text(block):
+    """Generate text 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 = []
+    for name, doc in params:
+        text.append(f'- {name}:  {doc}\n')
+
+    return '---\n' + b_doc + '\n### Params\n' + '\n'.join(text)
+
+def dag_doc_text(dag):
+    """Generate text documentation for a dag."""
+
+    # 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 dag_text

{sier2-0.29 → sier2-0.35}/src/sier2/panel/_panel.py

@@ -8,6 +8,7 @@ from typing import Callable
 
 from sier2 import Block, BlockValidateError, BlockState, Dag, BlockError
 from .._dag import _InputValues
+from .._util import trim
 from ._feedlogger import getDagPanelLogger, getBlockPanelLogger
 from ._panel_util import _get_state_color, dag_doc
 
@@ -54,7 +55,7 @@ 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.
+    and converts block execution errors to BlockError exceptions.
 
     It also uses the panel UI to provide extra information to the user.
     """
@@ -225,11 +226,30 @@ def _prepare_to_show(dag: Dag):
     )
     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())
+    cards = []
+    if dag.show_doc:
+        # The first line of the dag doc is the card header.
+        #
+        doc = dag.doc.strip()
+        ix = doc.find('\n')
+        if ix>=0:
+            header = doc[:ix]
+            doc = doc[ix:].strip()
+        else:
+            header = ''
+
+        name_text = pn.widgets.StaticText(
+            value=header,
+            css_classes=['card-title'],
+            styles={'font-size':'1.17em', 'font-weight':'bold'}
         )
-    )
+
+        card = pn.Card(pn.pane.Markdown(doc, sizing_mode='stretch_width'), header=pn.Row(name_text), sizing_mode='stretch_width')
+        cards.append(card)
+
+    cards.extend(BlockCard(parent_template=template, dag=dag, w=gw, dag_logger=dag_logger) for gw in dag.get_sorted())
+
+    template.main.append(pn.Column(*cards))
     template.sidebar.append(
         pn.Column(
             switch,
@@ -315,6 +335,10 @@ class BlockCard(pn.Card):
             )
         )
 
+        # Does this block have documentation to be displayed in the card?
+        #
+        doc = pn.pane.Markdown(w.block_doc, sizing_mode='scale_width') if w.block_doc else None
+
         # 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.
@@ -369,14 +393,17 @@ class BlockCard(pn.Card):
                         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 = pn.widgets.Button(name=w.continue_label, button_type='primary', align='end')
             c_button.on_click(on_continue)
 
+            row = [doc, c_button] if doc else [c_button]
             w_ = pn.Column(
                 w,
-                pn.Row(c_button, align='end'),
-               sizing_mode='scale_width'
+                pn.Row(*row),
+               sizing_mode='stretch_width'
             )
+        elif doc:
+            w_ = pn.Column(w, doc)
         else:
             w_ = w
 

sier2-0.29/src/sier2/_util.py

@@ -1,65 +0,0 @@
-import sys
-
-########
-# Documentation utilities
-########
-
-def trim(docstring):
-    """From PEP-257: Fix docstring indentation"""
-
-    if not docstring:
-        return ''
-    # Convert tabs to spaces (following the normal Python rules)
-    # and split into a list of lines:
-    lines = docstring.expandtabs().splitlines()
-    # Determine minimum indentation (first line doesn't count):
-    indent = sys.maxsize
-    for line in lines[1:]:
-        stripped = line.lstrip()
-        if stripped:
-            indent = min(indent, len(line) - len(stripped))
-    # Remove indentation (first line is special):
-    trimmed = [lines[0].strip()]
-    if indent < sys.maxsize:
-        for line in lines[1:]:
-            trimmed.append(line[indent:].rstrip())
-    # Strip off trailing and leading blank lines:
-    while trimmed and not trimmed[-1]:
-        trimmed.pop()
-    while trimmed and not trimmed[0]:
-        trimmed.pop(0)
-    # Return a single string:
-    return '\n'.join(trimmed)
-
-def block_doc_text(block):
-    """Generate text 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 = []
-    for name, doc in params:
-        text.append(f'- {name}:  {doc}\n')
-
-    return '---\n' + b_doc + '\n### Params\n' + '\n'.join(text)
-
-def dag_doc_text(dag):
-    """Generate text documentation for a dag."""
-
-    # 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 dag_text