PDU Types (pdu)

Module contains implementation of the DICOM Protocol Data Units (or PDU for short). Each PDU is represented by class that follows the simple interface that has only two methods:

  • encode - method that transforms PDU into raw byte string

  • decode - factory method that transforms raw byte string to PDU instance

In addition to PDUs, several items and sub-items classes can be found in this module. These classes are:

The rest sub-items for User Data Information Item can be found at User Data Sub-items (userdataitems).

pynetdicom2.pdu.PDU_HEADER_LENGTH = 6

Length of the fixed header that begins every PDU: 1 byte PDU type, 1 reserved byte and a 4-byte PDU length field (PS3.7 9.3). PDU length fields count only the bytes that follow this header.

class pynetdicom2.pdu.AAssociatePDUBase(called_ae_title: str, calling_ae_title: str, variable_items: list[ApplicationContextItem | PresentationContextItemRQ | PresentationContextItemAC | UserInformationItem], protocol_version: int = 1, reserved1: int = 0, reserved2: int = 0, reserved3: Iterable[int] | None = None)

Base class for A-ASSOCIATE-RQ and A-ASSOCIATE-AC PDUs

Variables:

  • called_ae_title – called AE Title (remote AET)

  • calling_ae_title – calling AE Title (local AET)

  • variable_items – list of various variable items

  • protocol_version – protocol version, should be 1

  • reserved1 – reserved field, defaults 0

  • reserved2 – reserved field, defaults 0

  • reserved3 – reserved field, defaults eight 0

property pdu_length: int

PDU length without the header

Returns:

PDU length

encode() → bytes

Encodes PDU into bytes

Returns:

encoded PDU

classmethod decode(raw_bytes: bytes) → AAssociatePDUBase

Factory method. Decodes A-ASSOCIATE-RQ PDU instance from raw string.

Parameters:

raw_bytes – bytes containing binary representation of the A-ASSOCIATE-RQ PDU

Returns:

decoded PDU

total_length() → int

Returns total PDU length including the header

Returns:

total PDU length

class pynetdicom2.pdu.AAssociateRqPDU(called_ae_title: str, calling_ae_title: str, variable_items: list[ApplicationContextItem | PresentationContextItemRQ | PresentationContextItemAC | UserInformationItem], protocol_version: int = 1, reserved1: int = 0, reserved2: int = 0, reserved3: Iterable[int] | None = None)

This class represents the A-ASSOCIATE-RQ PDU

Refer to DICOM PS3.8 9.3.2 for A-ASSOCIATE-RQ structure and fields

pdu_type: ClassVar[int] = 1

PDU Type

class pynetdicom2.pdu.AAssociateAcPDU(called_ae_title: str, calling_ae_title: str, variable_items: list[ApplicationContextItem | PresentationContextItemRQ | PresentationContextItemAC | UserInformationItem], protocol_version: int = 1, reserved1: int = 0, reserved2: int = 0, reserved3: Iterable[int] | None = None)

This class represents the A-ASSOCIATE-AC PDU

Refer to DICOM PS3.8 9.3.3 for A-ASSOCIATE-AC structure and fields

pdu_type: ClassVar[int] = 2

PDU Type

class pynetdicom2.pdu.AAssociateRjPDU(result: int, source: int, reason_diag: int, reserved1: int = 0, reserved2: int = 0)

This class represents the A-ASSOCIATE-RJ PDU (PS 3.8 9.3.4)

You can look up possible values for fields in DICOM standard (referenced above) or in documentation for AssociationRejectedError

Variables:

  • result – Result PDU field. (unsigned byte)

  • source – Source PDU field (unsigned byte)

  • reason_diag – Reason/Diag. PDU field (unsigned byte)

  • reserved1 – Reserved field, defaults to 0 (unsigned byte)

  • reserved2 – Reserved field, defaults to 0 (unsigned byte)

pdu_type: ClassVar[int] = 3

PDU Type

pdu_length = 4

This PDU has fixed length of 4 bytes

encode() → bytes

Converts PDU class to its binary representation

Returns:

PDU as a string of bytes

classmethod decode(rawstring: bytes) → AAssociateRjPDU

Factory method. Decodes A-ASSOCIATE-RJ PDU instance from raw string.

Parameters:

rawstring – rawstring containing binary representation of the A-ASSOCIATE-RJ PDU

Returns:

decoded PDU

classmethod total_length() → int

Returns PDU total length.

These PDUs have a fixed length, so the method always returns the same value regardless of specific instance

Returns:

PDU total length

class pynetdicom2.pdu.PDataTfPDU(data_value_items: list[PresentationDataValueItem], reserved: int = 0)

This class represents the P-DATA-TF PDU (as described in PS 3.8 9.3.5).

Variables:

  • reserved – reserved field, defaults 0

  • data_value_items – list of one of more PresentationDataValueItem

pdu_type: ClassVar[int] = 4

PDU Type

property pdu_length: int

PDU length without the header

Returns:

PDU length

encode() → bytes

Encodes PDataTfPDU into bytes

Returns:

encoded PDU

classmethod decode(rawstring: bytes) → PDataTfPDU

Factory method. Decodes P-DATA-TF PDU instance from raw string.

Parameters:

rawstring – rawstring containing binary representation of the P-DATA-TF PDU

Returns:

decoded PDU

total_length() → int

Returns total PDU length including the header

Returns:

total PDU length

class pynetdicom2.pdu.AReleasePDUBase(reserved1: int = 0, reserved2: int = 0)

Base class for the A-RELEASE-* PDUs.

Variables:

  • reserved1 – reserved field, defaults 0

  • reserved2 – reserved field, defaults 0

pdu_length = 4

Association Release PDUs have fixed length of 4 bytes

encode() → bytes

Encodes PDU into bytes

Returns:

encoded PDU

classmethod decode(rawstring: bytes) → AReleasePDUBase

Factory method. Decodes A-RELEASE-* PDU instance from raw string.

Parameters:

rawstring – rawstring containing binary representation of the A-RELEASE-* PDU

Returns:

decoded PDU

classmethod total_length() → int

Returns PDU total length.

These PDUs have a fixed length, so the method always returns the same value regardless of specific instance

Returns:

PDU total length

class pynetdicom2.pdu.AReleaseRqPDU(reserved1: int = 0, reserved2: int = 0)

This class represents the A-RELEASE-RQ PDU as described in PS 3.8 9.3.6

pdu_type: ClassVar[int] = 5

PDU Type

class pynetdicom2.pdu.AReleaseRpPDU(reserved1: int = 0, reserved2: int = 0)

This class represents the A-RELEASE-RP PDU as described in PS 3.8 9.3.7

pdu_type: ClassVar[int] = 6

PDU Type

class pynetdicom2.pdu.AAbortPDU(source: int, reason_diag: int, reserved1: int = 0, reserved2: int = 0, reserved3: int = 0)

This class represents the A-ABORT PDU as described in PS 3.8 9.3.8

Variables:

  • reserved1 – reserved field, defaults 0

  • reserved2 – reserved field, defaults 0

  • reserved3 – reserved field, defaults 0

  • reserved3 – reserved field, defaults 0

  • source –

    abort source:

    • 0 - DICOM UL service-user (initiated abort)

    • 1 - reserved

    • 2 - DICOM UL service-provider (initiated abort)

  • reason_diag –

    Reason/Diag. value:

    • 0 - reason-not-specified

    • 1 - unrecognized-PDU

    • 2 - unexpected-PDU

    • 3 - reserved

    • 4 - unrecognized-PDU parameter

    • 5 - unexpected-PDU parameter

    • 6 - invalid-PDU-parameter value

pdu_type: ClassVar[int] = 7

PDU Type

pdu_length = 4

Association Abort PDU have fixed length of 4 bytes

encode() → bytes

Encodes AAbortPDU into bytes

Returns:

encoded PDU

classmethod decode(rawstring: bytes) → AAbortPDU

Factory method. Decodes A-ABORT PDU instance from raw string.

Parameters:

rawstring – rawstring containing binary representation of the A-ABORT PDU

Returns:

decoded PDU

classmethod total_length() → int

Returns PDU total length.

These PDUs have a fixed length, so the method always returns the same value regardless of specific instance

Returns:

PDU total length

class pynetdicom2.pdu.ApplicationContextItem(context_name: str, reserved: int = 0)

Application Context Item (PS 3.8 9.3.2.1)

Variables:

  • reserved – reserved field, defaults 0

  • context_name – application context name (OID)

item_type = 16

PDU Item-type

property item_length: int

Item length, excluding the header

Returns:

item length

encode() → bytes

Encodes item into bytes

Returns:

encoded item

classmethod decode(stream: BytesIO) → ApplicationContextItem

Decodes application context item from data stream

Parameters:

stream – raw data stream

Returns:

decoded item

total_length() → int

Total item length, including the header

Returns:

total item length

class pynetdicom2.pdu.PresentationContextItemRQ(context_id: int, abs_sub_item: AbstractSyntaxSubItem, ts_sub_items: list[TransferSyntaxSubItem], reserved1: int = 0, reserved2: int = 0, reserved3: int = 0, reserved4: int = 0)

Presentation Context Item (request) PS 3.8 9.3.2.2

Variables:

  • context_id – presentation context ID

  • abs_sub_item – Abstract Syntax sub-item

  • ts_sub_items – list of Transfer Syntax sub-items

  • reserved1 – reserved field, defaults 0

  • reserved2 – reserved field, defaults 0

  • reserved3 – reserved field, defaults 0

  • reserved4 – reserved field, defaults 0

item_type = 32

PDU Item-type

property item_length: int

Item length, excluding the header

Returns:

item length

encode() → bytes

Encodes item into bytes

Returns:

encoded item

classmethod decode(stream: BytesIO) → PresentationContextItemRQ

Decodes presentation context item ‘request’ from data stream

Parameters:

stream – raw data stream

Returns:

decoded context item

total_length() → int

Total item length, including the header

Returns:

total item length

class pynetdicom2.pdu.PresentationContextItemAC(context_id: int, result_reason: int, ts_sub_item: TransferSyntaxSubItem, reserved1: int = 0, reserved2: int = 0, reserved3: int = 0)

Presentation Context Item (response) PS 3.8 9.3.3.2

Variables:

  • context_id

  • result_reason –

    result/reason, can be one of the following:

    • 0 - acceptance

    • 1 - user-rejection

    • 2 - no-reason (provider rejection)

    • 3 - abstract-syntax-not-supported (provider rejection)

    • 4 - transfer-syntaxes-not-supported (provider rejection)

  • ts_sub_item – list of Transfer Syntax sub-items

  • reserved1 – reserved field, defaults 0

  • reserved2 – reserved field, defaults 0

  • reserved3 – reserved field, defaults 0

item_type = 33

PDU Item-type

property item_length: int

Item length, excluding the header

Returns:

item length

encode() → bytes

Encodes item into bytes

Returns:

encoded item

classmethod decode(stream: BytesIO) → PresentationContextItemAC

Decodes presentation context item ‘accepted’ from data stream

Parameters:

stream – raw data stream

Returns:

decoded context item

total_length() → int

Total item length, including the header

Returns:

total item length

class pynetdicom2.pdu.AbstractSyntaxSubItem(name: str, reserved: int = 0)

Abstract Syntax Sub-Item (PS 3.8 9.3.2.2.1)

Variables:

  • name – Abstract Syntax name (UID) as byte string

  • reserved – reserved field. In most cases value should be default (0x00). Standard advises against testing this field value.

item_type = 48

Item type

property item_length: int

Item length, excluding the header

Returns:

item length

encode() → bytes

Encodes item into bytes

Returns:

encoded item

classmethod decode(stream: BytesIO) → AbstractSyntaxSubItem

Decodes abstract syntax sub-item from data stream

Parameters:

stream – raw data stream

Returns:

decoded abstract syntax sub-item

total_length() → int

Total item length, including the header

Returns:

total item length

class pynetdicom2.pdu.TransferSyntaxSubItem(name: str, reserved: int = 0)

Transfer Syntax Sub-Item (PS 3.8 9.3.2.2.2)

Variables:

  • name – Transfer Syntax name (UID) as byte string

  • reserved – reserved field. In most cases value should be default (0x00). Standard advises against testing this field value.

item_type = 64

Item type

property item_length: int

Item length, excluding the header

Returns:

item length

encode() → bytes

Encodes item into bytes

Returns:

encoded item

classmethod decode(stream: BytesIO) → TransferSyntaxSubItem

Decodes transfer syntax sub-item from data stream

Parameters:

stream – raw data stream

Returns:

decoded transfer syntax sub-item

total_length() → int

Total item length, including the header

Returns:

total item length

class pynetdicom2.pdu.UserInformationItem(user_data: list[ImplementationClassUIDSubItem | MaximumLengthSubItem | ImplementationVersionNameSubItem | AsynchronousOperationsWindowSubItem | ScpScuRoleSelectionSubItem | SOPClassExtendedNegotiationSubItem | UserIdentityNegotiationSubItem | UserIdentityNegotiationSubItemAc | GenericUserDataSubItem], reserved: int = 0)

User Information Item (PS 3.8 9.3.2.3)

Variables:

  • reserved – reserved field. In most cases value should be default (0x00). Standard advises against testing this field value.

  • user_data –

    list containing the following:

property item_length: int

Item length, excluding the header

Returns:

item length

encode() → bytes

Encodes item into bytes

Returns:

encoded item

static sub_items(stream: BytesIO) → Iterable[ImplementationClassUIDSubItem | MaximumLengthSubItem | ImplementationVersionNameSubItem | AsynchronousOperationsWindowSubItem | ScpScuRoleSelectionSubItem | SOPClassExtendedNegotiationSubItem | UserIdentityNegotiationSubItem | UserIdentityNegotiationSubItemAc | GenericUserDataSubItem]

Reads User Information sub-items from a data stream

Parameters:

stream – raw data stream

Raises:

exceptions.PDUProcessingError – [description]

Yield:

User Information sub-item

classmethod decode(stream: BytesIO) → UserInformationItem

Decodes user information item from data stream

Parameters:

stream – raw data stream

Returns:

decoded user information item

total_length() → int

Total item length, including the header

Returns:

total item length

class pynetdicom2.pdu.PresentationDataValueItem(context_id: int, data_value: bytes)

Presentation Data Value Item (PS 3.8 9.3.5.1)

Variables:

  • context_id – presentation context ID

  • data_value – item value (bytes)

property item_length: int

Item length, excluding the header

Returns:

item length

encode() → bytes

Encodes item into bytes

Returns:

encoded item

classmethod decode(stream: BytesIO) → PresentationDataValueItem

Decodes presentation data value item from data stream

Presentation data value is left in raw string format. The Application Entity is responsible for dealing with it.

Parameters:

stream – raw data stream

Returns:

decoded presentation data value item

total_length() → int

Total item length, including the header

Returns:

total item length