Merge pull request #5 from prjemian/chore/template_sync_684d265

upstream merge template repository

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,16 @@
+# Description
+
+Please include a summary of the change and (optionally) which issue is fixed. Please also include
+relevant motivation and context.
+
+Fixes # (issue)
+
+## Type of change
+
+Choose which options apply, and delete the ones which do not apply.
+
+- Bug fix (non-breaking change that fixes an issue)
+- New feature (non-breaking change that adds functionality)
+- Breaking change (fix or feature that would cause existing functionality to not work as expected)
+- Documentation update
+- Code maintenance/cleanup

.github/workflows/code.yml

@@ -132,6 +132,12 @@ jobs:
           COVERALLS_FLAG_NAME: ${{ matrix.python-version }} # -${{ matrix.redis-version }}
           COVERALLS_PARALLEL: true
 
+      - name: IPython Startup Test
+        shell: bash -l {0}
+        run: |
+          set -vxeuo pipefail
+          ipython -c "from instrument.startup import *; RE(make_devices())"
+
   # https://coveralls-python.readthedocs.io/en/latest/usage/configuration.html#github-actions-support
   coveralls:
     name: Report unit test coverage to coveralls

.pre-commit-config.yaml

@@ -2,7 +2,7 @@
 
 repos:
   - repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v4.6.0
+    rev: v5.0.0
     hooks:
       # exclude_types: [jupyter]
       - id: check-yaml

LICENSE

@@ -0,0 +1,48 @@
+Copyright (c) 2023-2025, UChicago Argonne, LLC
+
+All Rights Reserved
+
+BITS
+
+BCDA, Advanced Photon Source, Argonne National Laboratory
+
+
+OPEN SOURCE LICENSE
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice,
+   this list of conditions and the following disclaimer.  Software changes,
+   modifications, or derivative works, should be noted with comments and
+   the author and organization's name.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the names of UChicago Argonne, LLC or the Department of Energy
+   nor the names of its contributors may be used to endorse or promote
+   products derived from this software without specific prior written
+   permission.
+
+4. The software and the end-user documentation included with the
+   redistribution, if any, must include the following acknowledgment:
+
+   "This product includes software produced by UChicago Argonne, LLC
+   under Contract No. DE-AC02-06CH11357 with the Department of Energy."
+
+****************************************************************************
+
+DISCLAIMER
+
+THE SOFTWARE IS SUPPLIED "AS IS" WITHOUT WARRANTY OF ANY KIND.
+
+Neither the United States GOVERNMENT, nor the United States Department
+of Energy, NOR uchicago argonne, LLC, nor any of their employees, makes
+any warranty, express or implied, or assumes any legal liability or
+responsibility for the accuracy, completeness, or usefulness of any
+information, data, apparatus, product, or process disclosed, or
+represents that its use would not infringe privately owned rights.
+
+****************************************************************************

README.md

@@ -17,7 +17,7 @@ cd bs_model_instrument
 Set up the development environment.
 
 ```bash
-export ENV_NAME=bs_model_env
+export ENV_NAME=bits
 conda create -y -n $ENV_NAME python=3.11 pyepics
 conda activate $ENV_NAME
 pip install -e ."[all]"

docs/source/api/devices.rst

@@ -8,6 +8,11 @@ See the advice below to declare your instrument's ophyd-style in YAML files:
 * :ref:`api.configs.devices`
 * :ref:`api.configs.devices_aps_only`
 
+.. autosummary::
+    :nosignatures:
+
+    ~instrument.devices.factories
+
 The `instrument.startup` module calls ``RE(make_devices())`` to
 make the devices as described.
 
@@ -17,8 +22,11 @@ Declare all devices
 All ophyd-style devices are declared in one of the two YAML files listed above:
 
 * when code (classes, factory functions) is provided by a package:
+
   * refer to the package class (or function) directly in the YAML file
+
 * when local customization is needed (new support or modify a packaged class):
+
   * create local custom code that defines the class or factory
   * refer to local custom code in the YAML file
 
@@ -28,19 +36,19 @@ this API signature:
 .. code-block:: py
     :linenos:
 
-    callable(*, prefix="", name="", labels=[], **kwargs)
+    creator(*, prefix="", name="", labels=[], **kwargs)
 
 .. rubric:: Quick example
 
 An ophyd object for an EPICS motor PV ``gp:m1`` is created in Python code where
-``ophyd.EpicsMotor`` is the *callable*, ``"gp:m1"`` is the `prefix`, and the
+``ophyd.EpicsMotor`` is the *creator*, ``"gp:m1"`` is the `prefix`, and the
 other kwargs are ``name`` and ``labels``.
 
 .. code-block:: py
     :linenos:
 
     import ophyd
-    m1 = ophyd.EpicsMotor("ioc:m1", name="m1", labels=["motor"])
+    m1 = ophyd.EpicsMotor("ioc:m1", name="m1", labels=["motors"])
 
 This YAML replaces all the Python code above to create the ``m1`` object:
 
@@ -50,7 +58,7 @@ This YAML replaces all the Python code above to create the ``m1`` object:
     ophyd.EpicsMotor:
     - name: "m1"
       prefix: "ioc:m1"
-      labels: ["motor"]
+      labels: ["motors"]
 
 .. tip:: The devices are (re)created each time ``RE(make_devices())`` is run.
 
@@ -60,10 +68,11 @@ This YAML replaces all the Python code above to create the ``m1`` object:
     the Python code.
 
     The :func:`~instrument.utils.make_devices_yaml.make_devices()` plan stub
-    imports the callable and creates any devices listed below it.  In YAML:
+    imports the 'creator' (Python code) and creates any devices listed
+    below it.  In YAML:
 
-    * Each callable can only be listed once.
-    * All devices that are created with a callable are listed below it.
+    * Each 'creator' can only be listed once.
+    * All devices that are created with a 'creator' are listed below it.
     * Each device starts with a `-` and then the kwargs, as shown.
 
     Indentation is important. Follow the examples.
@@ -82,9 +91,12 @@ This YAML replaces all the Python code above to create the ``m1`` object:
             - motor
 
         ophyd.EpicsMotor:
-        - {name: m1, prefix: ioc:m1, labels: ["motor"]}
+        - {name: m1, prefix: ioc:m1, labels: ["motors"]}
+
+        ophyd.EpicsMotor: [{name: m1, prefix: ioc:m1, labels: ["motors"]}]
 
-        ophyd.EpicsMotor: [{name: m1, prefix: ioc:m1, labels: ["motor"]}]
+        instrument.devices.factories.motors:
+        - {prefix: ioc:m, names: m, first: 1, last: 1, labels: ["motors"]}
 
 Examples
 --------
@@ -108,11 +120,23 @@ describes five motors, using a one-line format for each dictionary.
     :linenos:
 
     ophyd.EpicsMotor:
-    - {name: m1, prefix: ioc:m1, labels: ["motor"]}
-    - {name: m2, prefix: ioc:m2, labels: ["motor"]}
-    - {name: m3, prefix: ioc:m3, labels: ["motor"]}
-    - {name: dx, prefix: vme:m58:c0:m1, labels: ["motor"]}
-    - {name: dy, prefix: vme:m58:c0:m2, labels: ["motor"]}
+    - {name: m1, prefix: ioc:m1, labels: ["motors"]}
+    - {name: m2, prefix: ioc:m2, labels: ["motors"]}
+    - {name: m3, prefix: ioc:m3, labels: ["motors"]}
+    - {name: dx, prefix: vme:m58:c0:m1, labels: ["motors"]}
+    - {name: dy, prefix: vme:m58:c0:m2, labels: ["motors"]}
+
+Using a factory to define some of these motors that fit a numerical pattern:
+
+.. code-block:: yaml
+    :linenos:
+
+    instrument.devices.factories.motors:
+    - {prefix: ioc:m, names: m, first: 1, last: 3, labels: ["motors"]}
+
+    ophyd.EpicsMotor:
+    - {name: dx, prefix: vme:m58:c0:m1, labels: ["motors"]}
+    - {name: dy, prefix: vme:m58:c0:m2, labels: ["motors"]}
 
 Scalers
 ~~~~~~~
@@ -192,12 +216,12 @@ Here's the local support code (in new file
 
         # the reciprocal axes are defined by SimMixin
 
-        mu = FCpt(EpicsMotor, "{prefix}{m_mu}", kind="hinted", labels=["motor"])
-        omega = FCpt(EpicsMotor, "{prefix}{m_omega}", kind="hinted", labels=["motor"])
-        chi = FCpt(EpicsMotor, "{prefix}{m_chi}", kind="hinted", labels=["motor"])
-        phi = FCpt(EpicsMotor, "{prefix}{m_phi}", kind="hinted", labels=["motor"])
-        gamma = FCpt(EpicsMotor, "{prefix}{m_gamma}", kind="hinted", labels=["motor"])
-        delta = FCpt(EpicsMotor, "{prefix}{m_delta}", kind="hinted", labels=["motor"])
+        mu = FCpt(EpicsMotor, "{prefix}{m_mu}", kind="hinted", labels=["motors"])
+        omega = FCpt(EpicsMotor, "{prefix}{m_omega}", kind="hinted", labels=["motors"])
+        chi = FCpt(EpicsMotor, "{prefix}{m_chi}", kind="hinted", labels=["motors"])
+        phi = FCpt(EpicsMotor, "{prefix}{m_phi}", kind="hinted", labels=["motors"])
+        gamma = FCpt(EpicsMotor, "{prefix}{m_gamma}", kind="hinted", labels=["motors"])
+        delta = FCpt(EpicsMotor, "{prefix}{m_delta}", kind="hinted", labels=["motors"])
 
         energy = Component(EpicsSignalRO, "BraggERdbkAO", kind="hinted", labels=["energy"])
         energy_units = Component(EpicsSignalRO, "BraggERdbkAO.EGU", kind="config")
@@ -279,3 +303,7 @@ can provide them to your plan stub:
 
     dither_x = oregistry["user_calcs.calc9"]
     dither_y = oregistry["user_calcs.calc10"]
+
+------------------
+
+.. automodule:: instrument.devices.factories

docs/source/install.rst

@@ -35,7 +35,7 @@ by this ``instrument`` package for routine data acquisition.
 .. code-block:: bash
     :linenos:
 
-    export INSTALL_ENVIRONMENT_NAME=model_instrument_env
+    export INSTALL_ENVIRONMENT_NAME=bits
     conda create -y -n "${INSTALL_ENVIRONMENT_NAME}" python pyqt=5 pyepics
     conda activate "${INSTALL_ENVIRONMENT_NAME}"
     pip install -e .

pyproject.toml

@@ -22,7 +22,7 @@ maintainers = [
 readme = "README.md"
 requires-python = ">=3.11"
 keywords = ['bluesky', 'queueserver']
-license = { file = "src/instrument/LICENSE" }
+license = { file = "LICENSE" }
 classifiers = [
     "Development Status :: 6 - Mature",
     "Environment :: Console",
@@ -74,8 +74,8 @@ doc = [
 all = ["instrument[dev,doc]"]
 
 [project.urls]
-"Homepage" = "https://BCDA-APS.github.io/bs_model_instrument/"
-"Bug Tracker" = "https://github.com/BCDA-APS/bs_model_instrument/issues"
+"Homepage" = "https://BCDA-APS.github.io/BITS/"
+"Bug Tracker" = "https://github.com/BCDA-APS/BITS/issues"
 
 # [project.scripts]
 # instrument = "instrument.app:main"

src/instrument/configs/devices.yml

@@ -1,5 +1,9 @@
 # Guarneri-style device YAML configuration
 
+instrument.devices.factories.predefined_device:
+- {creator: ophyd.sim.motor, name: sim_motor}
+- {creator: ophyd.sim.noisy_det, name: sim_det}
+
 apstools.devices.SimulatedApsPssShutterWithStatus:
 - name: shutter
   labels: ["shutters"]

src/instrument/devices/__init__.py

@@ -1,4 +1 @@
 """Ophyd-style devices."""
-
-from ophyd.sim import motor as sim_motor  # noqa: F401
-from ophyd.sim import noisy_det as sim_det  # noqa: F401