resolved merge issues

Author: Chsudeepta

.github/workflows/test-against-main.yml

@@ -0,0 +1,38 @@
+name: test-against-main
+on:
+  schedule:
+    - cron: "0 0 * * *"
+jobs:
+  tests:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        version: ['3.11', "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.version }}
+      - name: install requirements
+        run: pip install -e .[dev]
+      - name: install latest bluesky and ophyd-async
+        run: pip install --upgrade --force-reinstall git+https://github.com/bluesky/bluesky.git@main git+https://github.com/bluesky/ophyd-async.git@main
+      - name: run ruff
+        run: python -m ruff --check
+      - name: run pyright
+        run: python -m pyright
+      - name: run pytest
+        run: python -m pytest
+  results:
+    if: ${{ always() }}
+    runs-on: ubuntu-latest
+    name: Final Results
+    needs: [tests]
+    steps:
+    - run: exit 1
+      # see https://stackoverflow.com/a/67532120/4907315
+      if: >-
+          ${{
+               contains(needs.*.result, 'failure')
+            || contains(needs.*.result, 'cancelled')
+          }}

README.md

@@ -1,4 +1,4 @@
-# ibex_bluesky_core
+![ibex_bluesky_core](https://github.com/IsisComputingGroup/ibex_bluesky_core/blob/main/doc/logo.png?raw=True)
 
 Core bluesky plan stubs & devices for use at ISIS. Not instrument/technique specific.
 

doc/conf.py

@@ -46,6 +46,13 @@
 
 html_theme = "sphinx_rtd_theme"
 html_static_path = ["_static"]
+html_logo = "logo.png"
+html_theme_options = {
+    "logo_only": False,
+    "display_version": False,
+    "style_nav_header_background": "#343131",
+}
+html_favicon = "favicon.png"
 
 autoclass_content = "both"
 myst_heading_anchors = 3

doc/favicon.png

@@ -99,6 +99,13 @@ Reference documentation
 
    fitting/*
 
+.. toctree::
+   :maxdepth: 2
+   :caption: Plan stubs
+   :glob:
+
+   plan_stubs/*
+
 .. toctree::
    :maxdepth: 2
    :caption: Preprocessors

doc/index.rst

@@ -0,0 +1,77 @@
+# `call_sync` (calling external code)
+
+API reference: {py:obj}`ibex_bluesky_core.plan_stubs.call_sync`
+
+All interaction with the "outside world" should be via bluesky messages, and **not** directly called from
+within a plan. For example, the following is **bad**:
+
+```python
+import bluesky.plan_stubs as bps
+from genie_python import genie as g
+
+def bad_plan():
+    yield from bps.open_run()
+    g.cset("foo", 123)  # This is bad - must not do this
+    yield from bps.close_run()
+```
+
+```{danger}
+External I/O - including most `genie_python` or `inst` functions -  should never be done directly in a plan,
+as it will break:
+- Rewindability (for example, the ability to interrupt a scan and then later seamlessly continue it)
+- Simulation (the `cset` above would be executed during a simulation)
+- Error handling (including ctrl-c handling)
+- Ability to emit documents
+- Ability to use bluesky signals
+- ...
+```
+
+In the above case, a good plan, which uses bluesky messages in a better way using 
+a bluesky-native `Block` object, would be:
+
+```python
+import bluesky.plan_stubs as bps
+from ophyd_async.plan_stubs import ensure_connected
+from ibex_bluesky_core.devices.block import block_rw
+
+foo = block_rw(float, "foo")
+
+def good_plan():
+    yield from ensure_connected(foo)
+    yield from bps.open_run()
+    yield from bps.mv(foo, 123)
+    yield from bps.close_run()
+```
+
+However, if the functionality you want to use is not yet natively available in bluesky, a fallback option
+for synchronous functions is available using the `call_sync` plan stub:
+
+```python
+import bluesky.plan_stubs as bps
+from ibex_bluesky_core.plan_stubs import call_sync
+from genie_python import genie as g
+
+def good_plan():
+    yield from bps.open_run()
+    
+    # Note use of g.some_function, rather than g.some_function() - i.e. a function reference
+    # We can also access the returned value from the call.
+    return_value = yield from call_sync(g.some_function, 123, keyword_argument=456)
+    yield from bps.checkpoint()
+    yield from bps.close_run()
+```
+
+It is strongly recommended that any functions run in this way are "fast" (i.e. less than a few seconds).
+In particular, avoid doing arbitrarily-long waits - for example, waiting for detector data
+or sample environment. For these long-running tasks, seek to implement at least the long-running parts using 
+native bluesky mechanisms.
+
+```{note}
+`bps.checkpoint()` above instructs bluesky that this is a safe point from which to resume a plan. 
+`call_sync` always clears an active checkpoint first, as the code it runs may have arbitrary external
+side effects.
+
+If a plan is interrupted with no checkpoint active, it cannot be resumed later (it effectively forces
+the plan to abort rather than pause). You will see `bluesky.utils.FailedPause` as part of the traceback
+on ctrl-c, if this is the case.
+```

doc/logo.png

@@ -28,7 +28,7 @@ classifiers = [
   #   5 - Production/Stable
   "Development Status :: 3 - Alpha",
   "Intended Audience :: Developers",
-  "License :: OSI Approved :: MIT License",
+  "License :: OSI Approved :: BSD License",
 
   # Specify the Python versions you support here. In particular, ensure
   # that you indicate you support Python 3. These classifiers are *not*

doc/plan_stubs/external_code.md

@@ -1 +1,43 @@
 """Core plan stubs."""
+
+from typing import Callable, Generator, ParamSpec, TypeVar, cast
+
+import bluesky.plan_stubs as bps
+from bluesky.utils import Msg
+
+P = ParamSpec("P")
+T = TypeVar("T")
+
+
+CALL_SYNC_MSG_KEY = "ibex_bluesky_core_call_sync"
+
+
+def call_sync(func: Callable[P, T], *args: P.args, **kwargs: P.kwargs) -> Generator[Msg, None, T]:
+    """Call a synchronous user function in a plan, and returns the result of that call.
+
+    Attempts to guard against the most common pitfalls of naive implementations, for example:
+
+    - Blocking the whole event loop
+    - Breaking keyboard interrupt handling
+    - Not clearing the active checkpoint
+
+    It does not necessarily guard against all possible cases, and as such it is *recommended* to
+    use native bluesky functionality wherever possible in preference to this plan stub. This should
+    be seen as an escape-hatch.
+
+    The wrapped function will be run in a new thread.
+
+    This plan stub will clear any active checkpoints before running the external code, because
+    in general the external code is not safe to re-run later once it has started (e.g. it may have
+    done relative sets, or may have started some external process). This means that if a plan is
+    interrupted at any point between a call_sync and the next checkpoint, the plan cannot be
+    resumed - in this case bluesky.utils.FailedPause will appear in the ctrl-c stack trace.
+
+    Args:
+        func: A callable to run.
+        args: Arbitrary arguments to be passed to the wrapped function
+        kwargs: Arbitrary keyword arguments to be passed to the wrapped function
+
+    """
+    yield from bps.clear_checkpoint()
+    return cast(T, (yield Msg(CALL_SYNC_MSG_KEY, func, *args, **kwargs)))

pyproject.toml

@@ -18,6 +18,9 @@
 
 
 logger = logging.getLogger(__name__)
+from ibex_bluesky_core.plan_stubs import CALL_SYNC_MSG_KEY
+from ibex_bluesky_core.preprocessors import add_rb_number_processor
+from ibex_bluesky_core.run_engine._msg_handlers import call_sync_handler
 
 
 class _DuringTask(DuringTask):
@@ -93,6 +96,8 @@ def get_run_engine() -> RunEngine:
     log_callback = DocLoggingCallback()
     RE.subscribe(log_callback)
 
+    RE.register_command(CALL_SYNC_MSG_KEY, call_sync_handler)
+
     RE.preprocessors.append(functools.partial(bpp.plan_mutator, msg_proc=add_rb_number_processor))
 
     return RE