Add deprecation warnings for API changes

CHANGELOG.md

@@ -1,13 +1,32 @@
 ## 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 get and set decorators in LegendControl [#979](https://github.com/jupyter-widgets/ipyleaflet/pull/979)
 
-## Maintenance
+### 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`
+  * `legend.legends` -> `legend.legend`
+  * `legend.positioning` -> `legend.position`
+  * `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 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.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
 
 * Compute the public path automatically [#988](https://github.com/jupyter-widgets/ipyleaflet/pull/988)
 
@@ -16,8 +35,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
 

docs/source/changelog.rst

@@ -0,0 +1,4 @@
+Releases
+========
+
+The changes for each release are listed in the `ChangeLog <https://github.com/jupyter-widgets/ipyleaflet/blob/master/CHANGELOG.md>`_.

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

docs/source/index.rst

@@ -31,3 +31,4 @@ Table of Contents
     controls/index
     api_reference/index
     related_projects/index
+    changelog

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"
    ]
   },
   {

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'
@@ -1932,10 +1936,75 @@ 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:
+            warnings.warn("the name argument is deprecated, use title instead", DeprecationWarning)
+            kwargs.setdefault('title', kwargs['name'])
+            del kwargs['name']
         super().__init__(*args, **kwargs)
-        self.title = name
-        self.legend = legend
+
+    @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.
@@ -2283,15 +2352,15 @@ 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
         ----------
         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):
@@ -2305,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)
 
@@ -2322,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)
 
@@ -2333,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 = ()
 
@@ -2364,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)
 
@@ -2379,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)
 
@@ -2389,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 = ()