#212 Why Search (#223)

* #212 Savepoint

* #212 Savepoint

* #212 Prepare for versioned release

* #212 Savepoint

* #212 Update dependencies

* #212 Savepoint

* #212 Fix spacing

* Force re-test

Author: docktermj

CHANGELOG.md

@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning].
 
 ## [Unreleased]
 
+## [0.3.5] - 2025-04-16
+
+### Added in 0.3.5
+
+- `SzEngine.why_search`
+
 ## [0.3.4] - 2025-04-11
 
 ### Changed in 0.3.4

development-requirements.txt

@@ -15,7 +15,6 @@ sphinx-autodoc-typehints==3.1.0
 sphinx-gallery==0.19.0
 sphinx-jinja2-compat==0.3.0
 sphinx-prompt==1.9.0
-sphinxext-remoteliteralinclude==0.5.0
 sphinx-rtd-theme==3.0.2
 sphinx-tabs==3.4.7
 sphinx-toolbox==3.8.0
@@ -27,6 +26,7 @@ sphinxcontrib-jquery==4.1
 sphinxcontrib-jsmath==1.0.1
 sphinxcontrib-qthelp==2.0.0
 sphinxcontrib-serializinghtml==2.0.0
+sphinxext-remoteliteralinclude==0.5.0
 twine==6.1.0
 virtualenv==20.30.0
 wheel==0.46.1

examples/szengine/why_search.py

@@ -0,0 +1,29 @@
+#! /usr/bin/env python3
+
+import json
+
+from senzing import SzEngineFlags, SzError
+
+from senzing_core import SzAbstractFactoryCore
+
+ATTRIBUTES = json.dumps({"NAME_FULL": "BOB SMITH", "EMAIL_ADDRESS": "bsmith@work.com"})
+ENTITY_ID = 1
+FLAGS = SzEngineFlags.SZ_SEARCH_BY_ATTRIBUTES_DEFAULT_FLAGS
+INSTANCE_NAME = "Example"
+SEARCH_PROFILE = ""
+SETTINGS = {
+    "PIPELINE": {
+        "CONFIGPATH": "/etc/opt/senzing",
+        "RESOURCEPATH": "/opt/senzing/er/resources",
+        "SUPPORTPATH": "/opt/senzing/data",
+    },
+    "SQL": {"CONNECTION": "sqlite3://na:na@/tmp/sqlite/G2C.db"},
+}
+
+try:
+    sz_abstract_factory = SzAbstractFactoryCore(INSTANCE_NAME, SETTINGS)
+    sz_engine = sz_abstract_factory.create_engine()
+    RESULT = sz_engine.why_search(ATTRIBUTES, ENTITY_ID, FLAGS, SEARCH_PROFILE)
+    print(f"\n{RESULT}\n")
+except SzError as err:
+    print(f"\nERROR: {err}\n")

examples/szengine/why_search.txt

@@ -0,0 +1,20 @@
+// Output has been formatted for easier reading.
+{
+    "WHY_RESULTS": [
+        {
+            "ENTITY_ID": 1,
+            "MATCH_INFO": {
+                "WHY_KEY": "+PNAME+EMAIL",
+                "WHY_ERRULE_CODE": "SF1",
+                "MATCH_LEVEL_CODE": "POSSIBLY_RELATED"
+            }
+        }
+    ],
+    "ENTITIES": [
+        {
+            "RESOLVED_ENTITY": {
+                "ENTITY_ID": 1
+            }
+        }
+    ]
+}

requirements.txt

@@ -1,2 +1,2 @@
 orjson==3.10.16
-senzing==0.2.5
+senzing==0.2.6

setup.cfg

@@ -1,6 +1,6 @@
 [metadata]
 name = senzing_core
-version = 0.3.4
+version = 0.3.5
 author = senzing
 author_email = support@senzing.com
 description = Senzing Python SDK
@@ -21,7 +21,7 @@ package_dir =
 packages = find:
 python_requires = >=3.9
 install_requires =
-    senzing >= 0.2.2,<1.0.0
+    senzing >= 0.2.6,<1.0.0
 
 [options.packages.find]
 where = src

src/senzing_core/szabstractfactory.py

@@ -187,15 +187,15 @@ def reinitialize(self, config_id: int) -> None:
 
         if self.is_szengine_initialized:
             sz_engine = SzEngineCore()
-            sz_engine._reinitialize(config_id=config_id)  # pylint: disable=W0212
+            sz_engine.reinitialize(config_id=config_id)  # pylint: disable=W0212
 
         if self.is_szdiagnostic_initialized:
             sz_diagnostic = SzDiagnosticCore()
-            sz_diagnostic._reinitialize(config_id=config_id)  # pylint: disable=W0212
+            sz_diagnostic.reinitialize(config_id=config_id)  # pylint: disable=W0212
         if self.is_szengine_initialized:
             sz_engine = SzEngineCore()
-            sz_engine._reinitialize(config_id=config_id)  # pylint: disable=W0212
+            sz_engine.reinitialize(config_id=config_id)  # pylint: disable=W0212
 
         if self.is_szdiagnostic_initialized:
             sz_diagnostic = SzDiagnosticCore()
-            sz_diagnostic._reinitialize(config_id=config_id)  # pylint: disable=W0212
+            sz_diagnostic.reinitialize(config_id=config_id)  # pylint: disable=W0212

src/senzing_core/szdiagnostic.py

@@ -216,6 +216,11 @@ def purge_repository(self) -> None:
         self.check_result(result)
 
     @catch_non_sz_exceptions
-    def _reinitialize(self, config_id: int) -> None:
+    def reinitialize(self, config_id: int) -> None:
+        """
+        The `reinitialize` method reinitializes the Senzing object using a specific configuration
+        identifier. A list of available configuration identifiers can be retrieved using
+        `szconfigmanager.get_configs`.
+        """
         result = self.library_handle.SzDiagnostic_reinit(config_id)
         self.check_result(result)

src/senzing_core/szengine.py

@@ -215,6 +215,14 @@ class SzWhyRecordsV2Result(SzResponseReturnCodeResult):
     """In SzLang_helpers.h Sz_whyRecords_V2_result"""
 
 
+class SzWhySearchResult(SzResponseReturnCodeResult):
+    """In SzLang_helpers.h Sz_whyEntities_result"""
+
+
+class SzWhySearchV2Result(SzResponseReturnCodeResult):
+    """In SzLang_helpers.h Sz_whyEntities_V2_result"""
+
+
 # -----------------------------------------------------------------------------
 # SzEngineCore class
 # -----------------------------------------------------------------------------
@@ -503,6 +511,7 @@ def __init__(self, **kwargs: Any) -> None:
             c_char_p,
             c_longlong,
         ]
+        self.library_handle.Sz_whyRecords_V2_helper.restype = SzWhyRecordsV2Result
         self.library_handle.Sz_whyRecordInEntity_V2_helper.restype = SzWhyRecordInEntityV2Result
         self.library_handle.Sz_whyRecords_V2_helper.argtypes = [
             c_char_p,
@@ -511,7 +520,19 @@ def __init__(self, **kwargs: Any) -> None:
             c_char_p,
             c_longlong,
         ]
-        self.library_handle.Sz_whyRecords_V2_helper.restype = SzWhyRecordsV2Result
+        self.library_handle.Sz_whySearch_helper.restype = SzWhySearchResult
+        self.library_handle.Sz_whySearch_helper.argtypes = [
+            c_char_p,
+            c_longlong,
+            c_char_p,
+        ]
+        self.library_handle.Sz_whySearch_V2_helper.restype = SzWhySearchV2Result
+        self.library_handle.Sz_whySearch_V2_helper.argtypes = [
+            c_char_p,
+            c_longlong,
+            c_char_p,
+            c_longlong,
+        ]
         self.library_handle.SzHelper_free.argtypes = [c_void_p]
 
     def __del__(self) -> None:
@@ -976,7 +997,12 @@ def reevaluate_record(
         return self.no_info
 
     @catch_non_sz_exceptions
-    def _reinitialize(self, config_id: int) -> None:
+    def reinitialize(self, config_id: int) -> None:
+        """
+        The `reinitialize` method reinitializes the Senzing object using a specific configuration
+        identifier. A list of available configuration identifiers can be retrieved using
+        `szconfigmanager.get_configs`.
+        """
         result = self.library_handle.Sz_reinit(config_id)
         self.check_result(result)
 
@@ -1047,3 +1073,21 @@ def why_record_in_entity(
         with FreeCResources(self.library_handle, result.response):
             self.check_result(result.return_code)
             return as_python_str(result.response)
+
+    @catch_non_sz_exceptions
+    def why_search(
+        self,
+        attributes: str,
+        entity_id: int,
+        flags: int = SzEngineFlags.SZ_ENTITY_DEFAULT_FLAGS,
+        search_profile: str = "",
+    ) -> str:
+        result = self.library_handle.Sz_whySearch_V2_helper(
+            as_c_char_p(attributes),
+            entity_id,
+            as_c_char_p(search_profile),
+            flags,
+        )
+        with FreeCResources(self.library_handle, result.response):
+            self.check_result(result.return_code)
+            return as_python_str(result.response)

tests/szabstractfactory_test.py

@@ -1,3 +1,10 @@
+#! /usr/bin/env python3
+
+"""
+TODO: szabstractfactory_test.py
+"""
+
+
 from datetime import datetime
 from typing import Any, Dict
 
@@ -13,42 +20,51 @@
 from senzing_core import SzAbstractFactoryCore
 
 # -----------------------------------------------------------------------------
-# Testcases
+# Test cases
 # -----------------------------------------------------------------------------
 
 
-def test_create_configmanager(sz_abstract_factory: SzAbstractFactory) -> None:
-    """Create SzConfigManager."""
-    actual = sz_abstract_factory.create_configmanager()
+def test_create_configmanager(sz_abstractfactory: SzAbstractFactory) -> None:
+    """Test SzAbstractFactory.create_configmanager()."""
+    actual = sz_abstractfactory.create_configmanager()
     assert isinstance(actual, SzConfigManager)
 
 
-def test_create_diagnostic(sz_abstract_factory: SzAbstractFactory) -> None:
-    """Create SzDiagnostic."""
-    actual = sz_abstract_factory.create_diagnostic()
+def test_create_diagnostic(sz_abstractfactory: SzAbstractFactory) -> None:
+    """Test SzAbstractFactory.create_diagnostic()."""
+    actual = sz_abstractfactory.create_diagnostic()
     assert isinstance(actual, SzDiagnostic)
 
 
-def test_create_engine(sz_abstract_factory: SzAbstractFactory) -> None:
-    """Create SzEngine."""
-    actual = sz_abstract_factory.create_engine()
+def test_create_engine(sz_abstractfactory: SzAbstractFactory) -> None:
+    """Test SzAbstractFactory.create_engine()."""
+    actual = sz_abstractfactory.create_engine()
     assert isinstance(actual, SzEngine)
 
 
-def test_create_product(sz_abstract_factory: SzAbstractFactory) -> None:
-    """Create SzProduct."""
-    actual = sz_abstract_factory.create_product()
+def test_create_product(sz_abstractfactory: SzAbstractFactory) -> None:
+    """Test SzAbstractFactory.create_product()."""
+    actual = sz_abstractfactory.create_product()
     assert isinstance(actual, SzProduct)
 
 
-def test_reinitialize(sz_abstract_factory: SzAbstractFactory) -> None:
-    """Create SzConfig."""
+def test_help_1(sz_abstractfactory: SzAbstractFactory) -> None:
+    """Test SzAbstractFactory.help()."""
+    sz_abstractfactory.help()
+
+
+def test_help_2(sz_abstractfactory: SzAbstractFactory) -> None:
+    """Test SzAbstractFactory.help(...)."""
+    sz_abstractfactory.help("create_configmanager")
+
 
+def test_reinitialize(sz_abstractfactory: SzAbstractFactory) -> None:
+    """Test SzAbstractFactory.reinitialize()."""
     datasources = [f"TEST_DATASOURCE_{datetime.now().timestamp()}"]
 
     # Create Senzing objects.
 
-    sz_configmanager = sz_abstract_factory.create_configmanager()
+    sz_configmanager = sz_abstractfactory.create_configmanager()
     sz_config = sz_configmanager.create_config_from_template()
 
     # Add DataSources to Senzing configuration.
@@ -63,7 +79,7 @@ def test_reinitialize(sz_abstract_factory: SzAbstractFactory) -> None:
 
     # Update other Senzing objects.
 
-    sz_abstract_factory.reinitialize(config_id)
+    sz_abstractfactory.reinitialize(config_id)
 
 
 # -----------------------------------------------------------------------------
@@ -76,10 +92,10 @@ def test_reinitialize(sz_abstract_factory: SzAbstractFactory) -> None:
 # -----------------------------------------------------------------------------
 
 
-@pytest.fixture(name="sz_abstract_factory", scope="function")
-def sz_abstract_factory_fixture(engine_vars: Dict[Any, Any]) -> SzAbstractFactory:
+@pytest.fixture(name="sz_abstractfactory", scope="function")
+def szabstractfactory_fixture(engine_vars: Dict[Any, Any]) -> SzAbstractFactory:
     """
-    Single SzAbstractFactoryCore object to use for all tests.
+    SzAbstractFactory object to use for all tests.
     """
 
     factory_parameters = {