Add support for writing SMPTE ST 2136-1 compatible files.

Author: MichaelMauderer

colour_clf_io/__init__.py

@@ -22,6 +22,8 @@
 
 import typing
 
+from .parsing import Namespaces
+
 if typing.TYPE_CHECKING:
     from pathlib import Path
 
@@ -168,7 +170,11 @@ def read_clf(text: str | bytes) -> ProcessList | None:
     return ProcessList.from_xml(xml)
 
 
-def write_clf(process_list: ProcessList, path: str | Path | None = None) -> None | str:
+def write_clf(
+    process_list: ProcessList,
+    path: str | Path | None = None,
+    namespace: Namespaces = Namespaces.AMPAS,
+) -> 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.
@@ -180,12 +186,15 @@ def write_clf(process_list: ProcessList, path: str | Path | None = None) -> None
     path
         Location of the file, or *None* to return a string representation of the
         CLF document.
+    namespace
+        :class:`colour_clf_io.Namespaces` instance to be used for the namespace
+        of the document.
 
     Returns
     -------
     :class:`colour_clf_io.ProcessList`
     """
-    xml = process_list.to_xml()
+    xml = process_list.to_xml(namespace)
     serialised = lxml.etree.tostring(xml)
     if path is None:
         return serialised.decode("utf-8")

colour_clf_io/parsing.py

@@ -11,6 +11,7 @@
 import typing
 from abc import ABC, abstractmethod
 from dataclasses import dataclass
+from enum import Enum
 from itertools import islice
 from typing import TypeGuard, TypeVar
 
@@ -30,7 +31,7 @@
 __status__ = "Production"
 
 __all__ = [
-    "NAMESPACE_NAME",
+    "Namespaces",
     "ParserConfig",
     "XMLParsable",
     "XMLWritable",
@@ -46,9 +47,22 @@
     "elements_as_text_list",
     "sliding_window",
     "three_floats",
+    "detect_namespace",
 ]
 
-NAMESPACE_NAME: str = "urn:AMPAS:CLF:v3.0"
+
+class Namespaces(Enum):
+    """
+    Valid namespaces for parsing and serialising CLF documents.
+    """
+
+    AMPAS = "urn:AMPAS:CLF:v3.0"
+    SMTP = "http://www.smpte-ra.org/ns/2136-1/2024"
+
+
+@dataclass
+class UnknownNamespace:
+    namespace: str
 
 
 @dataclass
@@ -58,17 +72,17 @@ class ParserConfig:
 
     Attributes
     ----------
-    -   :attr:`~colour_clf_io.ParserConfig.namespace_name`
+    -   :attr:`~colour_clf_io.ParserConfig.name_space`
 
     Methods
     -------
     -   :meth:`~colour_clf_io.ParserConfig.clf_namespace_prefix_mapping`
     """
 
-    namespace_name: str | None = NAMESPACE_NAME
+    namespace: Namespaces | None
+    """
+    The namespace name used for parsing the *CLF* file.
     """
-    The namespace name used for parsing the *CLF* file. Usually this should
-    be the `CLF_NAMESPACE`, but it can be omitted."""
 
     def clf_namespace_prefix_mapping(self) -> dict[str, str] | None:
         """
@@ -80,8 +94,8 @@ def clf_namespace_prefix_mapping(self) -> dict[str, str] | None:
             Dictionary that contain the namespaces prefix mappings.
         """
 
-        if self.namespace_name:
-            return {"clf": self.namespace_name}
+        if self.namespace:
+            return {"clf": self.namespace.value}
 
         return None
 
@@ -524,3 +538,30 @@ def set_element_if_not_none(node: lxml.etree._Element, name: str, value: Any) ->
     if value is not None and value != "":
         child = lxml.etree.SubElement(node, name)
         child.text = str(value)
+
+
+def detect_namespace(node: lxml.etree._Element) -> Namespaces | UnknownNamespace | None:
+    """
+    Detect the namespace of the given CLF document.
+
+    Parameters
+    ----------
+    node
+        XML element to check for namespace.
+
+    Returns
+    -------
+    :class:`NameSpace` or :class:`UnknownNamespace` or None depending on whether a valid
+    namespace was detected, an invalid namespace was detected, or no namespace is
+    present.
+    """
+    document_namespace = node.xpath("namespace-uri(.)")
+    if not document_namespace:
+        return None
+    document_namespace = str(document_namespace)
+    match document_namespace:
+        case Namespaces.SMTP.value:
+            return Namespaces.SMTP
+        case Namespaces.AMPAS.value:
+            return Namespaces.AMPAS
+    return UnknownNamespace(document_namespace)

colour_clf_io/process_list.py

@@ -15,9 +15,11 @@
 from colour_clf_io.elements import Info
 from colour_clf_io.errors import ParsingError
 from colour_clf_io.parsing import (
-    NAMESPACE_NAME,
+    Namespaces,
     ParserConfig,
+    UnknownNamespace,
     check_none,
+    detect_namespace,
     element_as_text,
     elements_as_text_list,
     set_attr_if_not_none,
@@ -66,10 +68,10 @@ class ProcessList:
     -   https://docs.acescentral.com/specifications/clf/#processList
     """
 
-    id: str
+    id: str | None
     """A string to serve as a unique identifier of the *ProcessList*."""
 
-    compatible_CLF_version: str
+    compatible_CLF_version: str | None
     """
     A string indicating the minimum compatible CLF specification version
     required to read this file. The compCLFversion corresponding to this
@@ -123,10 +125,10 @@ class ProcessList:
     def from_xml(xml: lxml.etree._Element | None) -> ProcessList | None:
         """
         Parse and return a :class:`colour_clf_io.ProcessList` class instance
-        from the given XML element. Returns `None`` if the given XML element is
+        from the given XML element. Returns ``None`` if the given XML element is
         ``None``.
 
-        Expects the XML element to be a valid element according to the *CLF*
+        Expects the XML element to be a valid element, according to the *CLF*
         specification.
 
         Parameters
@@ -150,6 +152,27 @@ def from_xml(xml: lxml.etree._Element | None) -> ProcessList | None:
         if xml is None:
             return None
 
+        detected_namespace = detect_namespace(xml)
+        document_namespace: Namespaces | None = None
+        match detected_namespace:
+            case None:
+                document_namespace = None
+            case UnknownNamespace(value):
+                exception = f"Found invalid xmlns attribute in *ProcessList*: {value}"
+                raise ParsingError(exception)
+            case Namespaces():
+                document_namespace = detected_namespace
+
+        if document_namespace == Namespaces.SMTP:
+            error = (
+                "SMPTE ST 2136-1 files are not fully supported. See "
+                "https://github.com/colour-science/colour-clf-io/issues/6 "
+                "for more information. "
+            )
+            raise ParsingError(error)
+
+        config = ParserConfig(namespace=document_namespace)
+
         id_ = xml.get("id")
         check_none(id_, "ProcessList must contain an `id` attribute")
 
@@ -159,18 +182,6 @@ def from_xml(xml: lxml.etree._Element | None) -> ProcessList | None:
             'ProcessList must contain a "compCLFversion" attribute',
         )
 
-        # By default, we would expect the correct namespace as per the specification.
-        # But if it is not present, we will still try to parse the document anyway.
-        # We won't accept a wrong namespace through.
-        config = ParserConfig()
-        namespace = xml.xpath("namespace-uri(.)")
-        if not namespace:
-            config.namespace_name = None
-        elif namespace != config.namespace_name:
-            exception = f"Found invalid xmlns attribute in *ProcessList*: {namespace}"
-
-            raise ParsingError(exception)
-
         name = xml.get("name")
         inverse_of = xml.get("inverseOf")
         info = Info.from_xml(xml, config)
@@ -193,8 +204,8 @@ def from_xml(xml: lxml.etree._Element | None) -> ProcessList | None:
         assert_bit_depth_compatibility(process_nodes)
 
         return ProcessList(
-            id=id_,  # pyright: ignore
-            compatible_CLF_version=compatible_clf_version,  # pyright: ignore
+            id=id_,
+            compatible_CLF_version=compatible_clf_version,
             process_nodes=process_nodes,
             name=name,
             inverse_of=inverse_of,
@@ -204,17 +215,27 @@ def from_xml(xml: lxml.etree._Element | None) -> ProcessList | None:
             description=description,
         )
 
-    def to_xml(self) -> lxml.etree._Element:
+    def to_xml(self, name_space: Namespaces = Namespaces.AMPAS) -> lxml.etree._Element:
         """
         Serialise this object as an XML object.
 
+        Parameters
+        ----------
+        name_space
+            :class:`colour_clf_io.Namespaces` instance to be used for the namespace
+            of the document.
+
         Returns
         -------
         :class:`lxml.etree._Element`
         """
         xml = lxml.etree.Element("ProcessList")
 
-        xml.set("xmlns", NAMESPACE_NAME)
+        xml.set("xmlns", name_space.value)
+
+        for description_text in self.description:
+            description_element = lxml.etree.SubElement(xml, "Description")
+            description_element.text = description_text
 
         set_attr_if_not_none(xml, "id", self.id)
         set_attr_if_not_none(xml, "compCLFversion", self.compatible_CLF_version)
@@ -225,11 +246,7 @@ def to_xml(self) -> lxml.etree._Element:
 
         if self.info:
             xml.append(self.info.to_xml())
-        for description_text in self.description:
-            description_element = lxml.etree.SubElement(xml, "Description")
-            description_element.text = description_text
-        # TODO: we might have to store a single list of children in order to preserve
-        #   ordering of description and process nodes
+
         for process_node in self.process_nodes:
             xml.append(process_node.to_xml())
         return xml

colour_clf_io/process_nodes.py

@@ -854,8 +854,8 @@ def to_xml(self) -> lxml.etree._Element:
         xml = lxml.etree.Element("ASC_CDL")
         self.write_process_node_attributes(xml)
         xml.set("style", self.style.value)
-        if self.sat_node is not None:
-            xml.append(self.sat_node.to_xml())
         if self.sopnode is not None:
             xml.append(self.sopnode.to_xml())
+        if self.sat_node is not None:
+            xml.append(self.sat_node.to_xml())
         return xml