From DSS-Python: Error.UseExceptions, updated CompatFlags doc

Includes a test for Error.UseExceptions

Author: PMeira

opendssdirect/Basic.py

@@ -176,6 +176,9 @@ def CompatFlags(*args):
         so this flag can be used to toggle the old/bad values where feasible.
     - 0x4 (bit 2): Toggle some InvControl behavior introduced in OpenDSS 9.6.1.1. It could be a regression 
         but needs further investigation, so we added this flag in the time being.
+    - 0x8 (bit 3): When using "save circuit", the official OpenDSS always includes the "CalcVoltageBases" command
+        in the saved script. We found that it is not always a good idea, so we removed the command (leaving it 
+        commented). Use this flag to enable the command in the saved script.
 
     These flags may change for each version of DSS C-API, but the same value will not be reused. That is,
     when we remove a compatibility flag, it will have no effect but will also not affect anything else

opendssdirect/Error.py

@@ -1,4 +1,4 @@
-from ._utils import lib, get_string
+from ._utils import lib, get_string, Base
 
 
 def Description():
@@ -58,5 +58,33 @@ def ExtendedErrors(*args):
     lib.Error_Set_ExtendedErrors(Value)
 
 
-_columns = ["Description", "Number", "EarlyAbort"]
-__all__ = ["Description", "Number", "EarlyAbort", "ExtendedErrors"]
+def UseExceptions(*args):
+    """
+    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)
+    """
+    # Getter
+    if len(args) == 0:
+        return Base._use_exceptions
+
+    # Setter
+    value, = args
+    Base._enable_exceptions(bool(value))
+
+
+_columns = ["Description", "Number", "EarlyAbort", "ExtendedErrors", "UseExceptions"]
+__all__ = ["Description", "Number", "EarlyAbort", "ExtendedErrors", "UseExceptions"]

opendssdirect/_utils.py

@@ -3,14 +3,14 @@
 import numpy as np
 import warnings
 
-# Bind to the FFI module instance. This should be refined in a future version,
-# especially after DSS C-API 0.11 is fully released.
+# Bind to the FFI module instance. This should be refined in a future version
 lib = dss_py.prime_api_util.lib
 ffi = dss_py.prime_api_util.ffi
 api_util = dss_py.prime_api_util
 codec = api_util.codec
 CheckForError = dss_py.DSS_GR.CheckForError
 DSSException = dss_py._cffi_api_util.DSSException
+Base = dss_py._cffi_api_util.Base
 
 # Currently, we prefer the functions that return lists (suffix 2)
 # to keep higher compatibility with previous versions of OpenDSSDirect.py.

tests/test_opendssdirect.py

@@ -5342,3 +5342,20 @@ def test_dss_extensions_debug():
         assert "DEBUG" in opendssdirect.Basic.Version()
     else:
         assert "DEBUG" not in opendssdirect.Basic.Version()
+
+
+def test_exception_control(dss):
+    # Default behavior
+    assert dss.Error.UseExceptions()
+    with pt.raises(dss.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
+