hutch-python 1.19.0__tar.gz → 1.20.0__tar.gz

{hutch_python-1.19.0 → hutch_python-1.20.0}/.gitignore

@@ -118,3 +118,6 @@ hutch_python/tests/tst/db.txt
 
 # vscode
 .vscode
+
+# unit test artifacts
+*.sqlite

{hutch_python-1.19.0 → hutch_python-1.20.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: hutch-python
-Version: 1.19.0
+Version: 1.20.0
 Summary: Launcher and Config Reader for LCLS Interactive IPython Sessions
 Author: SLAC National Accelerator Laboratory
 License: Copyright (c) 2023, The Board of Trustees of the Leland Stanford Junior

{hutch_python-1.19.0 → hutch_python-1.20.0}/docs/source/releases.rst

@@ -2,6 +2,23 @@ Release History
 ###############
 
 
+v1.20.0 (2024-04-19)
+====================
+
+Features
+--------
+- Allow per-session separate ipython histories via ``--hist-file``
+  command-line argument. If omitted, default ipython behavior is used.
+  When ``--hist-file`` is included with no argument, the history file
+  will be written a local operator console hard drive, if available.
+  An argument can be provided to use any file as the history.sqlite file.
+
+Contributors
+------------
+- zllentz
+
+
+
 v1.19.0 (2024-04-15)
 ====================
 

{hutch_python-1.19.0 → hutch_python-1.20.0}/hutch_python/_version.py

@@ -12,5 +12,5 @@ __version__: str
 __version_tuple__: VERSION_TUPLE
 version_tuple: VERSION_TUPLE
 
-__version__ = version = '1.19.0'
-__version_tuple__ = version_tuple = (1, 19, 0)
+__version__ = version = '1.20.0'
+__version_tuple__ = version_tuple = (1, 20, 0)

hutch_python-1.20.0/hutch_python/cli.py

@@ -0,0 +1,236 @@
+"""
+This module defines the command-line interface arguments for the
+``hutch-python`` script. It also provides utilities that are only used at
+startup.
+"""
+from __future__ import annotations
+
+import argparse
+import dataclasses
+import logging
+import os
+import sys
+from pathlib import Path
+from string import Template
+
+import IPython
+import matplotlib
+from cookiecutter.main import cookiecutter
+from IPython import start_ipython
+from traitlets.config import Config
+
+from .constants import CONDA_BASE, DIR_MODULE
+from .env_version import log_env
+from .load_conf import load
+from .log_setup import configure_log_directory, debug_mode, setup_logging
+
+logger = logging.getLogger(__name__)
+opts_cache = {}
+DEFAULT_HISTFILE = "/u1/${USER}/hutch-python/history.sqlite"
+
+
+# Define the parser
+def get_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="hutch-python",
+                                     description="Launch LCLS Hutch Python")
+    parser.add_argument("--cfg", required=False, default=None,
+                        help="Configuration yaml file")
+    parser.add_argument("--exp", required=False, default=None,
+                        help="Experiment number override")
+    parser.add_argument("--debug", action="store_true", default=False,
+                        help="Start in debug mode")
+    parser.add_argument("--sim", action="store_true", default=False,
+                        help="Run with simulated DAQ (lcls1 only)")
+    parser.add_argument("--create", action="store", default=False,
+                        help="Create a new hutch deployment")
+    parser.add_argument("--hist-file", nargs="?", action="store",
+                        default=None, const=DEFAULT_HISTFILE,
+                        help=(
+                            "File to store the sqlite session history in. "
+                            "${VARIABLES} will be substituted for "
+                            "via shell environment variables, "
+                            "Though in some cases these may be expanded by the shell "
+                            "prior to reaching the python layer. "
+                            "If omitted, defaults to the ipython default location. "
+                            "If included but left blank, defaults to "
+                            f"{DEFAULT_HISTFILE} "
+                            "if the folder exists, "
+                            "otherwise uses the ipython default location. "
+                            "This folder is a local hard-drive location for lcls "
+                            "operator consoles."
+                        ))
+    parser.add_argument("script", nargs="?",
+                        help="Run a script instead of running interactively")
+    return parser
+
+
+parser = get_parser()
+
+# Append to module docs
+__doc__ += "\n::\n\n    " + parser.format_help().replace("\n", "\n    ")
+
+
+@dataclasses.dataclass
+class HutchPythonArgs:
+    cfg: str | None = None
+    exp: str | None = None
+    debug: bool = False
+    sim: bool = False
+    create: bool = False
+    hist_file: str | None = None
+    script: str | None = None
+
+
+def configure_tab_completion(ipy_config):
+    """
+    Disable Jedi and tweak IPython tab completion.
+
+    Parameters
+    ----------
+    ipy_config : traitlets.config.Config
+        IPython configuration.
+    """
+    # Old API for disabling Jedi. Keep in just in case API changes back.
+    ipy_config.InteractiveShellApp.Completer.use_jedi = False
+    # New API for disabling Jedi (two access points documented, use both)
+    ipy_config.Completer.use_jedi = False
+    ipy_config.IPCompleter.use_jedi = False
+    try:
+        # Monkeypatch IPython completion - we need it to respect __dir__
+        # when Jedi is disabled.
+        # Details: https://github.com/pcdshub/pcdsdevices/issues/709
+        # First, access it to see that the internals have not changed:
+        IPython.core.completer.dir2
+    except AttributeError:
+        logger.debug("Looks like the IPython API changed!")
+    else:
+        # Then monkeypatch it in:
+        IPython.core.completer.dir2 = dir
+
+
+def configure_ipython_session(args: HutchPythonArgs):
+    """
+    Configure a new IPython session.
+
+    Returns
+    -------
+    ipy_config : traitlets.config.Config
+        IPython configuration.
+    """
+    ipy_config = Config()
+    # Important Utilities
+    ipy_config.InteractiveShellApp.extensions = [
+        "hutch_python.ipython_log",
+        "hutch_python.bug",
+        "hutch_python.pt_app_config"
+    ]
+    # Matplotlib setup for ipython (automatically do %matplotlib)
+    backend = matplotlib.get_backend().replace("Agg", "").lower()
+    ipy_config.InteractiveShellApp.matplotlib = backend
+    if backend == "agg":
+        logger.warning("No matplotlib rendering available. "
+                       "Methods that create plots will not "
+                       "function properly.")
+
+    # Disable reformatting input with black
+    ipy_config.TerminalInteractiveShell.autoformatter = None
+    # Set up tab completion modifications
+    configure_tab_completion(ipy_config)
+
+    # disable default banner
+    ipy_config.TerminalIPythonApp.display_banner = False
+
+    # Run startup hook code, print banner after startup hook files
+    files = [
+        str(DIR_MODULE / "startup_script.py"),
+        str(DIR_MODULE / "print_hint_banner.py"),
+    ]
+    ipy_config.InteractiveShellApp.exec_files = files
+
+    # Custom history file with sensible non-NFS default for opr accounts
+    if args.hist_file is not None:
+        hist_file = Template(args.hist_file).safe_substitute(os.environ)
+        if hist_file == ":memory:" or Path(hist_file).parent.exists():
+            ipy_config.HistoryManager.hist_file = hist_file
+        else:
+            msg = f"No such directory for history file {hist_file}, using ipython default instead."
+            if args.hist_file == DEFAULT_HISTFILE:
+                # We expect this to be missing for non-opr users
+                logger.debug(msg)
+            else:
+                # You specified a file, so we need to warn about this
+                logger.warning(msg)
+
+    return ipy_config
+
+
+def main():
+    """
+    Do the full hutch-python launch sequence.
+
+    Parses the user's cli arguments and distributes them as needed to the
+    setup functions.
+    """
+    # Parse the user's arguments
+    args = parser.parse_args(namespace=HutchPythonArgs())
+
+    # Set up logging first
+    if args.cfg is None:
+        log_dir = None
+    else:
+        log_dir = os.path.join(os.path.dirname(args.cfg), "logs")
+
+    configure_log_directory(log_dir)
+    setup_logging()
+
+    # Debug mode next
+    if args.debug:
+        debug_mode(True)
+
+    # Do the first log message, now that logging is ready
+    logger.debug("cli starting with args %s", args)
+
+    # Check and display the environment info as appropriate (very early)
+    log_env()
+
+    # Options that mean skipping the python environment
+    if args.create:
+        hutch = args.create
+        envs_dir = CONDA_BASE / "envs"
+        if envs_dir.exists():
+            # Pick most recent pcds release in our common env
+            base = str(CONDA_BASE)
+            path_obj = sorted(envs_dir.glob("pcds-*"))[-1]
+            env = path_obj.name
+        else:
+            # Fallback: pick current env
+            try:
+                base = str(Path(os.environ["CONDA_EXE"]).parent.parent)
+                env = os.environ["CONDA_DEFAULT_ENV"]
+            except KeyError:
+                # Take a stab at some non-conda defaults; ideally these would
+                # be configurable with argparse.
+                base = str(Path(sys.executable).parent)
+                env = hutch
+        logger.info(("Creating hutch-python dir for hutch %s using"
+                     " base=%s env=%s"), hutch, base, env)
+        cookiecutter(str(DIR_MODULE / "cookiecutter"), no_input=True,
+                     extra_context=dict(base=base, env=env, hutch=hutch))
+        return
+
+    # Save whether we are an interactive session or a script session
+    opts_cache["script"] = args.script
+
+    # Load objects based on the configuration file
+    objs = load(cfg=args.cfg, args=args)
+
+    script = opts_cache.get("script")
+    if script is None:
+        # Finally start the interactive session
+        start_ipython(argv=["--quick"], user_ns=objs,
+                      config=configure_ipython_session(args))
+    else:
+        # Instead of setting up ipython, run the script with objs
+        with open(script) as fn:
+            code = compile(fn.read(), script, "exec")
+            exec(code, objs, objs)

{hutch_python-1.19.0 → hutch_python-1.20.0}/hutch_python/tests/test_cli.py

@@ -1,14 +1,18 @@
 import logging
 import os
 import shutil
+import subprocess
+import sys
 from pathlib import Path
+from string import Template
 
 import IPython.core.completer
 import pytest
 from conftest import cli_args, restore_logging
 
 import hutch_python.cli
-from hutch_python.cli import main
+from hutch_python.cli import (HutchPythonArgs, configure_ipython_session,
+                              get_parser, main)
 from hutch_python.load_conf import load
 
 from .conftest import skip_if_win32_generic
@@ -80,6 +84,56 @@ def test_create_arg():
     shutil.rmtree(test_dir)
 
 
+def run_hpy_and_exit(*args: str) -> subprocess.CompletedProcess:
+    return subprocess.run(
+        [sys.executable, "-m", "hutch_python"] + list(args),
+        input="exit\n",
+        universal_newlines=True,
+        capture_output=True,
+    )
+
+
+@pytest.mark.timeout(30)
+def test_hist_file_arg(monkeypatch):
+    logger.debug("test_hist_file_arg")
+    test_hist_file = (CFG_PATH.parent / "history.sqlite").resolve()
+    bad_hist_file = (CFG_PATH.parent / "aesefiudh" / "history.sqlite").resolve()
+    memory_hist_filename = ":memory:"
+
+    # Test that the sqlite file gets made
+    # First, need to remove the file if it already exists
+    if test_hist_file.exists():
+        test_hist_file.unlink()
+
+    # Run with the good arg and exit
+    run_hpy_and_exit("--hist-file", str(test_hist_file))
+    # Was the history file created?
+    assert test_hist_file.exists()
+    # Remove the file for future tests
+    test_hist_file.unlink()
+    # With the bad hist file we should still run ok with just a warning
+    run_hpy_and_exit("--hist-file", str(bad_hist_file))
+    assert not test_hist_file.exists()
+    # Same with the in-memory choice
+    run_hpy_and_exit("--hist-file", memory_hist_filename)
+    assert not test_hist_file.exists()
+
+    # Exercise the template + check default usage
+    # We can't actually write to the default default in a test context
+    # But we can check what the config would be
+    new_default = str(test_hist_file.parent / "${USER}-history.sqlite")
+    new_default_filled = Template(new_default).substitute({"USER": os.environ["USER"]})
+    monkeypatch.setattr(
+        hutch_python.cli,
+        "DEFAULT_HISTFILE",
+        new_default,
+    )
+    parser = get_parser()
+    args = parser.parse_args(["--hist-file"], namespace=HutchPythonArgs())
+    ipy_config = configure_ipython_session(args)
+    assert ipy_config.HistoryManager.hist_file == new_default_filled
+
+
 @skip_if_win32_generic
 def test_run_script():
     logger.debug('test_run_script')
@@ -102,7 +156,7 @@ def test_ipython_tab_completion():
 
     # Side-effect of the following is monkey-patching `dir2` to "fix" this for
     # us.
-    hutch_python.cli.configure_ipython_session()
+    hutch_python.cli.configure_ipython_session(HutchPythonArgs())
 
     completer = IPython.core.completer.Completer(namespace=ns)
     completer.limit_to__all__ = False

{hutch_python-1.19.0 → hutch_python-1.20.0}/hutch_python.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: hutch-python
-Version: 1.19.0
+Version: 1.20.0
 Summary: Launcher and Config Reader for LCLS Interactive IPython Sessions
 Author: SLAC National Accelerator Laboratory
 License: Copyright (c) 2023, The Board of Trustees of the Leland Stanford Junior

{hutch_python-1.19.0 → hutch_python-1.20.0}/hutch_python.egg-info/SOURCES.txt

@@ -51,7 +51,6 @@ docs/source/tutorial.ipynb
 docs/source/user_utils.rst
 docs/source/utils.rst
 docs/source/yaml_files.rst
-docs/source/upcoming_release_notes/379-enh_limit_devices.rst
 docs/source/upcoming_release_notes/template-full.rst
 docs/source/upcoming_release_notes/template-short.rst
 hutch_python/__init__.py

hutch_python-1.19.0/docs/source/upcoming_release_notes/379-enh_limit_devices.rst

@@ -1,22 +0,0 @@
-379 enh_limit_devices
-#####################
-
-API Changes
------------
-- N/A
-
-Features
---------
-- Adds load_level conf.yaml key for choosing the method used to gather happi devices
-
-Bugfixes
---------
-- N/A
-
-Maintenance
------------
-- N/A
-
-Contributors
-------------
-- tangkong

hutch_python-1.19.0/hutch_python/cli.py

@@ -1,184 +0,0 @@
-"""
-This module defines the command-line interface arguments for the
-``hutch-python`` script. It also provides utilities that are only used at
-startup.
-"""
-import argparse
-import logging
-import os
-import sys
-from pathlib import Path
-
-import IPython
-import matplotlib
-from cookiecutter.main import cookiecutter
-from IPython import start_ipython
-from traitlets.config import Config
-
-from .constants import CONDA_BASE, DIR_MODULE
-from .env_version import log_env
-from .load_conf import load
-from .log_setup import configure_log_directory, debug_mode, setup_logging
-
-logger = logging.getLogger(__name__)
-opts_cache = {}
-
-# Define the parser
-parser = argparse.ArgumentParser(prog='hutch-python',
-                                 description='Launch LCLS Hutch Python')
-parser.add_argument('--cfg', required=False, default=None,
-                    help='Configuration yaml file')
-parser.add_argument('--exp', required=False, default=None,
-                    help='Experiment number override')
-parser.add_argument('--debug', action='store_true', default=False,
-                    help='Start in debug mode')
-parser.add_argument('--sim', action='store_true', default=False,
-                    help='Run with simulated DAQ (lcls1 only)')
-parser.add_argument('--create', action='store', default=False,
-                    help='Create a new hutch deployment')
-parser.add_argument('script', nargs='?',
-                    help='Run a script instead of running interactively')
-
-# Append to module docs
-__doc__ += '\n::\n\n    ' + parser.format_help().replace('\n', '\n    ')
-
-
-def configure_tab_completion(ipy_config):
-    """
-    Disable Jedi and tweak IPython tab completion.
-
-    Parameters
-    ----------
-    ipy_config : traitlets.config.Config
-        IPython configuration.
-    """
-    # Old API for disabling Jedi. Keep in just in case API changes back.
-    ipy_config.InteractiveShellApp.Completer.use_jedi = False
-    # New API for disabling Jedi (two access points documented, use both)
-    ipy_config.Completer.use_jedi = False
-    ipy_config.IPCompleter.use_jedi = False
-    try:
-        # Monkeypatch IPython completion - we need it to respect __dir__
-        # when Jedi is disabled.
-        # Details: https://github.com/pcdshub/pcdsdevices/issues/709
-        # First, access it to see that the internals have not changed:
-        IPython.core.completer.dir2
-    except AttributeError:
-        logger.debug('Looks like the IPython API changed!')
-    else:
-        # Then monkeypatch it in:
-        IPython.core.completer.dir2 = dir
-
-
-def configure_ipython_session():
-    """
-    Configure a new IPython session.
-
-    Returns
-    -------
-    ipy_config : traitlets.config.Config
-        IPython configuration.
-    """
-    ipy_config = Config()
-    # Important Utilities
-    ipy_config.InteractiveShellApp.extensions = [
-        'hutch_python.ipython_log',
-        'hutch_python.bug',
-        'hutch_python.pt_app_config'
-    ]
-    # Matplotlib setup for ipython (automatically do %matplotlib)
-    backend = matplotlib.get_backend().replace('Agg', '').lower()
-    ipy_config.InteractiveShellApp.matplotlib = backend
-    if backend == 'agg':
-        logger.warning('No matplotlib rendering available. '
-                       'Methods that create plots will not '
-                       'function properly.')
-
-    # Disable reformatting input with black
-    ipy_config.TerminalInteractiveShell.autoformatter = None
-    # Set up tab completion modifications
-    configure_tab_completion(ipy_config)
-
-    # disable default banner
-    ipy_config.TerminalIPythonApp.display_banner = False
-
-    # Run startup hook code, print banner after startup hook files
-    files = [
-        str(DIR_MODULE / "startup_script.py"),
-        str(DIR_MODULE / "print_hint_banner.py"),
-    ]
-    ipy_config.InteractiveShellApp.exec_files = files
-
-    return ipy_config
-
-
-def main():
-    """
-    Do the full hutch-python launch sequence.
-
-    Parses the user's cli arguments and distributes them as needed to the
-    setup functions.
-    """
-    # Parse the user's arguments
-    args = parser.parse_args()
-
-    # Set up logging first
-    if args.cfg is None:
-        log_dir = None
-    else:
-        log_dir = os.path.join(os.path.dirname(args.cfg), 'logs')
-
-    configure_log_directory(log_dir)
-    setup_logging()
-
-    # Debug mode next
-    if args.debug:
-        debug_mode(True)
-
-    # Do the first log message, now that logging is ready
-    logger.debug('cli starting with args %s', args)
-
-    # Check and display the environment info as appropriate (very early)
-    log_env()
-
-    # Options that mean skipping the python environment
-    if args.create:
-        hutch = args.create
-        envs_dir = CONDA_BASE / 'envs'
-        if envs_dir.exists():
-            # Pick most recent pcds release in our common env
-            base = str(CONDA_BASE)
-            path_obj = sorted(envs_dir.glob('pcds-*'))[-1]
-            env = path_obj.name
-        else:
-            # Fallback: pick current env
-            try:
-                base = str(Path(os.environ['CONDA_EXE']).parent.parent)
-                env = os.environ['CONDA_DEFAULT_ENV']
-            except KeyError:
-                # Take a stab at some non-conda defaults; ideally these would
-                # be configurable with argparse.
-                base = str(Path(sys.executable).parent)
-                env = hutch
-        logger.info(('Creating hutch-python dir for hutch %s using'
-                     ' base=%s env=%s'), hutch, base, env)
-        cookiecutter(str(DIR_MODULE / 'cookiecutter'), no_input=True,
-                     extra_context=dict(base=base, env=env, hutch=hutch))
-        return
-
-    # Save whether we are an interactive session or a script session
-    opts_cache['script'] = args.script
-
-    # Load objects based on the configuration file
-    objs = load(cfg=args.cfg, args=args)
-
-    script = opts_cache.get('script')
-    if script is None:
-        # Finally start the interactive session
-        start_ipython(argv=['--quick'], user_ns=objs,
-                      config=configure_ipython_session())
-    else:
-        # Instead of setting up ipython, run the script with objs
-        with open(script) as fn:
-            code = compile(fn.read(), script, 'exec')
-            exec(code, objs, objs)