#205 Add WhySearch (#217)

* #205 Initial draft

* #205 Savepoint

* #205 Savepoint

* #205 Prepare for versioned release

Author: docktermj

CHANGELOG.md

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

docs/source/_static/.placeholder.txt

@@ -0,0 +1,15 @@
+import json
+
+from senzing import SzEngineFlags, SzError
+
+from . import sz_engine
+
+try:
+    attributes = json.dumps({"NAME_FULL": "BOB SMITH", "EMAIL_ADDRESS": "bsmith@work.com"})
+    ENTITY_ID = 1
+    flags = SzEngineFlags.SZ_SEARCH_BY_ATTRIBUTES_DEFAULT_FLAGS
+    SEARCH_PROFILE = "SEARCH"
+    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.py

@@ -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
+            }
+        }
+    ]
+}

examples/szengine/why_search.txt

@@ -1,6 +1,6 @@
 [metadata]
 name = senzing
-version = 0.2.5
+version = 0.2.6
 author = senzing
 author_email = support@senzing.com
 description = Python SDK method definitions

setup.cfg

@@ -932,6 +932,42 @@ def why_records(
                     :language: json
         """
 
+    @abstractmethod
+    def why_search(
+        self,
+        attributes: str,
+        entity_id: int,
+        flags: int = SzEngineFlags.SZ_SEARCH_BY_ATTRIBUTES_DEFAULT_FLAGS,
+        search_profile: str = "",
+    ) -> str:
+        """
+        The `why_search` method retrieves entity data based on a specific entity Id and a
+        user-specified set of entity attributes.
+
+        Args:
+            attributes (str): A JSON document with the attribute data to search for.
+            entity_id (int): The identifier of the entity to retrieve.
+            flags (int, optional): _description_. Defaults to SzEngineFlags.SZ_SEARCH_BY_ATTRIBUTES_DEFAULT_FLAGS.
+            search_profile (str): The name of a configured search profile. Defaults to SEARCH.
+
+        Returns:
+            str: A JSON document.
+
+        Raises:
+
+        .. collapse:: Example:
+
+            .. literalinclude:: ../../examples/szengine/why_search.py
+                :linenos:
+                :language: python
+
+            **Output:**
+
+            .. literalinclude:: ../../examples/szengine/why_search.txt
+                :linenos:
+                :language: json
+        """
+
     # -------------------------------------------------------------------------
     # Convenience methods
     # -------------------------------------------------------------------------

src/senzing/szengine.py

@@ -328,6 +328,15 @@ def why_records(
     ) -> str:
         return ""
 
+    def why_search(
+        self,
+        attributes: str,
+        entity_id: int,
+        flags: int = SzEngineFlags.SZ_SEARCH_BY_ATTRIBUTES_DEFAULT_FLAGS,
+        search_profile: str = "",
+    ) -> str:
+        return ""
+
 
 # -----------------------------------------------------------------------------
 # SzProductMock class

src/senzing_mock/senzing_mock.py

@@ -4,7 +4,6 @@
 TODO: szabstractfactory_test.py
 """
 
-
 import pytest
 
 from senzing import (
@@ -17,55 +16,55 @@
 from senzing_mock import SzAbstractFactoryMock
 
 # -----------------------------------------------------------------------------
-# SzAbstractFactory testcases
+# Test cases
 # -----------------------------------------------------------------------------
 
 
-def test_create_configmanager(szabstractfactory: SzAbstractFactory) -> None:
+def test_create_configmanager(sz_abstractfactory: SzAbstractFactory) -> None:
     """Test SzAbstractFactory.create_configmanager()."""
-    actual = szabstractfactory.create_configmanager()
+    actual = sz_abstractfactory.create_configmanager()
     assert isinstance(actual, SzConfigManager)
 
 
-def test_create_diagnostic(szabstractfactory: SzAbstractFactory) -> None:
+def test_create_diagnostic(sz_abstractfactory: SzAbstractFactory) -> None:
     """Test SzAbstractFactory.create_diagnostic()."""
-    actual = szabstractfactory.create_diagnostic()
+    actual = sz_abstractfactory.create_diagnostic()
     assert isinstance(actual, SzDiagnostic)
 
 
-def test_create_engine(szabstractfactory: SzAbstractFactory) -> None:
+def test_create_engine(sz_abstractfactory: SzAbstractFactory) -> None:
     """Test SzAbstractFactory.create_engine()."""
-    actual = szabstractfactory.create_engine()
+    actual = sz_abstractfactory.create_engine()
     assert isinstance(actual, SzEngine)
 
 
-def test_create_product(szabstractfactory: SzAbstractFactory) -> None:
+def test_create_product(sz_abstractfactory: SzAbstractFactory) -> None:
     """Test SzAbstractFactory.create_product()."""
-    actual = szabstractfactory.create_product()
+    actual = sz_abstractfactory.create_product()
     assert isinstance(actual, SzProduct)
 
 
-def test_help_1(szabstractfactory: SzAbstractFactory) -> None:
-    """Test SzAbstractFactory().help()."""
-    szabstractfactory.help()
+def test_help_1(sz_abstractfactory: SzAbstractFactory) -> None:
+    """Test SzAbstractFactory.help()."""
+    sz_abstractfactory.help()
 
 
-def test_help_2(szabstractfactory: SzAbstractFactory) -> None:
-    """Test SzAbstractFactory().help(...)."""
-    szabstractfactory.help("create_configmanager")
+def test_help_2(sz_abstractfactory: SzAbstractFactory) -> None:
+    """Test SzAbstractFactory.help(...)."""
+    sz_abstractfactory.help("create_configmanager")
 
 
-def test_reinitialize(szabstractfactory: SzAbstractFactory) -> None:
+def test_reinitialize(sz_abstractfactory: SzAbstractFactory) -> None:
     """Test SzAbstractFactory.reinitialize()."""
-    szabstractfactory.reinitialize(0)
+    sz_abstractfactory.reinitialize(0)
 
 
 # -----------------------------------------------------------------------------
-# SzAbstractFactory fixtures
+# Fixtures
 # -----------------------------------------------------------------------------
 
 
-@pytest.fixture(name="szabstractfactory", scope="module")
+@pytest.fixture(name="sz_abstractfactory", scope="function")
 def szabstractfactory_fixture() -> SzAbstractFactory:
     """
     Single sz_abstractfactory object to use for all tests.

tests/szabstractfactory_test.py

@@ -4,7 +4,6 @@
 TODO: szconfig_test.py
 """
 
-
 import pytest
 
 from senzing import SzConfig
@@ -36,17 +35,17 @@ def test_get_data_sources(sz_config: SzConfig) -> None:
 
 
 def test_help_1(sz_config: SzConfig) -> None:
-    """Test SzConfig().help()."""
+    """Test SzConfig.help()."""
     sz_config.help()
 
 
 def test_help_2(sz_config: SzConfig) -> None:
-    """Test SzConfig().help(...)."""
+    """Test SzConfig.help(...)."""
     sz_config.help("add_data_source")
 
 
 # -----------------------------------------------------------------------------
-# szConfig fixtures
+# Fixtures
 # -----------------------------------------------------------------------------
 
 

tests/szconfig_test.py

@@ -20,13 +20,13 @@ def test_create_config_from_config_id(sz_configmanager: SzConfigManager) -> None
     sz_configmanager.create_config_from_config_id(0)
 
 
-def test_create_config_from_config_string(sz_configmanager: SzConfigManager) -> None:
-    """Test SzConfigManager.create_config_from_config_string()."""
+def test_create_config_from_string(sz_configmanager: SzConfigManager) -> None:
+    """Test SzConfigManager.create_config_from_string()."""
     sz_configmanager.create_config_from_string("")
 
 
-def test_create_config_from_config_template(sz_configmanager: SzConfigManager) -> None:
-    """Test SzConfigManager.create_config_from_config_string()."""
+def test_create_config_from_template(sz_configmanager: SzConfigManager) -> None:
+    """Test SzConfigManager.create_config_from_template()."""
     sz_configmanager.create_config_from_template()
 
 
@@ -41,17 +41,17 @@ def test_get_default_config_id(sz_configmanager: SzConfigManager) -> None:
 
 
 def test_help_1(sz_configmanager: SzConfigManager) -> None:
-    """Test SzConfigManager().help()."""
+    """Test SzConfigManager.help()."""
     sz_configmanager.help()
 
 
 def test_help_2(sz_configmanager: SzConfigManager) -> None:
-    """Test SzConfigManager().help(...)."""
+    """Test SzConfigManager.help(...)."""
     sz_configmanager.help("register_config")
 
 
 def test_register_config(sz_configmanager: SzConfigManager) -> None:
-    """Test SzConfigManager.add_config()."""
+    """Test SzConfigManager.register_config()."""
     sz_configmanager.register_config("", "")
 
 
@@ -71,7 +71,7 @@ def test_set_default_config_id(sz_configmanager: SzConfigManager) -> None:
 
 
 # -----------------------------------------------------------------------------
-# SzConfigManager fixtures
+# Fixtures
 # -----------------------------------------------------------------------------