Use _check_for_error, drop the CheckForError; update docstrings.

Author: PMeira

README.md

@@ -39,7 +39,7 @@ In general, the DLL from `dss_capi` provides more features than both the officia
 
 Besides most of the COM methods, some of the unique DDLL methods are also exposed in adapted forms, namely the methods from `DYMatrix.pas`, especially `GetCompressedYMatrix` (check the source files for more information).
 
-Since no GUI components are used in the FreePascal DLL, we map nearly all OpenDSS errors to Python exceptions, which seems a more natural way of working in Python. You can still manually trigger an error check by calling the function `CheckForError()` from the main module or manually checking the `DSS.Error` interface.
+Since no GUI components are used in the FreePascal DLL, we map nearly all OpenDSS errors to Python exceptions, which seems a more natural way of working in Python. You can still manually trigger an error check by calling the function `_check_for_error()` from the main class or manually checking the `DSS.Error` interface.
 
 ## Installing
 

docs/changelog.md

@@ -16,6 +16,7 @@ relevant. See [DSS C-API's repository](https://github.com/dss-extensions/dss_cap
     - New `EnergyMeterRegisters` and `GeneratorRegisters` to simplify handling register indexes from EnergyMeters (`EnergyMeterRegisters`), Generators, PVSystems, and Storage objects (these last three use `GeneratorRegisters`).
 
 - Implement the DSSEvents interface. Note that this is not a popular interface and we haven't seen it used in Python with COM yet. OpenDSS comes with a couple of examples using VBA in Excel though.
+- Drop `CheckForError()`; use `_check_for_error()` instead (same function, but the latter doesn't pollute the public scope).
 
 - Packaging: Migrate build system to `pyproject.toml` and Hatch.
 
@@ -384,7 +385,7 @@ Major changes:
 - Uses `__slots__` to simplify attribute handling.
 - Exposes both the our classic API (e.g. `dss.v7.DSS_IR` for the immediate/direct results) and global result API (e.g. `dss.v7.DSS_GR` for the global result interface). See [DSS C-API's docs](https://github.com/dss-extensions/dss_capi/blob/master/docs/usage.md) for a detailed explanation. We default to the GR interface since it will generally be faster at the cost of a small memory overhead.
 - Although still experimental, the v8/PM module is more stable. If you try it, please give feedback.
-- Error checking is now done for most API writes. That is, if a an OpenDSS error occurs, it should cause a Python exception soon after. Previously, you need to call `CheckForError()` manually to trigger this. This change was introduced after user reports indicated that manually checking for errors is a common behavior.
+- Error checking is now done for most API writes. That is, if a an OpenDSS error occurs, it should cause a Python exception soon after. Previously, you need to call `_check_for_error()` manually to trigger this. This change was introduced after user reports indicated that manually checking for errors is a common behavior.
 - Exposes API extensions for the classes `LineGeometry`, `WireData`, `LineSpacing`, `CNData`, `TSData`, `Reactor`.
 - Makes most DSS classes iterable (including buses), e.g. you can now use:
 

dss/IActiveClass.py

@@ -26,7 +26,7 @@ def ActiveClassName(self) -> str:
 
         Original COM help: https://opendss.epri.com/ActiveClassName.html
         '''
-        return self._get_string(self.CheckForError(self._lib.ActiveClass_Get_ActiveClassName()))
+        return self._get_string(self._check_for_error(self._lib.ActiveClass_Get_ActiveClassName()))
 
     @property
     def AllNames(self) -> List[str]:
@@ -35,7 +35,7 @@ def AllNames(self) -> List[str]:
 
         Original COM help: https://opendss.epri.com/AllNames.html
         '''
-        return self.CheckForError(self._get_string_array(self._lib.ActiveClass_Get_AllNames))
+        return self._check_for_error(self._get_string_array(self._lib.ActiveClass_Get_AllNames))
 
     @property
     def Count(self) -> int:
@@ -44,10 +44,10 @@ def Count(self) -> int:
 
         Original COM help: https://opendss.epri.com/Count.html
         '''
-        return self.CheckForError(self._lib.ActiveClass_Get_Count())
+        return self._check_for_error(self._lib.ActiveClass_Get_Count())
 
     def __len__(self) -> int:
-        return self.CheckForError(self._lib.ActiveClass_Get_Count())
+        return self._check_for_error(self._lib.ActiveClass_Get_Count())
 
     def __iter__(self):
         n = self.First
@@ -65,7 +65,7 @@ def First(self) -> int:
 
         Original COM help: https://opendss.epri.com/First.html
         '''
-        return self.CheckForError(self._lib.ActiveClass_Get_First())
+        return self._check_for_error(self._lib.ActiveClass_Get_First())
 
     @property
     def Name(self) -> str:
@@ -74,14 +74,14 @@ def Name(self) -> str:
 
         Original COM help: https://opendss.epri.com/Name.html
         '''
-        return self._get_string(self.CheckForError(self._lib.ActiveClass_Get_Name()))
+        return self._get_string(self._check_for_error(self._lib.ActiveClass_Get_Name()))
 
     @Name.setter
     def Name(self, Value: AnyStr):
         if type(Value) is not bytes:
             Value = Value.encode(self._api_util.codec)
 
-        self.CheckForError(self._lib.ActiveClass_Set_Name(Value))
+        self._check_for_error(self._lib.ActiveClass_Set_Name(Value))
 
     @property
     def Next(self) -> int:
@@ -93,7 +93,7 @@ def Next(self) -> int:
 
         Original COM help: https://opendss.epri.com/Next.html
         '''
-        return self.CheckForError(self._lib.ActiveClass_Get_Next())
+        return self._check_for_error(self._lib.ActiveClass_Get_Next())
 
     @property
     def NumElements(self) -> int:
@@ -102,7 +102,7 @@ def NumElements(self) -> int:
 
         Original COM help: https://opendss.epri.com/NumElements.html
         '''
-        return self.CheckForError(self._lib.ActiveClass_Get_NumElements())
+        return self._check_for_error(self._lib.ActiveClass_Get_NumElements())
 
     @property
     def ActiveClassParent(self) -> str:
@@ -111,7 +111,7 @@ def ActiveClassParent(self) -> str:
 
         Original COM help: https://opendss.epri.com/ActiveClassParent.html
         '''
-        return self._get_string(self.CheckForError(self._lib.ActiveClass_Get_ActiveClassParent()))
+        return self._get_string(self._check_for_error(self._lib.ActiveClass_Get_ActiveClassParent()))
 
     def ToJSON(self, options: DSSJSONFlags = 0) -> str:
         '''
@@ -122,6 +122,6 @@ def ToJSON(self, options: DSSJSONFlags = 0) -> str:
         
         Additionally, the `ExcludeDisabled` flag can be used to excluded disabled elements from the output.
 
-        (API Extension)
+        **(API Extension)**
         '''
-        return self._get_string(self.CheckForError(self._lib.ActiveClass_ToJSON(options)))
+        return self._get_string(self._check_for_error(self._lib.ActiveClass_ToJSON(options)))