Merge branch 'feature/parameter_group_warning' into 'master'

Warn the user if they are creating a subscription to a parameter group of size 1

See merge request !88

pyjapc/_japc.py

@@ -19,10 +19,14 @@ try:
 except ImportError:
     # For Python 3.7, allow use of Literal. When py37 dropped, move to typing.Literal form.
     from typing_extensions import Literal  # type: ignore
+import warnings
 
 import cmmnbuild_dep_manager
 import jpype as jp
 import numpy as np
+import pytz
+
+from . import _jpype_utils
 
 if typing.TYPE_CHECKING:
     # Import the JPype CERN package for type-checking only (not importable at runtime).
@@ -36,10 +40,6 @@ _JPrimitiveTypes = (
     jp.JByte, jp.JShort, jp.JInt, jp.JLong,  # type: ignore
 )
 
-# Spyder gives trouble if this import is not the last
-import pytz
-
-from . import _jpype_utils
 
 # Define a sentinel which can be used as an alternative to None for
 # keyword argument defaults (thereby allowing None to have a meaning for those
@@ -1040,7 +1040,9 @@ class PyJapc:
 
         Args:
             parameterName (str or list[str]): The path + identifier of the device parameter
-                to subscribe to.
+                to subscribe to. If providing a list, a parameter group will be created - note
+                that this introduces a grouping/synchronisation step into JAPC - if this is
+                undesirable please call ``subscribeParam`` once per parameter to be subscribed to.
 
             onValueReceived (function):
                 If you subscribe to a simple parameter value, the
@@ -1113,6 +1115,11 @@ class PyJapc:
             japc.subscribeParam("CB.BHB1100/Acquisition#currentAverage", newValueCallback, getHeader=True)
             japc.startSubscriptions()
         """
+        if not isinstance(parameterName, str) and len(parameterName) == 1:
+            warnings.warn(
+                "Subscribing to a single parameter in a parameter group is not recommended. "
+                "Did you mean to only subscribe to one?"
+            )
         # Get the (cached) JAPC parameter object
         par = self._getJapcPar(parameterName)
         lisJ = self._createValueListener(par=par,