meerschaum 2.2.6__py3-none-any.whl → 2.3.0__py3-none-any.whl

meerschaum/_internal/shell/updates.py

@@ -0,0 +1,175 @@
+#! /usr/bin/env python3
+# -*- coding: utf-8 -*-
+# vim:fenc=utf-8
+
+"""
+If configured, check `api:mrsm` for announcement messages.
+"""
+
+import json
+from datetime import datetime, timezone, timedelta
+
+import meerschaum as mrsm
+from meerschaum.utils.typing import Union, SuccessTuple, Optional
+from meerschaum.config import get_config
+from meerschaum.utils.formatting import CHARSET, ANSI, colored
+from meerschaum.utils.misc import string_width, remove_ansi
+from meerschaum.config.paths import (
+    UPDATES_LOCK_PATH,
+    UPDATES_CACHE_PATH,
+)
+from meerschaum.utils.threading import Thread
+
+
+def cache_remote_version(debug: bool = False) -> SuccessTuple:
+    """
+    Fetch and cache the latest version if available.
+    """
+    allow_update_check = get_config('shell', 'updates', 'check_remote')
+    if not allow_update_check:
+        return True, "Update checks are disabled."
+
+    refresh_minutes = get_config('shell', 'updates', 'refresh_minutes')
+    update_delta = timedelta(minutes=refresh_minutes)
+
+    if UPDATES_CACHE_PATH.exists():
+        try:
+            with open(UPDATES_CACHE_PATH, 'r', encoding='utf8') as f:
+                cache_dict = json.load(f)
+        except Exception:
+            cache_dict = {}
+    else:
+        cache_dict = {}
+
+    now = datetime.now(timezone.utc)
+    last_check_ts_str = cache_dict.get('last_check_ts')
+    last_check_ts = datetime.fromisoformat(last_check_ts_str) if last_check_ts_str else None
+
+    need_update = (
+        last_check_ts_str is None
+        or ((now - last_check_ts) >= update_delta)
+    )
+
+    if not need_update:
+        return True, "No updates are needed."
+
+    try:
+        conn = mrsm.get_connector('api:mrsm')
+        remote_version = conn.get_mrsm_version(debug=debug, timeout=3)
+    except Exception:
+        remote_version = None
+
+    if remote_version is None:
+        return False, "Could not determine remote version."
+
+    with open(UPDATES_CACHE_PATH, 'w+', encoding='utf-8') as f:
+        json.dump(
+            {
+                'last_check_ts': now.isoformat(),
+                'remote_version': remote_version,
+            },
+            f,
+        )
+
+    return True, "Updated remote version cache."
+
+
+def run_version_check_thread(debug: bool = False) -> Union[Thread, None]:
+    """
+    Run the version update check in a separate thread.
+    """
+    allow_update_check = get_config('shell', 'updates', 'check_remote')
+    if not allow_update_check:
+        return None
+
+    thread = Thread(
+        target=cache_remote_version,
+        daemon=True,
+        kwargs={'debug': debug},
+    )
+    thread.start()
+    return thread
+
+
+_remote_version: Optional[str] = None
+def get_remote_version_from_cache() -> Optional[str]:
+    """
+    Return the version string from the local cache file.
+    """
+    global _remote_version
+    try:
+        with open(UPDATES_CACHE_PATH, 'r', encoding='utf-8') as f:
+            cache_dict = json.load(f)
+    except Exception:
+        return None
+
+    _remote_version = cache_dict.get('remote_version')
+    return _remote_version
+
+
+_out_of_date: Optional[bool] = None
+def mrsm_out_of_date() -> bool:
+    """
+    Determine whether to print the upgrade message.
+    """
+    global _out_of_date
+    if _out_of_date is not None:
+        return _out_of_date
+
+    ### NOTE: Remote version is cached asynchronously.
+    if not UPDATES_CACHE_PATH.exists():
+        return False
+
+    remote_version_str = get_remote_version_from_cache()
+
+    packaging_version = mrsm.attempt_import('packaging.version')
+    current_version = packaging_version.parse(mrsm.__version__)
+    remote_version = packaging_version.parse(remote_version_str)
+
+    _out_of_date = remote_version > current_version
+    return _out_of_date
+
+
+def get_update_message() -> str:
+    """
+    Return the formatted message for when the current version is behind the latest release.
+    """
+    if not mrsm_out_of_date():
+        return ''
+
+    intro = get_config('shell', CHARSET, 'intro')
+    update_message = get_config('shell', CHARSET, 'update_message')
+    remote_version = get_remote_version_from_cache()
+    if not remote_version:
+        return ''
+
+    intro_width = string_width(intro)
+    msg_width = string_width(update_message)
+    update_left_padding = ' ' * ((intro_width - msg_width) // 2)
+
+    update_line = (
+        colored(
+            update_message,
+            *get_config('shell', 'ansi', 'update_message', 'color')
+        ) if ANSI
+        else update_message
+    )
+    update_instruction = (
+        colored("Run ", 'white')
+        + colored("upgrade mrsm", 'green')
+        + colored(" to install ", 'white')
+        + colored(f'v{remote_version}', 'yellow')
+        + '.'
+    )
+    update_instruction_clean = remove_ansi(update_instruction)
+    instruction_width = string_width(update_instruction_clean)
+    instruction_left_padding = ' ' * ((intro_width - instruction_width) // 2)
+
+    return (
+        '\n\n'
+        + update_left_padding
+        + update_line
+        + '\n'
+        + instruction_left_padding
+        + update_instruction
+    )

meerschaum/actions/__init__.py

@@ -11,10 +11,20 @@ from meerschaum.utils.typing import Callable, Any, Optional, Union, List, Dict,
 from meerschaum.utils.packages import get_modules_from_package
 _custom_actions = []
 
+__all__ = (
+    'get_action',
+    'get_subactions',
+    'make_action',
+    'pre_sync_hook',
+    'post_sync_hook',
+    'get_main_action_name',
+    'get_completer',
+)
+
 def get_subactions(
-        action: Union[str, List[str]],
-        _actions: Optional[Dict[str, Callable[[Any], Any]]] = None,
-    ) -> Dict[str, Callable[[Any], Any]]:
+    action: Union[str, List[str]],
+    _actions: Optional[Dict[str, Callable[[Any], Any]]] = None,
+) -> Dict[str, Callable[[Any], Any]]:
     """
     Return a dictionary of an action's sub-action functions.
 
@@ -52,9 +62,9 @@ def get_subactions(
 
 
 def get_action(
-        action: Union[str, List[str]],
-        _actions: Optional[Dict[str, Callable[[Any], Any]]] = None,
-    ) -> Union[Callable[[Any], Any], None]:
+    action: Union[str, List[str]],
+    _actions: Optional[Dict[str, Callable[[Any], Any]]] = None,
+) -> Union[Callable[[Any], Any], None]:
     """
     Return a function corresponding to the given action list.
     This may be a custom action with an underscore, in which case, allow for underscores.
@@ -92,6 +102,8 @@ def get_action(
     if action[0] in _actions:
         subactions = get_subactions([action[0]], _actions=_actions)
         if action[1] not in subactions:
+            if (action[1] + 's') in subactions:
+                return subactions[action[1] + 's']
             return _actions[action[0]]
         return subactions[action[1]]
 
@@ -99,9 +111,9 @@ def get_action(
 
 
 def get_main_action_name(
-        action: Union[List[str], str],
-        _actions: Optional[Dict[str, Callable[[Any], SuccessTuple]]] = None,
-    ) -> Union[str, None]:
+    action: Union[List[str], str],
+    _actions: Optional[Dict[str, Callable[[Any], SuccessTuple]]] = None,
+) -> Union[str, None]:
     """
     Given an action list, return the name of the main function.
     For subactions, this will return the root function.
@@ -138,9 +150,9 @@ def get_main_action_name(
 
 
 def get_completer(
-        action: Union[List[str], str],
-        _actions: Optional[Dict[str, Callable[[Any], SuccessTuple]]] = None,
-    ) -> Union[
+    action: Union[List[str], str],
+    _actions: Optional[Dict[str, Callable[[Any], SuccessTuple]]] = None,
+) -> Union[
         Callable[['meerschaum._internal.shell.Shell', str, str, int, int], List[str]], None
     ]:
     """Search for a custom completer function for an action."""
@@ -177,10 +189,10 @@ def get_completer(
 
 
 def choose_subaction(
-        action: Optional[List[str]] = None,
-        options: Optional[Dict[str, Any]] = None,
-        **kw
-    ) -> SuccessTuple:
+    action: Optional[List[str]] = None,
+    options: Optional[Dict[str, Any]] = None,
+    **kw
+) -> SuccessTuple:
     """
     Given a dictionary of options and the standard Meerschaum actions list,
     check if choice is valid and execute chosen function, else show available
@@ -245,7 +257,7 @@ def _get_subaction_names(action: str, globs: dict = None) -> List[str]:
     return subactions
 
 
-def choices_docstring(action: str, globs : Optional[Dict[str, Any]] = None) -> str:
+def choices_docstring(action: str, globs: Optional[Dict[str, Any]] = None) -> str:
     """
     Append the an action's available options to the module docstring.
     This function is to be placed at the bottom of each action module.

meerschaum/actions/api.py

@@ -10,12 +10,12 @@ import os
 from meerschaum.utils.typing import SuccessTuple, Optional, List, Any
 
 def api(
-        action: Optional[List[str]] = None,
-        sysargs: Optional[List[str]] = None,
-        debug: bool = False,
-        mrsm_instance: Optional[str] = None,
-        **kw: Any
-    ) -> SuccessTuple:
+    action: Optional[List[str]] = None,
+    sysargs: Optional[List[str]] = None,
+    debug: bool = False,
+    mrsm_instance: Optional[str] = None,
+    **kw: Any
+) -> SuccessTuple:
     """
     Send commands to a Meerschaum WebAPI instance.
     
@@ -37,7 +37,8 @@ def api(
     """
     from meerschaum.utils.warnings import warn, info
     from meerschaum.utils.formatting import print_tuple
-    from meerschaum.utils.packages import attempt_import
+    from meerschaum._internal.arguments._parse_arguments import parse_dict_to_sysargs
+
     if action is None:
         action = []
     if sysargs is None:
@@ -52,7 +53,6 @@ def api(
 
     from meerschaum.config import get_config
     from meerschaum.connectors import get_connector
-    requests = attempt_import('requests')
     if debug:
         from meerschaum.utils.formatting import pprint
     api_configs = get_config('meerschaum', 'connectors', 'api', patch=True)
@@ -68,12 +68,13 @@ def api(
         del action[0]
         if len(args_to_send) > 1:
             del args_to_send[0]
+
     kw['action'] = action
     kw['debug'] = debug
     kw['sysargs'] = args_to_send
     kw['yes'] = True
  
-    api_conn = get_connector(type='api', label=api_label)
+    api_conn = get_connector(f'api:{api_label}')
     
     if mrsm_instance is not None and str(mrsm_instance) == str(api_conn):
         warn(
@@ -83,9 +84,8 @@ def api(
     elif mrsm_instance is not None:
         kw['mrsm_instance'] = str(mrsm_instance)
 
-    success, message = api_conn.do_action(**kw)
-    print_tuple((success, message), common_only=True)
-    msg = f"Action " + ('succeeded' if success else 'failed') + " with message:\n" + str(message)
+    sysargs = parse_dict_to_sysargs(kw)
+    success, message = api_conn.do_action(sysargs)
     return success, message
 
 def _api_start(

meerschaum/actions/attach.py

@@ -0,0 +1,113 @@
+#! /usr/bin/env python3
+# -*- coding: utf-8 -*-
+# vim:fenc=utf-8
+
+"""
+Attach to running jobs.
+"""
+
+import meerschaum as mrsm
+from meerschaum.utils.typing import Optional, List, Any, SuccessTuple
+
+def attach(
+    action: Optional[List[str]] = None,
+    executor_keys: Optional[str] = None,
+    **kwargs: Any
+) -> SuccessTuple:
+    """
+    Attach to a job, and prompt the user when blocking on input.
+    """
+    from meerschaum.actions import choose_subaction
+    attach_options = {
+        'jobs': _attach_jobs,
+        'logs': _attach_logs,
+    }
+    return choose_subaction(action, attach_options, executor_keys=executor_keys, **kwargs)
+
+
+def _complete_attach(
+    action: Optional[List[str]] = None,
+    **kw: Any
+) -> List[str]:
+    """
+    Override the default Meerschaum `complete_` function.
+    """
+    from meerschaum.actions.delete import _complete_delete_jobs
+
+    if action is None:
+        action = []
+
+    options = {
+        'job': _complete_delete_jobs,
+        'jobs': _complete_delete_jobs,
+        'log': _complete_delete_jobs,
+        'logs': _complete_delete_jobs,
+    }
+
+    if (
+        len(action) > 0 and action[0] in options
+            and kw.get('line', '').split(' ')[-1] != action[0]
+    ):
+        sub = action[0]
+        del action[0]
+        return options[sub](action=action, **kw)
+
+    from meerschaum._internal.shell import default_action_completer
+    return default_action_completer(action=(['attach'] + action), **kw)
+
+
+def _attach_jobs(
+    action: Optional[List[str]] = None,
+    name: Optional[str] = None,
+    executor_keys: Optional[str] = None,
+    **kwargs: Any
+) -> SuccessTuple:
+    """
+    Attach to a job, and prompt the user when blocking on input.
+    """
+    action = action or []
+    if not action and not name:
+        return False, "Provide the name of the job to attach to."
+
+    name = name or action[0]
+    job = mrsm.Job(name, executor_keys=executor_keys)
+    other_executor_keys = 'systemd' if executor_keys in (None, 'local') else 'local'
+    if not job.exists():
+        other_job = mrsm.Job(name, executor_keys=other_executor_keys)
+        if not other_job.exists():
+            return False, f"Job '{job.name}' does not exist."
+
+        job = other_job
+
+    success, message = True, "Success"
+
+    def _capture_result(result: SuccessTuple):
+        nonlocal success, message
+        success, message = result
+
+    try:
+        job.monitor_logs(
+            stop_callback_function=_capture_result,
+            accept_input=True,
+            stop_on_exit=True,
+            strip_timestamps=True,
+        )
+    except KeyboardInterrupt:
+        pass
+
+    return success, message
+
+
+def _attach_logs(*args, **kwargs) -> SuccessTuple:
+    """
+    Attach to jobs' logs.
+    """
+    from meerschaum.actions.show import _show_logs
+    return _show_logs(*args, **kwargs)
+
+
+### NOTE: This must be the final statement of the module.
+###       Any subactions added below these lines will not
+###       be added to the `help` docstring.
+from meerschaum.actions import choices_docstring as _choices_docstring
+attach.__doc__ += _choices_docstring('attach')

meerschaum/actions/copy.py

@@ -10,9 +10,9 @@ from __future__ import annotations
 from meerschaum.utils.typing import Union, Any, Sequence, SuccessTuple, Optional, Tuple, List
 
 def copy(
-        action: Optional[List[str]] = None,
-        **kw : Any
-    ) -> SuccessTuple:
+    action: Optional[List[str]] = None,
+    **kw : Any
+) -> SuccessTuple:
     """
     Duplicate connectors or pipes.
     
@@ -32,17 +32,16 @@ def copy(
 
 
 def _complete_copy(
-        action : Optional[List[str]] = None,
-        **kw : Any
-    ) -> List[str]:
+    action: Optional[List[str]] = None,
+    **kw: Any
+) -> List[str]:
     """
     Override the default Meerschaum `complete_` function.
-
     """
-    from meerschaum.actions.start import _complete_start_jobs
     from meerschaum.actions.edit import _complete_edit_config
     if action is None:
         action = []
+
     options = {
         'connector': _complete_copy_connectors,
         'connectors': _complete_copy_connectors,
@@ -61,15 +60,14 @@ def _complete_copy(
 
 
 def _copy_pipes(
-        yes: bool = False,
-        noask: bool = False,
-        force: bool = False,
-        debug: bool = False,
-        **kw
-    ) -> SuccessTuple:
+    yes: bool = False,
+    noask: bool = False,
+    force: bool = False,
+    debug: bool = False,
+    **kw
+) -> SuccessTuple:
     """
     Copy pipes' attributes and make new pipes.
-
     """
     from meerschaum import get_pipes, Pipe
     from meerschaum.utils.prompt import prompt, yes_no
@@ -132,16 +130,15 @@ def _copy_pipes(
 
     return successes > 0, msg
 
+
 def _copy_connectors(
-        action: Optional[List[str]] = None,
-        connector_keys: Optional[List[str]] = None,
-        nopretty: bool = False,
-        yes: bool = False,
-        force: bool = False,
-        noask: bool = False,
-        debug: bool = False,
-        **kw
-    ) -> SuccessTuple:
+    action: Optional[List[str]] = None,
+    connector_keys: Optional[List[str]] = None,
+    nopretty: bool = False,
+    force: bool = False,
+    debug: bool = False,
+    **kwargs: Any
+) -> SuccessTuple:
     """
     Create a new connector from an existing one.
 
@@ -153,39 +150,69 @@ def _copy_connectors(
     from meerschaum.config._edit import write_config
     from meerschaum.utils.warnings import info, warn
     from meerschaum.utils.formatting import pprint
+    from meerschaum.actions import get_action
     cf = _config()
     if action is None:
         action = []
     if connector_keys is None:
         connector_keys = []
 
-    _keys = list(set(action + connector_keys))
+    _keys = (action or []) + connector_keys
 
     if not _keys:
         return False, "No connectors to copy."
 
-    for ck in _keys:
-        try:
-            conn = parse_connector_keys(ck)
-        except Exception as e:
-            warn(f"Unable to parse connector '{ck}'. Skipping...", stack=False)
-            continue
+    if len(_keys) < 1 or len(_keys) > 2:
+        return False, "Provide one set of connector keys."
 
-        attrs = get_config('meerschaum', 'connectors', conn.type, conn.label)
-        pprint(attrs, nopretty=nopretty)
+    ck = _keys[0]
 
-        asking = True
-        #  while asking:
-            #  new_ck = prompt("Please enter a new label for the new connector ():")
+    try:
+        conn = parse_connector_keys(ck)
+    except Exception as e:
+        return False, f"Unable to parse connector '{ck}'."
 
+    if len(_keys) == 2:
+        new_ck = _keys[1] if ':' in _keys[1] else None
+        new_label = _keys[1].split(':')[-1]
+    else:
+        new_ck = None
+        new_label = None
+
+    try:
+        if new_label is None:
+            new_label = prompt(f"Enter a label for the new '{conn.type}' connector:")
+    except KeyboardInterrupt:
+        return False, "Nothing was copied."
+
+    if new_ck is None:
+        new_ck = f"{conn.type}:{new_label}"
+
+    info(f"Registering connector '{new_ck}' from '{ck}'...")
+
+    attrs = get_config('meerschaum', 'connectors', conn.type, conn.label)
+    pprint(attrs, nopretty=nopretty)
+    if not force and not yes_no(
+        f"Register connector '{new_ck}' with the above attributes?",
+        default='n',
+        **kwargs
+    ):
+        return False, "Nothing was copied."
+
+    register_connector = get_action(['register', 'connector'])
+    register_success, register_msg = register_connector(
+        [new_ck],
+        params=attrs,
+        **kwargs
+    )
+    return register_success, register_msg
 
-    return False, "Not implemented."
 
 def _complete_copy_connectors(
-        action : Optional[List[str]] = None,
-        line : str = '',
-        **kw : Any
-    ) -> List[str]:
+    action: Optional[List[str]] = None,
+    line: str = '',
+    **kw: Any
+) -> List[str]:
     from meerschaum.config import get_config
     from meerschaum.utils.misc import get_connector_labels
     types = list(get_config('meerschaum', 'connectors').keys())