# pydicom.dataelem.DataElement

class pydicom.dataelem.DataElement(tag: int | str | tuple[int, int], VR: str, value: Any, file_value_tell: int | None = None, is_undefined_length: bool = False, already_converted: bool = False, validation_mode: int | None = None)

  Contain and manipulate a DICOM Element.

  Examples

  While its possible to create a new `DataElement` directly and add it to a `Dataset`:

      >>> from pydicom import Dataset
      >>> elem = DataElement(0x00100010, 'PN', 'CITIZEN^Joan')
      >>> ds = Dataset()
      >>> ds.add(elem)

  Its far more convenient to use a `Dataset` to add a new `DataElement`, as the VR and tag are determined automatically from the DICOM dictionary:

      >>> ds = Dataset()
      >>> ds.PatientName = 'CITIZEN^Joan'

  Empty DataElement objects (e.g. with VM = 0) show an empty string as value for text VRs and None for non-text (binary) VRs:

      >>> ds = Dataset()
      >>> ds.PatientName = None
      >>> ds.PatientName
      ''

      >>> ds.BitsAllocated = None
      >>> ds.BitsAllocated

      >>> str(ds.BitsAllocated)
      'None'

  descripWidth

    For string display, this is the maximum width of the description field (default `35`).

    Type:

      int

  is_undefined_length

    Indicates whether the length field for the element was `0xFFFFFFFFL` (ie undefined).

    Type:

      bool

  maxBytesToDisplay

    For string display, elements with values containing data which is longer than this value will display `"array of # bytes"` (default `16`).

    Type:

      int

  showVR

    For string display, include the element’s VR just before it’s value (default `True`).

    Type:

      bool

  tag

    The element’s tag.

    Type:

      pydicom.tag.BaseTag

  validation_mode

    The mode used to validate the element’s value. See `Settings.writing_validation_mode` for more information.

    Type:

      int

  VR

    The element’s Value Representation.

    Type:

      str

  __init__(tag: int | str | tuple[int, int], VR: str, value: Any, file_value_tell: int | None = None, is_undefined_length: bool = False, already_converted: bool = False, validation_mode: int | None = None) → None

    Create a new `DataElement`.

    Parameters:

      - tag (int | str | tuple[int, int]) – The DICOM (group, element) tag in any form accepted by `Tag()` such as `'PatientName'`, `(0x10, 0x10)`, `0x00100010`, etc.

      - VR (str) – The 2 character DICOM value representation (see DICOM Standard, Part 5, Section 6.2).

      - value (Any) –

        The value of the data element, the allowed type depends on the VR and includes:

        - a single `str` value

        - an `int` or `int`

        - a `list` or `tuple` containing only a single type of item such as `str`, `int` or `float`

        - a raw `bytes` value

      - file_value_tell (int, optional) – The byte offset to the start of the encoded element value.

      - is_undefined_length (bool, optional) – Used internally to store whether the length field for this element was `0xFFFFFFFF`, i.e. ‘undefined length’. Default is `False`.

      - already_converted (bool, optional) – Used to determine whether or not the element’s value requires conversion to a value with VM > 1. Default is `False`.

      - validation_mode (int, optional) – Defines if values are validated and how validation errors are handled.

  Methods

  `__init__`(tag, VR, value[, file_value_tell, ...]) | Create a new `DataElement`.
  `clear`() | Clears the value, e.g. sets it to the configured empty value.
  `from_json`(dataset_class, tag, vr, value, ...) | Return a `DataElement` from a DICOM JSON Model attribute object.
  `to_json`([bulk_data_threshold, ...]) | Return a JSON representation of the `DataElement`.
  `to_json_dict`(bulk_data_element_handler, ...) | Return a dictionary representation of the `DataElement` conforming to the DICOM JSON Model as described in the DICOM Standard, Part 18, Annex F.
  `validate`(value) | Validate the current value against the DICOM standard.

  Attributes

  `VM` | Return the value multiplicity of the element as `int`.
  `descripWidth` |
  `empty_value` | Return the value for an empty element.
  `is_buffered` | Return `True` if the element's value is a `io.BufferedIOBase` instance, `False` otherwise.
  `is_empty` | Return `True` if the element has no value.
  `is_private` | Return `True` if the element's tag is private.
  `is_raw` |
  `is_retired` | Return the element's retired status as `bool`.
  `keyword` | Return the element's keyword (if known) as `str`.
  `maxBytesToDisplay` |
  `name` | Return the DICOM dictionary name for the element as `str`.
  `repval` | Return a `str` representation of the element's value.
  `showVR` |
  `value` | Get or set the element's value.

  property VM: int

    Return the value multiplicity of the element as `int`.

    Changed in version 3.0: SQ elements now always return a VM of `1`.

  clear() → None

    Clears the value, e.g. sets it to the configured empty value.

    See `empty_value_for_VR()`.

  property empty_value: bytes | list[str] | None | str | PersonName

    Return the value for an empty element.

    See `empty_value_for_VR()` for more information.

    Returns:

      The value this data element is assigned on decoding if it is empty.

    Return type:

      str or None

  classmethod from_json(dataset_class: type[Dataset], tag: str, vr: str, value: Any, value_key: str | None, bulk_data_uri_handler: Callable[[str, str, str], None | str | int | float | bytes] | Callable[[str], None | str | int | float | bytes] | None = None) → DataElement

    Return a `DataElement` from a DICOM JSON Model attribute object.

    Parameters:

      - dataset_class (dataset.Dataset derived class) – The class object to use for SQ element items.

      - tag (str) – The data element’s tag as uppercase hex.

      - vr (str) – The data element’s value representation (VR).

      - value (str or list[None | str | int | float | bytes | dict]) – The data element’s value(s).

      - value_key (str or None) – The attribute name for value, should be one of: `{"Value", "InlineBinary", "BulkDataURI"}`. If the element’s VM is `0` and none of the keys are used then will be `None`.

      - bulk_data_uri_handler (callable or None) – Callable function that accepts either the tag, vr and “BulkDataURI” value or just the “BulkDataURI” value of the JSON representation of a data element and returns the actual value of that data element (retrieved via DICOMweb WADO-RS). If no bulk_data_uri_handler is specified (default) then the corresponding element will have an “empty” value such as `""`, `b""` or `None` depending on the vr (i.e. the Value Multiplicity will be 0).

    Return type:

      DataElement

  property is_buffered: bool

    Return `True` if the element’s value is a `io.BufferedIOBase` instance, `False` otherwise.

  property is_empty: bool

    Return `True` if the element has no value.

  property is_private: bool

    Return `True` if the element’s tag is private.

    Added in version 2.1.

  property is_retired: bool

    Return the element’s retired status as `bool`.

    For officially registered DICOM Data Elements this will be `True` if the retired status as given in the DICOM Standard, Part 6, Table 6-1 is ‘RET’. For private or unknown elements this will always be `False`.

  property keyword: str

    Return the element’s keyword (if known) as `str`.

    For officially registered DICOM Data Elements this will be the Keyword as given in Table 6-1. For private or unknown elements this will return an empty string `''`.

  property name: str

    Return the DICOM dictionary name for the element as `str`.

    Returns:

      - For officially registered DICOM Data Elements this will be the Name as given in Table 6-1.

      - For private elements known to pydicom this will be the Name in the format `'[name]'`.

      - For unknown private elements this will be `'Private tag data'`.

      - Otherwise returns an empty string `''`.

    Return type:

      str

  property repval: str

    Return a `str` representation of the element’s value.

  to_json(bulk_data_threshold: int = 1024, bulk_data_element_handler: Callable[[DataElement], str] | None = None, dump_handler: Callable[[dict[str, Any]], str] | None = None) → str

    Return a JSON representation of the `DataElement`.

    Parameters:

      - bulk_data_threshold (int, optional) – Size of base64 encoded data element above which a value will be provided in form of a “BulkDataURI” rather than “InlineBinary”. Ignored if no bulk_data_element_handler is given.

      - bulk_data_element_handler (callable, optional) – Callable that accepts a bulk :class`data element <pydicom.dataelem.DataElement>` and returns the “BulkDataURI” as a `str` for retrieving the value of the data element via DICOMweb WADO-RS.

      - dump_handler (callable, optional) – Callable function that accepts a `dict` of `{str: Any}` and returns the serialized (dumped) JSON `str` (by default uses `json.dumps()`).

    Returns:

      Mapping representing a JSON encoded data element

    Return type:

      str

    See also

    `Dataset.to_json`

  to_json_dict(bulk_data_element_handler: Callable[[DataElement], str] | None, bulk_data_threshold: int) → dict[str, Any]

    Return a dictionary representation of the `DataElement` conforming to the DICOM JSON Model as described in the DICOM Standard, Part 18, Annex F.

    Parameters:

      - bulk_data_element_handler (callable or None) – Callable that accepts a bulk :class`data element <pydicom.dataelem.DataElement>` and returns the “BulkDataURI” as a `str` for retrieving the value of the data element via DICOMweb WADO-RS.

      - bulk_data_threshold (int) – Size of base64 encoded data element above which a value will be provided in form of a “BulkDataURI” rather than “InlineBinary”. Ignored if no bulk_data_element_handler is given.

    Returns:

      Mapping representing a JSON encoded data element as `{str: Any}`.

    Return type:

      dict

  validate(value: Any) → None

    Validate the current value against the DICOM standard. See `validate_value()` for details.

  property value: Any

    Get or set the element’s value.

    Parameters:

      val (Any) – The value to use to set the element’s value, should be an appropriate type for the VR. The value will be validated in accordance with the element’s `validation_mode`.

    Returns:

      The element’s value.

    Return type:

      Any