hypershell 2.6.4__py3-none-any.whl

hypershell/core/signal.py

@@ -0,0 +1,79 @@
+# SPDX-FileCopyrightText: 2025 Geoffrey Lentner
+# SPDX-License-Identifier: Apache-2.0
+
+"""Signal handling facility."""
+
+
+# type annotations
+from __future__ import annotations
+from typing import Optional, Final, Dict
+from types import FrameType
+
+# standard libs
+import platform
+from signal import signal as register
+
+
+# internal libs
+from hypershell.core.logging import Logger
+
+# public interface
+__all__ = ['check_signal', 'RECEIVED', 'SIGNAL_MAP',
+           'handler', 'register_handlers', 'register',
+           'SIGUSR1', 'SIGUSR2', 'SIGINT', 'SIGTERM', 'SIGKILL']
+
+
+if platform.system() != 'Windows':
+    from signal import SIGUSR1, SIGUSR2, SIGINT, SIGTERM, SIGKILL
+else:
+    # NOTE:
+    # Windows does not provide the signal facility
+    # While valid, these stubs have no effect because on Windows we never signal
+    SIGUSR1: Final[int] = 30
+    SIGUSR2: Final[int] = 31
+    SIGINT: Final[int] = 2
+    SIGTERM: Final[int] = 15
+    SIGKILL: Final[int] = 9
+
+
+# initialize logger
+log = Logger.with_name(__name__)
+
+
+# Global signal value set by handler when received
+RECEIVED: Optional[int] = None
+
+
+def check_signal() -> Optional[int]:
+    """Check for signal received and return if so."""
+    return RECEIVED
+
+
+SIGNAL_MAP: Final[Dict[int, str]] = {
+    SIGUSR1: 'SIGUSR1',
+    SIGUSR2: 'SIGUSR2',
+    SIGINT:  'SIGINT',
+    SIGTERM: 'SIGTERM',
+    SIGKILL: 'SIGKILL',
+}
+
+
+def handler(signum: int, frame: Optional[FrameType]) -> None:  # noqa: unused frame
+    """Generic handler assigns `signum` to global variable."""
+    log.debug(f'Received signal {signum}: {SIGNAL_MAP.get(signum, "???")}')
+    global RECEIVED
+    RECEIVED = signum
+
+
+if platform.system() == 'Windows':
+
+    def register_handlers() -> None:
+        """Empty function does nothing on Windows."""
+        pass
+
+else:
+
+    def register_handlers() -> None:
+        """Register signal handlers for client."""
+        register(SIGUSR1, handler)
+        register(SIGUSR2, handler)

hypershell/core/sys.py

@@ -0,0 +1,39 @@
+# SPDX-FileCopyrightText: 2025 Geoffrey Lentner
+# SPDX-License-Identifier: Apache-2.0
+
+"""
+Sanitize and supplement package environment.
+
+For most installations this module does nothing and can be ignored.
+For system installation as an application (non-library use) we do not want user
+programs (which may be Python-based with PYTHONPATH implications) to interfere
+with this program.
+
+If we are not installed in the user-site, we strip the user site-packages from
+`sys.path` as well as the current working directory. It should not matter what
+directory you run this program from.
+
+If `ctx.path.system.config`/hypershell.pth exists it will take this as truth
+"""
+
+# Standard libs
+import sys
+
+if sys
+
+# NOTE:
+#    This special module freezes the internal sys.path used by the application.
+#    We do not want to do this for library use or under any normal circumstances.
+#    When the program is installed system wide as a utility we need to ensure that
+#    we are not being polluted by some other applications environment (e.g., PYTHONPATH).
+#    This also allows us to suppliment with special locations of vendored dependencies.
+print('FIXING IMPORTS', flush=True)
+sys.path.clear()
+sys.path.extend([
+    '/Library/Frameworks/Python.framework/Versions/3.12/lib/python312.zip',
+    '/Library/Frameworks/Python.framework/Versions/3.12/lib/python3.12',
+    '/Library/Frameworks/Python.framework/Versions/3.12/lib/python3.12/lib-dynload',
+    '/Users/geoffrey/Library/Caches/pypoetry/virtualenvs/hypershell-NY9Seigz-py3.12/lib/python3.12/site-packages',
+    '/Users/geoffrey/Code/github.com/hypershell/hypershell/src'
+])
+print('FIXING IMPORTS - DONE', flush=True)

hypershell/core/tag.py

@@ -0,0 +1,47 @@
+# SPDX-FileCopyrightText: 2025 Geoffrey Lentner
+# SPDX-License-Identifier: Apache-2.0
+
+"""Tag interface and parsing."""
+
+
+# type annotations
+from __future__ import annotations
+from typing import Dict, List, Optional, Type
+
+# standard libs
+from dataclasses import dataclass
+
+# internal libs
+from hypershell.core.types import JSONValue, smart_coerce
+
+# public interface
+__all__ = ['Tag', ]
+
+
+@dataclass
+class Tag:
+    """Tag specification."""
+
+    name: str
+    value: JSONValue = ''
+
+    def to_dict(self: Tag) -> Dict[str, JSONValue]:
+        """Format tag specification as dictionary."""
+        return {self.name: self.value, }
+
+    @classmethod
+    def from_cmdline(cls: Type[Tag], arg: str) -> Tag:
+        """Construct from command-line `arg`."""
+        tag_part = arg.strip().split(':', 1)
+        if len(tag_part) == 1:
+            return cls(name=tag_part[0].strip())
+        else:
+            name, value = tag_part[0].strip(), smart_coerce(tag_part[1].strip())
+            # Task.ensure_valid_tag({name: value})
+            return cls(name, value)
+
+    @classmethod
+    def parse_cmdline_list(cls: Type[Tag], args: List[str]) -> Dict[str, Optional[JSONValue]]:
+        """Parse command-line list of tags."""
+        return {tag.name: tag.value for tag in map(cls.from_cmdline, args)}
+

hypershell/core/template.py

@@ -0,0 +1,201 @@
+# SPDX-FileCopyrightText: 2025 Geoffrey Lentner
+# SPDX-License-Identifier: Apache-2.0
+
+"""Template expansion facility for task execution."""
+
+
+# type annotations
+from __future__ import annotations
+from typing import Dict, Callable
+from types import ModuleType
+
+# standard libs
+import os
+import re
+import math
+import datetime
+import subprocess
+import functools
+
+# internal libs
+from hypershell.core.types import smart_coerce
+
+# public interface
+__all__ = ['Template', 'DEFAULT_TEMPLATE', ]
+
+
+# Matched in template and expanded accordingly
+PATTERN: re.Pattern = re.compile(r'{(.*?)}')
+
+
+# A plain {} is replaced verbatim with the input arguments
+DEFAULT_TEMPLATE = '{}'
+
+
+# Exposed modules for lambda expressions in templates
+EXPOSED_MODULES: Dict[str, ModuleType] = {
+    'os': os,
+    'path': os.path,
+    'math': math,
+    'dt': datetime,
+}
+
+
+class Template:
+    """Manage template expansion from command arguments."""
+
+    _template: str
+
+    def __init__(self: Template, template: str = DEFAULT_TEMPLATE) -> None:
+        """Initialize template with input `args` and `template` for expansion."""
+        self.template = template
+
+    @property
+    def template(self: Template) -> str:
+        """Access underlying raw string value."""
+        return self._template
+
+    @template.setter
+    def template(self: Template, value: str) -> None:
+        """Set underlying raw string value."""
+        if isinstance(value, str):
+            self._template = value
+        else:
+            raise AttributeError(f'Expected type \'str\' for member `template`')
+
+    class Error(Exception):
+        """Base exception type for Template exceptions."""
+
+    class UnmatchedPattern(Error):
+        """Template pattern does not match any implemented expansion."""
+
+    class FailedExpansion(Error):
+        """Failure to successfully expand a pattern given input arguments."""
+
+    def expand(self: Template, args: str) -> str:
+        """Expand template against input `args`."""
+        index = 0
+        expansion = ''
+        if not PATTERN.search(self.template):
+            return self.template
+        for match in PATTERN.finditer(self.template):
+            (key, ), start, end = match.groups(), match.start(), match.end()
+            expansion += self.template[index:start] + self._expand(args, key, start)
+            index = end
+        else:
+            return expansion + self.template[index:]
+
+    def _expand(self: Template, args: str, key: str, start: int) -> str:
+        """Determine simple vs complex pattern expansion."""
+        key = key.strip()  # allow whitespace (likely in shell and lambda patterns)
+        if key in self.simple_patterns:
+            return self.simple_patterns[key](args)
+        else:
+            return self._expand_complex(args, key, start)
+
+    def _expand_complex(self: Template, args: str, key: str, start: int) -> str:
+        """Expand complex (nested) patterns in template against `args`."""
+        key_ = '{' + key + '}'
+        for pattern, routine in self.complex_patterns.items():
+            if inner_match := re.match(pattern, key):
+                try:
+                    inner_key, = inner_match.groups()
+                    return routine(args, inner_key)
+                except Exception as error:
+                    raise self.FailedExpansion(f'Could not expand \'{key_}\' for args ({args}): {error}')
+        else:
+            raise self.UnmatchedPattern(f'\'{key_}\' in template (at position {start})')
+
+    @functools.cached_property
+    def simple_patterns(self: Template) -> Dict[str, Callable[[str], str]]:
+        """Map of pattern literals to their expansion routines."""
+        return {
+            '': self.expand_null,
+            '.': self.expand_first_dirname,
+            '..': self.expand_second_dirname,
+            '/': self.expand_basename,
+            '/-': self.expand_basename_without_ext,
+            '-': self.expand_fullpath_without_ext,
+            '+': self.expand_file_extension,
+            '++': self.expand_file_extension_without_dot,
+        }
+
+    @functools.cached_property
+    def complex_patterns(self: Template) -> Dict[str, Callable[[str, str], str]]:
+        """Map of complex patterns to their expansion routines."""
+        return {
+            r'\[(.*?)]': self.expand_slice,
+            '=(.*?)=': self.expand_lambda,
+            '%(.*?)%': self.expand_shell,
+        }
+
+    @staticmethod
+    def expand_null(args: str) -> str:
+        """Return `args` without change."""
+        return args
+
+    @staticmethod
+    def expand_first_dirname(args: str) -> str:
+        """Return parent directory of `args` assuming a valid path."""
+        return os.path.dirname(args)
+
+    @staticmethod
+    def expand_second_dirname(args: str) -> str:
+        """Return second parent directory of `args` assuming a valid path."""
+        return os.path.dirname(os.path.dirname(args))
+
+    @staticmethod
+    def expand_basename(args: str) -> str:
+        """Expand to basename of `args` assuming a valid path."""
+        return os.path.basename(args)
+
+    @staticmethod
+    def expand_basename_without_ext(args: str) -> str:
+        """Expand to basename of `args` without the file extension assuming a valid path."""
+        return os.path.splitext(os.path.basename(args))[0]
+
+    @staticmethod
+    def expand_fullpath_without_ext(args: str) -> str:
+        """Drop file extension from `args` assuming a valid path."""
+        return os.path.splitext(args)[0]
+
+    @staticmethod
+    def expand_file_extension(args: str) -> str:
+        """Return file extension of `args` assuming a valid path."""
+        return os.path.splitext(args)[1]
+
+    @staticmethod
+    def expand_file_extension_without_dot(args: str) -> str:
+        """Return file extension of `args` without the leading dot assuming a valid path."""
+        return os.path.splitext(args)[1].strip('.')
+
+    def expand_slice(self: Template, args: str, key: str) -> str:
+        """Expand slice `key` ([start][:stop][:step]) against args (on white space)."""
+        if re.match(r'(\d+)?:?(\d+)?:?(\d+)?$', key):
+            result = eval(f'chunks[{key}]', {'chunks': args.split()})
+            return ' '.join(result if isinstance(result, list) else [result, ])
+        else:
+            raise self.FailedExpansion(f'Invalid slice expression \'{key}\'')
+
+    @staticmethod
+    def expand_shell(args: str, key: str) -> str:
+        """Expand `key` as a shell command with @ replaced with `args`."""
+        return subprocess.check_output(key.replace('@', args), shell=True).decode().strip()
+
+    def expand_lambda(self: Template, args: str, key: str) -> str:
+        """Expand `key` as a lambda expression in `x` and evaluate against `args`."""
+        return str(self.build_lambda(key)(smart_coerce(args)))
+
+    @staticmethod
+    @functools.lru_cache(maxsize=None)
+    def build_lambda(expression: str) -> Callable[[str], str]:
+        """Construct lambda `expression` with single argument 'x'."""
+        return eval(f'lambda x: {expression}', EXPOSED_MODULES)
+
+    def __repr__(self: Template) -> str:
+        """Interactive representation."""
+        return f'Template(\'{self.template}\')'
+
+    def __str__(self: Template) -> str:
+        """String representation."""
+        return self.template

hypershell/core/thread.py

@@ -0,0 +1,56 @@
+# SPDX-FileCopyrightText: 2025 Geoffrey Lentner
+# SPDX-License-Identifier: Apache-2.0
+
+"""Thread base class implementation."""
+
+
+# type annotations
+from __future__ import annotations
+from typing import Optional, Type
+
+# standard libs
+import threading
+from abc import ABC, abstractmethod
+
+# public interface
+__all__ = ['Thread', ]
+
+
+class Thread(threading.Thread, ABC):
+    """Extends threading.Thread to provide exception handling."""
+
+    __exception: Exception = None
+    __should_halt: bool = False
+
+    def __init__(self: Thread, name: str) -> None:
+        super().__init__(name=name, daemon=True)
+
+    @abstractmethod
+    def run_with_exceptions(self: Thread) -> None:
+        """Implement `run` which may raise exceptions."""
+
+    def run(self: Thread) -> None:
+        """Call `run_with_exceptions` within a try/except block."""
+        try:
+            self.run_with_exceptions()
+        except Exception as exc:
+            self.__exception = exc
+
+    @classmethod
+    def new(cls: Type[Thread], *args, **kwargs) -> Thread:
+        """Initialize and start the thread."""
+        thread = cls(*args, **kwargs)
+        thread.start()
+        return thread
+
+    def stop(self: Thread, wait: bool = False, timeout: int = None) -> None:
+        """Signal to terminate."""
+        self.__should_halt = True
+        if wait:
+            self.join(timeout=timeout)
+
+    def join(self: Thread, timeout: Optional[float] = None) -> None:
+        """Calls Thread.join but re-raises exceptions."""
+        super().join(timeout=timeout)
+        if self.__exception:
+            raise self.__exception

hypershell/core/types.py

@@ -0,0 +1,32 @@
+# SPDX-FileCopyrightText: 2025 Geoffrey Lentner
+# SPDX-License-Identifier: Apache-2.0
+
+"""Automatic type coercion of input data."""
+
+
+# type annotations
+from typing import TypeVar
+
+# public interface
+__all__ = ['smart_coerce', 'JSONValue']
+
+
+# Each possible input type
+JSONValue = TypeVar('JSONValue', bool, int, float, str, type(None))
+
+
+def smart_coerce(value: str) -> JSONValue:
+    """Automatically coerce string to typed value."""
+    cmp_val = value.lower()
+    if cmp_val in ('null', 'none'):
+        return None
+    if cmp_val in ('true', 'false'):
+        return cmp_val == 'true'
+    try:
+        return int(value)
+    except ValueError:
+        pass
+    try:
+        return float(value)
+    except ValueError:
+        return value

hypershell/data/__init__.py

@@ -0,0 +1,137 @@
+# SPDX-FileCopyrightText: 2025 Geoffrey Lentner
+# SPDX-License-Identifier: Apache-2.0
+
+"""Database interface, models, and methods."""
+
+
+# type annotations
+from __future__ import annotations
+from typing import Final
+
+# standard libs
+import sys
+import functools
+
+# external libs
+from cmdkit.app import Application, exit_status
+from cmdkit.cli import Interface
+from cmdkit.config import ConfigurationError
+from sqlalchemy import inspect
+from sqlalchemy.orm import close_all_sessions
+from sqlalchemy.exc import OperationalError
+
+# internal libs
+from hypershell.core.logging import Logger
+from hypershell.core.config import config
+from hypershell.core.exceptions import handle_exception, DatabaseUninitialized, get_shared_exception_mapping
+from hypershell.data.core import engine, in_memory, schema
+from hypershell.data.model import Entity, Task
+
+# public interface
+__all__ = ['InitDBApp', 'initdb', 'truncatedb', 'checkdb', 'ensuredb', 'DATABASE_ENABLED', ]
+
+# initialize logger
+log = Logger.with_name(__name__)
+
+
+DATABASE_ENABLED: Final[bool] = not in_memory
+"""Set if database has been configured."""
+
+
+def initdb() -> None:
+    """Initialize database tables."""
+    Entity.metadata.create_all(engine)
+
+
+def truncatedb() -> None:
+    """Truncate database tables."""
+    # NOTE: We still might hang here if other sessions exist outside this app instance
+    close_all_sessions()
+    log.trace('Dropping all tables')
+    Entity.metadata.drop_all(engine)
+    log.trace('Creating all tables')
+    Entity.metadata.create_all(engine)
+    log.warning(f'Truncated database')
+
+
+def checkdb() -> None:
+    """Ensure database connection and tables exist."""
+    if not inspect(engine).has_table('task', schema=schema):
+        raise DatabaseUninitialized('Use \'initdb\' to initialize the database')
+
+
+def ensuredb(auto_init: bool = False) -> None:
+    """
+    Ensure database configuration before applying any operations.
+
+    If SQLite and `auto_init` we run :meth:`initdb`, else :meth:`checkdb`.
+    """
+    db = config.database.get('file', None) or config.database.get('database', None)
+    if config.database.provider == 'sqlite' and db in ('', ':memory:', None):
+        raise ConfigurationError('Missing database configuration')
+    if config.database.provider == 'sqlite' or auto_init is True:
+        initdb()
+    else:
+        checkdb()
+
+
+INITDB_PROGRAM = 'hs initdb'
+INITDB_USAGE = f"""\
+Usage:
+  {INITDB_PROGRAM} [-h] [--truncate [--yes]]
+
+  Initialize database (not needed for SQLite).
+  Use --truncate to zero out the task metadata.\
+"""
+
+INITDB_HELP = f"""\
+{INITDB_USAGE}
+
+Options:
+  -t, --truncate       Truncate database (task metadata will be lost).
+  -y, --yes            Auto-confirm truncation (default will prompt).
+  -h, --help           Show this message and exit.\
+"""
+
+
+class InitDBApp(Application):
+    """Initialize database (not needed for SQLite)."""
+
+    interface = Interface(INITDB_PROGRAM, INITDB_USAGE, INITDB_HELP)
+
+    ALLOW_NOARGS = True
+
+    truncate: bool = False
+    interface.add_argument('-t', '--truncate', action='store_true')
+
+    auto_confirm: bool = False
+    interface.add_argument('-y', '--yes', action='store_true', dest='auto_confirm')
+
+    exceptions = {
+        OperationalError: functools.partial(handle_exception, logger=log, status=exit_status.runtime_error),
+        **get_shared_exception_mapping(__name__),
+    }
+
+    def run(self: InitDBApp) -> None:
+        """Business logic for `initdb`."""
+        if not DATABASE_ENABLED:
+            raise ConfigurationError('No database configured')
+        elif not self.truncate:
+            initdb()
+        elif self.auto_confirm:
+            truncatedb()
+        elif not sys.stdout.isatty():
+            raise RuntimeError('Non-interactive prompt cannot confirm --truncate (see --yes).')
+        else:
+            if config.database.provider == 'sqlite':
+                site = config.database.file
+            else:
+                site = config.database.get('host', 'localhost')
+            print(f'Connected to: {config.database.provider} ({site})')
+            response = input(f'Truncate database ({Task.count()} tasks)? [Y]es/no: ').strip()
+            if response.lower() in ['', 'y', 'yes']:
+                truncatedb()
+            elif response.lower() in ['n', 'no']:
+                print('Stopping')
+            else:
+                raise RuntimeError(f'Stopping (invalid response: "{response}")')