diff --git a/Changes b/Changes index aa65afe7223d848a5ae5090e8f025423d20e9aab..f2ba442e8c78721ad39990c6c70ef0f25b3f87cd 100644 --- a/Changes +++ b/Changes @@ -1,24 +1,39 @@ -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 diff --git a/gnuplotlib.py b/gnuplotlib.py index c9ee7e7f2f3197aef75309c4e828776cf669b8f1..a5d5c884186b1b419b537d0ff9478af91f920059 100755 --- a/gnuplotlib.py +++ b/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]