[WIP] [RFC] Framework for extending Dataset

doc/release_notes/v1.4.0.rst

@@ -59,6 +59,7 @@ Enhancements
 * Added optional `handler` argument to
   :func:`~pydicom.dataset.Dataset.decompress`. This lets you specify a
   particular handler, rather than following pydicom's default order (:issue:`537`)
+* Added keyword propery to Tag class.  e.g. Tag(0x7fe00010).keyword give 'PixelData'
 * Added :func:`~pydicom.pixel_data_handlers.util.apply_voi_lut` function for
   applying VOI LUTs or windowing operations.
 * Added support for (7fe0,0008) *Float Pixel Data* and (7fe0,0009) *Double
@@ -69,3 +70,4 @@ Changes
 .......
 
 * :func:`~pydicom.encaps.get_frame_offsets` now returns whether the Basic Offset Table is empty and a list of the offsets.
+

pydicom/dataset.py

@@ -352,6 +352,12 @@ class Dataset(dict):
     # Python 2: Classes defining __eq__ should flag themselves as unhashable
     __hash__ = None
 
+    # Dataset extension tag handlers.
+    # Format {tag: handler class, ...},
+    # where handler class defines get_item and set_item,
+    #   possibly, get_attr and set_attr if desired
+    _handler_classes = {}
+
     def __init__(self, *args, **kwargs):
         """Create a new :class:`Dataset` instance."""
         self._parent_encoding = kwargs.get('parent_encoding', default_encoding)
@@ -382,13 +388,20 @@ def __init__(self, *args, **kwargs):
         # known private creator blocks
         self._private_blocks = {}
 
+        # Instances of handler classes for this Dataset instance
+        # The instance is created if a matching tag is found
+        self._handlers = {}
+        self.handlers_on = True
+
     def __enter__(self):
         """Method invoked on entry to a with statement."""
+        self.handlers_on = False
         return self
 
     def __exit__(self, exc_type, exc_val, exc_tb):
         """Method invoked on exit from a with statement."""
         # Returning False will re-raise any exceptions that occur
+        self.handlers_on = True
         return False
 
     def add(self, data_element):
@@ -429,6 +442,10 @@ def add_new(self, tag, VR, value):
         # use data_element.tag since DataElement verified it
         self._dict[data_element.tag] = data_element
 
+    @classmethod
+    def clear_handler_classes(cls):
+        cls._handler_classes = {}
+
     def data_element(self, name):
         """Return the element corresponding to the element keyword `name`.
 
@@ -791,6 +808,21 @@ def _character_set(self):
 
         return char_set
 
+    def _call_handler(self, tag, method):
+        """
+        tag:Tag
+                tag to handle
+        method: str
+                name of class method to call
+        """
+        if tag not in self._handlers:
+            # Create handler instance for the dataset instance
+            # Pass it a reference to this Dataset instance
+            self._handlers[tag] = self._handler_classes[tag](self)
+        with self as ds:  # handlers turned off in context to avoid inf loop
+            handler_method = getattr(ds._handlers[tag], method)
+            return handler_method(tag)
+
     def __getitem__(self, key):
         """Operator for ``Dataset[key]`` request.
 
@@ -846,6 +878,11 @@ def __getitem__(self, key):
             tag = key
         else:
             tag = Tag(key)
+
+        if self._handler_classes and self.handlers_on:
+            if tag in self._handler_classes:
+                return self._call_handler(tag, "get_item")
+
         data_elem = self._dict[tag]
 
         if isinstance(data_elem, DataElement):

pydicom/extensions.py

@@ -0,0 +1,20 @@
+from pydicom.dataset import Dataset
+from pydicom.tag import Tag
+import warnings
+
+
+def handle_dataset_tags(tags):
+    """Define a decorator to use with classes which handle tags"""
+    def decorator(handler_class):
+        existing_tags = set(Dataset._handler_classes.keys()) & set(tags)
+        if existing_tags:
+            warnings.warn(
+                "Registration of handler {!r} is overriding"
+                "existing handling of tags {}".format(handler_class,
+                                                      existing_tags)
+                )
+        Dataset._handler_classes.update({Tag(tag): handler_class
+                                        for tag in tags})
+        return handler_class
+
+    return decorator

pydicom/tag.py

@@ -222,6 +222,10 @@ def is_private_creator(self):
         """Return ``True`` if the tag is a private creator."""
         return self.is_private and 0x0010 <= self.element < 0x0100
 
+    @property
+    def keyword(self):
+        from pydicom.datadict import keyword_for_tag
+        return keyword_for_tag(self)
 
 def TupleTag(group_elem):
     """Fast factory for :class:`BaseTag` object with known safe (group, elem)

pydicom/tests/test_extensions.py

@@ -0,0 +1,53 @@
+# Copyright 2008-2018 pydicom authors. See LICENSE file for details.
+"""Test for encaps.py"""
+
+import pytest
+
+from pydicom.tag import Tag
+from pydicom.dataset import Dataset
+from pydicom.dataelem import DataElement
+from pydicom.extensions import handle_dataset_tags
+
+
+class TestDatasetExtension(object):
+    """Test handlers which extend Dataset"""
+    def setup(self):
+        @handle_dataset_tags(["ImagePositionPatient", "PatientName"])
+        class MyHandler:
+            def __init__(self, dataset):
+                self.ds = dataset
+
+            def get_item(self, tag):
+                """Return the data element instance"""
+                if tag.keyword == "ImagePositionPatient":
+                    x, y, z = self.ds.ImagePositionPatient
+                    # This one updates underlying dataset
+                    self.ds.ImagePositionPatient = [x + 1, y + 1, z + 1]
+                    return self.ds["ImagePositionPatient"]
+                elif tag.keyword == "PatientName":
+                    # This one leaves underlying dataset alone
+                    return DataElement(tag, "PN", "anonymous")
+                else:
+                    NotImplementedError("Unhandled tag")
+        self.ds = Dataset()
+        self.ds.PatientName = "Patient^Joe"
+        self.ds.ImagePositionPatient = [0.0, 0.0, 0.0]
+        self.ds.PatientID = "123"
+
+    def teardown(self):
+        Dataset.clear_handler_classes()
+
+    def test_get_item(self):
+        """Test handler handles specified tags when retrieved by tag."""
+        assert [1.0, 1.0, 1.0] == self.ds["ImagePositionPatient"].value
+        assert "anonymous" == self.ds["PatientName"].value
+        # Check that one we haven't changed is okay
+        assert "123" == self.ds["PatientID"].value
+
+    def test_get_attr(self):
+        """Test handler handles specified tags when retrieved by keyword."""
+        assert [1.0, 1.0, 1.0] == self.ds.ImagePositionPatient
+        assert "anonymous" == self.ds.PatientName
+
+        # assert that unchanged on still okay
+        assert "123" == self.ds.PatientID