Updated GeoComResponse to generic type

Author: MrClock8163

docs/conf.py

@@ -146,7 +146,8 @@
 nitpick_ignore = {
     ("py:class", "optional"),
     ("py:param", "_E"),
-    ("py:param", "_T")
+    ("py:param", "_T"),
+    ("py:param", "_P")
 }
 nitpick_ignore_regex = {
     ("py:obj", r"[a-zA-Z]{3}\.\w+")

src/geocompy/protocols.py

@@ -20,20 +20,24 @@
 """
 from enum import IntEnum
 from logging import Logger
-from typing import Any, Callable, Iterable, Literal, Generic, TypeVar
+from typing import (
+    Any, Callable, Iterable, Literal,
+    Generic, TypeVar, overload
+)
 
 from .communication import Connection, get_logger
 from .data import Angle, Byte
 
 
 _T = TypeVar("_T")
+_P = TypeVar("_P", bound=Any)
 
 
 class GeoComReturnCode(IntEnum):
     """Base class for all GeoCom return code enums."""
 
 
-class GeoComResponse:
+class GeoComResponse(Generic[_P]):
     """
     Container class for parsed GeoCom responses.
 
@@ -47,7 +51,7 @@ def __init__(
         comcode: GeoComReturnCode,
         rpccode: GeoComReturnCode,
         trans: int,
-        params: dict[str, Any]
+        params: _P | None = None
     ):
         """
         Parameters
@@ -67,9 +71,9 @@ def __init__(
             the command.
         trans : int
             Parsed transaction ID.
-        params : dict[str, Any]
+        params : Any | None, optional
             Collection of parsed response parameters. The content
-            is dependent on the executed function.
+            is dependent on the executed function. (default: None)
         """
         self.rpcname: str = rpcname
         """Name of the GeoCom function, that correspondes to the RPC,
@@ -86,7 +90,7 @@ def __init__(
             the command."""
         self.trans: int = trans
         """Parsed transaction ID."""
-        self.params: dict[str, Any] = params
+        self.params: _P | None = params
         """Collection of parsed response parameters. The content
             is dependent on the executed function."""
 
@@ -129,11 +133,86 @@ def __init__(
             logger = get_logger("/dev/null")
         self._logger: Logger = logger
 
+    @overload
     def request(
         self,
         rpc: int,
-        params: Iterable[int | float | bool | str | Angle | Byte] = [],
-        parsers: dict[str, Callable[[str], Any]] | None = None
+        params: Iterable[int | float | bool | str | Angle | Byte] = (),
+        parsers: Iterable[Callable[[str], Any]] | None = None
+    ) -> GeoComResponse[Iterable]:
+        """
+        Executes an RPC request and returns the parsed GeoCom response.
+
+        Constructs a request (from the given RPC code and parameters),
+        writes it to the serial line, then reads the response. The
+        response is then parsed using the provided parser functions.
+
+        Parameters
+        ----------
+        rpc : int
+            Number of the RPC to execute.
+        params : Iterable[int | float | bool | str | Angle | Byte], optional
+            Parameters for the request, by default ()
+        parsers : Iterable[Callable[[str], Any]] | None, optional
+            Parser functions for the values in the RPC response,
+            by default None
+
+        Returns
+        -------
+        GeoComResponse
+            Parsed return codes and parameters from the RPC response.
+
+        Raises
+        ------
+        NotImplementedError
+            If the method is not implemented on the class.
+
+        """
+
+    @overload
+    def request(
+        self,
+        rpc: int,
+        params: Iterable[int | float | bool | str | Angle | Byte] = (),
+        parsers: Callable[[str], _T] | None = None
+    ) -> GeoComResponse[_T]:
+        """
+        Executes an RPC request and returns the parsed GeoCom response.
+
+        Constructs a request (from the given RPC code and parameters),
+        writes it to the serial line, then reads the response. The
+        response is then parsed using the provided parser function.
+
+        Parameters
+        ----------
+        rpc : int
+            Number of the RPC to execute.
+        params : Iterable[int | float | bool | str | Angle | Byte], optional
+            Parameters for the request, by default []
+        parsers : Callable[[str], Any] | None, optional
+            Parser function for the value in the RPC response,
+            by default None
+
+        Returns
+        -------
+        GeoComResponse
+            Parsed return codes and parameters from the RPC response.
+
+        Raises
+        ------
+        NotImplementedError
+            If the method is not implemented on the class.
+        """
+
+    def request(
+        self,
+        rpc: int,
+        params: Iterable[int | float | bool | str | Angle | Byte] = (),
+        parsers: (
+            Iterable[Callable[[str], Any]]
+            | Callable[[str], Any]
+            | None
+        ) = None
     ) -> GeoComResponse:
         """
         Executes an RPC request and returns the parsed GeoCom response.
@@ -148,9 +227,8 @@ def request(
             Number of the RPC to execute.
         params : Iterable[int | float | bool | str | Angle | Byte], optional
             Parameters for the request, by default []
-        parsers : dict[str, Callable[[str], Any]] | None, optional
-            Parser functions for the values in the RPC response
-            (Maps the parser functions to the names of the parameters),
+        parsers : Iterable[Callable[[str], Any]] | None, optional
+            Parser functions for the values in the RPC response,
             by default None
 
         Returns
@@ -166,11 +244,79 @@ def request(
         """
         raise NotImplementedError()
 
+    @overload
+    def parse_response(
+        cls,
+        cmd: str,
+        response: str,
+        parsers: Iterable[Callable[[str], Any]] | None = None
+    ) -> GeoComResponse[Iterable]:
+        """
+        Parses RPC response and constructs :class:`GeoComResponse`
+        instance.
+
+        Parameters
+        ----------
+        cmd : str
+            Full, serialized request, that invoked the response.
+        response : str
+            Full, received response.
+        parsers : Iterable[Callable[[str], Any]], optional
+            Parser functions for the values in the RPC response, by
+            default None
+
+        Returns
+        -------
+        GeoComResponse
+            Parsed return codes and parameters from the RPC response.
+
+        Raises
+        ------
+        NotImplementedError
+            If the method is not implemented on the class.
+        """
+
+    @overload
     def parse_response(
         cls,
         cmd: str,
         response: str,
-        parsers: dict[str, Callable[[str], Any]]
+        parsers: Callable[[str], _T] | None = None
+    ) -> GeoComResponse[_T]:
+        """
+        Parses RPC response and constructs :class:`GeoComResponse`
+        instance.
+
+        Parameters
+        ----------
+        cmd : str
+            Full, serialized request, that invoked the response.
+        response : str
+            Full, received response.
+        parsers : Callable[[str], Any] | None, optional
+            Parser function for the value in the RPC response, by
+            default None
+
+        Returns
+        -------
+        GeoComResponse
+            Parsed return codes and parameters from the RPC response.
+
+        Raises
+        ------
+        NotImplementedError
+            If the method is not implemented on the class.
+        """
+
+    def parse_response(
+        cls,
+        cmd: str,
+        response: str,
+        parsers: (
+            Iterable[Callable[[str], Any]]
+            | Callable[[str], Any]
+            | None
+        ) = None
     ) -> GeoComResponse:
         """
         Parses RPC response and constructs :class:`GeoComResponse`
@@ -182,9 +328,11 @@ def parse_response(
             Full, serialized request, that invoked the response.
         response : str
             Full, received response.
-        parsers : dict[str, Callable[[str], Any]]
-            Parser functions for the values in the RPC response.
-            (Maps the parser functions to the names of the parameters.)
+        parsers : Iterable[Callable[[str], Any]]
+        | Callable[[str], Any]
+        | None, optional
+            Parser functions for the values in the RPC response,
+            by default None
 
         Returns
         -------
@@ -227,7 +375,7 @@ def __init__(
         desc: str,
         cmd: str,
         response: str,
-        value: _T,
+        value: _T | None,
         comment: str = ""
     ):
         """
@@ -253,7 +401,7 @@ def __init__(
         """Full, serialized command, that invoked this response."""
         self.response: str = response
         """Full, received response."""
-        self.value: _T = value
+        self.value: _T | None = value
         """Parsed response value. The content is dependent on the
         executed command."""
         self.comment: str = comment