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

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

acse_timeout: Return the ACSE timeout value.

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 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 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
... )

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 using Association.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 in `SSLContext.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 single `event.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 `ApplicationEntity.requested_contexts` is empty).

dimse_timeout: Return the DIMSE timeout.

implementation_class_uid¶: Return the current Implementation Class UID.

implementation_version_name¶: Return the current Implementation Version Name.

maximum_associations: Return the number of maximum associations as int.

maximum_pdu_size: Return the maximum PDU size accepted by the AE as int.

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

requested_contexts¶

Return a list of the requested PresentationContext items.

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

require_called_aet: Return whether the Called AE Title must match the AE title.

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 using shutdown().

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 if `None` 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 single `event.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 returns `None`.
Return type:	transport.ThreadedAssociationServer or None

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