#298 Update documentation (#332)

* #298 Update szconfig.py

* #298 Update szconfigmanager.py

* #298 Update szdiagnostic.py and szproduct.py

* 298 Update version, date, update

* 298 Update szengine

* #298 Update descriptions

* #298 Update descriptions

* #298 Update version to 4.0.0

* #298 Update version to 4.0.0

* #298 Update version to 4.0.0

* #298 Fix documentation

---------

Co-authored-by: antaenc <28313221+antaenc@users.noreply.github.com>

Author: docktermj

CHANGELOG.md

@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning].
 
 ## [Unreleased]
 
+## [4.0.0] - 2025-08-05
+
+### Changed in 4.0.0
+
+- For use with Senzing v4
+
 ## [0.2.20] - 2025-07-19
 
 ### Changed in 0.2.20

setup.cfg

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

src/senzing/constants.py

@@ -15,9 +15,9 @@
     "SZ_VERBOSE_LOGGING",
     "SZ_WITHOUT_INFO",
 ]
-__version__ = "0.0.1"  # See https://www.python.org/dev/peps/pep-0396/
-__date__ = "2023-10-30"
-__updated__ = "2023-10-30"
+__version__ = "4.0.0"
+__date__ = "2025-08-05"
+__updated__ = "2025-08-05"
 
 # -----------------------------------------------------------------------------
 # Constant helper values useful for flags

src/senzing/szabstractfactory.py

@@ -24,9 +24,9 @@
 # Metadata
 
 __all__ = ["SzAbstractFactory"]
-__version__ = "0.0.1"  # See https://www.python.org/dev/peps/pep-0396/
-__date__ = "2024-09-23"
-__updated__ = "2025-01-28"
+__version__ = "4.0.0"
+__date__ = "2025-08-05"
+__updated__ = "2025-08-05"
 
 
 # -----------------------------------------------------------------------------

src/senzing/szconfig.py

@@ -13,9 +13,9 @@
 # Metadata
 
 __all__ = ["SzConfig"]
-__version__ = "0.0.1"  # See https://www.python.org/dev/peps/pep-0396/
-__date__ = "2023-10-30"
-__updated__ = "2025-01-28"
+__version__ = "4.0.0"
+__date__ = "2025-08-05"
+__updated__ = "2025-08-05"
 
 # -----------------------------------------------------------------------------
 # SzConfig
@@ -89,6 +89,9 @@ def register_data_source(self, data_source_code: str) -> str:
         """
         The `register_data_source` method adds a data source to this configuration.
 
+        Because SzConfig is an in-memory representation, the repository is not changed
+        unless the configuration is exported and then registered via ConfigManager.
+
         Args:
             data_source_code (str): Name of data source code to add.
 
@@ -116,6 +119,14 @@ def unregister_data_source(self, data_source_code: str) -> str:
         """
         The `unregister_data_source` method removes a data source from this configuration.
 
+        Because SzConfig is an in-memory representation, the repository is not changed unless
+        the configuration is exported and then registered via ConfigManager.
+
+        Is idempotent.
+
+        Warning: If records in the repository refer to the unregistered datasource,
+        the configuration cannot be used as the active configuration.
+
         Args:
             data_source_code (str): Name of data source code to delete.
 

src/senzing/szconfigmanager.py

@@ -14,9 +14,9 @@
 # Metadata
 
 __all__ = ["SzConfigManager"]
-__version__ = "0.0.1"  # See https://www.python.org/dev/peps/pep-0396/
-__date__ = "2023-10-30"
-__updated__ = "2023-11-08"
+__version__ = "4.0.0"
+__date__ = "2025-08-05"
+__updated__ = "2025-08-05"
 
 # -----------------------------------------------------------------------------
 # SzConfigManager
@@ -93,8 +93,6 @@ def create_config_from_template(self) -> SzConfig:
         The `create_config_from_template` method creates a new SzConfig instance from the template
         configuration definition.
 
-        The template configuration is located at PIPELINE.RESOURCEPATH/templates/g2config.json
-
         Args:
             config_definition (str): The Senzing configuration JSON document.
 
@@ -122,6 +120,11 @@ def get_config_registry(self) -> str:
         """
         The `get_config_registry` method gets the configuration registry.
 
+        The registry contains the original timestamp, original comment, and configuration ID
+        of all configurations ever registered with the repository.
+
+        Registered configurations cannot be unregistered.
+
         Returns:
             str: A JSON document containing Senzing configurations.
 
@@ -146,8 +149,12 @@ def get_default_config_id(self) -> int:
         """
         The `get_default_config_id` method gets the default configuration ID for the repository.
 
+        Unless an explicit configuration ID is specified at initialization, the default configuration ID is used.
+
+        This may not be the same as the active configuration ID.
+
         Returns:
-            int:  A configuration identifier which identifies the current configuration in use.
+            int:  The current default configuration ID or zero if the default configuration has not been set.
 
         Raises:
             TypeError: Incorrect datatype of input parameter.
@@ -170,6 +177,10 @@ def register_config(self, config_definition: str, config_comment: str) -> int:
         """
         The `register_config` method registers a configuration definition in the repository.
 
+        Registered configurations do not become immediately active nor do they become the default.
+
+        Registered configurations cannot be unregistered.
+
         Args:
             config_definition (str): The Senzing configuration JSON document.
             config_comment (str):  free-form string of comments describing the configuration document.
@@ -199,9 +210,9 @@ def replace_default_config_id(self, current_default_config_id: int, new_default_
         The `replace_default_config_id` method replaces the existing default configuration ID with
         a new configuration ID.
 
-        It is like a "compare-and-swap" instruction to serialize concurrent editing of configuration.
-        If `current_default_config_id` is no longer the "current configuration identifier", the operation will fail.
-        To simply set the default configuration ID, use `set_default_config_id`.
+        The change is prevented if the current default configuration ID value is not as expected.
+
+        Use this in place of set_default_config_id() to handle race conditions.
 
         Args:
             current_default_config_id (int): The configuration identifier to replace.
@@ -223,7 +234,7 @@ def set_default_config(self, config_definition: str, config_comment: str) -> int
         The `set_default_config` method registers a configuration in the repository and sets its ID as the default
         for the repository.
 
-        To serialize modifying of the configuration identifier, see `replace_default_config_id`.
+        Convenience method for register_config() followed by set_default_config_id().
 
         Args:
             config_definition (str): The Senzing configuration JSON document.
@@ -250,7 +261,9 @@ def set_default_config_id(self, config_id: int) -> None:
         """
         The `set_default_config_id` method sets the default configuration ID.
 
-        To serialize modifying of the configuration identifier, see `replace_default_config_id`.
+        Usually this method is sufficient for setting the default configuration ID.
+        However in concurrent environments that could encounter race conditions,
+        consider using replace_default_config_id() instead.
 
         Args:
             config_id (int): The configuration identifier of the Senzing Engine configuration to use as the default.

src/senzing/szdiagnostic.py

@@ -11,9 +11,9 @@
 # Metadata
 
 __all__ = ["SzDiagnostic"]
-__version__ = "0.0.1"  # See https://www.python.org/dev/peps/pep-0396/
-__date__ = "2023-10-30"
-__updated__ = "2025-01-28"
+__version__ = "4.0.0"
+__date__ = "2025-08-05"
+__updated__ = "2025-08-05"
 
 # -----------------------------------------------------------------------------
 # SzDiagnostic
@@ -32,7 +32,12 @@ class SzDiagnostic(ABC):
     @abstractmethod
     def check_repository_performance(self, seconds_to_run: int) -> str:
         """
-        The `check_repository_performance` method conducts a rudimentary repository test to gauge I/O performance.
+        The `check_repository_performance` method conducts a rudimentary repository test to gauge I/O
+        and network performance.
+
+        Typically, this is only run when troubleshooting performance.
+
+        This is a non-destructive test.
 
         Args:
             seconds_to_run (int): Duration of the test in seconds.
@@ -89,8 +94,11 @@ def purge_repository(self) -> None:
         **Warning:**
         The `purge_repository` method purges all data in the repository, except the configuration.
 
-        Before calling `purge_repository` all other instances of the Senzing API
-        MUST be destroyed or shutdown.
+        WARNING: This method is destructive, it will delete all loaded records and entity resolution decisions.
+
+        Senzing does not provide a means to restore the data.
+
+        The only means of recovery would be restoring from a database backup.
 
         Raises: