New upstream version 0.38

Changes

-gnuplotlib (0.37) unstable; urgency=medium
+gnuplotlib (0.38)
+
+  * Extended add_plot_option() API
+  
+    This is a backwards-compatible update. There is NO API break. Two new
+    features:
+
+    - multiple key/value sets can be set in a single call by using keyword
+      arguments
+
+    - "overwrite" kwarg can be used to overwrite previously-set keys OR to
+      leave the previous ones without barfing
+
+ -- Dima Kogan <dkogan@debian.org>  Sun, 11 Apr 2021 18:42:07 -0700
+
+gnuplotlib (0.37)
 
   * Updated default hardcopy settings
 
  -- Dima Kogan <dkogan@debian.org>  Wed, 03 Feb 2021 14:31:33 -0800
 
-gnuplotlib (0.36) unstable; urgency=medium
+gnuplotlib (0.36)
 
   * add_plot_option() API change: takes single options as scalars and
     lists as lists, just like the plot options that accept multiple values
 
  -- Dima Kogan <dkogan@debian.org>  Fri, 13 Nov 2020 21:28:55 -0800
 
-gnuplotlib (0.35) unstable; urgency=medium
+gnuplotlib (0.35)
 
   * Improved default svg terminal settings
   * Added add_plot_option() function, more robust plot option parsing
 
  -- Dima Kogan <dkogan@debian.org>  Sun, 08 Nov 2020 01:33:03 -0800
 
-gnuplotlib (0.34) unstable; urgency=medium
+gnuplotlib (0.34)
 
   * Lots of updates to the guide contents, and to the way it is built
   * I now barf if both "_key" and "key" are given in any set of options

gnuplotlib.py

@@ -1092,7 +1092,7 @@ import numpy as np
 import numpysane as nps
 
 # setup.py assumes the version is a simple string in '' quotes
-__version__ = '0.37'
+__version__ = '0.38'
 
 # In a multiplot, the "process" options apply to the larger plot containing all
 # the subplots, and the "subplot" options apply to each invididual plot.
@@ -2745,45 +2745,81 @@ def wait():
     globalplot.wait()
 
 
-def add_plot_option(d, key, values):
+def add_plot_option(d,
+                    key       = None,
+                    values    = None,
+                    overwrite = None,
+                    **kwargs):
     r'''Ingests new key/value pairs into an option dict
 
-    SYNOPSIS
+SYNOPSIS
 
-        # A baseline plot_options dict was given to us. We want to make the
-        # plot, but make sure to omit the legend key
+    # A baseline plot_options dict was given to us. We want to make the
+    # plot, but make sure to omit the legend key
+    add_plot_option(plot_options, 'unset', 'key')
 
-        add_plot_option(plot_options, 'unset', 'key')
+    gp.plot(..., **plot_options)
 
-        gp.plot(..., **plot_options)
+DESCRIPTION
 
-    DESCRIPTION
+Given a plot_options dict we can easily add a new option with
+
+    plot_options[key] = value
+
+This has several potential problems:
+
+- If an option for this key already exists, the above will overwrite the old
+  value instead of adding a NEW option
+
+- All options may take a leading _ to avoid conflicting with Python reserved
+  words (set, _set for instance). The above may unwittingly create a
+  duplicate
+
+- Some plot options support multiple values, which the simple call ignores
+  completely
 
-    Given a plot_options dict we can easily add a new option with
+THIS function takes care of the _ in keys. And this function knows which
+keys support multiple values. If a duplicate is given, it will either raise
+an exception, or append to the existing list, as appropriate.
 
-        plot_options[key] = value
+If the given key supports multiple values, they can be given in a single
+call, as a list or a tuple.
 
-    This has several potential problems:
+Multiple key/values can be given using keyword arguments.
 
-    - If an option for this key already exists, the above will overwrite the old
-      value instead of adding a NEW option
+ARGUMENTS
 
-    - All options may take a leading _ to avoid conflicting with Python reserved
-      words (set, _set for instance). The above may unwittingly create a
-      duplicate
+- d: the plot options dict we're updating
 
-    - Some plot options support multiple values, which the simple call ignores
-      completely
+- key: string. The key being set
 
-    THIS function takes care of the _ in keys. And this function knows which
-    keys support multiple values. If a duplicate is given, it will either raise
-    an exception, or append to the existing list, as appropriate.
+- values: string (if setting a single value) or iterable (if setting multiple
+  values)
 
-    If the given key supports multiple values, they can be given in a single
-    call, as a list or a tuple.
+- **kwargs: more key/value pairs to set. We set the key/value positional
+  arguments first, and then move on to the kwargs
+
+- overwrite: optional boolean that controls how we handle overwriting keys that
+  do not accept multiple values. By default (overwrite is None), trying to set a
+  key that is already set results in an exception. elif overwrite: we overwrite
+  the previous values. elif not overwrite: we leave the previous value
 
     '''
 
+    if kwargs:
+        add_plot_option(d, key, values,
+                        overwrite)
+        for key in kwargs:
+            add_plot_option(d, key, kwargs[key],
+                            overwrite)
+        return
+
+    if key is None:
+        if values is not None:
+            raise Exception("key is None, but values is not. Giving up")
+        return
+
+
     key_normalized = key if key[0] != '_' else key[1:]
     if not (key_normalized in keysAcceptingIterable and \
             isinstance(values, (list,tuple))):
@@ -2793,10 +2829,17 @@ def add_plot_option(d, key, values):
     if len(values) == 0: return
 
     if key_normalized not in keysAcceptingIterable:
-        if key in d or key_normalized in d or len(values) > 1:
-            # Already have old key, so can't add a new key. Or have multiple new
-            # values.
-            raise GnuplotlibError("Options dict given multiple values for key '{}'".format(key_normalized))
+        if len(values) > 1:
+            raise GnuplotlibError("plot options given multiple values for key '{}'".format(key_normalized))
+        if key in d or key_normalized in d:
+            # A value already exists. What do I do?
+            if   (overwrite is not None) and overwrite:
+                pass
+            elif (overwrite is not None) and not overwrite:
+                return
+            else:
+                # overwrite is None (the default). Barf.
+                raise GnuplotlibError("plot options already have a value for key '{}'. Pass 'overwrite=False' to use the existing one of 'overwrite=True' to use the new one".format(key_normalized))
 
         d[key_normalized] = values[0]