pynetdicom.ae.ApplicationEntity¶

class pynetdicom.ae.ApplicationEntity(ae_title=b'PYNETDICOM')[source]¶

Represents a DICOM Application Entity (AE).

An AE may be a Service Class Provider (SCP), a Service Class User (SCU) or both.

acse_timeout¶

The maximum amount of time (in seconds) to wait for association related messages. A value of None means no timeout. (default: 30)

Type: int or float or None

ae_title¶

The local AE’s AE title.

Type: bytes

dimse_timeout¶

The maximum amount of time (in seconds) to wait for DIMSE related messages. A value of None means no timeout. (default: 30)

Type: int or float or None

network_timeout¶

The maximum amount of time (in seconds) to wait for network messages. A value of None means no timeout. (default: 60)

Type: int or float or None

maximum_associations¶

The maximum number of simultaneous associations requested by remote AEs. Note that this does not include the number of associations requested by the local AE (default 10).

Type: int

maximum_pdu_size¶

The maximum PDU receive size in bytes. A value of 0 means the PDU size is unlimited (default: 16382)

Type: int

require_calling_aet¶

Association acceptor only. If not an empty list, the association request’s Calling AE Title value must match one of the values in require_calling_aet. If an empty list then no matching will be performed (default).

Type: list of bytes

require_called_aet¶

Association acceptor only. If True, the association request’s Called AE Title value must match ae_title (default False).

Type: bool

__init__(ae_title=b'PYNETDICOM')[source]¶

Create a new Application Entity.

Parameters: ae_title (bytes, optional) – The AE title of the Application Entity (default: b'PYNETDICOM')

Methods

`__init__`([ae_title])	Create a new Application Entity.
`add_requested_context`(abstract_syntax[, …])	Add a presentation context to be proposed when requesting an association.
`add_supported_context`(abstract_syntax[, …])	Add a presentation context to be supported when accepting association requests.
`associate`(addr, port[, contexts, ae_title, …])	Request an association with a remote AE.
`make_server`(address[, ae_title, contexts, …])	Return an association server.
`remove_requested_context`(abstract_syntax[, …])	Remove a requested presentation context.
`remove_supported_context`(abstract_syntax[, …])	Remove a supported presentation context.
`shutdown`()	Stop any active association servers and threads.
`start_server`(address[, block, ssl_context, …])	Start the AE as an association acceptor.

Attributes

`acse_timeout`	The ACSE timeout value (in seconds).
`active_associations`	Return a list of the AE’s active `Association` threads.
`ae_title`	The AE title as length 16 `bytes`.
`dimse_timeout`	The DIMSE timeout (in seconds).
`implementation_class_uid`	The current Implementation Class UID as `str`.
`implementation_version_name`	The current Implementation Version Name as `bytes`.
`maximum_associations`	The number of maximum simultaneous associations as `int`.
`maximum_pdu_size`	The maximum PDU size accepted by the AE as `int`.
`network_timeout`	The network timeout (in seconds).
`requested_contexts`	A list of the requested `PresentationContext` items.
`require_called_aet`	Whether the Called AE Title must match the AE title.
`require_calling_aet`	The required calling AE title as a list of `bytes`.
`supported_contexts`	A list of the supported `PresentationContext` items.

property acse_timeout¶: The ACSE timeout value (in seconds).

property active_associations¶

Return a list of the AE’s active Association threads.

Returns: A list of all active association threads, both requestors and acceptors.
Return type: list of association.Association

add_requested_context(abstract_syntax, transfer_syntax=None)[source]¶

Add a presentation context to be proposed when requesting an association.

When an SCU sends an association request to a peer it includes a list of presentation contexts it would like the peer to support. This method adds a single PresentationContext to the list of the SCU’s requested contexts.

Only 128 presentation contexts can be included in the association request. Multiple presentation contexts may be requested with the same abstract syntax.

To remove a requested context or one or more of its transfer syntaxes see the remove_requested_context() method.

Parameters

abstract_syntax (str or pydicom.uid.UID) – The abstract syntax of the presentation context to request.
transfer_syntax (str/pydicom.uid.UID or list of str/pydicom.uid.UID) – The transfer syntax(es) to request (default: Implicit VR Little Endian, Explicit VR Little Endian, Explicit VR Big Endian).

Raises

ValueError – If 128 requested presentation contexts have already been added.

Examples

Add a requested presentation context for Verification SOP Class with the default transfer syntaxes by using its UID value.

>>> from pynetdicom import AE
>>> ae = AE()
>>> ae.add_requested_context('1.2.840.10008.1.1')
>>> print(ae.requested_contexts[0])
Abstract Syntax: Verification SOP Class
Transfer Syntax(es):
    =Implicit VR Little Endian
    =Explicit VR Little Endian
    =Explicit VR Big Endian

Add a requested presentation context for Verification SOP Class with the default transfer syntaxes by using the inbuilt VerificationSOPClass object.

>>> from pynetdicom import AE
>>> from pynetdicom.sop_class import VerificationSOPClass
>>> ae = AE()
>>> ae.add_requested_context(VerificationSOPClass)

Add a requested presentation context for Verification SOP Class with a transfer syntax of Implicit VR Little Endian.

>>> from pydicom.uid import ImplicitVRLittleEndian
>>> from pynetdicom import AE
>>> from pynetdicom.sop_class import VerificationSOPClass
>>> ae = AE()
>>> ae.add_requested_context(VerificationSOPClass, ImplicitVRLittleEndian)
>>> print(ae.requested_contexts[0])
Abstract Syntax: Verification SOP Class
Transfer Syntax(es):
    =Implicit VR Little Endian

Add two requested presentation contexts for Verification SOP Class using different transfer syntaxes for each.

>>> from pydicom.uid import (
...     ImplicitVRLittleEndian, ExplicitVRLittleEndian, ExplicitVRBigEndian
... )
>>> from pynetdicom import AE
>>> from pynetdicom.sop_class import VerificationSOPClass
>>> ae = AE()
>>> ae.add_requested_context(
...     VerificationSOPClass, [ImplicitVRLittleEndian, ExplicitVRBigEndian]
... )
>>> ae.add_requested_context(VerificationSOPClass, ExplicitVRLittleEndian)
>>> len(ae.requested_contexts)
2
>>> print(ae.requested_contexts[0])
Abstract Syntax: Verification SOP Class
Transfer Syntax(es):
    =Implicit VR Little Endian
    =Explicit VR Big Endian
>>> print(ae.requested_contexts[1])
Abstract Syntax: Verification SOP Class
Transfer Syntax(es):
    =Explicit VR Little Endian

References

DICOM Standard, Part 8, Section 7.1.1.13
DICOM Standard, Part 8, Table 9-18

add_supported_context(abstract_syntax, transfer_syntax=None, scu_role=None, scp_role=None)[source]¶

Add a presentation context to be supported when accepting association requests.

When an association request is received from a peer it supplies a list of presentation contexts that it would like the SCP to support. This method adds a PresentationContext to the list of the SCP’s supported contexts.

Where the abstract syntax is already supported the transfer syntaxes will be extended by those supplied in transfer_syntax. To remove a supported context or one or more of its transfer syntaxes see the remove_supported_context() method.

Parameters

abstract_syntax (str, pydicom.uid.UID or sop_class.SOPClass) – The abstract syntax of the presentation context to be supported.
transfer_syntax (str/pydicom.uid.UID or list of str/pydicom.uid.UID) – The transfer syntax(es) to support (default: Implicit VR Little Endian, Explicit VR Little Endian, Explicit VR Big Endian).
scu_role (bool or None, optional) –
If the association requestor includes an SCP/SCU Role Selection Negotiation item for this context then:
- If None then ignore the proposal (if either scp_role or scu_role is None then both are assumed to be) and use the default roles.
- If True accept the proposed SCU role
- If False reject the proposed SCU role
scp_role (bool or None, optional) –
If the association requestor includes an SCP/SCU Role Selection Negotiation item for this context then:
- If None then ignore the proposal (if either scp_role or scu_role is None then both are assumed to be) and use the default roles.
- If True accept the proposed SCP role
- If False reject the proposed SCP role

Examples

Add support for presentation contexts with an abstract syntax of Verification SOP Class and the default transfer syntaxes by using its UID value.

>>> from pynetdicom import AE
>>> ae = AE()
>>> ae.add_supported_context('1.2.840.10008.1.1')
>>> print(ae.supported_contexts[0])
Abstract Syntax: Verification SOP Class
Transfer Syntax(es):
    =Implicit VR Little Endian
    =Explicit VR Little Endian
    =Explicit VR Big Endian

Add support for presentation contexts with an abstract syntax of Verification SOP Class and the default transfer syntaxes by using the inbuilt VerificationSOPClass object.

>>> from pynetdicom import AE
>>> from pynetdicom.sop_class import VerificationSOPClass
>>> ae = AE()
>>> ae.add_supported_context(VerificationSOPClass)

Add support for presentation contexts with an abstract syntax of Verification SOP Class and a transfer syntax of Implicit VR Little Endian.

>>> from pydicom.uid import ImplicitVRLittleEndian
>>> from pynetdicom import AE
>>> from pynetdicom.sop_class import VerificationSOPClass
>>> ae = AE()
>>> ae.add_supported_context(VerificationSOPClass, ImplicitVRLittleEndian)
>>> print(ae.supported_contexts[0])
Abstract Syntax: Verification SOP Class
Transfer Syntax(es):
    =Implicit VR Little Endian

Add support for presentation contexts with an abstract syntax of Verification SOP Class and transfer syntaxes of Implicit VR Little Endian and Explicit VR Big Endian and then update the context to also support Explicit VR Little Endian.

>>> from pydicom.uid import (
...     ImplicitVRLittleEndian, ExplicitVRLittleEndian, ExplicitVRBigEndian
... )
>>> from pynetdicom import AE
>>> from pynetdicom.sop_class import VerificationSOPClass
>>> ae = AE()
>>> ae.add_supported_context(
...     VerificationSOPClass, [ImplicitVRLittleEndian, ExplicitVRBigEndian]
... )
>>> ae.add_supported_context(VerificationSOPClass, ExplicitVRLittleEndian)
>>> print(ae.supported_contexts[0])
Abstract Syntax: Verification SOP Class
Transfer Syntax(es):
    =Implicit VR Little Endian
    =Explicit VR Big Endian
    =Explicit VR Little Endian

Add support for CT Image Storage and if the association requestor includes an SCP/SCU Role Selection Negotiation item for CT Image Storage requesting the SCU and SCP roles then accept the proposal.

>>> from pynetdicom import AE
>>> from pynetdicom.sop_class import CTImageStorage
>>> ae = AE()
>>> ae.add_supported_context(CTImageStorage, scu_role=True, scp_role=True)

property ae_title¶: The AE title as length 16 bytes.

associate(addr, port, contexts=None, ae_title=b'ANY-SCP', max_pdu=16382, ext_neg=None, bind_address=('', 0), tls_args=None, evt_handlers=None)[source]¶

Request an association with a remote AE.

An Association thread is returned whether or not the association is accepted and should be checked using Association.is_established before sending any messages. The returned thread will only be running if the association was established.

Changed in version 1.2: Added bind_address and tls_arg keyword parameters

Changed in version 1.3: Added evt_handlers keyword parameter

Changed in version 1.5: evt_handlers now takes a list of 2- or 3-tuples

Parameters

addr (str) – The peer AE’s TCP/IP address.
port (int) – The peer AE’s listen port number.
contexts (list of presentation.PresentationContext, optional) – The presentation contexts that will be requested by the AE for support by the peer. If not used then the presentation contexts in the requested_contexts property will be requested instead.
ae_title (bytes, optional) – The peer’s AE title, will be used as the Called AE Title parameter value (default b'ANY-SCP').
max_pdu (int, optional) – The maximum PDV receive size in bytes to use when negotiating the association (default 16832). A value of 0 means the PDU size is unlimited.
ext_neg (list of UserInformation objects, optional) – Used if extended association negotiation is required.
bind_address (2-tuple, optional) – The (host, port) to bind the Association’s communication socket to, default ('', 0).
tls_args (2-tuple, optional) – If TLS is required then this should be a 2-tuple containing a (ssl_context, server_hostname), where ssl_context is the ssl.SSLContext instance to use to wrap the client socket and server_hostname is the value to use for the corresponding keyword argument in wrap_socket(). If no tls_args is supplied then TLS will not be used (default).
evt_handlers (list of 2- or 3-tuple, optional) – A list of (event, handler) or (event, handler, args), where event is an evt.EVT_* event tuple, handler is a callable function that will be bound to the event and args is a list of objects that will be passed to handler as optional extra arguments. At a minimum, handler should take an Event parameter and may return or yield objects depending on the exact event that the handler is bound to. For more information see the documentation.

Returns

assoc – If the association was established then a running Association thread, otherwise returns a thread that hasn’t been started.

Return type

association.Association

Raises

RuntimeError – If called with no requested presentation contexts (i.e. contexts has not been supplied and requested_contexts is empty).

property dimse_timeout¶: The DIMSE timeout (in seconds).

property implementation_class_uid¶: The current Implementation Class UID as str.

property implementation_version_name¶: The current Implementation Version Name as bytes.

make_server(address, ae_title=None, contexts=None, ssl_context=None, evt_handlers=None, server_class=None, **kwargs)[source]¶

Return an association server.

Allows the use of a custom association server class.

Accepts the same parameters as start_server(). Additional keyword parameters are passed to the constructor of server_class.

New in version 1.5.

property maximum_associations¶: The number of maximum simultaneous associations as int.

property maximum_pdu_size¶: The maximum PDU size accepted by the AE as int.

property network_timeout¶: The network timeout (in seconds).

remove_requested_context(abstract_syntax, transfer_syntax=None)[source]¶

Remove a requested presentation context.

Depending on the supplied parameters one of the following will occur:

abstract_syntax alone - all contexts with a matching abstract syntax all be removed.
abstract_syntax and transfer_syntax - for all contexts with a matching abstract syntax; if the supplied transfer_syntax list contains all of the context’s requested transfer syntaxes then the entire context will be removed. Otherwise only the matching transfer syntaxes will be removed from the context (and the context will remain with one or more transfer syntaxes).

Parameters

abstract_syntax (str, pydicom.uid.UID or sop_class.SOPClass) – The abstract syntax of the presentation context you wish to stop requesting when sending association requests.
transfer_syntax (UID str or list of UID str, optional) – The transfer syntax(es) you wish to stop requesting. If a list of str/UID then only those transfer syntaxes specified will no longer be requested. If not specified then the abstract syntax and all associated transfer syntaxes will no longer be requested (default).

Examples

Remove all requested presentation contexts with an abstract syntax of Verification SOP Class using its UID value.

>>> from pynetdicom import AE
>>> ae = AE()
>>> ae.add_requested_context('1.2.840.10008.1.1')
>>> print(ae.requested_contexts[0])
Abstract Syntax: Verification SOP Class
Transfer Syntax(es):
    =Implicit VR Little Endian
    =Explicit VR Little Endian
    =Explicit VR Big Endian
>>> ae.remove_requested_context('1.2.840.10008.1.1')
>>> len(ae.requested_contexts)
0

Remove all requested presentation contexts with an abstract syntax of Verification SOP Class using the inbuilt VerificationSOPClass object.

>>> from pynetdicom import AE
>>> from pynetdicom.sop_class import VerificationSOPClass
>>> ae = AE()
>>> ae.add_requested_context(VerificationSOPClass)
>>> ae.remove_requested_context(VerificationSOPClass)
>>> len(ae.requested_contexts)
0

For all requested presentation contexts with an abstract syntax of Verification SOP Class, stop requesting a transfer syntax of Implicit VR Little Endian. If a presentation context exists which only has a single Implicit VR Little Endian transfer syntax then it will be completely removed, otherwise it will be kept with its remaining transfer syntaxes.

Presentation context has only a single matching transfer syntax:

>>> from pydicom.uid import ImplicitVRLittleEndian
>>> from pynetdicom import AE
>>> from pynetdicom.sop_class import VerificationSOPClass
>>> ae.add_requested_context(VerificationSOPClass, ImplicitVRLittleEndian)
>>> print(ae.requested_contexts[0])
Abstract Syntax: Verification SOP Class
Transfer Syntax(es):
    =Implicit VR Little Endian
>>> ae.remove_requested_context(VerificationSOPClass, ImplicitVRLittleEndian)
>>> len(ae.requested_contexts)
0

Presentation context has at least one remaining transfer syntax:

>>> from pydicom.uid import ImplicitVRLittleEndian, ExplicitVRLittleEndian
>>> from pynetdicom import AE
>>> from pynetdicom.sop_class import VerificationSOPClass
>>> ae = AE()
>>> ae.add_requested_context(VerificationSOPClass)
>>> print(ae.requested_contexts[0])
Abstract Syntax: Verification SOP Class
Transfer Syntax(es):
    =Implicit VR Little Endian
    =Explicit VR Little Endian
    =Explicit VR Big Endian
>>> ae.remove_requested_context(
...     VerificationSOPClass, [ImplicitVRLittleEndian, ExplicitVRLittleEndian]
... )
>>> print(ae.requested_contexts[0])
Abstract Syntax: Verification SOP Class
Transfer Syntax(es):
    =Explicit VR Big Endian

remove_supported_context(abstract_syntax, transfer_syntax=None)[source]¶

Remove a supported presentation context.

Depending on the supplied parameters one of the following will occur:

abstract_syntax alone - the entire supported context will be removed.
abstract_syntax and transfer_syntax - If the supplied transfer_syntax list contains all of the context’s supported transfer syntaxes then the entire context will be removed. Otherwise only the matching transfer syntaxes will be removed from the context (and the context will remain with one or more transfer syntaxes).

Parameters

abstract_syntax (str, pydicom.uid.UID or sop_class.SOPClass) – The abstract syntax of the presentation context you wish to stop supporting.
transfer_syntax (UID str or list of UID str, optional) – The transfer syntax(es) you wish to stop supporting. If a list of str/UID then only those transfer syntaxes specified will no longer be supported. If not specified then the abstract syntax and all associated transfer syntaxes will no longer be supported (default).

Examples

Remove the supported presentation context with an abstract syntax of Verification SOP Class using its UID value.

>>> from pynetdicom import AE
>>> ae = AE()
>>> ae.add_supported_context('1.2.840.10008.1.1')
>>> print(ae.supported_contexts[0])
Abstract Syntax: Verification SOP Class
Transfer Syntax(es):
    =Implicit VR Little Endian
    =Explicit VR Little Endian
    =Explicit VR Big Endian
>>> ae.remove_supported_context('1.2.840.10008.1.1')
>>> len(ae.supported_contexts)
0

Remove the supported presentation context with an abstract syntax of Verification SOP Class using the inbuilt VerificationSOPClass object.

>>> from pynetdicom import AE, VerificationPresentationContexts
>>> from pynetdicom.sop_class import VerificationSOPClass
>>> ae = AE()
>>> ae.supported_contexts = VerificationPresentationContexts
>>> ae.remove_supported_context(VerificationSOPClass)

For the presentation contexts with an abstract syntax of Verification SOP Class, stop supporting the Implicit VR Little Endian transfer syntax. If the presentation context only has the single Implicit VR Little Endian transfer syntax then it will be completely removed, otherwise it will be kept with the remaining transfer syntaxes.

Presentation context has only a single matching transfer syntax:

>>> from pydicom.uid import ImplicitVRLittleEndian
>>> from pynetdicom import AE
>>> from pynetdicom.sop_class import VerificationSOPClass
>>> ae = AE()
>>> ae.add_supported_context(VerificationSOPClass, ImplicitVRLittleEndian)
>>> print(ae.supported_contexts[0])
Abstract Syntax: Verification SOP Class
Transfer Syntax(es):
    =Implicit VR Little Endian
>>> ae.remove_supported_context(VerificationSOPClass, ImplicitVRLittleEndian)
>>> len(ae.supported_contexts)
0

Presentation context has at least one remaining transfer syntax:

>>> from pydicom.uid import ImplicitVRLittleEndian, ExplicitVRLittleEndian
>>> from pynetdicom import AE
>>> from pynetdicom.sop_class import VerificationSOPClass
>>> ae = AE()
>>> ae.add_supported_context(VerificationSOPClass)
>>> print(ae.supported_contexts[0])
Abstract Syntax: Verification SOP Class
Transfer Syntax(es):
    =Implicit VR Little Endian
    =Explicit VR Little Endian
    =Explicit VR Big Endian
>>> ae.remove_supported_context(
...     VerificationSOPClass, [ImplicitVRLittleEndian, ExplicitVRLittleEndian]
... )
>>> print(ae.supported_contexts[0])
Abstract Syntax: Verification SOP Class
Transfer Syntax(es):
    =Explicit VR Big Endian

property requested_contexts¶

A list of the requested PresentationContext items.

Returns: The SCU’s requested presentation contexts.
Return type: list of presentation.PresentationContext

property require_called_aet¶: Whether the Called AE Title must match the AE title.

property require_calling_aet¶: The required calling AE title as a list of bytes.

shutdown()[source]¶: Stop any active association servers and threads.

New in version 1.2.

start_server(address, block=True, ssl_context=None, evt_handlers=None, ae_title=None, contexts=None)[source]¶

Start the AE as an association acceptor.

New in version 1.2.

If set to non-blocking then a running ThreadedAssociationServer instance will be returned. This can be stopped using shutdown().

Changed in version 1.3: Added evt_handlers keyword parameter

Changed in version 1.4: Added ae_title and contexts keyword parameters

Changed in version 1.5: evt_handlers now takes a list of 2- or 3-tuples

Parameters

address (2-tuple) – The (host, port) to use when listening for incoming association requests.
block (bool, optional) – If True (default) then the server will be blocking, otherwise it will start the server in a new thread and be non-blocking.
ssl_context (ssl.SSLContext, optional) – If TLS is required then this should the ssl.SSLContext instance to use to wrap the client sockets, otherwise if None then no TLS will be used (default).
evt_handlers (list of 2- or 3-tuple, optional) – A list of (event, handler) or (event, handler, args), where event is an evt.EVT_* event tuple, handler is a callable function that will be bound to the event and args is a list of objects that will be passed to handler as optional extra arguments. At a minimum, handler should take an Event parameter and may return or yield objects depending on the exact event that the handler is bound to. For more information see the documentation.
ae_title (bytes, optional) – The AE title to use for the local SCP. Leading and trailing spaces are non-significant. If this keyword parameter is not used then the AE title from the ae_title property will be used instead (default).
contexts (list of presentation.PresentationContext, optional) – The presentation contexts that will be supported by the SCP. If not used then the presentation contexts in the supported_contexts property will be used instead (default).

Returns

If block is False then returns the server instance, otherwise returns None.

Return type

transport.ThreadedAssociationServer or None

property supported_contexts¶

A list of the supported PresentationContext items.

Returns: The SCP’s supported presentation contexts, ordered by abstract syntax.
Return type: list of presentation.PresentationContext