Merge branch 'main' into token-exchange

Author: ZohebShaikh

.github/workflows/pr.yml

@@ -11,5 +11,5 @@ jobs:
       - name: PR Conventional Commit Validation
         uses:  ytanikin/pr-conventional-commits@1.5.1
         with:
-          task_types: '["feat","fix","docs","test","ci","refactor","perf","chore","revert"]'
+          task_types: '["feat","fix","docs","test","ci","refactor","perf","chore","revert", "depr"]'
           add_label: 'false'

docs/explanations/api-version.md

@@ -1,5 +1,5 @@
 # API Version
 
-Blueapi has [released versions](https://github.com/DiamondLightSource/blueapi/releases) that are complaint with [semantic versioning](https://semver.org/) to make updating/rolling back as easy as possible. Blueapi's [REST API](../reference/rest-spec.md) is versioned separately to the main application, since not all changes will affect it. The idea is that a change in the REST API version is a signal to client developers that they may need to do some work to update.
+Blueapi has [released versions](https://github.com/DiamondLightSource/blueapi/releases) that are compliant with [semantic versioning](https://semver.org/) to make updating/rolling back as easy as possible. Blueapi's [REST API](../reference/rest-spec.md) is versioned separately to the main application, since not all changes will affect it. The idea is that a change in the REST API version is a signal to client developers that they may need to do some work to update.
 
 If you are a developer contributing a PR, there is a unit test that will fail if the REST API has changed in your PR but the version defined in the code, [](#REST_API_VERSION), has not been updated. You should update the version for _any_ change to the API at all, whether it's a major, minor or patch update is to be determined by the developer(s) and the reviewer(s) involved. _Do not_ update [`docs/reference/openapi.yaml`](../reference/openapi.yaml), it is checked against `main` in CI. 

docs/explanations/events.md

@@ -16,14 +16,14 @@ a plan has started, finished, paused, errored etc. See the example below:
 ![sequence of event emission compared to plan start/finish, in a complicated case](../images/bluesky-events.png)
 
 Note the gap between the start of the plan and the issue of the first [`run start document`](https://blueskyproject.io/event-model/main/user/explanations/data-model.html#run-start-document), and the similar gap
-for the stop document vs end of the plan, thsse are typically used for setup and cleanup.
+for the stop document vs end of the plan, these are typically used for setup and cleanup.
 Also note that a plan can produce an arbitrary number of runs. This decoupling is fine in an IPython terminal
 because a human user can see when a plan has started, can see when it's finished and can see which runs are
 associated with which plans.
 
 ## New Events
 
-For the case of automation, we introduce a new set of events outside of the event model, specifically
+For the case of automation, we introduce a new set of events outside the event model, specifically
 pertaining to the running of the plan and state of the `RunEngine`. At a minimum, an event is emitted
 every time the engine:
 

src/blueapi/core/context.py

@@ -220,18 +220,43 @@ def with_config(self, config: EnvironmentConfig) -> None:
 
             match source:
                 case PlanSource():
+                    LOGGER.info("Including plans from %s", source.module)
                     self.with_plan_module(mod)
                 case DeviceSource():
+                    LOGGER.info("Including devices from %s", source.module)
+                    LOGGER.warning(
+                        "'devices' environment kind is deprecated - please convert "
+                        "configuration to use deviceManager"
+                    )
                     self.with_device_module(mod)
                 case DodalSource(mock=mock):
+                    LOGGER.info(
+                        "Including devices from 'dodal' source %s", source.module
+                    )
+                    LOGGER.warning(
+                        "'dodal' environment kind is deprecated - please convert "
+                        "configuration to use deviceManager"
+                    )
                     self.with_dodal_module(mod, mock=mock)
                 case DeviceManagerSource(mock=mock, name=name):
+                    LOGGER.info(
+                        "Including devices from 'deviceManager' source %s:%s",
+                        source.module,
+                        name,
+                    )
                     manager = getattr(mod, name)
                     if not isinstance(manager, DeviceManager):
                         raise ValueError(
                             f"{name} in module {mod} is not a device manager"
                         )
                     self.with_device_manager(manager, mock)
+        if not self.devices:
+            LOGGER.warning(
+                "Context had no devices after loading environment - are all modules "
+                "included and marked with the correct 'kind'?"
+            )
+        if not self.plans:
+            LOGGER.warning("Context had no plans registered after loading environment")
 
     def with_plan_module(self, module: ModuleType) -> None:
         """
@@ -284,6 +309,15 @@ def with_device_manager(self, manager: DeviceManager, mock: bool = False):
                 f"{len(errs)} errors while connecting devices",
                 exc_info=NotConnectedError(errs),
             )
+        if not (
+            build_result.devices
+            or build_result.build_errors
+            or build_result.connection_errors
+        ):
+            LOGGER.warning("Device manager did not build any devices")
+
+        utils.report_successful_devices(build_result.devices, mock)
+
         return build_result.devices, {
             **build_result.build_errors,
             **build_result.connection_errors,
@@ -322,6 +356,8 @@ def with_dodal_module(
                 f"{len(exceptions)} exceptions occurred while instantiating devices"
             )
             LOGGER.exception(NotConnectedError(exceptions))
+        elif not devices:
+            LOGGER.warning("No devices were loaded from dodal module %s", module)
         return devices, exceptions
 
     def register_plan(self, plan: PlanGenerator) -> PlanGenerator:

src/blueapi/log.py

@@ -90,6 +90,7 @@ def set_up_stream_handler(
     Args:
         logger: Logger to attach handler to
         logging_config: LoggingConfig
+        filters: list of filters
     """
     stream_handler = logging.StreamHandler()
     stream_handler.setLevel(logging_config.level)
@@ -137,7 +138,7 @@ class IBMColorBlindSafeColors(enum.Enum):
 
 
 class ColorFormatter(logging.Formatter):
-    """Colors level_name of log using IBM color blind safe palette."""
+    """Colors level_name of log using IBM color-blind safe palette."""
 
     def _level_colour(self, level_no: int) -> tuple[int, int, int] | None:
         match level_no:

src/blueapi/service/main.py

@@ -366,7 +366,6 @@ def get_tasks(
     Retrieve tasks based on their status.
     The status of a newly created task is 'unstarted'.
     """
-    tasks = []
     if task_status:
         add_span_attributes({"status": task_status})
         try:

src/blueapi/utils/__init__.py

@@ -1,5 +1,5 @@
 from .base_model import BlueapiBaseModel, BlueapiModelConfig, BlueapiPlanModelConfig
-from .connect_devices import connect_devices
+from .connect_devices import connect_devices, report_successful_devices
 from .file_permissions import get_owner_gid, is_sgid_set
 from .invalid_config_error import InvalidConfigError
 from .modules import is_function_sourced_from_module, load_module_all
@@ -17,6 +17,7 @@
     "InvalidConfigError",
     "NumtrackerClient",
     "connect_devices",
+    "report_successful_devices",
     "is_sgid_set",
     "get_owner_gid",
     "is_function_sourced_from_module",

src/blueapi/utils/connect_devices.py

@@ -15,7 +15,7 @@
 LOGGER = logging.getLogger(__name__)
 
 
-def _report_successful_devices(
+def report_successful_devices(
     devices: Mapping[str, AnyDevice],
     sim_backend: bool,
 ) -> None:
@@ -86,14 +86,14 @@ def is_simulated_device(name, factory, **kwargs):
         real_devices, exceptions = _establish_device_connections(
             run_engine, real_devices, False
         )
-        _report_successful_devices(real_devices, False)
+        report_successful_devices(real_devices, False)
         exception_map |= exceptions
     if len(sim_devices) > 0:
         sim_devices, exceptions = _establish_device_connections(
             run_engine,
             sim_devices,  # type: ignore
             True,
         )
-        _report_successful_devices(sim_devices, True)
+        report_successful_devices(sim_devices, True)
         exception_map |= exceptions
     return exception_map

src/blueapi/worker/task_worker.py

@@ -213,7 +213,7 @@ def get_tasks_by_status(self, status: TaskStatusEnum) -> list[TrackableTask]:
         """
         Retrieve a list of tasks based on their status.
         Args:
-           TaskStatusEnum: The status to filter tasks by.
+           status TaskStatusEnum: The status to filter tasks by.
         Returns:
           list[TrackableTask]: A list of tasks that match the given status.
         """