Config: change extra_tracking to array and environment to table.

This is a cleaner way of setting the options instead of parsing a multi-line string.

There are also some additional checks to ensure the examples in the configuration are
valid.

Author: bcbnz

data/share/matplotlib-pgfutils/pgfutils.toml

@@ -118,14 +118,11 @@ legend_font_size = 10.0
 separate_legend = false
 
 # Extra library-specific file trackers to install.
-extra_tracking = ""
-
-# Environment variables to set. This should be a multi-line value; place one or
-# more spaces between each subsequenct line (these spaces will be removed when
-# parsing the configuration). Each line should be in the format name = value,
-# with the value being read as a string, and leading and trailing spaces being
-# removed from both the name and the value.
-environment = ""
+extra_tracking = []
+
+# Environment variables to set. This a table mapping variable name to value; both must
+# be strings.
+environment = {}
 
 
 

doc/config.md

@@ -234,50 +234,43 @@ calling `setup_figure`.
 
 ### Extra tracking
 
-This is a comma-separated list of extra libraries to install file tracking on.
-See the [file tracking](file_tracking.md) documentation for more details.
+This is an array of strings naming extra libraries to install file tracking on. See the
+[file tracking](file_tracking.md) documentation for more details.
 
 
 ### Environment variables
 
-Environment variables to set can be specified using the multi-line option
-``environment``. Each line represents one environment variable in the format
-``name = value``:
+Environment variables to set can be specified using the table option `environment`. Each
+entry represents one environment variable:
 
 ```toml
 [pgfutils]
-environment = '''
-  name1 = "value1"
-  name2 = "value2"
-'''
+environment = {name1 = "value1", name2 = "value2"}
 ```
 
-Existing environment variables of the same name will be overwritten. This means that if
-you specify the same variable multiple times the last value will be used. For example,
-the configuration
+TOML requires inline tables as used in the previous example to be on a single line. If
+you prefer to split this over multiple lines, you can make `environment` an explicit
+table:
 
 ```toml
-[pgfutils]
-environment = '''
-  name1 = "value1"
-  name2 = "value2"
-  name1 = "value3"
-'''
+[pgfutils.environment]
+name1 = "value1"
+name2 = "value2"
 ```
 
-will result in `name1` being set to `value3`. The variables are set during the call to
-`setup_figure()`, so any libraries that read the environment variables must be imported
-after this call.
+Existing environment variables of the same name will be overwritten. This means that
+environment variables given in the configuration file will override existing values, and
+that environment variables given in the `setup_figure` call will override values from
+the configuration file. The variables are set during the call to `setup_figure()`, so
+any libraries that read the environment variables must be imported after this call.
 
 Note that the `PGFUTILS_TRACK_FILES` variable described in the [file tracking
 documentation](file_tracking.md) can be configured through this option, for example to
 output tracked files to stdout:
 
 ```toml
 [pgfutils]
-environment = '''
-  PGFUTILS_TRACK_FILES = "1"
-'''
+environment = {PGFUTILS_TRACK_FILES = "1"}
 ```
 
 
@@ -288,49 +281,49 @@ it is a dependency. If it is in one of the directories given under the `data` ke
 any subdirectory of one of these directories, then it is counted as a dependency. The
 top-level directory (the directory the script was run from) is always included as a data
 directory, so you only need to specify directories outside the top-level directory.
-Multiple entries must be specified on separate lines of the configuration.
+These paths must be given as an array of strings, each corresponding to one path.
 
 ```toml
 [paths]
-data = '''
-  /data/common
-'''
+data = [
+  '/data/common'
+]
 ```
 
 Note that these directories are not added to any kind of search path, so any
 code which uses them still has to give a complete path.
 
-If you have Python code in other libraries you want to be able to import in
-your scripts, you can use the `pythonpath` option in the `paths` section of the
-configuration file to specify custom search paths for Python. This is a
-multi-line entry with one path per line.  The paths are inserted at the start
-of `sys.path` when you call `setup_figure()`. They are inserted in the order
-given in the configuration, which means the last path in the configuration will
-be the first entry in `sys.path`. They are not modified or checked in any way.
-Relative paths will therefore be interpreted by Python as being relative to the
-directory it was run from, which should be the top-level directory of your
-project.
+If you have Python code in other libraries you want to be able to import in your
+scripts, you can use the `pythonpath` option in the `paths` section of the configuration
+file to specify custom search paths for Python. This is an array of strings, each
+corresponding to one path entry. The paths are inserted at the start of `sys.path` when
+you call `setup_figure()`. They are inserted in the order given in the configuration,
+which means the last path in the configuration will be the first entry in `sys.path`.
+They are not modified or checked in any way.  Relative paths will therefore be
+interpreted by Python as being relative to the directory it was run from, which should
+be the top-level directory of your project.
 
 ```toml
 [paths]
-pythonpath = '''
-  pythonlib/
-  /usr/share/myotherlib
-'''
+pythonpath = [
+  'pythonlib/',
+  '/usr/share/myotherlib',
+]
 ```
 
 Python imports can also be handled by the [file tracking](file_tracking.md). If
 enabled, any library imported from a directory (or subdirectory) specified in
 the `pythonpath` option is treated as a dependency and output as part of the
 file tracking details. If you have other libraries which are already in the
 Python path which you want to be tracked as dependencies, you can add the
-appropriate directories to the `extra_imports` option:
+appropriate directories to the `extra_imports` option. As with the other path settings,
+this must be an array of strings, each corresponding to a single path.
 
 ```toml
 [paths]
-extra_imports = '''
-   /home/username/.local/lib/
-'''
+extra_imports = [
+   '/home/username/.local/lib/'
+]
 ```
 
 
@@ -339,10 +332,10 @@ Matplotlib rcParams
 
 Matplotlib can be customised using its [rcParams][] system (this is how pgfutils does
 much of its setup). If you want to override rcParams settings, you can specify them in
-the `rcParams` section:
+the `rcparams` section:
 
 ```toml
-[rcParams]
+[rcparams]
 "figure.facecolor" = "blue"
 "xtick.labelsize" = 8
 ```

doc/config_defaults_pgfutils.toml

@@ -21,7 +21,7 @@ legend_font_size = 10
 separate_legend = false
 
 # Extra libraries to install file tracking on.
-extra_tracking = ""
+extra_tracking = []
 
 # Environment variables to set.
-environment = ""
+environment = {}

doc/file_tracking.md

@@ -92,19 +92,21 @@ Extra tracking
 By default, tracking is only installed on standard Python functions. If you use
 the [netCDF4][1] library, tracking can also be enabled for files opened by it
 (which includes other libraries that use netCDF4, such as xarray). To enable
-this project-wide, set the `extra_tracking` option to `netCDF4` in your
+this project-wide, add the `netCDF4` option to the `extra_tracking` option in your
 configuration:
 
-```INI
+```toml
 [pgfutils]
-extra_tracking = netCDF4
+extra_tracking = [
+  "netCDF4"
+]
 ```
 
 To only enable it for a specific figure, add the option to the ``setup_figure``
 call:
 
 ```python
-setup_figure(width=1, height=0.4, extra_tracking="netCDF4")
+setup_figure(width=1, height=0.4, extra_tracking=["netCDF4"])
 ```
 
 

pgfutils.py

@@ -350,8 +350,8 @@ class PGFUtilsConfig(TypedDict):
     legend_opacity: float
     figure_background: Color
     axes_background: Color
-    extra_tracking: str
-    environment: str
+    extra_tracking: set[str]
+    environment: dict[str, str]
     separate_legend: bool
 
 
@@ -410,8 +410,8 @@ def __init__(self, load_file: bool = True) -> None:
             legend_opacity=0.8,
             figure_background=parse_color("transparent"),
             axes_background=parse_color("white"),
-            extra_tracking="",
-            environment="",
+            extra_tracking=set(),
+            environment={},
             separate_legend=False,
         )
         self.post_processing = dict(fix_raster_paths=True, tikzpicture=False)
@@ -543,9 +543,23 @@ def update(self, new_settings: Mapping[str, Mapping[str, Any]]):
                     if args == (Path,):
                         for item in val:
                             section[key].add(Path(item).resolve())
+                    elif args == (str,):
+                        for item in val:
+                            section[key].add(str(item))
                     else:
                         raise RuntimeError(f"unhandled set type {args}")
 
+                # For a dictionary, handle based on the type of the items.
+                elif origin is dict:
+                    if not isinstance(val, dict):
+                        raise ConfigError(name, key, "value must be a dictionary")
+
+                    if args == (str, str):
+                        for k, v in val.items():
+                            section[key][str(k)] = str(v)
+                    else:
+                        raise RuntimeError(f"unhandled dict type {args}")
+
                 # Assume a string.
                 else:
                     section[key] = val
@@ -713,26 +727,12 @@ def setup_figure(
         config.update({"pgfutils": kwargs})
 
     # Set environment variables specified in the configuration.
-    for line in config.pgfutils["environment"].splitlines():
-        line = line.strip()
-        if not line:
-            continue
-
-        # Check the variables are formatted correctly.
-        if "=" not in line:
-            raise ValueError(
-                "Environment variables should be in the form NAME=VALUE. "
-                f"The line '{line}' does not match this."
-            )
-
-        # And set them.
-        key, value = line.split("=", 1)
-        os.environ[key.strip()] = value.strip()
+    os.environ.update(config.pgfutils["environment"])
 
     # Install extra file trackers if desired.
-    extra = config.pgfutils["extra_tracking"].strip()
+    extra = config.pgfutils["extra_tracking"]
     if extra:
-        _install_extra_file_trackers(extra.split(","))
+        _install_extra_file_trackers(extra)
 
     # Reset our interactive flag on each call.
     _interactive = False

tests/sources/environment/check_set/override.py

@@ -7,7 +7,7 @@
 
 from pgfutils import save, setup_figure
 
-setup_figure()
+setup_figure(environment={"name2": "value3"})
 
 import os
 
@@ -18,7 +18,7 @@
     raise ValueError(
         "Incorrect value ({}) for environment variable name1".format(name1)
     )
-if name2 != "value2":
+if name2 != "value3":
     raise ValueError(
         "Incorrect value ({}) for environment variable name2".format(name2)
     )

tests/sources/environment/check_set/pgfutils.toml

@@ -2,7 +2,4 @@
 # SPDX-License-Identifier: BSD-3-Clause
 
 [pgfutils]
-environment="""
-  name1=value1
-  name2 = value2   
-"""
+environment = {name1="value1", name2="value2"}