Merge branch 'release/v0.2.0'

Author: MichaelMauderer

README.rst

@@ -38,30 +38,58 @@ Features
 The following features are available:
 
 - Reading *CLF* files to a Python representation.
-
-The following features are planned and in development:
-
 - Writing *CLF* files from the Python representation.
-- Validating *CLF* files according to the specification.
+- Executing *CLF* workflows and applying them to colours or images.
 
-Features that will not be part of this library:
-
-- Executing *CLF* workflows and applying them to colours or images. This feature will be implemented as part of `Colour
-  <https://github.com/colour-science/colour/>`__.
 
 Examples
 ^^^^^^^^
 
-The main entry point of the library is the ``read_clf`` function in the main namespace.
+The main entry point of the library is the ``read_clf`` function in the main namespace, which allows one to parse
+a CLF document:
 
 .. code-block:: python
 
     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.read_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))
+
+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 +101,21 @@ 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)
+
+To execute a CLF workflow, you can create a *CLFProcessList* that can be applied to some input.
+
+.. code-block:: python
+
+    lut = colour_clf_io.CLFProcessList(clf_doc)
+    input_value = [0, 32768, 65535]
+    result = lut.apply(input_value)
+    print(result)
 
 .. 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))
+    [ 0.  1.  1.]
 
 User Guide
 ----------
@@ -98,6 +132,10 @@ Primary Dependencies
 - `lxml >= 5.2.1 < 6 <https://pypi.org/project/lxml/>`__
 - `numpy >= 1.24, < 2 <https://pypi.org/project/numpy>`__
 
+If you want to execute CLF workflows, you will also need
+
+- `colour-science >= 0.4.6 <https://pypi.org/project/colour-science>`__
+
 Pypi
 ~~~~
 
@@ -111,6 +149,17 @@ The overall development dependencies are installed as follows::
 
     pip install --user 'colour-clf-io[development]'
 
+UV
+~~~~
+
+Using uv you can simply install **Colour - CLF IO** via::
+
+    uv add colour-clf-io
+
+or, if you want to execute CLF workflows::
+
+    uv add colour-clf-io --optional processing
+
 
 Contributing
 ^^^^^^^^^^^^

colour_clf_io/__init__.py

@@ -1,14 +1,16 @@
 """
-CLF Parsing
-===========
+Colour - CLF IO
+===============
 
 Defines the functionality and data structures to parse *CLF* files.
 
 The main functionality is exposed through the following two methods:
--   :func:`colour.io.clf.read_clf`: Read a file in the *CLF* format and return the
-    corresponding :class: ProcessList.
--   :func:`colour.io.clf.parse_clf`: Read a string that contains a *CLF* file and
+-   :func:`colour.io.clf.read_clf_from_file`: Read a file in the *CLF* format and
     return the corresponding :class: ProcessList.
+-   :func:`colour.io.clf.read_clf`: Read a string that contains a *CLF* file and
+    return the corresponding :class: ProcessList.
+-   :func:`colour.io.clf.write_clf`: Take a :class: ProcessList and output the
+    corresponding CLF document.
 
 References
 ----------
@@ -20,6 +22,8 @@
 
 import typing
 
+from .parsing import Namespaces
+
 if typing.TYPE_CHECKING:
     from pathlib import Path
 
@@ -99,12 +103,19 @@
 __application_name__ = "Colour - CLF IO"
 
 __major_version__ = "0"
-__minor_version__ = "1"
-__change_version__ = "1"
+__minor_version__ = "2"
+__change_version__ = "0"
 __version__ = f"{__major_version__}.{__minor_version__}.{__change_version__}"
 
+try:
+    from colour_clf_io.processing import CLFProcessList
+
+    __all__ += ["CLFProcessList"]
+except ImportError:
+    pass
+
 
-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*.
 
@@ -124,13 +135,17 @@ def read_clf(path: str | Path) -> ProcessList | None:
         If the given file does not contain a valid *CLF* file.
     """
 
-    xml = lxml.etree.parse(str(path))  # noqa: S320
+    xml = lxml.etree.parse(str(path))
     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*.
 
@@ -150,6 +165,39 @@ def parse_clf(text: str | bytes) -> ProcessList | None:
         If the given string does not contain a valid *CLF* file.
     """
 
-    xml = lxml.etree.fromstring(text)  # noqa: S320
+    xml = lxml.etree.fromstring(text)
 
     return ProcessList.from_xml(xml)
+
+
+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.
+
+    Parameters
+    ----------
+    process_list
+        *ProcessList* that should be written.
+    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(namespace)
+    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