pynetdicom.ae.ApplicationEntity¶

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

Represents a DICOM Application Entity (AE).

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

__init__(ae_title: str = 'PYNETDICOM') → None[source]¶

Create a new Application Entity.

Changed in version 2.0: ae_title should be str

Parameters:: ae_title (str, optional) – The AE title of the Application Entity as an ASCII string (default: '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`	Get or set the ACSE timeout value (in seconds).
`active_associations`	Return a list of the AE's active `Association` threads.
`ae_title`	Get or set the AE title as `str`.
`connection_timeout`	Get or set the connection timeout (in seconds).
`dimse_timeout`	Get or set the DIMSE timeout (in seconds).
`implementation_class_uid`	Get or set the Implementation Class UID as `UID`.
`implementation_version_name`	Get or set the Implementation Version Name as `str`.
`maximum_associations`	Get or set the number of maximum simultaneous associations as `int`.
`maximum_pdu_size`	Get or set the maximum PDU size accepted by the AE as `int`.
`network_timeout`	Get or set the network timeout (in seconds).
`requested_contexts`	Get or set a list of the requested `PresentationContext` items.
`require_called_aet`	Get or set whether the Called AE Title must match the AE title.
`require_calling_aet`	Get or set the required calling AE title as a list of `str`.
`supported_contexts`	Get or set a list of the supported `PresentationContext` items.

property acse_timeout: float | None¶

Get or set the ACSE timeout value (in seconds).

Parameters:: value (Union[int, float, None]) – The maximum amount of time (in seconds) to wait for association related messages. A value of None means no timeout. (default: 30)

property active_associations: List[Association]¶

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

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

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 Verification object.

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

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 Verification
>>> ae = AE()
>>> ae.add_requested_context(Verification, 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 Verification
>>> ae = AE()
>>> ae.add_requested_context(
...     Verification, [ImplicitVRLittleEndian, ExplicitVRBigEndian]
... )
>>> ae.add_requested_context(Verification, 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 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) – 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: DEFAULT_TRANSFER_SYNTAXES).
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 Verification object.

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

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 Verification
>>> ae = AE()
>>> ae.add_supported_context(Verification, 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 Verification
>>> ae = AE()
>>> ae.add_supported_context(
...     Verification, [ImplicitVRLittleEndian, ExplicitVRBigEndian]
... )
>>> ae.add_supported_context(Verification, 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: str¶

Get or set the AE title as str.

Changed in version 2.0: ae_title should be set using str and returns str rather than bytes

Parameters:: value (str) – The AE title to use for the local Application Entity as an ASCII string.
Returns:: The local Application Entity’s AE title.
Return type:: str

associate(addr: str, port: int, contexts: list[PresentationContext] | None = None, ae_title: str = 'ANY-SCP', max_pdu: int = 16382, ext_neg: List[MaximumLengthNotification | ImplementationClassUIDNotification | ImplementationVersionNameNotification | AsynchronousOperationsWindowNegotiation | SCP_SCU_RoleSelectionNegotiation | SOPClassExtendedNegotiation | UserIdentityNegotiation | SOPClassCommonExtendedNegotiation] | None = None, bind_address: Tuple[str, int] = ('', 0), tls_args: Tuple[SSLContext, str] | None = None, evt_handlers: List[tuple[NotificationEvent | InterventionEvent, Callable] | tuple[NotificationEvent | InterventionEvent, Callable, list[Any]]] | None = None) → Association[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

Changed in version 2.0:

ae_title should now be str

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 (str, optional) – The peer’s AE title, will be used as the Called AE Title parameter value (default '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 PDV size is unlimited.
ext_neg (list of UserInformation objects, optional) –
A list containing optional extended negotiation items:
- AsynchronousOperationsWindowNegotiation (0 or 1 item)
- SCP_SCU_RoleSelectionNegotiation (0 to N items)
- SOPClassCommonExtendedNegotiation (0 to N items)
- SOPClassExtendedNegotiation (0 to N items)
- UserIdentityNegotiation (0 or 1 item)
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 connection_timeout: float | None¶

Get or set the connection timeout (in seconds).

Added in version 2.0.

Parameters:: value (int, float or None) – The maximum amount of time (in seconds) to wait for a TCP connection to be established. A value of None (default) means no timeout. The value is passed to socket.settimeout() and is only used during the connection phase of an association request.

property dimse_timeout: float | None¶

Get or set the DIMSE timeout (in seconds).

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

property implementation_class_uid: UID¶

Get or set the Implementation Class UID as UID.

Parameters:: value (str or pydicom.uid.UID) – The association request’s Implementation Class UID value.

property implementation_version_name: str | None¶

Get or set the Implementation Version Name as str.

Parameters:: value (str or None) – If set then an Implementation Version Name item with the corresponding value will be added to the association request, otherwise no item will be sent.
Returns:: The set Implementation Version Name.
Return type:: str or None

Return an association server.

Added in version 1.5.

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.

Changed in version 2.0: ae_title should now be str

Parameters:: server_class (object, optional) – The class object to use when creating the server. Defaults to AssociationServer if not used.
Returns:: The object passed via server_class or the AssociationServer.
Return type:: object

property maximum_associations: int¶

Get or set the number of maximum simultaneous associations as int.

Parameters:: value (int) – The maximum number of simultaneous associations requested by remote AEs. This does not include the number of associations requested by the local AE (default 10).

property maximum_pdu_size: int¶

Get or set the maximum PDU size accepted by the AE as int.

Parameters:: value (int) – The maximum PDU receive size in bytes. A value of 0 means the PDU size is unlimited (default: 16382). Increasing this value or setting it to unlimited is an effective way of improving the throughput when sending large amounts of data due to the reduced DIMSE messaging overhead.

property network_timeout: float | None¶

Get or set the network timeout (in seconds).

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

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 Verification object.

>>> from pynetdicom import AE
>>> from pynetdicom.sop_class import Verification
>>> ae = AE()
>>> ae.add_requested_context(Verification)
>>> ae.remove_requested_context(Verification)
>>> 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 Verification
>>> ae.add_requested_context(Verification, ImplicitVRLittleEndian)
>>> print(ae.requested_contexts[0])
Abstract Syntax: Verification SOP Class
Transfer Syntax(es):
    =Implicit VR Little Endian
>>> ae.remove_requested_context(Verification, 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 Verification
>>> ae = AE()
>>> ae.add_requested_context(Verification)
>>> 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(
...     Verification, [ImplicitVRLittleEndian, ExplicitVRLittleEndian]
... )
>>> print(ae.requested_contexts[0])
Abstract Syntax: Verification SOP Class
Transfer Syntax(es):
    =Explicit VR Big Endian

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 Verification object.

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

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 Verification
>>> ae = AE()
>>> ae.add_supported_context(Verification, ImplicitVRLittleEndian)
>>> print(ae.supported_contexts[0])
Abstract Syntax: Verification SOP Class
Transfer Syntax(es):
    =Implicit VR Little Endian
>>> ae.remove_supported_context(Verification, 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 Verification
>>> ae = AE()
>>> ae.add_supported_context(Verification)
>>> 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(
...     Verification, [ImplicitVRLittleEndian, ExplicitVRLittleEndian]
... )
>>> print(ae.supported_contexts[0])
Abstract Syntax: Verification SOP Class
Transfer Syntax(es):
    =Explicit VR Big Endian

property requested_contexts: list[PresentationContext]¶

Get or set a list of the requested PresentationContext items.

Examples

Set the requested presentation contexts using an inbuilt list of service specific PresentationContext items:

>>> from pynetdicom import AE, StoragePresentationContexts
>>> ae = AE()
>>> ae.requested_contexts = StoragePresentationContexts

Set the requested presentation contexts using a list of PresentationContext items:

>>> from pydicom.uid import ImplicitVRLittleEndian
>>> from pynetdicom import AE
>>> from pynetdicom.presentation import PresentationContext
>>> context = PresentationContext()
>>> context.abstract_syntax = '1.2.840.10008.1.1'
>>> context.transfer_syntax = [ImplicitVRLittleEndian]
>>> ae = AE()
>>> ae.requested_contexts = [context]
>>> print(ae.requested_contexts[0])
Abstract Syntax: Verification SOP Class
Transfer Syntax(es):
    =Implicit VR Little Endian

Parameters:: contexts (list of PresentationContext) – The presentation contexts to request when acting as an SCU.
Raises:: ValueError – If trying to add more than 128 requested presentation contexts.