pynetdicom.ae.ApplicationEntity¶
-
class
pynetdicom.ae.
ApplicationEntity
(ae_title=b'PYNETDICOM')¶ 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 there is no maximum size (default: 16382)
- Type
int
-
require_calling_aet
¶ 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). (Association acceptor only).
- Type
list of bytes
-
require_called_aet
¶ If True, the association request’s Called AE Title value must match AE.ae_title (default False). (Association acceptor only).
- Type
bool
-
__init__
(ae_title=b'PYNETDICOM')¶ 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.
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
Return the ACSE timeout value.
Return a list of the AE’s active
Association
threads.Return the AE title as length 16
bytes
.Return the DIMSE timeout.
Return the current Implementation Class UID.
Return the current Implementation Version Name.
Return the number of maximum associations as int.
Return the maximum PDU size accepted by the AE as int.
Return the network timeout.
Return a list of the requested
PresentationContext
items.Return whether the Called AE Title must match the AE title.
Return the required calling AE title as a list of bytes.
Return a list of the supported
PresentationContexts
items.-
property
acse_timeout
Return the ACSE timeout value.
-
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)¶ 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 1. 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 2. 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
- 1
DICOM Standard, Part 8, Section 7.1.1.13
- 2
DICOM Standard, Part 8, Table 9-18
-
add_supported_context
(abstract_syntax, transfer_syntax=None, scu_role=None, scp_role=None)¶ 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 the 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 isNone
then both are assumed to be) and use the default roles.If
True
accept the proposed SCU roleIf
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 isNone
then both are assumed to be) and use the default roles.If
True
accept the proposed SCP roleIf
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 Little Endian =Explicit VR Big 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
Return 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)¶ Request an association with a remote AE.
An
Association
thread is returned whether or not the association is accepted and should be checked usingAssociation.is_established
before sending any messages. The returned thread will only be running if the association was established.- 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 AE.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).
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 inSSLContext.wrap_sockets()
. If no tls_args is supplied then TLS will not be used (default).evt_handlers (list of 2-tuple, optional) – A list of (event, handler), where event is an
evt.EVT_*
event tuple and handler is a callable function that will be bound to the event. The handler should take a singleevent.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
- Raises
RuntimeError – If called with no requested presentation contexts (i.e. contexts has not been supplied and
ApplicationEntity.requested_contexts
is empty).
-
property
dimse_timeout
Return the DIMSE timeout.
-
property
implementation_class_uid
¶ Return the current Implementation Class UID.
-
property
implementation_version_name
¶ Return the current Implementation Version Name.
-
property
maximum_associations
Return the number of maximum associations as int.
-
property
maximum_pdu_size
Return the maximum PDU size accepted by the AE as int.
-
property
network_timeout
Return the network timeout.
-
remove_requested_context
(abstract_syntax, transfer_syntax=None)¶ 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(ex) 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.reqested_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)¶ 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(ex) 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
¶ Return a list of the requested
PresentationContext
items.- Returns
The SCU’s requested presentation contexts.
- Return type
list of presentation.PresentationContext
-
property
require_called_aet
Return whether the Called AE Title must match the AE title.
-
property
require_calling_aet
Return the required calling AE title as a list of bytes.
-
shutdown
()¶ Stop any active association servers and threads.
-
start_server
(address, block=True, ssl_context=None, evt_handlers=None, ae_title=None, contexts=None)¶ Start the AE as an association acceptor.
If set to non-blocking then a running
ThreadedAssociationServer
instance will be returned. This can be stopped usingshutdown()
.- 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
SSLContext
instance to use to wrap the client sockets, otherwise ifNone
then no TLS will be used (default).evt_handlers (list of 2-tuple, optional) – A list of (event, handler), where event is an
evt.EVT_*
event tuple and handler is a callable function that will be bound to the event. The handler should take a singleevent.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.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
AE.supported_contexts
property will be used instead (default).
- Returns
If block is
False
then returns the server instance, otherwise returnsNone
.- Return type
-
property
supported_contexts
¶ Return a list of the supported
PresentationContexts
items.- Returns
The SCP’s supported presentation contexts, ordered by abstract syntax.
- Return type
list of presentation.PresentationContext
-