Add metadata saving support to SVG.

QuLogic · QuLogic · commit 15e2117b054b · 2020-06-09T23:22:16.000-04:00
diff --git a/doc/users/next_whats_new/2020-04-23-ES-svg-metadata.rst b/doc/users/next_whats_new/2020-04-23-ES-svg-metadata.rst
@@ -0,0 +1,9 @@
+Saving SVG now supports adding metadata
+---------------------------------------
+
+When saving SVG files, metadata can now be passed which will be saved in the
+file using `Dublin Core`_ and `RDF`_. A list of valid metadata can be found in
+the documentation for `.FigureCanvasSVG.print_svg`.
+
+.. _Dublin Core: https://www.dublincore.org/specifications/dublin-core/
+.. _RDF: https://www.w3.org/1999/.status/PR-rdf-syntax-19990105/status
diff --git a/lib/matplotlib/backends/backend_svg.py b/lib/matplotlib/backends/backend_svg.py
@@ -1,10 +1,12 @@
 from collections import OrderedDict
 import base64
+import datetime
 import gzip
 import hashlib
 from io import BytesIO, StringIO, TextIOWrapper
 import itertools
 import logging
+import os
 import re
 import uuid
 
@@ -17,6 +19,7 @@
      _Backend, FigureCanvasBase, FigureManagerBase, RendererBase)
 from matplotlib.backends.backend_mixed import MixedModeRenderer
 from matplotlib.colors import rgb2hex
+from matplotlib.dates import UTC
 from matplotlib.font_manager import findfont, get_font
 from matplotlib.ft2font import LOAD_NO_HINTING
 from matplotlib.mathtext import MathTextParser
@@ -273,7 +276,8 @@ def generate_css(attrib={}):
 
 
 class RendererSVG(RendererBase):
-    def __init__(self, width, height, svgwriter, basename=None, image_dpi=72):
+    def __init__(self, width, height, svgwriter, basename=None, image_dpi=72,
+                 *, metadata=None):
         self.width = width
         self.height = height
         self.writer = XMLWriter(svgwriter)
@@ -304,6 +308,7 @@ def __init__(self, width, height, svgwriter, basename=None, image_dpi=72):
             xmlns="http://www.w3.org/2000/svg",
             version="1.1",
             attrib={'xmlns:xlink': "http://www.w3.org/1999/xlink"})
+        self._write_metadata(metadata)
         self._write_default_style()
 
     def finalize(self):
@@ -312,6 +317,112 @@ def finalize(self):
         self.writer.close(self._start_id)
         self.writer.flush()
 
+    def _write_metadata(self, metadata):
+        # Add metadata following the Dublin Core Metadata Initiative, and the
+        # Creative Commons Rights Expression Language. This is mainly for
+        # compatibility with Inkscape.
+        if metadata is None:
+            metadata = {}
+        metadata = {
+            'Format': 'image/svg+xml',
+            'Type': 'http://purl.org/dc/dcmitype/StillImage',
+            'Creator':
+                f'Matplotlib v{mpl.__version__}, https://matplotlib.org/',
+            **metadata
+        }
+        writer = self.writer
+
+        if 'Title' in metadata:
+            writer.element('title', text=metadata['Title'], indent=False)
+
+        # Special handling.
+        date = metadata.get('Date', None)
+        if date is not None:
+            if isinstance(date, str):
+                dates = [date]
+            elif isinstance(date, (datetime.datetime, datetime.date)):
+                dates = [date.isoformat()]
+            elif np.iterable(date):
+                dates = []
+                for d in date:
+                    if isinstance(d, str):
+                        dates.append(d)
+                    elif isinstance(d, (datetime.datetime, datetime.date)):
+                        dates.append(d.isoformat())
+                    else:
+                        raise ValueError(
+                            'Invalid type for Date metadata. '
+                            'Expected iterable of str, date, or datetime, '
+                            'not {!r}.'.format(type(d)))
+            else:
+                raise ValueError('Invalid type for Date metadata. '
+                                 'Expected str, date, datetime, or iterable '
+                                 'of the same, not {!r}.'.format(type(date)))
+            metadata['Date'] = '/'.join(dates)
+        else:
+            # Get source date from SOURCE_DATE_EPOCH, if set.
+            # See https://reproducible-builds.org/specs/source-date-epoch/
+            date = os.getenv("SOURCE_DATE_EPOCH")
+            if date:
+                date = datetime.datetime.utcfromtimestamp(int(date))
+                metadata['Date'] = date.replace(tzinfo=UTC).isoformat()
+            else:
+                metadata['Date'] = datetime.datetime.today().isoformat()
+
+        mid = writer.start('metadata')
+        writer.start('rdf:RDF', attrib={
+                'xmlns:dc': "http://purl.org/dc/elements/1.1/",
+                'xmlns:cc': "http://creativecommons.org/ns#",
+                'xmlns:rdf': "http://www.w3.org/1999/02/22-rdf-syntax-ns#",
+            })
+        writer.start('cc:Work')
+
+        uri = metadata.pop('Type', None)
+        if uri is not None:
+            writer.element('dc:type', attrib={'rdf:resource': uri})
+
+        # Single value only.
+        for key in ['title', 'coverage', 'date', 'description', 'format',
+                    'identifier', 'language', 'relation', 'source']:
+            info = metadata.pop(key.title(), None)
+            if info is not None:
+                writer.element(f'dc:{key}', text=info, indent=False)
+
+        # Multiple Agent values.
+        for key in ['creator', 'contributor', 'publisher', 'rights']:
+            agents = metadata.pop(key.title(), None)
+            if agents is None:
+                continue
+
+            if isinstance(agents, str):
+                agents = [agents]
+
+            writer.start(f'dc:{key}')
+            for agent in agents:
+                writer.start('cc:Agent')
+                writer.element('dc:title', text=agent, indent=False)
+                writer.end('cc:Agent')
+            writer.end(f'dc:{key}')
+
+        # Multiple values.
+        keywords = metadata.pop('Keywords', None)
+        if keywords is not None:
+            if isinstance(keywords, str):
+                keywords = [keywords]
+
+            writer.start('dc:subject')
+            writer.start('rdf:Bag')
+            for keyword in keywords:
+                writer.element('rdf:li', text=keyword, indent=False)
+            writer.end('rdf:Bag')
+            writer.end('dc:subject')
+
+        writer.close(mid)
+
+        if metadata:
+            raise ValueError('Unknown metadata key(s) passed to SVG writer: ' +
+                             ','.join(metadata))
+
     def _write_default_style(self):
         writer = self.writer
         default_style = generate_css({
@@ -1163,6 +1274,36 @@ class FigureCanvasSVG(FigureCanvasBase):
     fixed_dpi = 72
 
     def print_svg(self, filename, *args, **kwargs):
+        """
+        Parameters
+        ----------
+        filename : str or path-like or file-like
+            Output target; if a string, a file will be opened for writing.
+        metadata : Dict[str, Any], optional
+            Metadata in the SVG file defined as key-value pairs of strings,
+            datetimes, or lists of strings, e.g., ``{'Creator': 'My software',
+            'Contributor': ['Me', 'My Friend'], 'Title': 'Awesome'}``.
+
+            The standard keys and their value types are:
+
+            * *str*: ``'Coverage'``, ``'Description'``, ``'Format'``,
+              ``'Identifier'``, ``'Language'``, ``'Relation'``, ``'Source'``,
+              ``'Title'``, and ``'Type'``.
+            * *str* or *list of str*: ``'Contributor'``, ``'Creator'``,
+              ``'Keywords'``, ``'Publisher'``, and ``'Rights'``.
+            * *str*, *date*, *datetime*, or *tuple* of same: ``'Date'``. If a
+              non-*str*, then it will be formatted as ISO 8601.
+
+            Values have been predefined for ``'Creator'``, ``'Date'``,
+            ``'Format'``, and ``'Type'``. They can be removed by setting them
+            to `None`.
+
+            Information is encoded as `Dublin Core Metadata`__.
+
+            .. _DC: https://www.dublincore.org/specifications/dublin-core/
+
+            __ DC_
+        """
         with cbook.open_file_cm(filename, "w", encoding="utf-8") as fh:
 
             filename = getattr(fh, 'name', '')
@@ -1187,15 +1328,15 @@ def print_svgz(self, filename, *args, **kwargs):
                 gzip.GzipFile(mode='w', fileobj=fh) as gzipwriter:
             return self.print_svg(gzipwriter)
 
-    def _print_svg(
-            self, filename, fh, *, dpi=72, bbox_inches_restore=None, **kwargs):
+    def _print_svg(self, filename, fh, *, dpi=72, bbox_inches_restore=None,
+                   metadata=None, **kwargs):
         self.figure.set_dpi(72.0)
         width, height = self.figure.get_size_inches()
         w, h = width * 72, height * 72
 
         renderer = MixedModeRenderer(
             self.figure, width, height, dpi,
-            RendererSVG(w, h, fh, filename, dpi),
+            RendererSVG(w, h, fh, filename, dpi, metadata=metadata),
             bbox_inches_restore=bbox_inches_restore)
 
         self.figure.draw(renderer)
diff --git a/lib/matplotlib/figure.py b/lib/matplotlib/figure.py
@@ -2081,6 +2081,8 @@ def savefig(self, fname, *, transparent=None, **kwargs):
               `~.FigureCanvasAgg.print_png`.
             - 'pdf' with pdf backend: See the parameter ``metadata`` of
               `~.backend_pdf.PdfPages`.
+            - 'svg' with svg backend: See the parameter ``metadata`` of
+              `~.FigureCanvasSVG.print_svg`.
             - 'eps' and 'ps' with PS backend: Only 'Creator' is supported.
 
         pil_kwargs : dict, optional
diff --git a/lib/matplotlib/tests/test_backend_svg.py b/lib/matplotlib/tests/test_backend_svg.py
@@ -1,5 +1,7 @@
+import datetime
 from io import BytesIO
 import re
+import sys
 import tempfile
 import xml.parsers.expat
 
@@ -236,7 +238,9 @@ def test_url():
         assert b'http://example.com/' + v in b
 
 
-def test_url_tick():
+def test_url_tick(monkeypatch):
+    monkeypatch.setenv('SOURCE_DATE_EPOCH', '19680801')
+
     fig1, ax = plt.subplots()
     ax.scatter([1, 2, 3], [4, 5, 6])
     for i, tick in enumerate(ax.yaxis.get_major_ticks()):
@@ -259,3 +263,58 @@ def test_url_tick():
     for i in range(len(ax.yaxis.get_major_ticks())):
         assert f'http://example.com/{i}'.encode('ascii') in b1
     assert b1 == b2
+
+
+def test_svg_default_metadata(monkeypatch):
+    # Values have been predefined for 'Creator', 'Date', 'Format', and 'Type'.
+    monkeypatch.setenv('SOURCE_DATE_EPOCH', '19680801')
+
+    fig, ax = plt.subplots()
+    fd = BytesIO()
+    fig.savefig(fd, format='svg')
+    fd.seek(0)
+    buf = fd.read().decode()
+    fd.close()
+
+    # Creator
+    assert mpl.__version__ in buf
+    # Date
+    assert '1970-08-16' in buf
+    # Format
+    assert 'image/svg+xml' in buf
+    # Type
+    assert 'StillImage' in buf
+
+
+def test_svg_metadata():
+    single_value = ['Coverage', 'Identifier', 'Language', 'Relation', 'Source',
+                    'Title', 'Type']
+    multi_value = ['Contributor', 'Creator', 'Keywords', 'Publisher', 'Rights']
+    metadata = {
+        'Date': [datetime.date(1968, 8, 1),
+                 datetime.datetime(1968, 8, 2, 1, 2, 3)],
+        'Description': 'description\ntext',
+        **{k: f'{k} foo' for k in single_value},
+        **{k: [f'{k} bar', f'{k} baz'] for k in multi_value},
+    }
+
+    fig, ax = plt.subplots()
+    fd = BytesIO()
+    fig.savefig(fd, format='svg', metadata=metadata)
+    fd.seek(0)
+    buf = fd.read().decode()
+    fd.close()
+
+    # Check things that are easy, single or multi-value entries.
+    for k in ['Description', *single_value]:
+        if sys.platform == 'win32':
+            assert metadata[k].replace('\n', '\r\n') in buf
+        else:
+            assert metadata[k] in buf
+    for k in multi_value:
+        for v in metadata[k]:
+            assert v in buf
+
+    # Check special things.
+    assert '1968-08-01' in buf  # Start date
+    assert '1968-08-02T01:02:03' in buf  # End date
