Exceptions: add toggle to disable mapping Error.Number to Python exceptions

Includes new tests, and a few general formatting/docstring changes.
Closes #54

Author: PMeira

dss/IBus.py

@@ -57,7 +57,7 @@ def ZscRefresh(self) -> bool:
 
     @property
     def Coorddefined(self) -> bool:
-        '''False=0 else True. Indicates whether a coordinate has been defined for this bus'''
+        '''Indicates whether a coordinate has been defined for this bus'''
         return self.CheckForError(self._lib.Bus_Get_Coorddefined()) != 0
 
     @property

dss/IError.py

@@ -61,10 +61,35 @@ def ExtendedErrors(self) -> bool:
         off to restore the previous behavior.
         
         (API Extension)
-        
         '''
         return self._lib.Error_Get_ExtendedErrors() != 0
 
     @ExtendedErrors.setter
     def ExtendedErrors(self, Value: bool):
         self._lib.Error_Set_ExtendedErrors(Value)
+
+    @property
+    def UseExceptions(self) -> bool:
+        """
+        Controls whether the automatic error checking mechanism is enable, i.e., if
+        the DSS engine errors (from the `Error` interface) are mapped exception when
+        detected. 
+        
+        **When disabled, the user takes responsibility for checking for errors.**
+        This can be done through the `Error` interface. When `Error.Number` is not
+        zero, there should be an error message in `Error.Description`. This is compatible
+        with the behavior on the official OpenDSS (Windows-only COM implementation) when 
+        `AllowForms` is disabled.
+
+        Users can also use the DSS command `Export ErrorLog` to inspect for errors.
+
+        **WARNING:** This is a global setting, affects all DSS instances from DSS-Python 
+        and OpenDSSDirect.py.
+
+        (API Extension)
+        """
+        return Base._use_exceptions
+    
+    @UseExceptions.setter
+    def UseExceptions(self, value: bool):
+        Base._enable_exceptions(value)

dss/IPVSystems.py

@@ -92,7 +92,7 @@ def daily(self) -> str:
         '''
         Name of the dispatch shape to use for daily simulations. Must be previously
         defined as a Loadshape object of 24 hrs, typically. In the default dispatch
-        mode, the PVSystem element uses this loadshape to trigger State changes.        
+        mode, the PVSystem element uses this loadshape to trigger State changes.
         
         (API Extension)
         '''

dss/_cffi_api_util.py

@@ -43,7 +43,7 @@ def __str__(self):
         return f'(#{self.args[0]}) {self.args[1]}'
 
 
-# For backwards compatibility
+# For backwards compatibility, will be removed for version 1.0
 DssException = DSSException
 use_com_compat = set_case_insensitive_attributes
 
@@ -105,6 +105,8 @@ class Base:
         '_errorPtr',
     ]
 
+    _use_exceptions = True
+
     def __init__(self, api_util):
         self._lib = api_util.lib
         self._api_util = api_util
@@ -137,9 +139,39 @@ def __init__(self, api_util):
             cls._dss_attributes = lowercase_map
 
 
+    @staticmethod
+    def _enable_exceptions(do_enable: bool):
+        """
+        Controls whether the automatic error checking mechanism is enable, i.e., if
+        the DSS engine errors (from the `Error` interface) are mapped exception when
+        detected. 
+        
+        **When disabled, the user takes responsibility for checking for errors.**
+        This can be done through the `Error` interface. When `Error.Number` is not
+        zero, there should be an error message in `Error.Description`. This is compatible
+        with the behavior on the official OpenDSS (Windows-only COM implementation) when 
+        `AllowForms` is disabled.
+
+        Users can also use the DSS command `Export ErrorLog` to inspect for errors.
+
+        **WARNING:** This is a global setting, affects all DSS instances from DSS-Python 
+        and OpenDSSDirect.py.
+        """
+        Base._use_exceptions = bool(do_enable)
+
     def _check_for_error(self, result=None):
-        '''Checks for an OpenDSS error. Raises an exception if any, otherwise returns the `result` parameter.'''
-        if self._errorPtr[0]:
+        """
+        Checks for a DSS engine error (on the default configuration).
+
+        By default, raises an exception if any error is detected, otherwise returns the `result` parameter.
+        
+        If the user disabled exceptions, any error is simply ignored. Note that, in this case, manually
+        calling this function would have no purpose/effects.
+
+        Note that, **in the future**, we may try showing a popup form like the official OpenDSS does on Windows
+        if AllowForms is True. This behavior is not very portable though and not adequate for automated scripts.
+        """
+        if self._errorPtr[0] and Base._use_exceptions:
             error_num = self._errorPtr[0]
             self._errorPtr[0] = 0
             raise DSSException(error_num, self._get_string(self._lib.Error_Get_Description()))

tests/test_general.py

@@ -29,7 +29,7 @@ def setup_function():
     DSS.AllowChangeDir = True
     DSS.COMErrorResults = True # TODO: change to False
     DSS.CompatFlags = 0
-
+    DSS.Error.UseExceptions = True
 
 def test_zip_redirect():
     with pytest.raises(DSSException):
@@ -604,6 +604,21 @@ def test_essentials(DSS: IDSS = DSS):
     for expected, b in zip(['sourcebus', '1', '2', '3'], DSS.ActiveCircuit.ActiveBus):
         assert expected == b.Name
 
+def test_exception_control(DSS: IDSS = DSS):
+    # Default behavior
+    assert DSS.Error.UseExceptions
+    with pytest.raises(DSSException):
+        DSS.Text.Command = 'this_is_an_invalid_command1'
+
+    # Behavior without exceptions
+    DSS.Error.UseExceptions = False
+    assert not DSS.Error.UseExceptions
+    DSS.Text.Command = 'this_is_an_invalid_command2'
+    # There should be an error code waiting for us...
+    assert DSS.Error.Number != 0
+    # ...but it should be gone after we read it
+    assert DSS.Error.Number == 0
+
 
 def test_patch_comtypes():
     if WIN32: