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

{hutch-python-1.18.5 → 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.18.5 → hutch_python-1.20.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: hutch-python
-Version: 1.18.5
+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.18.5 → hutch_python-1.20.0}/docs/source/releases.rst

@@ -2,6 +2,45 @@ 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)
+====================
+
+Features
+--------
+- Updates EpicsArch script, adding several debug/testin flags and ensuring
+  information is up-to-date.  Includes:
+
+  - ``update_file``: feature that updates EpicsArch based on current questionnaire
+  - ``--softlink``: point arch file to new experiment via symbolic link
+  - ``--level``: specify a debug level
+  - ``--cds-items``: displays questionnaire data for a given run and experiment
+  - ``--link-path``: allows user to provide custom filepath for softlinks
+- Adds load_level conf.yaml key for choosing the method used to gather happi devices
+
+Contributors
+------------
+- c-tsoi
+- tangkong
+
+
+
 v1.18.5 (2023-09-14)
 ====================
 

{hutch-python-1.18.5 → hutch_python-1.20.0}/docs/source/yaml_files.rst

@@ -3,8 +3,8 @@ Yaml Files
 
 ``hutch-python`` uses a ``conf.yml`` file for basic configuration. This is a
 standard yaml file with the following valid keys:
-``hutch``, ``db``, ``load``, ``experiment``, ``obj_config``, ``daq_type``,
-``daq_host``, and ``daq_platform``.
+``hutch``, ``db``, ``load``, ``load_level``, ``experiment``, ``obj_config``,
+``daq_type``, ``daq_host``, and ``daq_platform``.
 
 
 hutch
@@ -69,6 +69,22 @@ This key is used to include hutch-specific code.
 ``from module import *`` for each of these modules.
 
 
+load_level
+----------
+The ``load_level`` key expects one of the following strings, corresponding to the
+amount of ophyd devices to load:
+
+- ``UPSTREAM``: The hutch's devices, and devices upstream from the requested hutch.
+If there are multiple paths to the requested hutch, all paths' devices are loaded.
+- ``STANDARD``: Devices gathered via ``UPSTREAM``, plus devices that share the
+"beamline" field in happi with the ``UPSTREAM`` devices.  (The current standard)
+- ``ALL``: All devices in the happi database.  Use this option at your own risk.
+
+.. code-block:: YAML
+
+   load_level: UPSTREAM
+
+
 experiment
 ----------
 

hutch_python-1.20.0/hutch_python/_version.py

@@ -0,0 +1,16 @@
+# file generated by setuptools_scm
+# don't change, don't track in version control
+TYPE_CHECKING = False
+if TYPE_CHECKING:
+    from typing import Tuple, Union
+    VERSION_TUPLE = Tuple[Union[int, str], ...]
+else:
+    VERSION_TUPLE = object
+
+version: str
+__version__: str
+__version_tuple__: VERSION_TUPLE
+version_tuple: VERSION_TUPLE
+
+__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.18.5 → hutch_python-1.20.0}/hutch_python/constants.py

@@ -32,6 +32,7 @@ VALID_KEYS = (
     'hutch',
     'db',
     'load',
+    'load_level',
     'experiment',
     'daq_platform',
     'daq_type',