21292: Improves typehinting for utilities module (#267)

Co-authored-by: DawnHogan <[email protected]>
Co-authored-by: howso-automation <[email protected]>

Author: 3 people

Diff for: howso/utilities/features.py

@@ -5,7 +5,7 @@
 from enum import Enum
 from functools import partial
 import locale
-from typing import Any, Optional
+import typing as t
 import warnings
 
 import numpy as np
@@ -62,31 +62,42 @@ class FeatureSerializer:
     @classmethod
     def serialize(  # noqa: C901
         cls,
-        data: pd.DataFrame | np.ndarray | Iterable[Any] | None,
+        data: t.Optional[pd.DataFrame | np.ndarray | Iterable[t.Any]],
         columns: Iterable[str] | None,
         features: Mapping,
         *,
         warn: bool = False
-    ) -> list[list[Any]] | None:
+    ) -> list[list[t.Any]] | None:
         """
         Serialize case data into list of lists.
 
         Parameters
         ----------
-        data : pandas.DataFrame or numpy.ndarray or list of list or None
-            The data to serialize.
-        columns : list of str or None
-            The case column mapping. The order corresponds to the order of cases
-            in output.
+        data : pd.DataFrame or np.ndarray or Iterable, default None
+            The data to serialize, typically in a Pandas DataFrame, Numpy ndarray or Python Iterable such as a list.
+        columns : Iterable of str, default None
+            The case column mapping. The order corresponds to the order of cases in output.
+            `columns` must be provided for non-DataFrame Iterables.
         features : Mapping
             The dictionary of feature name to feature attributes.
         warn : bool, default False
             If warnings should be raised by serializer.
 
         Returns
         -------
-        list of list or None
+        list of list or Any or None
             The serialized data from DataFrame.
+
+        ...
+
+        Raises
+        ------
+        HowsoError
+            An `pd.ndarray` or `Iterable` is provided, `columns` was left undefined 
+            or the given columns does not match the columns defined within a given `pd.DataFrame`.
+        ValueError
+            The provided `pd.DataFrame` contains non-unique columns or, an unexpected datatype 
+            was received (should be either pd.DataFrame, np.ndarray or Python Iterable (non-str)).
         """
         # Import locally to prevent a circular import
         from howso.client.exceptions import HowsoError
@@ -158,9 +169,9 @@ def serialize(  # noqa: C901
     @classmethod
     def deserialize(
         cls,
-        data: Iterable[Iterable[Any]] | Iterable[Mapping[str, Any]],
+        data: Iterable[Iterable[t.Any] | Mapping[str, t.Any]],
         columns: Iterable[str],
-        features: Optional[Mapping] = None
+        features: t.Optional[Mapping] = None
     ) -> pd.DataFrame:
         """
         Deserialize case data into a DataFrame.
@@ -172,8 +183,9 @@ def deserialize(
         ----------
         data : list of list or list of dict
             The context data.
-        columns : list of str
-            The case column mapping.
+        columns : Iterable of str
+            The case column mapping. The order corresponds to the order of cases in output.
+            `columns` must be provided for non-DataFrame Iterables.
 
             The order corresponds to how the data will be mapped to columns in
             the output. Ignored for list of dict where the dict key is the column
@@ -635,7 +647,7 @@ def format_unknown_column(cls, column: pd.Series, feature: Mapping
         return column
 
     @staticmethod
-    def _get_typing_info(feature: Optional[Mapping]) -> dict:
+    def _get_typing_info(feature: t.Optional[Mapping]) -> dict:
         """
         Get typing info from feature attributes.
 

Diff for: howso/utilities/installation_verification.py

@@ -14,7 +14,7 @@
 import random
 import sys
 import traceback
-from typing import Callable, Iterable, List, Optional, Tuple, Union
+import typing as t
 import warnings
 
 from faker.config import AVAILABLE_LOCALES
@@ -67,17 +67,17 @@ class Status(IntEnum):
     OK = 4
 
 
-Requirements = Iterable[Union[type, object]]
+Requirements = t.Iterable[t.Union[type, object]]
 
 
 @dataclass
 class Check:
     """Store the specification of a single check."""
 
     name: str
-    fn: Callable
-    client_required: Optional[str] = None
-    other_requirements: Optional[Requirements] = None
+    fn: t.Callable
+    client_required: t.Optional[str] = None
+    other_requirements: t.Optional[Requirements] = None
 
 
 class InstallationCheckRegistry:
@@ -106,9 +106,9 @@ def __init__(self):
         )
 
     def add_check(self, name: str,
-                  fn: Callable,
-                  client_required: Optional[str] = None,
-                  other_requirements: Optional[Requirements] = None
+                  fn: t.Callable,
+                  client_required: t.Optional[str] = None,
+                  other_requirements: t.Optional[Requirements] = None
                   ):
         """
         Add a check for this installation.
@@ -129,7 +129,7 @@ def add_check(self, name: str,
         """
         if (
             other_requirements and
-            not isinstance(other_requirements, Iterable)
+            not isinstance(other_requirements, t.Iterable)
         ):
             other_requirements = [other_requirements]
         self._checks.append(
@@ -167,8 +167,15 @@ def client(self) -> AbstractHowsoClient:
         return self._client
 
     @property
-    def client_classes(self) -> List[str]:
-        """Return list of super class names for the current cached client."""
+    def client_classes(self) -> list[str]:
+        """
+        Return list of super class names for the current cached client.
+
+        Returns
+        -------
+        list of class names
+        """
+
         if self._client is None:
             return []
         if self._client_classes == []:
@@ -460,8 +467,8 @@ def get_nonce(length=8) -> str:
 
 def generate_dataframe(*, client: AbstractHowsoClient,
                        num_samples: int = 150,
-                       timeout: Optional[int] = None
-                       ) -> Tuple[pd.DataFrame, Union[float, int]]:
+                       timeout: t.Optional[int] = None
+                       ) -> tuple[pd.DataFrame, float | int]:
     """
     Use HowsoClient to create a dataframe of random data.
 
@@ -582,7 +589,7 @@ def check_not_emulated(*, registry: InstallationCheckRegistry):
 
 
 def check_generate_dataframe(*, registry: InstallationCheckRegistry,
-                             threshold: Optional[float] = None):
+                             threshold: t.Optional[float] = None):
     """
     Rate the speed in which a dataframe was able to be generated.
 
@@ -696,7 +703,7 @@ def check_locales_available(*, registry: InstallationCheckRegistry):
 
 
 def check_save(*, registry: InstallationCheckRegistry,
-               source_df: Optional[pd.DataFrame] = None):
+               source_df: t.Optional[pd.DataFrame] = None):
     """
     Ensure that a model can can be saved.
 
@@ -745,7 +752,7 @@ def check_save(*, registry: InstallationCheckRegistry,
 
 
 def check_synthesizer_create_delete(*, registry: InstallationCheckRegistry,
-                                    source_df: Optional[pd.DataFrame] = None):
+                                    source_df: t.Optional[pd.DataFrame] = None):
     """
     Ensure that a model can can be created and deleted.
 
@@ -799,7 +806,7 @@ def check_synthesizer_create_delete(*, registry: InstallationCheckRegistry,
 
 
 def check_latency(*, registry: InstallationCheckRegistry,
-                  source_df: Optional[pd.DataFrame] = None,
+                  source_df: t.Optional[pd.DataFrame] = None,
                   notice_threshold: int = 10, warning_threshold: int = 20,
                   timeout: int = 10):
     """
@@ -922,7 +929,7 @@ def check_performance(*, registry: InstallationCheckRegistry,
 def check_engine_operation(
     *,
     registry: InstallationCheckRegistry,
-    source_df: Optional[pd.DataFrame] = None
+    source_df: t.Optional[pd.DataFrame] = None
 ):
     """
     Ensure that Howso Engine operates as it should.
@@ -991,7 +998,7 @@ def check_engine_operation(
 
 def check_validator_operation(
     *, registry: InstallationCheckRegistry,
-    source_df: Optional[pd.DataFrame] = None,
+    source_df: t.Optional[pd.DataFrame] = None,
 ):
     """
     Ensure that Validator-Enterprise operates as it should.