From 65eeb9b7442dfa7671622d34d62c8f0816312bea Mon Sep 17 00:00:00 2001 From: Jason Grout Date: Thu, 23 Jun 2022 11:26:22 -0600 Subject: [PATCH 1/8] Follow up of #979, correcting our LegendControl docs where needed. I left in a backwards-compatible shim for giving the name argument to the LegendControl. --- docs/source/controls/legend_control.rst | 10 +++++----- examples/LegendControl.ipynb | 10 +++++----- ipyleaflet/leaflet.py | 9 ++++++--- 3 files changed, 16 insertions(+), 13 deletions(-) diff --git a/docs/source/controls/legend_control.rst b/docs/source/controls/legend_control.rst index 37dcce23d..1d08f3bc0 100644 --- a/docs/source/controls/legend_control.rst +++ b/docs/source/controls/legend_control.rst @@ -10,7 +10,7 @@ Example m = Map(center=(-10,-45), zoom=4) - legend = LegendControl({"low":"#FAA", "medium":"#A55", "High":"#500"}, name="Legend", position="bottomright") + legend = LegendControl({"low":"#FAA", "medium":"#A55", "High":"#500"}, title="Legend", position="bottomright") m.add(legend) m @@ -20,12 +20,12 @@ Example # Manipulate the legend # Set/Get legend title - legend.name = "Risk" # Set name - legend.name # Get name + legend.title = "Risk" # Set title + legend.title # Get title # Set/Get legend content - legend.legends = {"el1":"#FAA", "el2":"#A55", "el3":"#500"} # Set content - legend.legends # Get content + legend.legend = {"el1":"#FAA", "el2":"#A55", "el3":"#500"} # Set content + legend.legend # Get content legend.add_legend_element("el5","#000") # Add a legend element legend.remove_legend_element("el5") # Remove a legend element diff --git a/examples/LegendControl.ipynb b/examples/LegendControl.ipynb index 22ba678b4..997e06b56 100644 --- a/examples/LegendControl.ipynb +++ b/examples/LegendControl.ipynb @@ -54,7 +54,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "By default, you need to provide at least a dictionary with pair key=> the label to display and value=> the desired color. By default, it is named 'Legend', but you can pass a name as argument as well." + "By default, you need to provide at least a dictionary with pair key=> the label to display and value=> the desired color. By default, it is titled 'Legend', but you can pass a title as argument as well." ] }, { @@ -65,7 +65,7 @@ "source": [ "a_legend = LegendControl(\n", " {\"low\": \"#FAA\", \"medium\": \"#A55\", \"High\": \"#500\"},\n", - " name=\"Legend\",\n", + " title=\"Legend\",\n", " position=\"bottomright\",\n", ")" ] @@ -90,7 +90,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "### Name" + "### Title" ] }, { @@ -99,8 +99,8 @@ "metadata": {}, "outputs": [], "source": [ - "a_legend.name = \"Risk\" ## set name\n", - "a_legend.name # get name" + "a_legend.title = \"Risk\" ## set title\n", + "a_legend.title # get title" ] }, { diff --git a/ipyleaflet/leaflet.py b/ipyleaflet/leaflet.py index 61fca5a9c..e8023531d 100644 --- a/ipyleaflet/leaflet.py +++ b/ipyleaflet/leaflet.py @@ -1932,10 +1932,13 @@ class LegendControl(Control): "value 2": "#55A", "value 3": "#005"}).tag(sync=True) - def __init__(self, legend, *args, name="Legend", **kwargs): + def __init__(self, legend, *args, **kwargs): + kwargs["legend"] = legend + # For backwards compatibility with ipyleaflet<=0.16.0 + if 'name' in kwargs: + kwargs.setdefault('title', kwargs['name']) + del kwargs['name'] super().__init__(*args, **kwargs) - self.title = name - self.legend = legend def add_legend_element(self, key, value): """Add a new legend element. From d08d8b2744838c3e589af765e7a240bcdd44ca6e Mon Sep 17 00:00:00 2001 From: Jason Grout Date: Thu, 23 Jun 2022 11:33:14 -0600 Subject: [PATCH 2/8] Update changelog with more explicit migration instructions for LegendControl. --- CHANGELOG.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 64352b36c..a6eaafb49 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,7 +5,13 @@ * Add Map panes [#999](https://github.com/jupyter-widgets/ipyleaflet/pull/999) * Allow setting Map.dragging [#1001](https://github.com/jupyter-widgets/ipyleaflet/pull/1001) * Add visible attribute to GeoJSON layer [#1002](https://github.com/jupyter-widgets/ipyleaflet/pull/1002) -* [BREAKING CHANGE] Remove get and set decorators in LegendControl [#979](https://github.com/jupyter-widgets/ipyleaflet/pull/979) +* [BREAKING CHANGE] Remove `name`, `legends`, `positioning`, and `positionning` properties in LegendControl [#979](https://github.com/jupyter-widgets/ipyleaflet/pull/979). Update your code with the following substitutions for a LegendControl `legend`: + * `legend.name` -> `legend.title` + * `legend.legends` -> `legend.legend` + * `legend.positioning` -> `legend.position` + * `legend.positionnning` -> `legend.position` + + The recommended way to create a LegendControl with a given title is to use the `title` parameter: `LegendControl({}, title='My Title')`. There is a backwards compatibility shim in place, so giving the title as `name` in the constructor still works, but is not recommended: `LegendControl({}, name='My Title')` ## Maintenance From beb5ed88aececf61ce741d4b26f60af9e0ba8c91 Mon Sep 17 00:00:00 2001 From: Jason Grout Date: Thu, 23 Jun 2022 11:35:18 -0600 Subject: [PATCH 3/8] Tweak changelog wording and sections. --- CHANGELOG.md | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index a6eaafb49..c7dbec65e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,11 +1,17 @@ ## v0.17.0 + +Here are some highlights of changes in this version. See the full list of changes for more details: https://github.com/jupyter-widgets/ipyleaflet/compare/0.16.0...0.17.0 + ### New Features * Make it possible to use Choropleth layer with data containing NaNs [#972](https://github.com/jupyter-widgets/ipyleaflet/pull/972) * Add Map panes [#999](https://github.com/jupyter-widgets/ipyleaflet/pull/999) * Allow setting Map.dragging [#1001](https://github.com/jupyter-widgets/ipyleaflet/pull/1001) * Add visible attribute to GeoJSON layer [#1002](https://github.com/jupyter-widgets/ipyleaflet/pull/1002) -* [BREAKING CHANGE] Remove `name`, `legends`, `positioning`, and `positionning` properties in LegendControl [#979](https://github.com/jupyter-widgets/ipyleaflet/pull/979). Update your code with the following substitutions for a LegendControl `legend`: + +### Breaking Changes + +* Remove `name`, `legends`, `positioning`, and `positionning` properties in LegendControl [#979](https://github.com/jupyter-widgets/ipyleaflet/pull/979). Update your code with the following substitutions for a LegendControl `legend`: * `legend.name` -> `legend.title` * `legend.legends` -> `legend.legend` * `legend.positioning` -> `legend.position` @@ -13,7 +19,7 @@ The recommended way to create a LegendControl with a given title is to use the `title` parameter: `LegendControl({}, title='My Title')`. There is a backwards compatibility shim in place, so giving the title as `name` in the constructor still works, but is not recommended: `LegendControl({}, name='My Title')` -## Maintenance +### Maintenance * Compute the public path automatically [#988](https://github.com/jupyter-widgets/ipyleaflet/pull/988) @@ -22,8 +28,6 @@ * Document use of multiple basemaps [#971](https://github.com/jupyter-widgets/ipyleaflet/pull/971) * Add a small introduction text [#992](https://github.com/jupyter-widgets/ipyleaflet/pull/992) -**Full Changelog**: https://github.com/jupyter-widgets/ipyleaflet/compare/0.16.0...0.17.0 - ## v0.16.0 ### New features From 93c14b3b5ef926853ee2266bcbe38ea86fd97786 Mon Sep 17 00:00:00 2001 From: Jason Grout Date: Thu, 23 Jun 2022 14:20:40 -0600 Subject: [PATCH 4/8] Document the add/remove/substitute changes in #982 --- CHANGELOG.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index c7dbec65e..25b219c6a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -18,6 +18,14 @@ Here are some highlights of changes in this version. See the full list of change * `legend.positionnning` -> `legend.position` The recommended way to create a LegendControl with a given title is to use the `title` parameter: `LegendControl({}, title='My Title')`. There is a backwards compatibility shim in place, so giving the title as `name` in the constructor still works, but is not recommended: `LegendControl({}, name='My Title')` +* Deprecate layer and control-specific methods for maps, in favor of methods that work for both layers and controls [#982](https://github.com/jupyter-widgets/ipyleaflet/pull/982). Update your code with the following substitutions for a Map `map`: + * `map.add_control(...)` or `map.add_layer(...)` -> `map.add(...)` + * `map.remove_control(...)` or `map.remove_layer(...)` -> `map.remove(...)` + * `map.remove_control(...)` or `map.remove_layer(...)` -> `map.remove(...)` + * `map.substitute_control(...)` or `map.substitute_layer(...)` -> `map.substitute(...)` + * `map.clear_controls(...)` or `map.clear_layers(...)` -> `map.clear(...)` + + The inline operators still continue to work as before, such as `map += control` or `map -= layer`. ### Maintenance From b15b6f7039c2278b070562b3e921bc4920dfb765 Mon Sep 17 00:00:00 2001 From: Jason Grout Date: Thu, 23 Jun 2022 14:36:01 -0600 Subject: [PATCH 5/8] Point to changelog from docs to provide visibility for the breaking changes. --- docs/source/changelog.rst | 4 ++++ docs/source/index.rst | 1 + 2 files changed, 5 insertions(+) create mode 100644 docs/source/changelog.rst diff --git a/docs/source/changelog.rst b/docs/source/changelog.rst new file mode 100644 index 000000000..bab463aea --- /dev/null +++ b/docs/source/changelog.rst @@ -0,0 +1,4 @@ +Releases +======== + +The changes for each release are listed in the `ChangeLog `_. diff --git a/docs/source/index.rst b/docs/source/index.rst index f00297ccc..162472a70 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -31,3 +31,4 @@ Table of Contents controls/index api_reference/index related_projects/index + changelog From 8351f11eb347999a252e2036274dbbf2fb8f0ec1 Mon Sep 17 00:00:00 2001 From: Jason Grout Date: Fri, 24 Jun 2022 19:22:17 -0600 Subject: [PATCH 6/8] Add deprecation warnings for deprecated API changes. This also adds back in some API changes as deprecated, and switches a few more from PendingDeprecationWarnings to DeprecationWarnings. --- CHANGELOG.md | 4 +- ipyleaflet/leaflet.py | 90 +++++++++++++++++++++++++++++++++++++------ 2 files changed, 80 insertions(+), 14 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 25b219c6a..39f224c60 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -11,13 +11,13 @@ Here are some highlights of changes in this version. See the full list of change ### Breaking Changes -* Remove `name`, `legends`, `positioning`, and `positionning` properties in LegendControl [#979](https://github.com/jupyter-widgets/ipyleaflet/pull/979). Update your code with the following substitutions for a LegendControl `legend`: +* Deprecate LegendControl properties `name`, `legends`, `positioning`, and `positionning` [#979](https://github.com/jupyter-widgets/ipyleaflet/pull/979) and [#1005](https://github.com/jupyter-widgets/ipyleaflet/pull/1005). Update your code with the following substitutions for a LegendControl `legend`: * `legend.name` -> `legend.title` * `legend.legends` -> `legend.legend` * `legend.positioning` -> `legend.position` * `legend.positionnning` -> `legend.position` - The recommended way to create a LegendControl with a given title is to use the `title` parameter: `LegendControl({}, title='My Title')`. There is a backwards compatibility shim in place, so giving the title as `name` in the constructor still works, but is not recommended: `LegendControl({}, name='My Title')` + The `name` argument in creating a LegendControl is also deprecated, please use the `title` argument instead: `LegendControl({}, title='My Title')`. * Deprecate layer and control-specific methods for maps, in favor of methods that work for both layers and controls [#982](https://github.com/jupyter-widgets/ipyleaflet/pull/982). Update your code with the following substitutions for a Map `map`: * `map.add_control(...)` or `map.add_layer(...)` -> `map.add(...)` * `map.remove_control(...)` or `map.remove_layer(...)` -> `map.remove(...)` diff --git a/ipyleaflet/leaflet.py b/ipyleaflet/leaflet.py index e8023531d..0286238dc 100644 --- a/ipyleaflet/leaflet.py +++ b/ipyleaflet/leaflet.py @@ -1107,7 +1107,7 @@ def add_layer(self, layer): layer: layer instance The new layer to include in the group. """ - warnings.warn("add_layer will be deprecated in future version, use add instead", PendingDeprecationWarning) + warnings.warn("add_layer is deprecated, use add instead", DeprecationWarning) self.add(layer) @@ -1122,7 +1122,7 @@ def remove_layer(self, rm_layer): layer: layer instance The layer to remove from the group. """ - warnings.warn("remove_layer will be deprecated in future version, use remove instead", PendingDeprecationWarning) + warnings.warn("remove_layer is deprecated, use remove instead", DeprecationWarning) self.remove(rm_layer) @@ -1139,7 +1139,7 @@ def substitute_layer(self, old, new): new: layer instance The new layer to include in the group. """ - warnings.warn("substitute_layer will be deprecated in future version, substitute instead", PendingDeprecationWarning) + warnings.warn("substitute_layer is deprecated, use substitute instead", DeprecationWarning) self.substitute(old, new) @@ -1151,7 +1151,7 @@ def clear_layers(self): """ - warnings.warn("clear_layers will be deprecated in future version, use clear instead", PendingDeprecationWarning) + warnings.warn("clear_layers is deprecated, use clear instead", DeprecationWarning) self.layers = () @@ -1915,6 +1915,10 @@ class LegendControl(Control): A control which contains a legend. + .. deprecated :: 0.17.0 + The constructor argument 'name' is deprecated, use the 'title' argument instead. + + Attributes ---------- title: str, default 'Legend' @@ -1936,10 +1940,72 @@ def __init__(self, legend, *args, **kwargs): kwargs["legend"] = legend # For backwards compatibility with ipyleaflet<=0.16.0 if 'name' in kwargs: + warnings.warn("the name argument is deprecated, use title instead", DeprecationWarning) kwargs.setdefault('title', kwargs['name']) del kwargs['name'] super().__init__(*args, **kwargs) + @property + def name(self): + """The title of the legend. + + .. deprecated :: 0.17.0 + Use title attribute instead. + """ + warnings.warn(".name is deprecated, use .title instead", DeprecationWarning) + return self.title + + @name.setter + def name(self, title): + warnings.warn(".name is deprecated, use .title instead", DeprecationWarning) + self.title = title + + @property + def legends(self): + """The legend information. + + .. deprecated :: 0.17.0 + Use legend attribute instead. + """ + + warnings.warn(".legends is deprecated, use .legend instead", DeprecationWarning) + return self.legend + + @legends.setter + def legends(self, legends): + warnings.warn(".legends is deprecated, use .legend instead", DeprecationWarning) + self.legend = legends + + @property + def positioning(self): + """The position information. + + .. deprecated :: 0.17.0 + Use position attribute instead. + """ + warnings.warn(".positioning is deprecated, use .position instead", DeprecationWarning) + return self.position + + @positioning.setter + def positioning(self, position): + warnings.warn(".positioning is deprecated, use .position instead", DeprecationWarning) + self.position = position + + @property + def positionning(self): + """The position information. + + .. deprecated :: 0.17.0 + Use position attribute instead. + """ + warnings.warn(".positionning is deprecated, use .position instead", DeprecationWarning) + return self.position + + @positionning.setter + def positionning(self, position): + warnings.warn(".positionning is deprecated, use .position instead", DeprecationWarning) + self.position = position + def add_legend_element(self, key, value): """Add a new legend element. @@ -2286,7 +2352,7 @@ def _validate_layers(self, proposal): def add_layer(self, layer): """Add a layer on the map. - .. deprecated :: 0.0 + .. deprecated :: 0.17.0 Use add method instead. Parameters @@ -2294,7 +2360,7 @@ def add_layer(self, layer): layer: Layer instance The new layer to add. """ - warnings.warn("add_layer will be deprecated in future version, use add instead", PendingDeprecationWarning) + warnings.warn("add_layer is deprecated, use add instead", DeprecationWarning) self.add(layer) def remove_layer(self, rm_layer): @@ -2308,7 +2374,7 @@ def remove_layer(self, rm_layer): layer: Layer instance The layer to remove. """ - warnings.warn("remove_layer will be deprecated in future version, use remove instead", PendingDeprecationWarning) + warnings.warn("remove_layer is deprecated, use remove instead", DeprecationWarning) self.remove(rm_layer) @@ -2325,7 +2391,7 @@ def substitute_layer(self, old, new): new: Layer instance The new layer to add. """ - warnings.warn("substitute_layer will be deprecated in future version, use substitute instead", PendingDeprecationWarning) + warnings.warn("substitute_layer is deprecated, use substitute instead", DeprecationWarning) self.substitute(old, new) @@ -2336,7 +2402,7 @@ def clear_layers(self): Use add method instead. """ - warnings.warn("clear_layers will be deprecated in future version, use clear instead", PendingDeprecationWarning) + warnings.warn("clear_layers is deprecated, use clear instead", DeprecationWarning) self.layers = () @@ -2367,7 +2433,7 @@ def add_control(self, control): The new control to add. """ - warnings.warn("add_control will be deprecated in future version, use add instead", PendingDeprecationWarning) + warnings.warn("add_control is deprecated, use add instead", DeprecationWarning) self.add(control) @@ -2382,7 +2448,7 @@ def remove_control(self, control): control: Control instance The control to remove. """ - warnings.warn("remove_control will be deprecated in future version, use remove instead", PendingDeprecationWarning) + warnings.warn("remove_control is deprecated, use remove instead", DeprecationWarning) self.remove(control) @@ -2392,7 +2458,7 @@ def clear_controls(self): .. deprecated :: 0.17.0 Use clear method instead. """ - warnings.warn("clear_controls will be deprecated in future version, use clear instead", PendingDeprecationWarning) + warnings.warn("clear_controls is deprecated, use clear instead", DeprecationWarning) self.controls = () From 94cc2e74da5acc746cc922d8752a85297dc46781 Mon Sep 17 00:00:00 2001 From: Jason Grout Date: Fri, 24 Jun 2022 22:55:11 -0600 Subject: [PATCH 7/8] Tweak changelog wording --- CHANGELOG.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 39f224c60..5468a16a7 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -18,10 +18,9 @@ Here are some highlights of changes in this version. See the full list of change * `legend.positionnning` -> `legend.position` The `name` argument in creating a LegendControl is also deprecated, please use the `title` argument instead: `LegendControl({}, title='My Title')`. -* Deprecate layer and control-specific methods for maps, in favor of methods that work for both layers and controls [#982](https://github.com/jupyter-widgets/ipyleaflet/pull/982). Update your code with the following substitutions for a Map `map`: +* Deprecate layer and control-specific method names for Map and LayerGroup, in favor of methods that work for both layers and controls [#982](https://github.com/jupyter-widgets/ipyleaflet/pull/982). Update your code with the following substitutions for a Map `map` (or LayerGroup): * `map.add_control(...)` or `map.add_layer(...)` -> `map.add(...)` * `map.remove_control(...)` or `map.remove_layer(...)` -> `map.remove(...)` - * `map.remove_control(...)` or `map.remove_layer(...)` -> `map.remove(...)` * `map.substitute_control(...)` or `map.substitute_layer(...)` -> `map.substitute(...)` * `map.clear_controls(...)` or `map.clear_layers(...)` -> `map.clear(...)` From 850a4c36e201cb899dfec91514c35ec2e1a5634e Mon Sep 17 00:00:00 2001 From: Jason Grout Date: Sat, 25 Jun 2022 06:53:50 -0700 Subject: [PATCH 8/8] Update CHANGELOG.md to note deprecated API --- CHANGELOG.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 5468a16a7..2b86d59b6 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,7 +9,7 @@ Here are some highlights of changes in this version. See the full list of change * Allow setting Map.dragging [#1001](https://github.com/jupyter-widgets/ipyleaflet/pull/1001) * Add visible attribute to GeoJSON layer [#1002](https://github.com/jupyter-widgets/ipyleaflet/pull/1002) -### Breaking Changes +### Deprecated API * Deprecate LegendControl properties `name`, `legends`, `positioning`, and `positionning` [#979](https://github.com/jupyter-widgets/ipyleaflet/pull/979) and [#1005](https://github.com/jupyter-widgets/ipyleaflet/pull/1005). Update your code with the following substitutions for a LegendControl `legend`: * `legend.name` -> `legend.title`