pynetdicom.association.Association

class pynetdicom.association.Association(ae: ApplicationEntity, mode: str)[source]

Manage an Association with a peer AE.

acceptor

Representation of the association’s acceptor AE.

Type:

association.ServiceUser

acse

The Association Control Service Element provider.

Type:

acse.ACSE

dimse

The DICOM Message Service Element provider.

Type:

dimse.DIMSEServiceProvider

dul

The DICOM Upper Layer service provider.

Type:

dul.DULServiceProvider

is_aborted

True if the association has been aborted, False otherwise.

Type:

bool

is_established

True if the association has been established, False otherwise.

Type:

bool

is_rejected

True if the association was rejected, False otherwise.

Type:

bool

is_released

True if the association has been released, False otherwise.

Type:

bool

network_timeout_response

If "A-RELEASE" then initiate a normal association release on expiry of the network timeout, otherwise issue an A-ABORT (default).

Type:

str

requestor

Representation of the association’s requestor AE.

Type:

association.ServiceUser

__init__(ae: ApplicationEntity, mode: str) → None[source]

Create a new Association instance.

The association starts in State 1 (idle). Association negotiation won’t begin until an AssociationSocket is assigned using set_socket() and start() is called.

Parameters:

Methods

__init__(ae, mode)

Create a new Association instance.

abort()

Abort the Association by sending an A-ABORT to the remote AE.

bind(event, handler[, args])

Bind a callable handler to an event.

getName()

Return a string used for identification purposes only.

get_events()

Return a list of currently bound events.

get_handlers(event)

Return the handlers bound to a specific event.

isDaemon()

Return whether this thread is a daemon.

is_alive()

Return whether the thread is alive.

join([timeout])

Wait until the thread terminates.

kill()

Kill the Association thread.

release()

Initiate association release by send an A-RELEASE request.

request()

Request an association with a peer.

run()

Method representing the thread's activity.

run_reactor()

The main Association reactor.

send_c_cancel(msg_id[, context_id, query_model])

Send a C-CANCEL request to the peer AE.

send_c_echo([msg_id])

Send a C-ECHO request to the peer AE.

send_c_find(dataset, query_model[, msg_id, ...])

Send a C-FIND request to the peer AE.

send_c_get(dataset, query_model[, msg_id, ...])

Send a C-GET request to the peer AE.

send_c_move(dataset, move_aet, query_model)

Send a C-MOVE request to the peer AE.

send_c_store(dataset[, msg_id, priority, ...])

Send a C-STORE request to the peer AE.

send_n_action(dataset, action_type, ...[, ...])

Send an N-ACTION request to the peer AE.

send_n_create(dataset, class_uid[, ...])

Send an N-CREATE request to the peer AE.

send_n_delete(class_uid, instance_uid[, ...])

Send an N-DELETE request to the peer AE.

send_n_event_report(dataset, event_type, ...)

Send an N-EVENT-REPORT request to the peer AE.

send_n_get(identifier_list, class_uid, ...)

Send an N-GET request to the peer AE.

send_n_set(dataset, class_uid, instance_uid)

Send an N-SET request to the peer AE.

setDaemon(daemonic)

Set whether this thread is a daemon.

setName(name)

Set the name string for this thread.

set_socket(socket)

Set the socket to use for communicating with the peer.

start()

Start the thread's activity.

unbind(event, handler)

Unbind a callable handler from an event.

Attributes

accepted_contexts

Return a list of accepted PresentationContext items.

acse_timeout

The ACSE timeout (in seconds).

ae

Return the parent ApplicationEntity.

daemon

A boolean value indicating whether this thread is a daemon thread.

dimse_timeout

The DIMSE timeout (in seconds).

ident

Thread identifier of this thread or None if it has not been started.

is_acceptor

Return True if the local AE is the association acceptor.

is_requestor

Return True if the local AE is the association requestor.

local

Return a dict with information about the local AE.

lock

Return the AE's threading.Lock.

mode

The Association's mode as a str.

name

A string used for identification purposes only.

native_id

Native integral thread ID of this thread, or None if it has not been started.

network_timeout

The network timeout (in seconds).

rejected_contexts

Return a list of rejected PresentationContext.

remote

Return a dict with information about the peer AE.
abort() → None[source]

Abort the Association by sending an A-ABORT to the remote AE.

property accepted_contexts: list[PresentationContext]

Return a list of accepted PresentationContext items.

property acse_timeout: float | None

The ACSE timeout (in seconds).

property ae: ApplicationEntity

Return the parent ApplicationEntity.

bind(event: NotificationEvent | InterventionEvent, handler: Callable, args: None | list[Any] = None) → None[source]

Bind a callable handler to an event.

Added in version 1.3.

Changed in version 1.5: Added args keyword parameter.

Parameters:

  • event (collections.namedtuple) – The event to bind the function to.

  • handler (callable) – The function that will be called if the event occurs.

  • args (list, optional) – Optional extra arguments to be passed to the handler (default: no extra arguments passed to the handler).

property dimse_timeout: int | float | None

The DIMSE timeout (in seconds).

get_events() → list[NotificationEvent | InterventionEvent][source]

Return a list of currently bound events.

Added in version 1.3.

get_handlers(event: NotificationEvent | InterventionEvent) → list[tuple[Callable, list[Any] | None]] | tuple[Callable, list[Any] | None][source]

Return the handlers bound to a specific event.

Added in version 1.3.

Changed in version 1.5: Returns a 2-tuple of (callable, args) or list of 2-tuple.

Parameters:

event (namedtuple) – The event bound to the handlers.

Returns:

If the event is a notification event then returns a list of 2-tuples containing the callable functions bound to event and the arguments passed to the callable as (callable, args). If the event is an intervention event then returns either a 2-tuple of (callable, args) if a handler is bound to the event or (None, None) if no handler has been bound.

Return type:

2-tuple of (callable, args), list of 2-tuple

property is_acceptor: bool

Return True if the local AE is the association acceptor.

property is_requestor: bool

Return True if the local AE is the association requestor.

kill() → None[source]

Kill the Association thread.

property local: dict[str, Any]

Return a dict with information about the local AE.

property lock: allocate_lock

Return the AE’s threading.Lock.

property mode: str

The Association’s mode as a str.

Parameters:

mode (str) – The mode of the Association, must be either 'requestor' or 'acceptor'. If 'requestor' then its assumed that the local AE requests an association with peers and (by default) acts as the SCU. If 'acceptor' then its assumed that the local AE is listening for association requests and (by default) acts as the SCP.

property network_timeout: int | float | None

The network timeout (in seconds).

property rejected_contexts: list[PresentationContext]

Return a list of rejected PresentationContext.

release() → None[source]

Initiate association release by send an A-RELEASE request.

property remote: dict[str, Any]

Return a dict with information about the peer AE.

request() → None[source]

Request an association with a peer.

A request can only be made once the Association instance has been configured for requestor mode and been assigned an AssociationSocket.

run_reactor() → None[source]

The main Association reactor.

send_c_cancel(msg_id: int, context_id: int | None = None, query_model: str | UID | None = None) → None[source]

Send a C-CANCEL request to the peer AE.

Changed in version 2.0: Added query_model and made context_id optional

Parameters:

  • msg_id (int) – The Message ID of the C-GET/C-MOVE/C-FIND operation to be cancelled. Must be between 0 and 65535, inclusive.

  • context_id (int, optional) – The presentation context ID of the original C-GET/C-MOVE/C-FIND service request. Required if query_model is not used.

  • query_model (str or pydicom.uid.UID, optional) – The query model used with the original C-GET/C-MOVE/C-FIND service request. Required if context_id is not used.

send_c_echo(msg_id: int = 1) → Dataset[source]

Send a C-ECHO request to the peer AE.

Parameters:

msg_id (int, optional) – The C-ECHO request’s Message ID, must be between 0 and 65535, inclusive, (default 1).

Returns:

status – If the peer timed out, aborted or sent an invalid response then returns an empty Dataset. If a valid response was received from the peer then returns a Dataset containing at least a (0000,0900) Status element, and, depending on the returned Status value, may optionally contain additional elements (see DICOM Standard, Part 7, Annex C).

The DICOM Standard, Part 7, Table 9.3-13 indicates that the Status value of a C-ECHO response “shall have a value of Success”. However Section 9.1.5.1.4 indicates it may have any of the following values:

Success
0x0000 - Success
Failure
0x0122 - SOP class not supported
0x0210 - Duplicate invocation
0x0211 - Unrecognised operation
0x0212 - Mistyped argument

As the actual status depends on the peer SCP, it shouldn’t be assumed that it will be one of these.

Return type:

pydicom.dataset.Dataset

Raises:

  • RuntimeError – If called without an association to a peer SCP.

  • ValueError – If the association has no accepted presentation context for Verification SOP Class.

See also

C_ECHO, VerificationServiceClass

References

send_c_find(dataset: Dataset, query_model: str | UID, msg_id: int = 1, priority: int = 2) → Iterator[tuple[Dataset, Dataset | None]][source]

Send a C-FIND request to the peer AE.

Yields (status, identifier) pairs for each response from the peer.

Changed in version 1.5: query_model now only accepts a UID string

Changed in version 2.1: Added support for Repository Query

Parameters:

  • dataset (pydicom.dataset.Dataset) – The C-FIND request’s Identifier dataset. The exact requirements for the Identifier dataset are Service Class specific (see the DICOM Standard, Part 4).

  • query_model (pydicom.uid.UID or str) – The value to use for the C-FIND request’s (0000,0002) Affected SOP Class UID parameter, which usually corresponds to the Information Model that is to be used.

  • msg_id (int, optional) – The C-FIND request’s Message ID, must be between 0 and 65535, inclusive, (default 1).

  • priority (int, optional) –

    The value of the C-FIND request’s Priority parameter (may not be supported by the peer), one of:

    • 0 - Medium

    • 1 - High

    • 2 - Low (default)

Yields:

  • status (pydicom.dataset.Dataset) – If the peer timed out, aborted or sent an invalid response then yields an empty Dataset. If a response was received from the peer then yields a Dataset containing at least a (0000,0900) Status element, and depending on the returned value, may optionally contain additional elements (see the DICOM Standard, Part 7, Section 9.1.2.1.6 and Annex C).

    The status for the requested C-FIND operation should be one of the following values, but as the value depends on the peer this can’t be assumed:

    General C-FIND (Part 7, Section 9.1.2.1.6 and Annex C)

    Cancel
    0xFE00 - Matching terminated due to Cancel request
    Success
    0x0000 - Matching is complete: no final Identifier is supplied
    Failure
    0x0122 - SOP class not supported

    Query/Retrieve Service, Basic Worklist Management Service, Hanging Protocol Query/Retrieve Service, Defined Procedure Protocol Query/Retrieve Service, Substance Administration Query Service, Color Palette Query/Retrieve Service, Implant Template Query/Retrieve Service, Inventory Query/Retrieve Service, Protocol Approval Query/Retrieve Service and Unified Protocol Step Service specific (DICOM Standard, Part 4, Annexes C.4.1, K.4.1.1.4, U.4.1, HH, V.4.1.1.4, X, BB, II, JJ and CC):

    Failure
    0xA700 - Out of resources
    0xA900 - Identifier does not match SOP Class
    0xC000 to 0xCFFF - Unable to process
    Pending
    0xFF00 - Matches are continuing: current match is supplied and any Optional Keys were supported in the same manner as Required Keys
    0xFF01 - Matches are continuing: warning that one or more Optional Keys were not supported for existence and/or matching for this Identifier)

    Query/Retrieve Service - Repository Query specific (DICOM Standard, Part 5, Annex C.6.4):

    Warning
    0xB001 - Matching reached response limit, subsequent request may return additional matches
    Failure
    0xA710 - Invalid prior record key

    Relevant Patient Information Query Service specific (DICOM Standard Part 4, Annex Q.2.1.1.4):

    Failure
    0xA700 - Out of resources
    0xA900 - Identifier does not match SOP Class
    0xC000 - Unable to process
    0xC100 - More than one match found
    0xC200 - Unable to support requested template
    Pending
    0xFF00 - Matches are continuing: current match is supplied and any Optional Keys were supported in the same manner as Required Keys

  • identifier (pydicom.dataset.Dataset or None) – If the status category is ‘Pending’ then the C-FIND response’s Identifier Dataset If the status category is not ‘Pending’ this will be None. The exact contents of the response Identifier are Service Class specific (see the DICOM Standard, Part 4).

Raises:

  • RuntimeError – If send_c_find is called with no established association.

  • ValueError – If no accepted Presentation Context for query_model exists or if unable to encode the Identifier dataset.

See also

C_FIND, BasicWorklistManagementServiceClass, ColorPaletteQueryRetrieveServiceClass, DefinedProcedureProtocolQueryRetrieveServiceClass, HangingProtocolQueryRetrieveServiceClass, ImplantTemplateQueryRetrieveServiceClass, InventoryQueryRetrieveServiceClass, ProtocolApprovalQueryRetrieveServiceClass, QueryRetrieveServiceClass, RelevantPatientInformationQueryServiceClass, SubstanceAdministrationQueryServiceClass, UnifiedProcedureStepServiceClass

References

send_c_get(dataset: Dataset, query_model: str | UID, msg_id: int = 1, priority: int = 2) → Iterator[tuple[Dataset, Dataset | None]][source]

Send a C-GET request to the peer AE.

Yields (status, identifier) pairs for each response from the peer.

A C-STORE handler should be implemented and bound to evt.EVT_C_STORE prior to calling send_c_get() as the peer will return any matches via a C-STORE sub-operation over the current association. In addition, SCP/SCU Role Selection Negotiation must be supported by the Association.

Changed in version 1.5: query_model now only accepts a UID string

Parameters:

  • dataset (pydicom.dataset.Dataset) – The C-GET request’s Identifier dataset. The exact requirements for the Identifier are Service Class specific (see the DICOM Standard, Part 4).

  • query_model (pydicom.uid.UID or str) – The value to use for the C-GET request’s (0000,0002) Affected SOP Class UID parameter, which usually corresponds to the Information Model that is to be used.

  • msg_id (int, optional) – The C-GET request’s Message ID, must be between 0 and 65535, inclusive, (default 1).

  • priority (int, optional) –

    The value of the C-GET request’s Priority parameter (may not be supported by the peer), one of:

    • 0 - Medium

    • 1 - High

    • 2 - Low (default)

Yields:

  • status (pydicom.dataset.Dataset) – If the peer timed out, aborted or sent an invalid response then yields an empty Dataset. If a response was received from the peer then yields a Dataset containing at least a (0000,0900) Status element, and depending on the returned value may optionally contain additional elements (see the DICOM Standard, Part 7, Section 9.1.3.1.6 and Annex C).

    The status for the requested C-GET operation should be one of the following values, but as the value depends on the peer this can’t be assumed:

    General C-GET (DICOM Standard, Part 7, Section 9.1.3 and Annex C)

    Success
    0x0000 - Sub-operations complete: no failures or warnings
    Failure
    0x0122 - SOP class not supported
    0x0124 - Not authorised
    0x0210 - Duplicate invocation
    0x0211 - Unrecognised operation
    0x0212 - Mistyped argument

    Query/Retrieve Service, Hanging Protocol Query/Retrieve Service, Defined Procedure Protocol Query/Retrieve Service, Color Palette Query/Retrieve Service, Implant Template Query/Retrieve Service, Inventory Query/Retrieve Service and Protocol Approval Query/Retrieve Service specific (DICOM Standard, Part 4, Annexes C.4.3, Y.C.4.2.1.4, Z.4.2.1.4, U.4.3, X, BB, HH, II and JJ):

    Pending
    0xFF00 - Sub-operations are continuing
    Cancel
    0xFE00 - Sub-operations terminated due to Cancel indication
    Failure
    0xA701 - Out of resources: unable to calculate number of matches
    0xA702 - Out of resources: unable to perform sub-operations
    0xA900 - Identifier does not match SOP class
    0xAA00 - None of the frames requested were found in the SOP instance
    0xAA01 - Unable to create new object for this SOP class
    0xAA02 - Unable to extract frames
    0xAA03 - Time-based request received for a non-time-based original SOP Instance
    0xAA04 - Invalid request
    0xC000 to 0xCFFF - Unable to process
    Warning
    0xB000 - Sub-operations completed: one or more failures or warnings

  • identifier (pydicom.dataset.Dataset or None) – If the status category is ‘Pending’ or ‘Success’ then yields None. If the status category is ‘Warning’, ‘Failure’ or ‘Cancel’ then yields a Dataset which should contain an (0008,0058) Failed SOP Instance UID List element, however as this comes from the peer this is not guaranteed and may instead be an empty Dataset.

Raises:

  • RuntimeError – If send_c_get() is called with no established association.

  • ValueError – If no accepted Presentation Context for query_model exists or if unable to encode the Identifier dataset.

See also

C_GET, QueryRetrieveServiceClass, HangingProtocolQueryRetrieveServiceClass, DefinedProcedureProtocolQueryRetrieveServiceClass, ColorPaletteQueryRetrieveServiceClass, ImplantTemplateQueryRetrieveServiceClass, InventoryQueryRetrieveServiceClass, ProtocolApprovalQueryRetrieveServiceClass

References

send_c_move(dataset: Dataset, move_aet: str, query_model: str | UID, msg_id: int = 1, priority: int = 2) → Iterator[tuple[Dataset, Dataset | None]][source]

Send a C-MOVE request to the peer AE.

Yields (status, identifier) pairs for each response from the peer.

The peer will attempt to start a new association with an Storage SCP with AE title move_aet and hence the Storage SCP must be known to the Move SCP. Once the association has been established, the peer will use the C-STORE service to send any matching datasets to the nominated Storage SCP.

Changed in version 1.5: query_model now only accepts a UID string

Changed in version 2.0: move_aet should be str

Parameters:

  • dataset (pydicom.dataset.Dataset) – The C-MOVE request’s Identifier dataset. The exact requirements for the Identifier are Service Class specific (see the DICOM Standard, Part 4).

  • move_aet (str) – The value of the Move Destination parameter for the C-MOVE request, should be the AE title of the Storage SCP for the C-STORE sub-operations performed by the peer.

  • query_model (pydicom.uid.UID or str) – The value to use for the C-MOVE request’s (0000,0002) Affected SOP Class UID parameter, which usually corresponds to the Information Model that is to be used when querying.

  • msg_id (int, optional) – The C-MOVE request’s Message ID, must be between 0 and 65535, inclusive, (default 1).

  • priority (int, optional) –

    The value of the C-MOVE request’s Priority parameter (may not be supported by the peer), one of:

    • 0 - Medium

    • 1 - High

    • 2 - Low (default)

Yields:

  • status (pydicom.dataset.Dataset) – If the peer timed out, aborted or sent an invalid response then yields an empty Dataset. If a response was received from the peer then yields a Dataset containing at least a (0000,0900) Status element, and depending on the returned value, may optionally contain additional elements (see the DICOM Standard, Part 7, Section 9.1.4.1.7 and Annex C).

    The status for the requested C-MOVE operation should be one of the following values, but as the value depends on the peer this can’t be assumed:

    General C-MOVE (DICOM Standard, Part 7, 9.1.4.1.7 and Annex C)

    Cancel
    0xFE00 - Sub-operations terminated due to Cancel indication
    Success
    0x0000 - Sub-operations complete: no failures
    Failure
    0x0122 - SOP class not supported

    Query/Retrieve Service, Hanging Protocol Query/Retrieve Service, Defined Procedure Protocol Query/Retrieve Service, Color Palette Query/Retrieve Service , Implant Template Query/Retrieve Service, Inventory Query/Retrieve Service and Protocol Approval Query/Retrieve Service specific (DICOM Standard, Part 4, Annexes C, U, Y, X, BB, HH and JJ):

    Failure
    0xA701 - Out of resources: unable to calculate number of matches
    0xA702 - Out of resources: unable to perform sub-operations
    0xA801 - Move destination unknown
    0xA900 - Identifier does not match SOP Class
    0xAA00 - None of the frames requested were found in the SOP instance
    0xAA01 - Unable to create new object for this SOP class
    0xAA02 - Unable to extract frames
    0xAA03 - Time-based request received for a non-time-based original SOP Instance
    0xAA04 - Invalid request
    0xC000 to 0xCFFF - Unable to process
    Pending
    0xFF00 - Sub-operations are continuing
    Warning
    0xB000 - Sub-operations complete: one or more failures

  • identifier (pydicom.dataset.Dataset or None) – If the status category is ‘Pending’ or ‘Success’ then yields None. If the status category is ‘Warning’, ‘Failure’ or ‘Cancel’ then yields a Dataset which should contain an (0008,0058) Failed SOP Instance UID List element, however as this comes from the peer this is not guaranteed and may instead be an empty Dataset.

Raises:

  • RuntimeError – If send_c_move() is called with no established association.

  • ValueError – If no accepted Presentation Context for query_model exists or if unable to encode the dataset.

See also

C_MOVE, QueryRetrieveServiceClass, HangingProtocolQueryRetrieveServiceClass, ColorPaletteQueryRetrieveServiceClass, ImplantTemplateQueryRetrieveServiceClass, InventoryQueryRetrieveServiceClass, ProtocolApprovalQueryRetrieveServiceClass

References

send_c_store(dataset: str | Path | Dataset, msg_id: int = 1, priority: int = 2, originator_aet: str | None = None, originator_id: int | None = None) → Dataset[source]

Send a C-STORE request to the peer AE.

Changed in version 2.0:

  • Changed dataset parameter to either be a dataset or the path to a dataset.

  • originator_aet should now be str

Parameters:

  • dataset (pydicom.dataset.Dataset, str or pathlib.Path) – The DICOM dataset to send to the peer or the file path to the dataset to be sent. If a file path then the dataset will be read and decoded using dcmread().

  • msg_id (int, optional) – The C-STORE request’s Message ID, must be between 0 and 65535, inclusive, (default 1).

  • priority (int, optional) –

    The value of the C-STORE request’s Priority parameter (may not be supported by the peer), one of:

    • 0 - Medium

    • 1 - High

    • 2 - Low (default)

  • originator_aet (str, optional) – The value of the Move Originator Application Entity Title parameter for the C-STORE request. This is the AE title of the peer that invoked the C-MOVE operation for which this C-STORE sub-operation is being performed (default None).

  • originator_id (int, optional) – The value of the Move Originator Message ID parameter for the C-STORE request. This is the original Message ID parameter value for the C-MOVE request primitive for which the C-STORE sub-operation is being performed (default None).

Returns:

status – If the peer timed out, aborted or sent an invalid response then returns an empty Dataset. If a valid response was received from the peer then returns a Dataset containing at least a (0000,0900) Status element, and, depending on the returned value, may optionally contain additional elements (see DICOM Standard, Part 7, Annex C).

The status for the requested C-STORE operation should be one of the following, but as the value depends on the peer SCP this can’t be assumed:

General C-STORE (DICOM Standard, Part 7, 9.1.1.1.9 and Annex C):

Success
0x0000 - Success
Failure
0x0117 - Invalid SOP instance
0x0122 - SOP class not supported
0x0124 - Not authorised
0x0210 - Duplicate invocation
0x0211 - Unrecognised operation
0x0212 - Mistyped argument

Storage Service and Non-Patient Object Storage Service specific (DICOM Standard, Part 4, Annexes B.2.3 and GG):

Failure
0xA700 to 0xA7FF - Out of resources
0xA900 to 0xA9FF - Data set does not match SOP class
0xC000 to 0xCFFF - Cannot understand
Warning
0xB000 - Coercion of data elements
0xB006 - Element discarded
0xB007 - Data set does not match SOP class

Non-Patient Object Service Class specific (DICOM Standard, Part 4, Annex GG.4.2)

Failure
0xA700 - Out of resources
0xA900 - Data set does not match SOP class
0xC000 - Cannot understand

Return type:

pydicom.dataset.Dataset

Raises:

  • RuntimeError – If send_c_store() is called with no established association.

  • AttributeError – If dataset is missing (0008,0016) SOP Class UID, (0008,0018) SOP Instance UID elements or the (0002,0010) Transfer Syntax UID file meta information element.

  • ValueError – If no accepted Presentation Context for dataset exists or if unable to encode the dataset.

See also

C_STORE, StorageServiceClass, NonPatientObjectStorageServiceClass, STORE_SEND_CHUNKED_DATASET

References

send_n_action(dataset: Dataset, action_type: int, class_uid: str | UID, instance_uid: str | UID, msg_id: int = 1, meta_uid: str | UID | None = None) → tuple[Dataset, Dataset | None][source]

Send an N-ACTION request to the peer AE.

Changed in version 1.4: Added meta_uid keyword parameter

Parameters:

  • dataset (pydicom.dataset.Dataset or None) – The dataset that will be sent as the Action Information parameter in the request, or None if not required.

  • action_type (int) – The value of the request’s (0000,1008) Action Type ID parameter.

  • class_uid (pydicom.uid.UID) – The UID to be sent for the request’s (0000,0003) Requested SOP Class UID parameter.

  • instance_uid (pydicom.uid.UID) – The UID to be sent for the request’s (0000,1001) Requested SOP Instance UID parameter.

  • msg_id (int, optional) – The request’s Message ID parameter value, must be between 0 and 65535, inclusive, (default 1).

  • meta_uid (pydicom.uid.UID, optional) – If the service class operates under a presentation context negotiated using a Meta SOP Class rather than a standard SOP Class (such as with Print Management service class and its Basic Grayscale Print Management Meta SOP Class) then this value will be used to determine the corresponding presentation context.

Returns:

  • status (pydicom.dataset.Dataset) – If the peer timed out, aborted or sent an invalid response then returns an empty Dataset. If a response was received from the peer then returns a Dataset containing at least a (0000,0900) Status element, and depending on the returned value, may optionally contain additional elements (see the DICOM Standard, Part 7, Section 10.1.4.1.10 and Annex C).

    General N-ACTION (DICOM Standard, Part 7, Section 10.1.4 and Annex C)

    Success
    0x0000 - Successful operation
    Failure
    0x0110 - Processing failure
    0x0112 - No such SOP Instance
    0x0114 - No such argument
    0x0115 - Invalid argument value
    0x0117 - Invalid object instance
    0x0118 - No such SOP Class
    0x0119 - Class-Instance conflict
    0x0123 - No such action
    0x0124 - Not authorised
    0x0210 - Duplicate invocation
    0x0211 - Unrecognised operation
    0x0212 - Mistyped argument
    0x0213 - Resource limitation

    Storage Management Service specific (DICOM Standard Part 4, Annex KK.2.2.3):

    Warning
    0xB010 - Attribute list error - One or more of Key Attributes are not supported for matching

  • action_reply (pydicom.dataset.Dataset or None) – If the status category is ‘Success’ or ‘Warning’ then a Dataset containing attributes corresponding to those supplied in the Action Reply. Because Action Reply is optional the returned Dataset may be empty.

    If the status category is ‘Failure’ or if the peer timed-out, aborted, or sent an invalid response then returns None.

See also

N_ACTION, ApplicationEventLoggingServiceClass, MediaCreationManagementServiceClass, PrintManagementServiceClass, RTMachineVerificationServiceClass, StorageCommitmentServiceClass, StorageManagementServiceClass, UnifiedProcedureStepServiceClass

References

send_n_create(dataset: Dataset, class_uid: str | UID, instance_uid: str | UID | None = None, msg_id: int = 1, meta_uid: str | UID | None = None) → tuple[Dataset, Dataset | None][source]

Send an N-CREATE request to the peer AE.

Changed in version 1.4: Added meta_uid keyword parameter

Parameters:

  • dataset (pydicom.dataset.Dataset or None) – The dataset that will be sent as the Attribute List parameter in the N-CREATE request, or None if not required.

  • class_uid (pydicom.uid.UID) – The UID to be sent for the request’s (0000,0002) Affected SOP Class UID parameter.

  • instance_uid (pydicom.uid.UID, optional) – The UID to be sent for the request’s (0000,1000) Affected SOP Instance UID parameter.

  • msg_id (int, optional) – The request’s Message ID parameter value, must be between 0 and 65535, inclusive, (default 1).

  • meta_uid (pydicom.uid.UID, optional) – If the service class operates under a presentation context negotiated using a Meta SOP Class rather than a standard SOP Class (such as with Print Management service class and its Basic Grayscale Print Management Meta SOP Class) then this value will be used to determine the corresponding presentation context.

Returns:

  • status (pydicom.dataset.Dataset) – If the peer timed out, aborted or sent an invalid response then returns an empty Dataset. If a response was received from the peer then returns a Dataset containing at least a (0000,0900) Status element, and depending on the returned value, may optionally contain additional elements (see the DICOM Standard, Part 7, Section 10.1.5.1.6 and Annex C).

    General N-CREATE (DICOM Standard, Part 7, Section 10.1.5 and Annex C)

    Success
    0x0000 - Successful operation
    Failure
    0x0110 - Processing failure
    0x0112 - No such SOP Instance
    0x0114 - No such argument
    0x0115 - Invalid argument value
    0x0117 - Invalid object instance
    0x0118 - No such SOP Class
    0x0119 - Class-Instance conflict
    0x0123 - No such action
    0x0124 - Not authorised
    0x0210 - Duplicate invocation
    0x0211 - Unrecognised operation
    0x0212 - Mistyped argument
    0x0213 - Resource limitation

    Print Management Service specific (DICOM Standard Part 4, Annex H.4.1.2.1.2, H.4.2.2.1.2 and H.4.9.2.1.2):

    Warning
    0xB600 - Memory allocation not supported
    0xB605 - Requested Min Density or Max Density outside of printer’s operating range. The printer will use its respective minimum or maximum density value instead
    Failure
    0xC616 - There is an existing Film Box that has not been printed and N-ACTION at the Film Session level is not supported. A new Film Box will not be created when a previous Film Box has not been printed

    Media Creation Management Service specific (DICOM Standard Part 4, Annex S.3.2.1.4):

    Failure
    0xA510 - Failed: an initiate media creation action has already been received for this SOP Instance

    Unified Procedure Step Service specific (DICOM Standard Part 4, Annex CC.2.5.4):

    Warning
    0xB300 - THE UPS was created with modifications
    Failure
    0xC309 - The provided value of UPS State was not ‘SCHEDULED’

    RT Machine Verification Service specific (DICOM Standard Part 4, Annex DD.3.2.1.2):

    Failure
    0xC221 - The Referenced Fraction Group Number does not exist in the referenced plan
    0xC222 - No beams exist within the referenced fraction group
    0xC223 - SCU already verifying and cannot currently process this request
    0xC227 - No such object instance - Referenced RT Plan not found

  • attribute_list (pydicom.dataset.Dataset or None) – If the status category is ‘Success’ or ‘Warning’ then a Dataset containing attributes corresponding to those supplied in the Attribute List. Because Attribute List is optional the returned Dataset may be empty.

    If the status category is ‘Failure’ or if the peer timed-out, aborted, or sent an invalid response then returns None.

See also

N_CREATE, InstanceAvailabilityNotificationServiceClass, MediaCreationManagementServiceClass, PrintManagementServiceClass, ProcedureStepServiceClass, RTMachineVerificationServiceClass, UnifiedProcedureStepServiceClass

References

send_n_delete(class_uid: str | UID, instance_uid: str | UID, msg_id: int = 1, meta_uid: str | UID | None = None) → Dataset[source]

Send an N-DELETE request to the peer AE.

Changed in version 1.4: Added meta_uid keyword parameter

Parameters:

  • class_uid (pydicom.uid.UID) – The UID to be sent for the request’s (0000,0003) Requested SOP Class UID parameter.

  • instance_uid (pydicom.uid.UID) – The UID to be sent for the request’s (0000,1001) Requested SOP Instance UID parameter.

  • msg_id (int, optional) – The request’s Message ID parameter value, must be between 0 and 65535, inclusive, (default 1).

  • meta_uid (pydicom.uid.UID, optional) – If the service class operates under a presentation context negotiated using a Meta SOP Class rather than a standard SOP Class (such as with Print Management service class and its Basic Grayscale Print Management Meta SOP Class) then this value will be used to determine the corresponding presentation context.

Returns:

status – If the peer timed out, aborted or sent an invalid response then returns an empty Dataset. If a response was received from the peer then returns a Dataset containing at least a (0000,0900) Status element, and depending on the returned value, may optionally contain additional elements (see the DICOM Standard, Part 7, Section 10.1.6.1.7 and Annex C).

General N-DELETE (DICOM Standard, Part 7, Section 10.1.6 and Annex C)

Success
0x0000 - Successful operation
Failure
0x0110 - Processing failure
0x0112 - No such SOP Instance
0x0117 - Invalid object instance
0x0118 - No such SOP Class
0x0119 - Class-Instance conflict
0x0124 - Not authorised
0x0210 - Duplicate invocation
0x0211 - Unrecognised operation
0x0212 - Mistyped argument
0x0213 - Resource limitation

Return type:

pydicom.dataset.Dataset

See also

N_DELETE, PrintManagementServiceClass, RTMachineVerificationServiceClass

References

send_n_event_report(dataset: Dataset, event_type: int, class_uid: str | UID, instance_uid: str | UID, msg_id: int = 1, meta_uid: str | UID | None = None) → tuple[Dataset, Dataset | None][source]

Send an N-EVENT-REPORT request to the peer AE.

Changed in version 1.4: Added meta_uid keyword parameter

Parameters:

  • dataset (pydicom.dataset.Dataset or None) – The dataset that will be sent as the Event Information parameter in the N-EVENT-REPORT request, if no Event Information parameter is needed then None.

  • event_type (int) – The value to be sent for the request’s (0000,1002) Event Type ID parameter.

  • class_uid (pydicom.uid.UID) – The UID to be sent for the request’s (0000,0003) Affected SOP Class UID parameter.

  • instance_uid (pydicom.uid.UID) – The UID to be sent for the request’s (0000,1000) Affected SOP Instance UID parameter.

  • msg_id (int, optional) – The request’s Message ID parameter value, must be between 0 and 65535, inclusive, (default 1).

  • meta_uid (pydicom.uid.UID, optional) – If the service class operates under a presentation context negotiated using a Meta SOP Class rather than a standard SOP Class (such as with Print Management service class and its Basic Grayscale Print Management Meta SOP Class) then this value will be used to determine the corresponding presentation context.

Returns:

  • status (pydicom.dataset.Dataset) – If the peer timed out, aborted or sent an invalid response then returns an empty Dataset. If a response was received from the peer then returns a Dataset containing at least a (0000,0900) Status element, and depending on the returned value, may optionally contain additional elements (see the DICOM Standard, Part 7, Section 10.1.1.1.8 and Annex C).

    General N-EVENT-REPORT (DICOM Standard, Part 7, Section 10.1.1 and Annex C)

    Success
    0x0000 - Successful operation
    Failure
    0x0110 - Processing failure
    0x0112 - No such SOP Instance
    0x0113 - No such event type
    0x0114 - No such argument
    0x0115 - Invalid argument value
    0x0117 - Invalid object instance
    0x0118 - No such SOP Class
    0x0119 - Class-Instance conflict
    0x0210 - Duplicate invocation
    0x0211 - Unrecognised operation
    0x0212 - Mistyped argument
    0x0213 - Resource limitation

  • event_reply (pydicom.dataset.Dataset or None) – If the status category is ‘Success’ or ‘Warning’ then a Dataset containing attributes corresponding to those supplied in the Event Reply. Because Event Reply is optional the returned Dataset may be empty.

    If the status category is ‘Failure’ or if the peer timed-out, aborted, or sent an invalid response then returns None.

See also

N_EVENT_REPORT, PrintManagementServiceClass, ProcedureStepServiceClass, RTMachineVerificationServiceClass, StorageCommitmentServiceClass, StorageManagementServiceClass, UnifiedProcedureStepServiceClass

References

send_n_get(identifier_list: list[BaseTag], class_uid: str | UID, instance_uid: str | UID, msg_id: int = 1, meta_uid: str | UID | None = None) → tuple[Dataset, Dataset | None][source]

Send an N-GET request to the peer AE.

Changed in version 1.4: Added meta_uid keyword parameter

Parameters:

  • identifier_list (list of pydicom.tag.BaseTag) – A list of DICOM Data Element tags to be sent for the request’s (0000,1005) Attribute Identifier List parameter. Should either be a list of pydicom BaseTag objects or a list of values that is acceptable for creating them.

  • class_uid (pydicom.uid.UID) – The UID to be sent for the request’s (0000,0003) Requested SOP Class UID parameter.

  • instance_uid (pydicom.uid.UID) – The UID to be sent for the request’s (0000,1001) Requested SOP Instance UID parameter.

  • msg_id (int, optional) – The request’s Message ID parameter value, must be between 0 and 65535, inclusive, (default 1).

  • meta_uid (pydicom.uid.UID, optional) – If the service class operates under a presentation context negotiated using a Meta SOP Class rather than a standard SOP Class (such as with Print Management service class and its Basic Grayscale Print Management Meta SOP Class) then this value will be used to determine the corresponding presentation context.

Returns:

  • status (pydicom.dataset.Dataset) – If the peer timed out, aborted or sent an invalid response then returns an empty Dataset. If a response was received from the peer then returns a Dataset containing at least a (0000,0900) Status element, and depending on the returned value, may optionally contain additional elements (see the DICOM Standard, Part 7, Section 10.1.2.1.9 and Annex C).

    General N-GET (DICOM Standard, Part 7, Section 10.1.2 and Annex C)

    Success
    0x0000 - Successful operation
    Warning
    0x0107 - Attribute list error
    Failure
    0x0110 - Processing failure
    0x0112 - No such SOP Instance
    0x0117 - Invalid object instance
    0x0118 - No such SOP Class
    0x0119 - Class-Instance conflict
    0x0122 - SOP class not supported
    0x0124 - Not authorised
    0x0210 - Duplicate invocation
    0x0211 - Unrecognised operation
    0x0212 - Mistyped argument
    0x0213 - Resource limitation

    Modality Performed Procedure Step Management Service and Media Creation Management Service specific (DICOM Standard, Part 4, Annex F.8.2.1.4 and Annex S.3.2.4.4):

    Warning
    0x0001 - Requested optional Attributes are not supported

    Unified Procedure Step Service specific (DICOM Standard, Part 4, Annex CC.2.7.4):

    Warning
    0x0001 - Requested optional Attributes are not supported
    Failure
    0xC307 - Specified SOP Instance UID doesn’t exist or is not a UPS Instance managed by this SCP

    RT Machine Verification Service specific (DICOM Standard, Part 4, Annex DD.3.2.2.3):

    Failure
    0xC112 - Applicable Machine Verification Instance not found

  • attribute_list (pydicom.dataset.Dataset or None) – If the status category is ‘Success’ or ‘Warning’ then a Dataset containing attributes corresponding to those supplied in the Attribute List. Because Attribute List is optional the returned Dataset may be empty.

    If the status category is ‘Failure’ or if the peer timed-out, aborted, or sent an invalid response then returns None.

See also

N_GET, DisplaySystemManagementServiceClass, MediaCreationManagementServiceClass, PrintManagementServiceClass, ProcedureStepServiceClass, RTMachineVerificationServiceClass, UnifiedProcedureStepServiceClass

References

send_n_set(dataset: Dataset, class_uid: str | UID, instance_uid: str | UID, msg_id: int = 1, meta_uid: str | UID | None = None) → tuple[Dataset, Dataset | None][source]

Send an N-SET request to the peer AE.

Changed in version 1.4: Added meta_uid keyword parameter

Parameters:

  • dataset (pydicom.dataset.Dataset) – The dataset that will be sent as the Modification List parameter in the N-SET request.

  • class_uid (pydicom.uid.UID) – The UID to be sent for the request’s (0000,0003) Requested SOP Class UID parameter.

  • instance_uid (pydicom.uid.UID) – The UID to be sent for the request’s (0000,1001) Requested SOP Instance UID parameter.

  • msg_id (int, optional) – The request’s Message ID parameter value, must be between 0 and 65535, inclusive, (default 1).

  • meta_uid (pydicom.uid.UID, optional) – If the service class operates under a presentation context negotiated using a Meta SOP Class rather than a standard SOP Class (such as with Print Management service class and its Basic Grayscale Print Management Meta SOP Class) then this value will be used to determine the corresponding presentation context.

Returns:

  • status (pydicom.dataset.Dataset) – If the peer timed out, aborted or sent an invalid response then returns an empty Dataset. If a response was received from the peer then returns a Dataset containing at least a (0000,0900) Status element, and depending on the returned value, may optionally contain additional elements (see the DICOM Standard, Part 7, Section 10.1.3.1.9 and Annex C).

    General N-SET (DICOM Standard, Part 7, Section 10.1.3 and Annex C)

    Success
    0x0000 - Successful operation
    Warning
    0x0107 - Attribute list error
    0x0116 - Attribute value out of range
    Failure
    0x0105 - No such attribute
    0x0106 - Invalid attribute value
    0x0110 - Processing failure
    0x0112 - No such SOP Instance
    0x0117 - Invalid object instance
    0x0118 - No such SOP Class
    0x0119 - Class-Instance conflict
    0x0121 - Missing attribute value
    0x0122 - SOP class not supported
    0x0124 - Not authorised
    0x0210 - Duplicate invocation
    0x0211 - Unrecognised operation
    0x0212 - Mistyped argument
    0x0213 - Resource limitation

    Print Management Service specific (DICOM Standard Part 4, Annex H.4.1.2.1.2, H.4.2.2.1.2, H.4.3.1.2.1.2 and H.4.3.2.2.1.2):

    Warning
    0xB600 - Memory allocation not supported
    0xB604 - Image size larger than image box size, the image has been demagnified
    0xB605 - Requested Min Density or Max Density outside of printer’s operating range. The printer will use its respective minimum or maximum density value instead
    0xB609 - Image size is larger than the Image Box. The Image has been cropped to fit
    0xB60A - Image size or Combined Print Image size is larger than the Image Box size. The Image or Combined Print Image has been decimated to fit
    Failure
    0xC603 - Image size is larger than image box size
    0xC605 - Insufficient memory in printer to store the image
    0xC613 - Combined Print Image size is larger than the Image Box size
    0xC616 - There is an existing Film Box that has not been printed and N-ACTION at the Film Session level is not supported. A new Film Box will not be created when a previous Film Box has not been printed

    Unified Procedure Step Service specific (DICOM Standard, Part 4, Annex CC.2.6.4):

    Warning
    0x0001 - Requested optional attributes are not supported
    0xB305 - Coerced invalid values to valid values
    Failure
    0xC300 - The UPS may no longer be updated
    0xC301 - The correct Transaction UID was not provided
    0xC307 - Specified SOP Instance UID does not exist or is not a UPS Instance managed by this SCP
    0xC310 - The UPS is not in the ‘IN PROGRESS’ state

    RT Machine Verification Service specific (DICOM Standard, Part 4, Annex DD.3.2.1.2):

    Failure
    0xC224 - Reference Beam Number not found within the referenced Fraction Group
    0xC225 - Referenced device or accessory not supported
    0xC226 - Referenced device or accessory not found with the referenced beam

  • attribute_list (pydicom.dataset.Dataset or None) – If the status category is ‘Success’ or ‘Warning’ then a Dataset containing attributes corresponding to those supplied in the Attribute List. Because Attribute List is optional the returned Dataset may be empty.

    If the status category is ‘Failure’ or if the peer timed-out, aborted, or sent an invalid response then returns None.

See also

N_SET, PrintManagementServiceClass, ProcedureStepServiceClass, RTMachineVerificationServiceClass, UnifiedProcedureStepServiceClass

References

set_socket(socket: AssociationSocket) → None[source]

Set the socket to use for communicating with the peer.

Parameters:

socket (transport.AssociationSocket) – The socket to use.

Raises:

RuntimeError – If the Association already has a socket set.

unbind(event: NotificationEvent | InterventionEvent, handler: Callable) → None[source]

Unbind a callable handler from an event.

Added in version 1.3.

Parameters:

  • event (namedtuple) – The event to unbind the function from.

  • handler (callable) – The function that will no longer be called if the event occurs.