diff --git a/doc/api/api_changes/2015-03-03-LEO.rst b/doc/api/api_changes/2015-03-03-LEO.rst new file mode 100755 index 000000000000..270affdf33ed --- /dev/null +++ b/doc/api/api_changes/2015-03-03-LEO.rst @@ -0,0 +1,21 @@ +Added set_params function to all Locator types +```````````````````````````````````````````````` + +This was a bug fix targeted at making the api for Locators more consistent. + +In the old behavior, only locators of type MaxNLocator have set_params() +defined, causing its use on any other Locator to throw an AttributeError *( +aside: set_params(args) is a function that sets the parameters of a Locator +instance to be as specified within args)*. The fix involves moving set_params() +to the Locator class such that all subtypes will have this function defined. + +Since each of the Locator subtype have their own modifiable parameters, a +universal set_params() in Locator isn't ideal. Instead, a default no-operation +function that raises a warning is implemented in Locator. Subtypes extending +Locator will then override with their own implementations. Subtypes that do +not have a need for set_params() will fall back onto their parent's +implementation, which raises a warning as intended. + +In the new behavior, all Locator instances will not throw an AttributeError +when set_param() is called. For Locators that do not implement set_params(), +the default implementation in Locator is used. diff --git a/doc/users/whats_new/2015-03-03_locator-set_params.rst b/doc/users/whats_new/2015-03-03_locator-set_params.rst new file mode 100755 index 000000000000..22b95b7315ed --- /dev/null +++ b/doc/users/whats_new/2015-03-03_locator-set_params.rst @@ -0,0 +1,16 @@ +API Consistency fix within Locators set_params() function +--------------------------------------------------------- + +set_params() function, which sets parameters within a Locator type instance, +is now available to all Locator types. The implementation also prevents unsafe +usage by strictly defining the parameters that a user can set. + +To use, simply call set_params() on a Locator instance with desired arguments: +:: + + loc = matplotlib.ticker.LogLocator() + # Set given attributes for loc. + loc.set_params(numticks=8, numdecs=8, subs=[2.0], base=8) + # The below will error, as there is no such parameter for LogLocator + # named foo + # loc.set_params(foo='bar')