pycomap 2.1.0__tar.gz → 2.1.1__tar.gz

{pycomap-2.1.0 → pycomap-2.1.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pycomap
-Version: 2.1.0
+Version: 2.1.1
 Summary: Async Python client for ComAp controllers: LAN discovery and the native ECDH/AES-encrypted control protocol
 Author: Igor Panteleyev
 Author-email: Igor Panteleyev <panteleev.igor69@gmail.com>
@@ -50,7 +50,7 @@ async with Controller(
     await ctrl.set_setpoint("Summer Time Mode", "Winter")  # STRING_LIST by label
 ```
 
-See the [API docs](https://igor-panteleev.github.io/pycomap/) for full reference. `just docs-serve` to browse locally.
+See the [API docs](https://igor-panteleev.github.io/pycomap/) for full reference, built with [Zensical](https://zensical.org/). `just docs-serve` to browse locally.
 
 ## Development
 

{pycomap-2.1.0 → pycomap-2.1.1}/README.md

@@ -23,7 +23,7 @@ async with Controller(
     await ctrl.set_setpoint("Summer Time Mode", "Winter")  # STRING_LIST by label
 ```
 
-See the [API docs](https://igor-panteleev.github.io/pycomap/) for full reference. `just docs-serve` to browse locally.
+See the [API docs](https://igor-panteleev.github.io/pycomap/) for full reference, built with [Zensical](https://zensical.org/). `just docs-serve` to browse locally.
 
 ## Development
 

{pycomap-2.1.0 → pycomap-2.1.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "pycomap"
-version = "2.1.0"
+version = "2.1.1"
 description = "Async Python client for ComAp controllers: LAN discovery and the native ECDH/AES-encrypted control protocol"
 readme = "README.md"
 license = "MIT"
@@ -38,10 +38,11 @@ build-backend = "uv_build"
 
 [dependency-groups]
 dev = [
+    "configargparse>=1.7.5",
     "ifaddr>=0.2.0",
-    "mkdocs>=1.6,<2",
-    "mkdocs-material>=9.5",
-    "mkdocstrings[python]>=0.25",
+    "python-dotenv>=1.2.2",
+    "zensical>=0.0.50",
+    "mkdocstrings-python>=1.0",
     "pre-commit>=4.6.0",
     "pytest>=8",
     "pytest-asyncio>=0.24",

{pycomap-2.1.0 → pycomap-2.1.1}/src/pycomap/controller.py

@@ -319,6 +319,51 @@ class Controller[TransportT: Transport]:
         except KeyError:
             raise KeyError(f"no setpoint named {name_or_number!r}") from None
 
+    def _string_list_options(
+        self, desc: ValueDescription | SetpointDescription
+    ) -> list[tuple[int, str]]:
+        """Shared ``STRING_LIST`` option lookup for
+        [value_options][pycomap.Controller.value_options] and
+        [setpoint_options][pycomap.Controller.setpoint_options].
+
+        Options are stored in ``CommonNames`` at indices ``[low_limit .. high_limit]``.
+        """
+        if desc.data_type is not DataType.STRING_LIST:
+            raise ComApProtocolError(
+                f"{desc.name!r} is DataType.{desc.data_type.name}, not STRING_LIST"
+            )
+        return [
+            (wire_value, self._common_names[desc.low_limit + wire_value])
+            for wire_value in range(desc.high_limit - desc.low_limit + 1)
+            if desc.low_limit + wire_value < len(self._common_names)
+        ]
+
+    def value_options(self, name_or_number: str | int) -> list[tuple[int, str]]:
+        """Return the available options for a ``STRING_LIST`` value.
+
+        Options are stored in ``CommonNames`` at indices ``[low_limit .. high_limit]``.
+        The wire value (0-based) is what the controller sends on the wire and what
+        [value_label][pycomap.Controller.value_label] expects; the label is the string
+        shown on the front panel and in InteliConfig. Note that
+        [read_values][pycomap.Controller.read_values] resolves ``STRING_LIST`` values to
+        their label automatically — this method is for enumerating all possible options
+        up front (e.g. to build a legend or validate against known states).
+
+        Args:
+            name_or_number: Value name or comm object number.
+
+        Returns:
+            ``[(wire_value, label), ...]`` ordered by wire value.
+
+        Raises:
+            ComApProtocolError: If the value is not ``STRING_LIST`` type.
+
+        Examples:
+            >>> ctrl.value_options("Engine State")
+            [(0, 'Ready'), (1, 'Prestart'), (2, 'Cranking'), ...]
+        """
+        return self._string_list_options(self.value_info(name_or_number))
+
     def setpoint_options(self, name_or_number: str | int) -> list[tuple[int, str]]:
         """Return the available options for a ``STRING_LIST`` setpoint.
 
@@ -340,16 +385,7 @@ class Controller[TransportT: Transport]:
             >>> ctrl.setpoint_options("Summer Time Mode")
             [(0, 'Disabled'), (1, 'Winter'), (2, 'Summer'), (3, 'Winter-S'), (4, 'Summer-S')]
         """
-        desc = self.setpoint_info(name_or_number)
-        if desc.data_type is not DataType.STRING_LIST:
-            raise ComApProtocolError(
-                f"setpoint {desc.name!r} is DataType.{desc.data_type.name}, not STRING_LIST"
-            )
-        return [
-            (wire_value, self._common_names[desc.low_limit + wire_value])
-            for wire_value in range(desc.high_limit - desc.low_limit + 1)
-            if desc.low_limit + wire_value < len(self._common_names)
-        ]
+        return self._string_list_options(self.setpoint_info(name_or_number))
 
     def value_label(self, name_or_number: str | int, wire_value: int) -> str:
         """Return the display label for a ``STRING_LIST`` value's wire integer.