meerschaum 2.2.5.dev3__py3-none-any.whl → 2.2.7__py3-none-any.whl

meerschaum/_internal/entry.py

@@ -8,20 +8,15 @@ The entry point for launching Meerschaum actions.
 """
 
 from __future__ import annotations
-from meerschaum.utils.typing import SuccessTuple, List, Optional, Dict
+from meerschaum.utils.typing import SuccessTuple, List, Optional, Dict, Callable, Any
 
 def entry(sysargs: Optional[List[str]] = None) -> SuccessTuple:
-    """Parse arguments and launch a Meerschaum action.
-    The `action` list removes the first element.
-    
-    Examples of action:
-        'show actions' -> ['actions']
-        'show' -> []
+    """
+    Parse arguments and launch a Meerschaum action.
 
     Returns
     -------
-    A `SuccessTuple` indicating success. If `schedule` is provided, this will never return.
-
+    A `SuccessTuple` indicating success.
     """
     from meerschaum._internal.arguments import parse_arguments
     from meerschaum.config.static import STATIC_CONFIG
@@ -51,9 +46,9 @@ def entry(sysargs: Optional[List[str]] = None) -> SuccessTuple:
 
 
 def entry_with_args(
-        _actions: Optional[Dict[str, Callable[[Any], SuccessTuple]]] = None,
-        **kw
-    ) -> SuccessTuple:
+    _actions: Optional[Dict[str, Callable[[Any], SuccessTuple]]] = None,
+    **kw
+) -> SuccessTuple:
     """Execute a Meerschaum action with keyword arguments.
     Use `_entry()` for parsing sysargs before executing.
     """
@@ -96,7 +91,12 @@ def entry_with_args(
 
     kw['action'] = remove_leading_action(kw['action'], _actions=_actions)
 
-    do_action = functools.partial(_do_action_wrapper, action_function, plugin_name, **kw)
+    do_action = functools.partial(
+        _do_action_wrapper,
+        action_function,
+        plugin_name,
+        **kw
+    )
     if kw.get('schedule', None) and not skip_schedule:
         from meerschaum.utils.schedule import schedule_function
         from meerschaum.utils.misc import interval_str

meerschaum/_internal/shell/Shell.py

@@ -95,8 +95,8 @@ def _insert_shell_actions(
         setattr(_shell_class, 'complete_' + a, completer)
 
 def _completer_wrapper(
-        target: Callable[[Any], List[str]]
-    ) -> Callable[['meerschaum._internal.shell.Shell', str, str, int, int], Any]:
+    target: Callable[[Any], List[str]]
+) -> Callable[['meerschaum._internal.shell.Shell', str, str, int, int], Any]:
     """
     Wrapper for `complete_` functions so they can instead use Meerschaum arguments.
     """
@@ -125,13 +125,13 @@ def _completer_wrapper(
 
 
 def default_action_completer(
-        text: Optional[str] = None,
-        line: Optional[str] = None,
-        begin_index: Optional[int] = None,
-        end_index: Optional[int] = None,
-        action: Optional[List[str]] = None,
-        **kw: Any
-    ) -> List[str]:
+    text: Optional[str] = None,
+    line: Optional[str] = None,
+    begin_index: Optional[int] = None,
+    end_index: Optional[int] = None,
+    action: Optional[List[str]] = None,
+    **kw: Any
+) -> List[str]:
     """
     Search for subactions by default. This may be overridden by each action.
     """
@@ -206,13 +206,11 @@ def get_shell_intro(with_color: bool = True) -> str:
     """
     from meerschaum.utils.formatting import CHARSET, ANSI, colored
     intro = get_config('shell', CHARSET, 'intro', patch=patch)
-    intro += '\n' + ''.join(
-        [' '
-            for i in range(
-                string_width(intro) - len('v' + version)
-            )
-        ]
-    ) + 'v' + version
+    intro += (
+        '\n'
+        + (' ' * (string_width(intro) - len('v' + version)))
+        + f'v{version}'
+    )
 
     if not with_color or not ANSI:
         return intro
@@ -225,10 +223,10 @@ def get_shell_intro(with_color: bool = True) -> str:
 
 class Shell(cmd.Cmd):
     def __init__(
-            self,
-            actions: Optional[Dict[str, Any]] = None,
-            sysargs: Optional[List[str]] = None
-        ):
+        self,
+        actions: Optional[Dict[str, Any]] = None,
+        sysargs: Optional[List[str]] = None
+    ):
         """
         Customize the CLI from configuration
         """
@@ -297,19 +295,25 @@ class Shell(cmd.Cmd):
         except Exception as e:
             pass
 
+        ### Finally, spawn the version update thread.
+        from meerschaum._internal.shell.updates import run_version_check_thread
+        self._update_thread = run_version_check_thread(debug=shell_attrs.get('debug', False))
+
+
     def load_config(self, instance: Optional[str] = None):
         """
         Set attributes from the shell configuration.
         """
         from meerschaum.utils.misc import remove_ansi
         from meerschaum.utils.formatting import CHARSET, ANSI, colored
-        
+        from meerschaum._internal.shell.updates import get_update_message
+
         if shell_attrs.get('intro', None) != '':
             self.intro = (
                 get_shell_intro(with_color=False)
                 if shell_attrs.get('intro', None) != ''
                 else ""
-            )
+            ) + get_update_message()
 
         shell_attrs['intro'] = self.intro
         shell_attrs['_prompt'] = get_config('shell', CHARSET, 'prompt', patch=patch)

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/_internal/term/__init__.py

@@ -22,7 +22,7 @@ tornado, tornado_ioloop, terminado = attempt_import(
 
 def get_webterm_app_and_manager() -> Tuple[
         tornado.web.Application,
-        terminado.UniqueTermManager, 
+        terminado.UniqueTermManager,
     ]:
     """
     Construct the Tornado web app and term manager from the provided sysargs.
@@ -47,7 +47,7 @@ def get_webterm_app_and_manager() -> Tuple[
             {'term_manager': term_manager}
         ),
         (
-            r"/", 
+            r"/",
             TermPageHandler
         ),
     ]

meerschaum/actions/bootstrap.py

@@ -221,18 +221,17 @@ def _bootstrap_pipes(
     return (successes > 0), msg
 
 def _bootstrap_connectors(
-        action : Optional[List[str]] = None,
-        connector_keys : Optional[List[str]] = None,
-        yes : bool = False,
-        force : bool = False,
-        noask : bool = False,
-        debug : bool = False,
-        return_keys : bool = False,
-        **kw : Any
-    ) -> Union[SuccessTuple, Tuple[str, str]]:
+    action: Optional[List[str]] = None,
+    connector_keys: Optional[List[str]] = None,
+    yes: bool = False,
+    force: bool = False,
+    noask: bool = False,
+    debug: bool = False,
+    return_keys: bool = False,
+    **kw: Any
+) -> Union[SuccessTuple, Tuple[str, str]]:
     """
     Prompt the user for the details necessary to create a Connector.
-
     """
     from meerschaum.connectors.parse import is_valid_connector_keys
     from meerschaum.connectors import connectors, get_connector, types, custom_types
@@ -386,10 +385,10 @@ def _bootstrap_connectors(
 
 
 def _bootstrap_plugins(
-        action: Optional[List[str]] = None,
-        debug: bool = False,
-        **kwargs: Any
-    ) -> SuccessTuple:
+    action: Optional[List[str]] = None,
+    debug: bool = False,
+    **kwargs: Any
+) -> SuccessTuple:
     """
     Launch an interactive wizard to guide the user to creating a new plugin.
     """

meerschaum/actions/python.py

@@ -9,14 +9,14 @@ from __future__ import annotations
 from meerschaum.utils.typing import SuccessTuple, Any, List, Optional
 
 def python(
-        action: Optional[List[str]] = None,
-        sub_args: Optional[List[str]] = None,
-        nopretty: bool = False,
-        noask: bool = False,
-        venv: Optional[str] = None,
-        debug: bool = False,
-        **kw: Any
-    ) -> SuccessTuple:
+    action: Optional[List[str]] = None,
+    sub_args: Optional[List[str]] = None,
+    nopretty: bool = False,
+    noask: bool = False,
+    venv: Optional[str] = None,
+    debug: bool = False,
+    **kw: Any
+) -> SuccessTuple:
     """
     Launch a virtual environment's Python interpreter with Meerschaum imported.
     You may pass flags to the Python binary by surrounding each flag with `[]`.
@@ -56,6 +56,9 @@ def python(
     if action is None:
         action = []
 
+    if noask:
+        nopretty = True
+
     joined_actions = (
         ["import meerschaum as mrsm"]
         if venv is None and not sub_args

meerschaum/actions/register.py

@@ -7,12 +7,13 @@ Register new Pipes. Requires the API to be running.
 """
 
 from __future__ import annotations
+import meerschaum as mrsm
 from meerschaum.utils.typing import SuccessTuple, Any, List, Optional, Dict
 
 def register(
-        action: Optional[List[str]] = None,
-        **kw: Any
-    ) -> SuccessTuple:
+    action: Optional[List[str]] = None,
+    **kw: Any
+) -> SuccessTuple:
     """
     Register new items (pipes, plugins, users).
 
@@ -23,22 +24,25 @@ def register(
         'pipes'     : _register_pipes,
         'plugins'   : _register_plugins,
         'users'     : _register_users,
+        'connectors': _register_connectors,
     }
     return choose_subaction(action, options, **kw)
 
 
 def _complete_register(
-        action: Optional[List[str]] = None,
-        **kw: Any
-    ) -> List[str]:
+    action: Optional[List[str]] = None,
+    **kw: Any
+) -> List[str]:
     """
     Override the default Meerschaum `complete_` function.
     """
     if action is None:
         action = []
     options = {
-        'plugin' : _complete_register_plugins,
-        'plugins' : _complete_register_plugins,
+        'plugin': _complete_register_plugins,
+        'plugins': _complete_register_plugins,
+        'connector': _complete_register_connectors,
+        'connectors': _complete_register_connectors,
     }
 
     if len(action) > 0 and action[0] in options:
@@ -51,14 +55,14 @@ def _complete_register(
 
 
 def _register_pipes(
-        connector_keys: Optional[List[str]] = None,
-        metric_keys: Optional[List[str]] = None,
-        location_keys: Optional[List[str]] = None,
-        params: Optional[Dict[str, Any]] = None,
-        tags: Optional[List[str]] = None,
-        debug: bool = False,
-        **kw: Any
-    ) -> SuccessTuple:
+    connector_keys: Optional[List[str]] = None,
+    metric_keys: Optional[List[str]] = None,
+    location_keys: Optional[List[str]] = None,
+    params: Optional[Dict[str, Any]] = None,
+    tags: Optional[List[str]] = None,
+    debug: bool = False,
+    **kw: Any
+) -> SuccessTuple:
     """
     Create and register Pipe objects.
 
@@ -147,15 +151,18 @@ def _register_pipes(
 
 
 def _register_plugins(
-        action: Optional[List[str]] = None,
-        repository: Optional[str] = None,
-        shell: bool = False,
-        debug: bool = False,
-        yes: bool = False,
-        noask: bool = False,
-        force: bool = False,
-        **kw: Any
-    ) -> SuccessTuple:
+    action: Optional[List[str]] = None,
+    repository: Optional[str] = None,
+    shell: bool = False,
+    debug: bool = False,
+    yes: bool = False,
+    noask: bool = False,
+    force: bool = False,
+    **kw: Any
+) -> SuccessTuple:
+    """
+    Upload plugins to an API instance (repository).
+    """
     from meerschaum.utils.debug import dprint
     from meerschaum.plugins import reload_plugins, get_plugins_names
     from meerschaum.connectors.parse import parse_repo_keys
@@ -196,14 +203,23 @@ def _register_plugins(
     successes = {}
 
     for name, plugin in plugins_to_register.items():
-        desc = None
         plugin.attributes = repo_connector.get_plugin_attributes(plugin, debug=debug)
         if plugin.attributes is None:
             plugin.attributes = {}
+
+        try:
+            description_text = plugin.attributes.get('description', '')
+            doc_text = plugin.module.__doc__.lstrip().rstrip()
+        except Exception:
+            description_text = ''
+            doc_text = ''
+
+        desc = description_text or doc_text or ''
+
         question = f"Would you like to add a description to plugin '{name}'?"
-        if plugin.attributes.get('description', None):
+        if desc:
             info(f"Found existing description for plugin '{plugin}':")
-            print(plugin.attributes['description'])
+            print(desc)
             question = (
                 "Would you like to overwrite this description?\n"
                 + "To edit the existing text, visit /dash/plugins for this repository."
@@ -213,9 +229,14 @@ def _register_plugins(
             default='n',
             yes=yes
         ):
-            info('Press (Esc + Enter) to submit the description, (CTRL + C) to cancel.')
+            info('Press (Esc + Enter) to submit, (CTRL + C) to cancel.')
             try:
-                desc = prompt('', multiline=True, icon=False)
+                desc = prompt(
+                    '',
+                    multiline=True,
+                    icon=False,
+                    default_editable=desc.lstrip().rstrip(),
+                )
             except KeyboardInterrupt:
                 desc = None
             if desc == '':
@@ -246,17 +267,19 @@ def _register_plugins(
     reload_plugins(debug=debug)
     return total_success > 0, msg
 
+
 def _complete_register_plugins(*args, **kw):
     from meerschaum.actions.uninstall import _complete_uninstall_plugins
     return _complete_uninstall_plugins(*args, **kw)
 
+
 def _register_users(
-        action: Optional[List[str]] = None,
-        mrsm_instance: Optional[str] = None,
-        shell: bool = False,
-        debug: bool = False,
-        **kw: Any
-    ) -> SuccessTuple:
+    action: Optional[List[str]] = None,
+    mrsm_instance: Optional[str] = None,
+    shell: bool = False,
+    debug: bool = False,
+    **kw: Any
+) -> SuccessTuple:
     """
     Register a new user to a Meerschaum instance.
     """
@@ -294,7 +317,7 @@ def _register_users(
         nonregistered_users.append(user)
 
     ### prompt for passwords and emails, then try to register
-    success = dict()
+    success = {}
     successfully_registered_users = set()
     for _user in nonregistered_users:
         try:
@@ -337,6 +360,95 @@ def _register_users(
     )
     return succeeded > 0, msg
 
+
+def _register_connectors(
+    action: Optional[List[str]] = None,
+    connector_keys: Optional[List[str]] = None,
+    params: Optional[Dict[str, Any]] = None,
+    **kwargs: Any
+) -> SuccessTuple:
+    """
+    Create new connectors programmatically with `--params`.
+    See `bootstrap connector`.
+
+    Examples:
+
+    mrsm register connector sql:tmp --params 'uri:sqlite:////tmp/tmp.db'
+
+    mrsm register connector -c sql:new --params '{"database": "/tmp/new.db"}'
+    """
+    from meerschaum.config import get_config, write_config
+    from meerschaum.utils.prompt import yes_no
+    from meerschaum.utils.warnings import warn
+    all_keys = (action or []) + (connector_keys or [])
+    if len(all_keys) != 1:
+        return (
+            False,
+            "Provide one pair of keys for the connector to be registered."
+        )
+
+    keys = all_keys[0]
+
+    if keys.count(':') != 1:
+        return False, "Connector keys must be in the format `type:label`."
+
+    type_, label = keys.split(':', maxsplit=1)
+    mrsm_config = get_config('meerschaum')
+    if 'connectors' not in mrsm_config:
+        mrsm_config['connectors'] = {}
+
+    if type_ not in mrsm_config['connectors']:
+        mrsm_config['connectors'] = {}
+
+    is_new = True
+    if label in mrsm_config['connectors'][type_]:
+        rich_table, rich_json, rich_box = mrsm.attempt_import(
+            'rich.table',
+            'rich.json',
+            'rich.box',
+        )
+        existing_params = mrsm_config['connectors'][type_][label]
+        if existing_params == params:
+            return True, "Connector exists, nothing to do."
+
+        table = rich_table.Table(box=rich_box.MINIMAL)
+        table.add_column('Existing Parameters')
+        table.add_column('New Parameters')
+        table.add_row(
+            rich_json.JSON.from_data(existing_params),
+            rich_json.JSON.from_data(params or {}),
+        )
+
+        mrsm.pprint(table)
+        warn(f"Connector '{keys}' already exists.", stack=False)
+        if not yes_no(
+            f"Do you want to overwrite connector '{keys}'?",
+            default='n',
+            **kwargs
+        ):
+            return False, "Nothing was changed."
+
+        is_new = False
+
+    mrsm_config['connectors'][type_][label] = params
+    if not write_config({'meerschaum': mrsm_config}):
+        return False, "Failed to update configuration."
+
+    msg = (
+        "Successfully "
+        + ("registered" if is_new else "updated")
+        + f" connector '{keys}'."
+    )
+    return True, msg
+
+
+def _complete_register_connectors(
+    action: Optional[List[str]] = None, **kw: Any
+) -> List[str]:
+    from meerschaum.actions.show import _complete_show_connectors
+    return _complete_show_connectors(action)
+
+
 ### NOTE: This must be the final statement of the module.
 ###       Any subactions added below these lines will not
 ###       be added to the `help` docstring.