pynetdicom uses an event-handler system to give the user access to the data exchanged between different services within an AE as well as the PDUs and data sent between the local and peer AEs. Two different types of events are used: notification events and intervention events. Events are imported using from pynetdicom import evt

Notification Events

Notification events are those events where bound event handlers don’t need to return or yield anything (i.e. the user is notified some event has occurred). Each notification event can have multiple handlers bound to it and any exceptions raised by the handlers are caught and the exception message logged instead. The table below lists the available notification events.




Association aborted


Association accepted


ACSE received a primitive from the DUL service provider


ACSE sent a primitive to the DUL service provider


Connection with remote closed


Connection with remote opened


Data received from the peer AE


Data sent to the peer AE


DIMSE service received and decoded a message


DIMSE service encoded and sent a message


Association established


State machine transitioning


PDU received from the peer AE


PDU sent to the peer AE


Association rejected


Association released


Association requested

By default, a number of notification handlers are bound for logging purposes. If you wish to remove these then you can do the following before creating any associations:

from pynetdicom import _config

# Don't bind any of the default notification handlers
_config.LOG_HANDLER_LEVEL = 'none'

Intervention Events

Intervention events are those events where the bound event handler must return or yield certain expected values so that pynetdicom can complete an action (i.e. user intervention is required). Each intervention event has only a single handler bound to it at all times. If the user hasn’t bound their own handler then a default will be used, which usually returns a negative response (i.e. service request failed, or extended negotiation ignored). The sole exception is the default handler for evt.EVT_C_ECHO which returns an 0x0000 Success status. The table below lists the possible intervention events.

Event Handlers

Event handlers are callable functions bound to an event that, at a minimum, get passed a single parameter, event, which is an Event instance. All Event instances come with at least three attributes:

Additional attributes and properties are available depending on the event type, see the handler implementation documentation for more information.

Handlers can be bound to events through the evt_handlers keyword parameter with AE.associate() and AE.start_server(). evt_handlers should be a list of 2- or 3-tuples:

from pynetdicom import evt, AE
from pynetdicom.sop_class import VerificationSOPClass, CTImageStorage

def handle_echo(event):
    # Because we used a 2-tuple to bind `handle_echo` we
    #   have no extra parameters
    return 0x0000

def handle_store(event, arg1, arg2):
    # Because we used a 3-tuple to bind `handle_store` we
    #   have optional extra parameters
    assert arg1 == 'optional'
    assert arg2 == 'parameters'
    return 0x0000

handlers = [
    (evt.EVT_C_ECHO, handle_echo),
    (evt.EVT_C_STORE, handle_store, ['optional', 'parameters']),

ae = AE()
ae.start_server(('localhost', 11112), evt_handlers=handlers)

If using a 3-tuple then the third item should be a list of objects that will be passed to the handler as extra parameters.

The other way to bind handlers to events is through the Association.bind() and AssociationServer.bind() methods. Handlers can be unbound with Association.unbind() and AssociationServer.unbind() methods. See the Association guide for more details.