Ctrl+K

dss.IDSSEvents

dss.IDSSEvents#

Module Contents#

Classes#

DSSEventsConnection

Wraps a classic DSS Event handler class and its connection state. This should not be manually created. Use DSS.Events.WithEvents() instead.

IDSSEvents

This interface provides connection to classic the OpenDSS Events API. For official OpenDSS documentation about this feature, see the document titled “Evaluation of Distribution Reconfiguration Functions in Advanced Distribution Management Systems, Example Assessments of Distribution Automation Using Open Distribution Systems Simulator” (2011), which is available from EPRI at https://restservice.epri.com/publicdownload/000000000001020090/0/Product (archived copy here).

API#

class dss.IDSSEvents.DSSEventsConnection(api_util, handler)#

Wraps a classic DSS Event handler class and its connection state. This should not be manually created. Use DSS.Events.WithEvents() instead.

__init__(api_util, handler)#
close()#

Alias to disconnect; for compatibility with win32com code.

disconnect()#

Disconnects the event handler associated to this o

class dss.IDSSEvents.IDSSEvents(api_util, prefer_lists=False)#

Bases: dss._cffi_api_util.Base

This interface provides connection to classic the OpenDSS Events API. For official OpenDSS documentation about this feature, see the document titled “Evaluation of Distribution Reconfiguration Functions in Advanced Distribution Management Systems, Example Assessments of Distribution Automation Using Open Distribution Systems Simulator” (2011), which is available from EPRI at https://restservice.epri.com/publicdownload/000000000001020090/0/Product (archived copy here).

VBA/Excel examples of the classic COM usage are found in the folder “Examples/civinlar model/” (mirrored here, with minor changes), which is distributed along with the official OpenDSS.

For a quick intro, this interface allows connecting an object (event handler) that runs custom actions are three points of the solution process (InitControls, StepControls, CheckControls). Instead of manually writing a full solution loop, users can use this to connect an event handler to the existing OpenDSS solution loops/algorithms, which allows some customization opportunities.

Note that AltDSS/DSS C-API provides more/extra events, but this interface is intended to replace usage of similar comtypes and win32com features. That is, see AltDSS-Python for the extra events, some of which are used by the AltDSS-Python itself to provide direct-object access.

Since the intention is to allow easy migration (and/or interoperability) with both the comtypes and win32com modules, both styles of event handler classes are allowed:

class EventHandler:
    '''An event handler in the style of win32com'''
    def OnInitControls(self):
        print('Init')

    def OnStepControls(self):
        print('Step')

    def OnCheckControls(self):
        print('Check')

# this would be used like:
evt_conn = win32com.client.WithEvents(DSSObj.Events, EventHandler)

or

class EventHandler:
    '''An event handler in the style of comtypes'''
    def InitControls(self):
        print('Init')

    def StepControls(self):
        print('Step')

    def CheckControls(self):
        print('Check')

# this would be used like:
iface = comtypes.gen.OpenDSSengine.IDSSEventsEvents
evt_conn = comtypes.client.GetEvents(DSSObj.Events, EventHandler(), interface=iface)

Like the COM implementations, DSS-Python requires that the three event types are handled. The method names can be either style (OnInitControls or InitControls). To make things easier, there are two methods in our implementation of the Events API that partially mimic the functions used in the COM modules. Use whichever is more convenient.

evt_conn = DSSObj.Events.WithEvents(EventHandler) # like win32com, using a class

# or
evt_conn = DSSObj.Events.GetEvents(EventHandler()) # like comtypes, using an object instance
GetEvents(handler_obj) → dss.IDSSEvents.DSSEventsConnection#

Connects an object instance to the classic event system compatibility layer.

This is intended to replace usage of comtypes.client.GetEvents() (when previously used with the OpenDSS COM engine).

(API Extension)

WithEvents(handler_class) → dss.IDSSEvents.DSSEventsConnection#

Creates an instance of handler_class and connects it to the classic event system compatibility layer.

This is intended to replace usage of win32com.client.WithEvents() (when previously used with the OpenDSS COM engine).

(API Extension)

__init__(api_util, prefer_lists=False)#
Contents