Merge pull request #4 from colour-science/feature/xml_writing

PR: Writing CLF files.

Author: KelSolaar

README.rst

@@ -58,10 +58,44 @@ The main entry point of the library is the ``read_clf`` function in the main nam
 
     import colour_clf_io
 
-    example = """
-    <?xml version="1.0" ?>
-    <ProcessList xmlns="urn:AMPAS:CLF:v3.0" id="Example Wrapper" compCLFversion="2.0">
-        <LUT3D id="lut-24" name="green look" interpolation="trilinear" inBitDepth="12i" outBitDepth="16f">
+    example = """<?xml version="1.0" ?>
+        <ProcessList xmlns="urn:AMPAS:CLF:v3.0" id="Example Wrapper" compCLFversion="2.0">
+            <LUT3D id="lut-24" name="green look" interpolation="trilinear" inBitDepth="12i" outBitDepth="16f">
+                <Description>3D LUT</Description>
+                <Array dim="2 2 2 3">
+                    0.0 0.0 0.0
+                    0.0 0.0 1.0
+                    0.0 1.0 0.0
+                    0.0 1.0 1.0
+                    1.0 0.0 0.0
+                    1.0 0.0 1.0
+                    1.0 1.0 0.0
+                    1.0 1.0 1.0
+                </Array>
+                </LUT3D>
+        </ProcessList>
+    """  # noqa: E501
+    clf_doc = colour_clf_io.parse_clf(example)
+    print(clf_doc)
+
+.. code-block:: text
+
+    ProcessList(id='Example Wrapper', compatible_CLF_version='3.0', process_nodes=[LUT3D(id='lut-24', name='green look', in_bit_depth=<BitDepth.i12: '12i'>, out_bit_depth=<BitDepth.f16: '16f'>, description='3D LUT', array=Array(values=[0.0, 0.0, 0.0, 0.0, 0.0, 1.0, 0.0, 1.0, 0.0, 0.0, 1.0, 1.0, 1.0, 0.0, 0.0, 1.0, 0.0, 1.0, 1.0, 1.0, 0.0, 1.0, 1.0, 1.0], dim=(2, 2, 2, 3)), half_domain=False, raw_halfs=False, interpolation=<Interpolation3D.TRILINEAR: 'trilinear'>)], name=None, inverse_of=None, description=[], input_descriptor='', output_descriptor='', info=Info(app_release=None, copyright=None, revision=None, aces_transform_id=None, aces_user_name=None, calibration_info=None))
+
+and for writing a CLF file the ``write_clf`` function can be used to serialise a ``ProcessList`` back to XML
+
+
+.. code-block:: python
+
+    xml = colour_clf_io.write_clf(clf_doc)
+    print(xml)
+
+.. code-block:: text
+
+    <?xml version="1.0" encoding="UTF-8" standalone="no"?>
+    <ProcessList xmlns="urn:AMPAS:CLF:v3.0" compCLFversion="3.0" id="Example Wrapper">
+        <Info/>
+        <LUT3D id="lut-24" inBitDepth="12i" interpolation="trilinear" name="green look" outBitDepth="16f">
             <Description>3D LUT</Description>
             <Array dim="2 2 2 3">
                 0.0 0.0 0.0
@@ -73,15 +107,8 @@ The main entry point of the library is the ``read_clf`` function in the main nam
                 1.0 1.0 0.0
                 1.0 1.0 1.0
             </Array>
-            </LUT3D>
+        </LUT3D>
     </ProcessList>
-    """  # noqa: E501
-    clf_doc = colour_clf_io.read_clf(EXAMPLE_WRAPPER.format(example))
-    print(clf_doc)
-
-.. code-block:: text
-
-    ProcessList(id='Example Wrapper', compatible_CLF_version='3.0', process_nodes=[LUT3D(id='lut-24', name='green look', in_bit_depth=<BitDepth.i12: '12i'>, out_bit_depth=<BitDepth.f16: '16f'>, description='3D LUT', array=Array(values=[0.0, 0.0, 0.0, 0.0, 0.0, 1.0, 0.0, 1.0, 0.0, 0.0, 1.0, 1.0, 1.0, 0.0, 0.0, 1.0, 0.0, 1.0, 1.0, 1.0, 0.0, 1.0, 1.0, 1.0], dim=(2, 2, 2, 3)), half_domain=False, raw_halfs=False, interpolation=<Interpolation3D.TRILINEAR: 'trilinear'>)], name=None, inverse_of=None, description=[], input_descriptor='', output_descriptor='', info=Info(app_release=None, copyright=None, revision=None, aces_transform_id=None, aces_user_name=None, calibration_info=None))
 
 User Guide
 ----------

colour_clf_io/__init__.py

@@ -104,7 +104,7 @@
 __version__ = f"{__major_version__}.{__minor_version__}.{__change_version__}"
 
 
-def read_clf(path: str | Path) -> ProcessList | None:
+def read_clf_from_file(path: str | Path) -> ProcessList:
     """
     Read given *CLF* file and return a *ProcessList*.
 
@@ -127,10 +127,14 @@ def read_clf(path: str | Path) -> ProcessList | None:
     xml = lxml.etree.parse(str(path))  # noqa: S320
     xml_process_list = xml.getroot()
 
-    return ProcessList.from_xml(xml_process_list)
+    process_list = ProcessList.from_xml(xml_process_list)
+    if process_list is None:
+        err = "Process list could not be parsed."
+        raise ValueError(err)
+    return process_list
 
 
-def parse_clf(text: str | bytes) -> ProcessList | None:
+def read_clf(text: str | bytes) -> ProcessList | None:
     """
     Read given string as a *CLF* file and return a *ProcessList*.
 
@@ -153,3 +157,29 @@ def parse_clf(text: str | bytes) -> ProcessList | None:
     xml = lxml.etree.fromstring(text)  # noqa: S320
 
     return ProcessList.from_xml(xml)
+
+
+def write_clf(process_list: ProcessList, path: str | Path | None = None) -> None | str:
+    """
+    Write the given *ProcessList* as a CLF file to the target
+    location. If no *path* is given the CLF document will be returned as a string.
+
+    Parameters
+    ----------
+    process_list
+        *ProcessList* that should be written.
+    path
+        Location of the file, or *None* to return a string representation of the
+        CLF document.
+
+    Returns
+    -------
+    :class:`colour_clf_io.ProcessList`
+    """
+    xml = process_list.to_xml()
+    serialised = lxml.etree.tostring(xml)
+    if path is None:
+        return serialised.decode("utf-8")
+    with open(path, "wb") as f:
+        f.write(serialised)
+    return None

colour_clf_io/elements.py

@@ -8,25 +8,28 @@
 
 from __future__ import annotations
 
+import sys
 import typing
 from dataclasses import dataclass
 
 if typing.TYPE_CHECKING:
     import numpy.typing as npt
 
-if typing.TYPE_CHECKING:
-    import lxml.etree
+import lxml.etree
 
 from colour_clf_io.errors import ParsingError
 from colour_clf_io.parsing import (
     ParserConfig,
     XMLParsable,
+    XMLWritable,
     check_none,
     child_element,
     child_element_or_exception,
     map_optional,
     retrieve_attributes,
     retrieve_attributes_as_float,
+    set_attr_if_not_none,
+    set_element_if_not_none,
     three_floats,
 )
 from colour_clf_io.values import Channel
@@ -48,9 +51,24 @@
     "ExponentParams",
 ]
 
+if sys.version_info >= (3, 12):
+    from itertools import batched
+else:
+    from itertools import islice
+
+    T = typing.TypeVar("T")
+
+    def batched(iterable: typing.Iterable[T], n: int) -> typing.Iterator[tuple[T, ...]]:
+        if n < 1:
+            err = "n must be at least one"
+            raise ValueError(err)
+        it = iter(iterable)
+        while batch := tuple(islice(it, n)):
+            yield batch
+
 
 @dataclass
-class Array(XMLParsable):
+class Array(XMLParsable, XMLWritable):
     """
     Represent an *Array* element.
 
@@ -124,6 +142,30 @@ def from_xml(
 
         return Array(values=values, dim=dimensions)
 
+    def to_xml(self) -> lxml.etree._Element:
+        """
+        Serialise this object as an XML object.
+
+        Returns
+        -------
+        :class:`lxml.etree._Element`
+        """
+        xml = lxml.etree.Element("Array")
+        xml.set("dim", " ".join(map(str, self.dim)))
+
+        def wrap_with_newlines(s: str) -> str:
+            return f"\n{s}\n"
+
+        if len(self.dim) <= 1:
+            text = "\n".join(map(str, self.values))
+        else:
+            row_length = self.dim[-1]
+            text = "\n".join(
+                " ".join(map(str, row)) for row in batched(self.values, row_length)
+            )
+        xml.text = wrap_with_newlines(text)
+        return xml
+
     def as_array(self) -> npt.NDArray:
         """
         Convert the *CLF* element into a numpy array.
@@ -144,7 +186,7 @@ def as_array(self) -> npt.NDArray:
 
 
 @dataclass
-class CalibrationInfo(XMLParsable):
+class CalibrationInfo(XMLParsable, XMLWritable):
     """
     Represent a *CalibrationInfo* container element for a
     :class:`colour_clf_io.ProcessList` class instance.
@@ -227,9 +269,32 @@ def from_xml(
 
         return CalibrationInfo(**attributes)
 
+    def to_xml(self) -> lxml.etree._Element:
+        """
+        Serialise this object as an XML object.
+
+        Returns
+        -------
+        :class:`lxml.etree._Element`
+        """
+        xml = lxml.etree.Element("CalibrationInfo")
+        set_attr_if_not_none(
+            xml, "DisplayDeviceSerialNum", self.display_device_serial_num
+        )
+        set_attr_if_not_none(
+            xml, "DisplayDeviceHostName", self.display_device_host_name
+        )
+        set_attr_if_not_none(xml, "OperatorName", self.operator_name)
+        set_attr_if_not_none(xml, "CalibrationDateTime", self.calibration_date_time)
+        set_attr_if_not_none(xml, "MeasurementProbe", self.measurement_probe)
+        set_attr_if_not_none(
+            xml, "CalibrationSoftwareName", self.calibration_software_name
+        )
+        return xml
+
 
 @dataclass
-class SOPNode(XMLParsable):
+class SOPNode(XMLParsable, XMLWritable):
     """
     Represent a *SOPNode* element for a :class:`colour_clf_io.ASC_CDL`
     *Process Node*.
@@ -312,6 +377,20 @@ def from_xml(
 
         return SOPNode(slope=slope, offset=offset, power=power)
 
+    def to_xml(self) -> lxml.etree._Element:
+        """
+        Serialise this object as an XML object.
+
+        Returns
+        -------
+        :class:`lxml.etree._Element`
+        """
+        xml = lxml.etree.Element("SOPNode")
+        set_element_if_not_none(xml, "Slope", " ".join(map(str, self.slope)))
+        set_element_if_not_none(xml, "Offset", " ".join(map(str, self.offset)))
+        set_element_if_not_none(xml, "Power", " ".join(map(str, self.power)))
+        return xml
+
     @classmethod
     def default(cls) -> SOPNode:
         """
@@ -331,7 +410,7 @@ def default(cls) -> SOPNode:
 
 
 @dataclass
-class SatNode(XMLParsable):
+class SatNode(XMLParsable, XMLWritable):
     """
     Represent a *SatNode* element for a :class:`colour_clf_io.ASC_CDL`
     *Process Node*.
@@ -399,6 +478,18 @@ def from_xml(
 
         return SatNode(saturation=saturation)
 
+    def to_xml(self) -> lxml.etree._Element:
+        """
+        Serialise this object as an XML object.
+
+        Returns
+        -------
+        :class:`lxml.etree._Element`
+        """
+        xml = lxml.etree.Element("SatNode")
+        set_element_if_not_none(xml, "Saturation", self.saturation)
+        return xml
+
     @classmethod
     def default(cls) -> SatNode:
         """
@@ -414,7 +505,7 @@ def default(cls) -> SatNode:
 
 
 @dataclass
-class Info(XMLParsable):
+class Info(XMLParsable, XMLWritable):
     """
     Represent an *Info* element.
 
@@ -520,9 +611,27 @@ def from_xml(xml: lxml.etree._Element | None, config: ParserConfig) -> Info | No
 
         return Info(calibration_info=calibration_info, **attributes)
 
+    def to_xml(self) -> lxml.etree._Element:
+        """
+        Serialise this object as an XML object.
+
+        Returns
+        -------
+        :class:`lxml.etree._Element`
+        """
+        xml = lxml.etree.Element("Info")
+        set_attr_if_not_none(xml, "AppRelease", self.app_release)
+        set_attr_if_not_none(xml, "Copyright", self.copyright)
+        set_attr_if_not_none(xml, "Revision", self.revision)
+        set_attr_if_not_none(xml, "AcesTransformID", self.aces_transform_id)
+        set_attr_if_not_none(xml, "AcesUserName", self.aces_user_name)
+        if self.calibration_info is not None:
+            xml.append(self.calibration_info.to_xml())
+        return xml
+
 
 @dataclass
-class LogParams(XMLParsable):
+class LogParams(XMLParsable, XMLWritable):
     """
     Represent a *LogParams* element for a :class:`colour_clf_io.Log`
     *Process Node*.
@@ -649,6 +758,26 @@ def from_xml(
 
         return LogParams(channel=channel, **attributes)
 
+    def to_xml(self) -> lxml.etree._Element:
+        """
+        Serialise this object as an XML object.
+
+        Returns
+        -------
+        :class:`lxml.etree._Element`
+        """
+        xml = lxml.etree.Element("LogParams")
+        set_attr_if_not_none(xml, "base", self.base)
+        set_attr_if_not_none(xml, "logSideSlope", self.log_side_slope)
+        set_attr_if_not_none(xml, "logSideOffset", self.log_side_offset)
+        set_attr_if_not_none(xml, "linSideSlope", self.lin_side_slope)
+        set_attr_if_not_none(xml, "linSideOffset", self.lin_side_offset)
+        set_attr_if_not_none(xml, "linSideBreak", self.lin_side_break)
+        set_attr_if_not_none(xml, "linearSlope", self.linear_slope)
+        if self.channel is not None:
+            xml.set("channel", self.channel.value)
+        return xml
+
     @classmethod
     def default(cls) -> LogParams:
         """
@@ -673,7 +802,7 @@ def default(cls) -> LogParams:
 
 
 @dataclass
-class ExponentParams(XMLParsable):
+class ExponentParams(XMLParsable, XMLWritable):
     """
     Represent a *ExponentParams* element for a :class:`colour_clf_io.Exponent`
     *Process Node*.
@@ -772,6 +901,21 @@ def from_xml(
 
         return ExponentParams(channel=channel, exponent=exponent, **attributes)
 
+    def to_xml(self) -> lxml.etree._Element:
+        """
+        Serialise this object as an XML object.
+
+        Returns
+        -------
+        :class:`lxml.etree._Element`
+        """
+        xml = lxml.etree.Element("ExponentParams")
+        set_attr_if_not_none(xml, "exponent", self.exponent)
+        set_attr_if_not_none(xml, "offset", self.offset)
+        if self.channel is not None:
+            xml.set("channel", self.channel.value)
+        return xml
+
     @classmethod
     def default(cls) -> ExponentParams:
         """