hypershell 2.6.4__py3-none-any.whl

hypershell/core/config.py

@@ -0,0 +1,359 @@
+# SPDX-FileCopyrightText: 2025 Geoffrey Lentner
+# SPDX-License-Identifier: Apache-2.0
+
+"""Runtime configuration for HyperShell."""
+
+
+# type annotations
+from __future__ import annotations
+from typing import TypeVar, Union, List, Optional, Protocol, Final, Iterator
+
+# standard libs
+import os
+import re
+import sys
+import shutil
+import tomlkit
+import logging
+import socket
+import functools
+from datetime import datetime
+
+# external libs
+from cmdkit.config import Namespace, Configuration, Environ, ConfigurationError
+from cmdkit.app import exit_status
+
+# internal libs
+from hypershell.core.platform import path, home
+from hypershell.core.exceptions import write_traceback
+
+# public interface
+__all__ = ['config', 'update', 'default', 'ConfigurationError', 'Namespace', 'blame',
+           'load', 'reload', 'reload_local', 'load_file', 'reload_file', 'load_env', 'reload_env', 'load_task_env',
+           'DEFAULT_LOGGING_STYLE', 'LOGGING_STYLES', 'ACTIVE_CONFIG_VARS', 'SSH_GROUPS',
+           'find_available_ports']
+
+# partial logging (not yet configured - initialized afterward)
+log = logging.getLogger(__name__)
+
+
+DEFAULT_LOGGING_STYLE = 'default'
+LOGGING_STYLES = {
+    'default': {
+        'format': ('%(ansi_bold)s%(ansi_level)s%(levelname)8s%(ansi_reset)s %(ansi_faint)s[%(name)s]%(ansi_reset)s'
+                   ' %(message)s'),
+    },
+    'system': {
+        'format': '%(asctime)s.%(msecs)03d %(hostname)s %(levelname)8s [%(app_id)s] [%(name)s] %(message)s',
+    },
+    'detailed': {
+        'format': ('%(ansi_faint)s%(asctime)s.%(msecs)03d %(hostname)s %(ansi_reset)s'
+                   '%(ansi_level)s%(ansi_bold)s%(levelname)8s%(ansi_reset)s '
+                   '%(ansi_faint)s[%(name)s]%(ansi_reset)s %(message)s'),
+    },
+    'detailed-compact': {
+        'format': ('%(ansi_faint)s%(elapsed_hms)s [%(hostname_short)s] %(ansi_reset)s'
+                   '%(ansi_level)s%(ansi_bold)s%(levelname)8s%(ansi_reset)s '
+                   '%(ansi_faint)s[%(relative_name)s]%(ansi_reset)s %(message)s'),
+    }
+}
+
+
+# environment variables and configuration files are automatically
+# depth-first merged with defaults
+default = Namespace({
+
+    'database': {
+        'provider': 'sqlite',
+    },
+
+    'logging': {
+        'color': True,
+        'level': 'warning',
+        'datefmt': '%Y-%m-%d %H:%M:%S',
+        'style': DEFAULT_LOGGING_STYLE,
+        **LOGGING_STYLES.get(DEFAULT_LOGGING_STYLE),
+    },
+
+    'task': {
+        'cwd': os.getcwd(),
+        'timeout': None,    # seconds, period to wait before killing tasks
+        'signalwait': 10,   # seconds to wait between signal escalation (INT, TERM, KILL)
+    },
+
+    'submit': {
+        'bundlesize': 1,    # size of task bundle to accumulate before committing
+        'bundlewait': 5     # seconds to wait before committing regardless of size
+    },
+
+    'server': {
+        'bind': 'localhost',
+        'port': 50_001,
+        'auth': '__HYPERSHELL__BAD__AUTHKEY__',
+        'queuesize': 1,     # only allow a single bundle (scheduler must wait)
+        'bundlesize': 1,
+        'bundlewait': 5,    # seconds
+        'attempts': 1,
+        'eager': False,     # prefer failed tasks to new tasks
+        'wait': 5,          # seconds to wait between database queries
+        'evict': 600,       # assume client is gone if no heartbeat after this many seconds
+    },
+
+    'client': {
+        'bundlesize': 1,    # size of task bundle to accumulate before returning
+        'bundlewait': 5,    # seconds to wait before returning regardless of size
+        'heartrate': 10,    # seconds to wait between heartbeats
+        'timeout': None,    # seconds to wait for bundle from server before shutting down
+    },
+
+    'ssh': {
+        'config': os.path.join(home, '.ssh', 'config'),
+        'nodelist': {}  # Populated by user configuration
+    },
+
+    'autoscale': {
+        'policy': 'fixed',  # Either 'fixed' or 'dynamic'
+        'factor': 1,
+        'period': 60,  # seconds to wait between checks
+        'launcher': '',  # empty means just 'hs client'
+        'size': {
+            'init': 1,
+            'min': 0,
+            'max': 2,
+        },
+    },
+
+    'console': {
+        'theme': 'monokai',
+    },
+
+    # NOTE: defining HYPERSHELL_EXPORT_XXX defines XXX within task env
+    'export': {}
+})
+
+
+def reload_file(filepath: str) -> Namespace:
+    """Force reloading configuration file."""
+    if not os.path.exists(filepath):
+        return Namespace({})
+    try:
+        return Namespace.from_toml(filepath)
+    except Exception as err:
+        raise ConfigurationError(f'(from file: {filepath}) {err.__class__.__name__}: {err}')
+
+
+@functools.lru_cache(maxsize=None)
+def load_file(filepath: str) -> Namespace:
+    """Load configuration file."""
+    return reload_file(filepath)
+
+
+def reload_env() -> Environ:
+    """Force reloading environment variables and expanding hierarchy as namespace."""
+    return Environ(prefix='HYPERSHELL').expand()
+
+
+@functools.lru_cache(maxsize=None)
+def load_env() -> Environ:
+    """Load environment variables and expand hierarchy as namespace."""
+    return reload_env()
+
+
+def partial_load(system: Optional[str] = path.system.config,
+                 user: Optional[str] = path.user.config,
+                 local: Optional[str] = path.local.config,
+                 **preload: Namespace) -> Configuration:
+    """Load configuration from files and merge environment variables."""
+    return Configuration(**{
+        'default': default, **preload,
+        'system': {} if not system else load_file(system),
+        'user': {} if not user else load_file(user),
+        'local': {} if not user else load_file(local),
+        'env': load_env(),
+    })
+
+
+def partial_reload(system: Optional[str] = path.system.config,
+                   user: Optional[str] = path.user.config,
+                   local: Optional[str] = path.local.config,
+                   **preload: Namespace) -> Configuration:
+    """Force reload configuration from files and merge environment variables."""
+    return Configuration(**{
+        'default': default, **preload,
+        'system': {} if not system else reload_file(system),
+        'user': {} if not user else reload_file(user),
+        'local': {} if not local else reload_file(local),
+        'env': reload_env(),
+    })
+
+
+def blame(base: Configuration, *varpath: str) -> Optional[str]:
+    """Construct filename or variable assignment string based on precedent of `varpath`."""
+    source = base.which(*varpath)
+    if not source:
+        return None
+    if source in ('system', 'user', 'local'):
+        return f'from: {path.get(source).config}'
+    elif source == 'env':
+        return 'from: HYPERSHELL_' + '_'.join([node.upper() for node in varpath])
+    else:
+        return f'from: <{source}>'
+
+
+def get_logging_style(base: Configuration) -> str:
+    """Get and check valid on `config.logging.style`."""
+    style = base.logging.style
+    label = blame(base, 'logging', 'style')
+    if not isinstance(style, str):
+        raise ConfigurationError(f'Expected string for `logging.style` ({label})')
+    style = style.lower()
+    if style in LOGGING_STYLES:
+        return style
+    else:
+        raise ConfigurationError(f'Unrecognized `logging.style` \'{style}\' ({label})')
+
+
+def build_preloads(base: Configuration) -> Namespace:
+    """Build 'preload' namespace from base configuration."""
+    return Namespace({'logging': LOGGING_STYLES.get(get_logging_style(base))})
+
+
+class LoaderImpl(Protocol):
+    """Loader interface for building configuration."""
+    def __call__(self: LoaderImpl,
+                 system: Optional[str] = path.system.config,
+                 user: Optional[str] = path.user.config,
+                 local: Optional[str] = path.local.config,
+                 **preload: Namespace) -> Configuration: ...
+
+
+def build_configuration(loader: LoaderImpl) -> Configuration:
+    """Construct full configuration."""
+    return loader(preload=build_preloads(base=loader()))
+
+
+def load() -> Configuration:
+    """Load configuration from files and merge environment variables."""
+    return build_configuration(loader=partial_load)
+
+
+def reload() -> Configuration:
+    """Load configuration from files and merge environment variables."""
+    return build_configuration(loader=partial_reload)
+
+
+def reload_local(filepath: Optional[str] = None) -> Configuration:
+    """Load configuration but only include one file."""
+    loader = functools.partial(partial_reload, system=None, user=None, local=filepath)
+    return build_configuration(loader=loader)
+
+
+try:
+    if (local_config := os.getenv('HYPERSHELL_CONFIG_FILE', None)) is not None:
+        path.local.config = local_config  # Modified as to not lie to the user
+        config = reload_local(local_config)
+    else:
+        config = load()
+except Exception as error:
+    write_traceback(error, module=__name__)
+    sys.exit(exit_status.bad_config)
+
+
+ACTIVE_CONFIG_VARS: Final[List[str]] = [
+    re.sub(r'_(?!(env|eval))', r'.', name.lower())
+    for name in Namespace(config).to_env().flatten()
+]
+
+
+SSH_GROUPS = []
+try:
+    if isinstance(config.ssh.nodelist, dict):
+        SSH_GROUPS = list(config.ssh.nodelist)
+except KeyError:
+    pass
+
+
+def find_available_ports(start: int = default.server.port,
+                         end: int = default.server.port + 1_000) -> Iterator[int]:
+    """Yield available ports by testing each in turn."""
+    for port in range(start, end + 1):
+        with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as sock:
+            sock.settimeout(1)
+            try:
+                sock.bind(("0.0.0.0", port))
+                yield port
+            except socket.error:
+                pass
+    else:
+        raise RuntimeError(f'Could not find available port in range {start}-{end}')
+
+
+DEFAULT_CONFIG_HEADERS = f"""\
+# File automatically created on {datetime.now()}
+# Settings here are merged automatically with defaults and environment variables
+"""
+
+
+def update(scope: str, partial: dict) -> None:
+    """Extend the current configuration and commit it to disk."""
+    config_path = path[scope].config
+    os.makedirs(os.path.dirname(config_path), exist_ok=True)
+    if os.path.exists(config_path):
+        timestamp = datetime.now().strftime('%Y%m%d-%H%M%S')
+        config_backup_path = os.path.join(os.path.dirname(config_path), f'.config.{timestamp}.toml')
+        shutil.copy(config_path, config_backup_path)
+        shutil.copystat(config_path, config_backup_path)
+        log.debug(f'Created backup file ({config_backup_path})')
+    else:
+        with open(config_path, mode='w') as stream:
+            stream.write(DEFAULT_CONFIG_HEADERS)
+    with open(config_path, mode='r') as stream:
+        new_config = tomlkit.parse(stream.read())
+    _inplace_update(new_config, partial)
+    with open(config_path, mode='w') as stream:
+        tomlkit.dump(new_config, stream)
+
+
+# Re-implemented from `cmdkit.config.Namespace` (but works with `tomlkit`)
+def _inplace_update(original: dict, partial: dict) -> dict:
+    """
+    Like normal `dict.update` but if values in both are mappable, descend
+    a level deeper (recursive) and apply updates there instead.
+    """
+    for key, value in partial.items():
+        if isinstance(value, dict) and isinstance(original.get(key), dict):
+            original[key] = _inplace_update(original.get(key, {}), value)
+        else:
+            original[key] = value
+    return original
+
+
+if os.name == 'nt':
+    PATH_DELIMITER = ';'
+else:
+    PATH_DELIMITER = ':'
+
+
+T = TypeVar('T')
+
+
+def __collapse_if_list_impl(value: Union[T, List[str]]) -> Union[T, str]:
+    """If `value` is a list, collapse it to a path-like list (with ':' or ';')."""
+    return value if not isinstance(value, list) else PATH_DELIMITER.join([str(member) for member in value])
+
+
+def __collapse_lists(ns: Namespace) -> Namespace:
+    """Collapse member values if they are a list, recursively."""
+    result = Namespace()
+    for key, value in ns.items():
+        if isinstance(value, Namespace):
+            result[key] = __collapse_lists(value)
+        else:
+            result[key] = __collapse_if_list_impl(value)
+    return result
+
+
+@functools.cache
+def load_task_env() -> Environ:
+    """Export environment defined in `config.export`."""
+    return __collapse_lists(config.export).to_env().flatten()

hypershell/core/exceptions.py

@@ -0,0 +1,120 @@
+# SPDX-FileCopyrightText: 2025 Geoffrey Lentner
+# SPDX-License-Identifier: Apache-2.0
+
+"""Core exception handling useful for import-time issues."""
+
+
+# type annotations
+from __future__ import annotations
+from typing import Dict, Union, Callable, Type
+
+# standard libraries
+import os
+import sys
+import logging
+import functools
+import traceback
+from datetime import datetime
+
+# external libs
+from cmdkit.app import exit_status
+from cmdkit.config import Namespace
+from cmdkit.config import ConfigurationError
+from cmdkit.ansi import faint, bold, magenta, yellow, red, COLOR_STDERR
+
+# internal libs
+from hypershell.core.platform import default_path
+
+# public interface
+__all__ = ['display_warning', 'display_error', 'display_critical', 'traceback_filepath', 'write_traceback',
+           'handle_exception', 'handle_exception_silently', 'handle_disconnect', 'handle_address_unknown',
+           'HostAddressInfo', 'DatabaseUninitialized',
+           'get_shared_exception_mapping', ]
+
+
+def _display_message(levelname: str, error: Union[Exception, str],
+                     module: str = None, colorized: Callable[[str], str] = None) -> None:
+    """Generic message display for import-time warnings and errors."""
+    text = error if isinstance(error, str) else f'{error.__class__.__name__}: {error}'
+    if COLOR_STDERR:
+        name = '' if not module else faint(f'[{module}]')
+        level = levelname if colorized is None else bold(colorized(levelname))
+    else:
+        name = '' if not module else f'[{module}]'
+        level = levelname
+    print(f'{level} {name} {text}', file=sys.stderr)
+
+
+# Specialized methods for each severity level
+display_warning = functools.partial(_display_message, 'WARNING', colorized=yellow)
+display_error = functools.partial(_display_message, 'ERROR', colorized=red)
+display_critical = functools.partial(_display_message, 'CRITICAL', colorized=magenta)
+
+
+class HostAddressInfo(Exception):
+    """Could not resolve hostname."""
+
+
+class DatabaseUninitialized(Exception):
+    """The database needs to be initialized before operations."""
+
+
+def traceback_filepath(path: Namespace = None) -> str:
+    """Construct filepath for writing traceback."""
+    path = path or default_path
+    time = datetime.now().strftime('%Y%m%d-%H%M%S')
+    return os.path.join(path.log, f'exception-{time}.log')
+
+
+def write_traceback(exc: Exception, site: Namespace = None, logger: logging.Logger = None,
+                    status: int = exit_status.uncaught_exception, module: str = None) -> int:
+    """Write exception to file and return exit code."""
+    write = functools.partial(display_critical, module=module) if not logger else logger.critical
+    path = traceback_filepath(site)
+    with open(path, mode='w') as stream:
+        print(traceback.format_exc(), file=stream)
+    write(f'{exc.__class__.__name__}: ' + str(exc).replace('\n', ' - '))
+    write(f'Exception traceback written to {path}')
+    return status
+
+
+def handle_disconnect(exc: Exception, logger: logging.Logger) -> int:
+    """An EOFError results from the server hanging up the client."""
+    logger.critical(f'{exc.__class__.__name__}: server disconnected')
+    return exit_status.runtime_error
+
+
+def handle_exception(exc: Exception, logger: logging.Logger, status: int) -> int:
+    """Log the exception argument and exit with `status`."""
+    logger.critical(f'{exc.__class__.__name__}: ' + str(exc).replace('\n', ' - '))
+    return status
+
+
+def handle_exception_silently(exc: Exception) -> int:
+    """Return status held by `exc.args` without logging."""
+    status, = exc.args
+    return status
+
+
+def handle_address_unknown(exc: Exception,  # noqa: unused
+                           logger: logging.Logger,
+                           status: int = exit_status.runtime_error) -> int:
+    """Could not get address info for hostname (see `socket.gaierror`)."""
+    logger.critical(f'{exc.__class__.__name__}: {exc}')
+    return status
+
+
+def get_shared_exception_mapping(modname: str = 'hypershell') -> Dict[Type[Exception], Callable[[Exception], int]]:
+    """Globally defined exception cases for all application subcommands."""
+    # We need a single location to define basic exception cases but cannot define them under
+    # `hypershell.__init__` as a class-level override of `Application.exceptions` because the
+    # subcommand classes are imported first. This function is now part of core and has no
+    # internal dependencies, so it can be imported by all other modules.
+    logger = logging.getLogger(modname)
+    return {
+        RuntimeError: functools.partial(handle_exception, logger=logger, status=exit_status.runtime_error),
+        FileNotFoundError: functools.partial(handle_exception, logger=logger, status=exit_status.runtime_error),
+        ConfigurationError: functools.partial(handle_exception, logger=logger, status=exit_status.bad_config),
+        DatabaseUninitialized: functools.partial(handle_exception, logger=logger, status=exit_status.runtime_error),
+        Exception: functools.partial(write_traceback, logger=logger, status=exit_status.runtime_error),
+    }

hypershell/core/fsm.py

@@ -0,0 +1,82 @@
+# SPDX-FileCopyrightText: 2025 Geoffrey Lentner
+# SPDX-License-Identifier: Apache-2.0
+
+"""Instrumentation for building finite state machines."""
+
+
+# type annotations
+from __future__ import annotations
+from typing import Dict, Callable, Type
+
+# standard libs
+from enum import Enum
+from abc import ABC
+# FUZZ: import time
+# FUZZ: import random
+# PERF: from collections import defaultdict
+# PERF: from time import perf_counter
+
+# internal libs
+from hypershell.core.exceptions import write_traceback
+from hypershell.core.logging import Logger
+
+# public interface
+__all__ = ['State', 'StateMachine', ]
+
+
+log = Logger.with_name(__name__)
+
+
+class State(Enum):
+    """Shared base for finite state enums (must have at least HALT)."""
+
+
+class StateMachine(ABC):
+    """Base class for a finite state machine implementation."""
+
+    state: State
+    states: Type[State]
+    actions: Dict[State, Callable[[], State]]
+
+    __should_halt: bool = False
+
+    # NOTE: Only needed during performance profiling
+    # PERF: __perf_counter: float = 0
+    # PERF: __perf_data: Dict[int, float]
+
+    def next(self) -> State:
+        """Return next state (halt if necessary)."""
+        previous_state = self.state
+        try:
+            if self.__should_halt:
+                return self.states.HALT  # noqa: HALT defined in implemented State enums
+            else:
+                action = self.actions.get(previous_state)
+                # PERF: self.__perf_counter = perf_counter()
+                next_state = action()
+                # PERF: self.__perf_data[previous_state.value] += perf_counter() - self.__perf_counter
+        except Exception as error:
+            # NOTE: Only non-RuntimeError instances are "unexpected"
+            if not isinstance(error, RuntimeError):
+                log.critical(f'Uncaught exception from {self.__class__}')
+                write_traceback(error, logger=log, module=__name__)
+            raise
+        else:
+            # NOTE: Development aids not typically engaged
+            # FUZZ: time.sleep(random.uniform(0, 5))  # FUZZ
+            # FUZZ: log.devel(f'{self.__class__.__name__}: {previous_state} -> {next_state}')
+            return next_state
+
+    def run(self) -> None:
+        """Run machine until state is set to `HALT`."""
+        # PERF: self.__perf_data = defaultdict(lambda: 0)
+        while self.state is not self.states.HALT:  # noqa: HALT defined in implemented State enums
+            self.state = self.next()
+        # PERF: time_total = sum(self.__perf_data.values())
+        # PERF: for key, value in self.__perf_data.items():
+        # PERF:     t = 100 * value / time_total
+        # PERF:     log.trace(f'Profiler[{self.__class__.__name__}] {self.states(key).name}: {t:.3f}')
+
+    def halt(self) -> None:
+        """Set flag to signal for termination."""
+        self.__should_halt = True

hypershell/core/heartbeat.py

@@ -0,0 +1,70 @@
+# SPDX-FileCopyrightText: 2025 Geoffrey Lentner
+# SPDX-License-Identifier: Apache-2.0
+
+"""Heartbeat data passed between client and server."""
+
+
+# type annotations
+from __future__ import annotations
+from typing import Type
+
+# standard libs
+import json
+from enum import Enum
+from datetime import datetime
+from dataclasses import dataclass
+
+# internal libs
+from hypershell.core.logging import HOSTNAME, INSTANCE
+
+# public interface
+__all__ = ['ClientState', 'Heartbeat']
+
+
+class ClientState(Enum):
+    """Client state."""
+
+    RUNNING = 0
+    FINISHED = 1
+
+    @classmethod
+    def from_value(cls: Type[ClientState], value: int) -> ClientState:
+        """Instance from associated integer value."""
+        return {0: cls.RUNNING, 1: cls.FINISHED}.get(value)
+
+
+@dataclass
+class Heartbeat:
+    """Momentary notice of a client's active status."""
+
+    uuid: str
+    host: str
+    time: datetime
+    state: ClientState
+
+    @classmethod
+    def new(cls: Type[Heartbeat],
+            uuid: str = None,
+            host: str = None,
+            time: datetime = None,
+            state: ClientState = None) -> Heartbeat:
+        """Create new instance."""
+        return cls(uuid=(uuid or INSTANCE),
+                   host=(host or HOSTNAME),
+                   time=(time or datetime.now().astimezone()),
+                   state=(state or ClientState.RUNNING))
+
+    def pack(self: Heartbeat) -> bytes:
+        """Serialize data."""
+        return json.dumps({'uuid': self.uuid,
+                           'host': self.host,
+                           'time': str(self.time),
+                           'state': self.state.value}).encode('utf-8')
+
+    @classmethod
+    def unpack(cls: Type[Heartbeat], data: bytes) -> Heartbeat:
+        """Deserialize from raw `data`."""
+        data = json.loads(data.decode('utf-8'))
+        data['time'] = datetime.fromisoformat(data['time'])
+        data['state'] = ClientState.from_value(data['state'])
+        return cls(**data)