118 ant 1 (#119)

* #118 - Save point

* #118 - Save point

* #118 - Save point

* #118 - Save point

* #118 - Save point

* #118 - Save point

* #118 - Save point

* #118 - Update setup and changelog

Author: antaenc

CHANGELOG.md

@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning].
 
 ## [Unreleased]
 
+## [0.2.1] - 2024-11-22
+
+### Added in 0.2.1.
+
+- Improvements to helpers 
+
 ## [0.2.0] - 2024-11-04
 
 ### Deleted in 0.2.0.

setup.cfg

@@ -1,6 +1,6 @@
 [metadata]
 name = senzing_core
-version = 0.2.0
+version = 0.2.1
 author = senzing
 author_email = support@senzing.com
 description = Python SDK for Senzing API

src/senzing/_helpers.py

@@ -10,9 +10,9 @@
 
 import json
 import os
-import re
 import sys
 import threading
+from contextlib import suppress
 from ctypes import (
     CDLL,
     POINTER,
@@ -29,7 +29,7 @@
 from ctypes.util import find_library
 from functools import wraps
 from types import TracebackType
-from typing import Any, Callable, Dict, List, Optional, Type, TypeVar, Union
+from typing import Any, Callable, Dict, List, Optional, Tuple, Type, TypeVar, Union
 
 from senzing_abstract import ENGINE_EXCEPTION_MAP
 
@@ -82,54 +82,63 @@ def __exit__(
 # -----------------------------------------------------------------------------
 
 
-# TODO Not just catching ctypes exceptions, now also catching entity/record json building exceptions
-# TODO Check functions without try/except are caught by this
-def catch_exceptions(func_to_decorate: Callable[P, T]) -> Callable[P, T]:
+def catch_non_sz_exceptions(func_to_decorate: Callable[P, T]) -> Callable[P, T]:
     """
-    # TODO
+    The Python SDK methods convert Python types to ctypes and utilize helper functions. If incorrect types/values are
+    used standard library exceptions are raised not SzError based exceptions as the Senzing library hasn't been called
+    yet. Raise the original Python exception type and append information to identify the SDK method called, accepted
+    arguments & types and the arguments and types the SDK method received.
 
     :meta private:
     """
 
     @wraps(func_to_decorate)
-    def catch_inner(*args: P.args, **kwargs: P.kwargs) -> T:
-        method_name = func_to_decorate.__name__
-        module_name = func_to_decorate.__module__
-        basic_msg = f"wrong type for an argument when calling {module_name}.{method_name}"
-
+    def wrapped_func(*args: P.args, **kwargs: P.kwargs) -> T:  # pylint: disable=too-many-locals
         try:
             return func_to_decorate(*args, **kwargs)
-        except ArgumentError as err:
-            # Checking can find the information from ctypes.Argument error, works currently but could change in future?
-            # If can locate what we are looking for from ctypes.ArgumentError, give a more detailed and useful exception message
-            # Current message from ctypes: ctypes.ArgumentError: argument 2: TypeError: wrong type
-            bad_arg_match = None
-            if err.args:
-                bad_arg_match = re.match(r"argument (\d+):", err.args[0])
-
-            if bad_arg_match:
-                bad_arg_index = bad_arg_match.group(1)
-                try:
-                    bad_arg_index = int(bad_arg_index)
-                    bad_arg_value = args[bad_arg_index]
-                    bad_arg_type = type(bad_arg_value)
-                    bad_arg_tuple = list(func_to_decorate.__annotations__.items())[bad_arg_index - 1]
-                except (IndexError, ValueError):
-                    raise TypeError(basic_msg) from err
-
-                if len(bad_arg_tuple) != 2:
-                    raise TypeError(basic_msg) from err
-
-                raise TypeError(
-                    f"wrong type for argument {bad_arg_tuple[0]}, expected {bad_arg_tuple[1]} but received {bad_arg_type.__name__} when calling {module_name}.{method_name}"
-                ) from None
-
-            raise TypeError(basic_msg) from err
-        # NOTE Catch TypeError from the test in as_uintptr_t()
-        except TypeError as err:
-            raise TypeError(f"{basic_msg} - {err}") from None
-
-    return catch_inner
+        # ctypes.ArgumentError from converting python types to ctypes before call to Senzing library
+        except (ArgumentError, TypeError, ValueError, json.JSONDecodeError) as err:
+            annotations_dict = func_to_decorate.__annotations__
+
+            # Remove kwargs and return type, not needed initially
+            with suppress(KeyError):
+                del annotations_dict["return"]
+                del annotations_dict["kwargs"]
+
+            # Get the wrapped functions argument names and types and build a string of accepted arguments and types
+            func_arg_names, func_arg_types = zip(*annotations_dict.items())
+            func_zip = list(zip(func_arg_names, func_arg_types))
+            accepts = ", ".join(
+                [f"{tup[0]}: {tup[1] if isinstance(tup[1], str) else tup[1].__name__}" for tup in func_zip]
+            )
+
+            # Get the values of the arguments received by the wrapped function and build a string of received arguments
+            # and types
+            received_arg_values = list(args[1:])
+            # If no kwargs, arguments are in order of the wrapped function signature, get the first x argument names
+            if received_arg_values and not kwargs:
+                func_arg_names = func_arg_names[: len(received_arg_values)]
+
+            if kwargs:
+                kwargs_arg_names, kwargs_arg_values = zip(*kwargs.items())
+                # First get the names of all required arguments
+                non_default_args: Tuple[Any] = func_to_decorate.__defaults__ if func_to_decorate.__defaults__ else ()
+                func_arg_names = func_arg_names[: len(func_arg_names) - len(non_default_args)]
+                # Add any kwarg arguments to the set of function arguments names
+                func_arg_names = func_arg_names + kwargs_arg_names
+                # Add the value of the kwargs
+                received_arg_values.extend(list(kwargs_arg_values))
+            arg_zip = list(zip(func_arg_names, received_arg_values))
+            received = ", ".join([f"{tup[0]}: {type(tup[1]).__name__}" for tup in arg_zip])
+
+            err_msg = f"{err} - {func_to_decorate.__module__}.{func_to_decorate.__name__} accepts - {accepts} - but received - {received}"
+
+            # Convert ctypes ArgumentError to a TypeError for simplicity, a user shouldn't need ctypes in their code
+            err_class = TypeError if err.__class__.__name__ == "ArgumentError" else err.__class__
+
+            raise err_class(err_msg) from err
+
+    return wrapped_func
 
 
 # -----------------------------------------------------------------------------
@@ -153,7 +162,7 @@ def load_sz_library(lib: str = "") -> CDLL:
             f"ERROR: Unable to load the Senzing library: {err}\n"
             "ERROR: Did you remember to setup your environment by sourcing the setupEnv file?\n"
             "ERROR: For more information: https://senzing.zendesk.com/hc/en-us/articles/115002408867-Introduction-G2-Quickstart\n"
-            "ERROR: If you are running Ubuntu or Debian also review the ssl and crypto information at https://senzing.zendesk.com/hc/en-us/articles/115010259947-System-Requirements\n",
+            "ERROR: If you are running Ubuntu or Debian also review the ssl and crypto information at https://senzing.zendesk.com/hc/en-us/articles/115010259947-System-Requirements",
         )
         raise sdk_exception(1) from err
 
@@ -187,45 +196,6 @@ def check_result_rc(
 # -----------------------------------------------------------------------------
 
 
-def check_type_is_list(to_check: Any) -> None:
-    """
-    Check the input type is a list, if not raise TypeError.
-
-    :meta private:
-    """
-    if not isinstance(to_check, list):
-        raise TypeError(f"expected type list, got {type(to_check).__name__}")
-
-
-def check_list_types(to_check: List[Any]) -> None:
-    """
-    Check the elements of a list for:
-        - All the same type
-        - If a list of tuples
-            - The number of elements in each tuple is the same
-            - The number of elements in each tuple is of the expected size
-
-    :meta private:
-    """
-    if not to_check:
-        return
-
-    # Check all elements in the list are of the same type
-    types = all(isinstance(elem, type(to_check[0])) for elem in to_check[1:])
-    if not types:
-        raise TypeError(f"elements in the list are not of the same type - {to_check}")
-
-    # If elements are tuples check they are the same size and correct size
-    if isinstance(to_check[0], tuple):
-        num_elements = set(len(elem) for elem in to_check)
-        if len(num_elements) > 1:
-            raise TypeError(f"number of tuple elements for each tuple are not of the same size - {to_check}")
-
-        number_of_tuples = num_elements.pop()
-        if number_of_tuples != 2:
-            raise TypeError(f"number of elements in a tuple is {number_of_tuples}, expected 2 - {to_check}")
-
-
 # TODO - Investigate adding and recalling is working correctly
 def escape_json_str(to_escape: str) -> str:
     """
@@ -234,7 +204,9 @@ def escape_json_str(to_escape: str) -> str:
     :meta private:
     """
     if not isinstance(to_escape, str):
-        raise TypeError(f"expected a str, got{to_escape}")
+        # TODO - Ant -
+        raise TypeError("expected a str")
+    # return to_escape
     # TODO ensure_ascii=False = èAnt\\n👍
     # TODO             =True  = \\u00e8Ant\\n\\ud83d\\udc4d'
     # print(f"{to_escape=}")
@@ -247,7 +219,9 @@ def build_dsrc_code_json(dsrc_code: str) -> str:
     """
     Build JSON string of single data source code.
 
-    {"DSRC_CODE": "CUSTOMERS"}
+    Input: CUSTOMERS
+
+    Output: {"DSRC_CODE": "CUSTOMERS"}
 
     :meta private:
     """
@@ -258,56 +232,65 @@ def build_data_sources_json(dsrc_codes: list[str]) -> str:
     """
     Build JSON string of data source codes.
 
-    {"DATA_SOURCES": ["REFERENCE", "CUSTOMERS"]}'
+    Input: ["REFERENCE", "CUSTOMERS"]
+
+    Output: {"DATA_SOURCES": ["REFERENCE", "CUSTOMERS"]}'
 
     :meta private:
     """
-    check_type_is_list((dsrc_codes))
-    check_list_types(dsrc_codes)
-    dsrcs = ", ".join([f"{escape_json_str(code)}" for code in dsrc_codes])
+
+    try:
+        dsrcs = ", ".join([f"{escape_json_str(code)}" for code in dsrc_codes])
+    except (TypeError, ValueError) as err:
+        raise err.__class__(err)
+
     return f"{START_DSRC_JSON}{dsrcs}{END_JSON}"
 
 
 def build_entities_json(entity_ids: Union[List[int], None]) -> str:
     """
     Build JSON string of entity ids.
 
-    {"ENTITIES": [{"ENTITY_ID": 1}, {"ENTITY_ID": 100002}]}
+    Input: [1, 100002]
+
+    Output: {"ENTITIES": [{"ENTITY_ID": 1}, {"ENTITY_ID": 100002}]}
 
     :meta private:
     """
-    # NOTE This is needed if required_data_sources is sent to find_path_*, avoid_* could
-    # NOTE be set to None (default) or []
-    if not entity_ids or len(entity_ids) == 0:
+    if not entity_ids or (isinstance(entity_ids, list) and len(entity_ids) == 0):
         return ""
 
-    check_type_is_list(entity_ids)
-    check_list_types(entity_ids)
-    entities = ", ".join([f'{{"ENTITY_ID": {id}}}' for id in entity_ids])
+    try:
+        entities = ", ".join([f'{{"ENTITY_ID": {id}}}' for id in entity_ids])
+    except (TypeError, ValueError) as err:
+        raise err.__class__(err)
+
     return f"{START_ENTITIES_JSON}{entities}{END_JSON}"
 
 
 def build_records_json(record_keys: Union[List[tuple[str, str]], None]) -> str:
     """
     Build JSON string of data source and record ids.
 
-    {"RECORDS":[{"DATA_SOURCE":"CUSTOMERS","RECORD_ID":"1001"},{"DATA_SOURCE":"WATCHLIST","RECORD_ID":"1007"}]}
+    From: [("CUSTOMERS", "1001"), ("WATCHLIST", 1007)]
+
+    To: {"RECORDS":[{"DATA_SOURCE":"CUSTOMERS","RECORD_ID":"1001"},{"DATA_SOURCE":"WATCHLIST","RECORD_ID":"1007"}]}
 
     :meta private:
     """
-    # NOTE This is needed if required_data_sources is sent to find_path_*, avoid_* could
-    # NOTE be set to None (default) or []
-    if not record_keys or len(record_keys) == 0:
+    if not record_keys or (isinstance(record_keys, list) and len(record_keys) == 0):
         return ""
 
-    check_type_is_list(record_keys)
-    check_list_types(record_keys)
-    records = ", ".join(
-        [
-            f'{{"DATA_SOURCE": {escape_json_str(ds)}, "RECORD_ID": {escape_json_str(rec_id)}}}'
-            for ds, rec_id in record_keys
-        ]
-    )
+    try:
+        records = ", ".join(
+            [
+                f'{{"DATA_SOURCE": {escape_json_str(ds)}, "RECORD_ID": {escape_json_str(rec_id)}}}'
+                for ds, rec_id in record_keys
+            ]
+        )
+    except (TypeError, ValueError) as err:
+        raise err.__class__(err)
+
     return f"{START_RECORDS_JSON}{records}{END_JSON}"
 
 
@@ -428,7 +411,7 @@ def engine_exception(
     get_last_exception_code: Callable[[], int],
 ) -> Exception:
     """
-    Generate a new Senzing Exception based on the SDK product_id & error_id.
+    Generate a Senzing error.
 
     :meta private:
     """

src/senzing/szconfig.py

@@ -29,7 +29,7 @@
     as_python_str,
     as_str,
     build_dsrc_code_json,
-    catch_exceptions,
+    catch_non_sz_exceptions,
     check_result_rc,
     load_sz_library,
 )
@@ -184,7 +184,7 @@ def __del__(self) -> None:
     # SzConfig methods
     # -------------------------------------------------------------------------
 
-    @catch_exceptions
+    @catch_non_sz_exceptions
     def add_data_source(
         self,
         config_handle: int,
@@ -200,7 +200,7 @@ def add_data_source(
             self.check_result(result.return_code)
             return as_python_str(result.response)
 
-    @catch_exceptions
+    @catch_non_sz_exceptions
     def close_config(self, config_handle: int, **kwargs: Any) -> None:
         result = self.library_handle.SzConfig_close_helper(as_c_uintptr_t(config_handle))
         self.check_result(result)
@@ -210,7 +210,7 @@ def create_config(self, **kwargs: Any) -> int:
         self.check_result(result.return_code)
         return result.response  # type: ignore[no-any-return]
 
-    @catch_exceptions
+    @catch_non_sz_exceptions
     def delete_data_source(
         self,
         config_handle: int,
@@ -226,21 +226,21 @@ def delete_data_source(
     def _destroy(self, **kwargs: Any) -> None:
         _ = self.library_handle.SzConfig_destroy()
 
-    @catch_exceptions
+    @catch_non_sz_exceptions
     def export_config(self, config_handle: int, **kwargs: Any) -> str:
         result = self.library_handle.SzConfig_save_helper(as_c_uintptr_t(config_handle))
         with FreeCResources(self.library_handle, result.response):
             self.check_result(result.return_code)
             return as_python_str(result.response)
 
-    @catch_exceptions
+    @catch_non_sz_exceptions
     def get_data_sources(self, config_handle: int, **kwargs: Any) -> str:
         result = self.library_handle.SzConfig_listDataSources_helper(as_c_uintptr_t(config_handle))
         with FreeCResources(self.library_handle, result.response):
             self.check_result(result.return_code)
             return as_python_str(result.response)
 
-    @catch_exceptions
+    @catch_non_sz_exceptions
     def _initialize(
         self,
         instance_name: str,
@@ -255,7 +255,7 @@ def _initialize(
         )
         self.check_result(result)
 
-    @catch_exceptions
+    @catch_non_sz_exceptions
     def import_config(self, config_definition: str, **kwargs: Any) -> int:
         result = self.library_handle.SzConfig_load_helper(as_c_char_p(config_definition))
         self.check_result(result.return_code)