Merge pull request jupyter-widgets#1005 from jasongrout/legend

Add deprecation warnings for API changes
HaudinFlorence · Jun 30, 2022 · 4d5fc50 · 4d5fc50
2 parents 28cc971 + 850a4c3
commit 4d5fc50
Show file tree

Hide file tree

Showing 15 changed files with 853 additions and 87 deletions.
diff --git a/CHANGELOG.md b/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
 

diff --git a/docs/source/changelog.rst b/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>`_.
diff --git 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/docs/source/index.rst b/docs/source/index.rst
@@ -33,3 +33,4 @@ Table of Contents
     controls/index
     api_reference/index
     related_projects/index
+    changelog
diff --git a/examples/AwesomeIcons.ipynb b/examples/AwesomeIcons.ipynb
@@ -100,7 +100,11 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
+<<<<<<< HEAD
    "version": "3.10.5"
+=======
+   "version": "3.9.13"
+>>>>>>> e5a95b3 (Add subitems to a layer (either layers or controls).)
   }
  },
  "nbformat": 4,

diff --git a/examples/Choropleth.ipynb b/examples/Choropleth.ipynb
@@ -27,9 +27,22 @@
     "from branca.colormap import linear\n",
     "import random\n",
     "\n",
+    "center = (43, -100)\n",
+    "zoom = 4\n",
     "geo_json_data = json.load(open(\"us-states.json\"))\n",
-    "m = ipyleaflet.Map(center=(43, -100), zoom=4)\n",
-    "unemployment = pd.read_csv(\"US_Unemployment_Oct2012.csv\")"
+    "m = ipyleaflet.Map(center=center, zoom=zoom)\n",
+    "unemployment = pd.read_csv(\"US_Unemployment_Oct2012.csv\")\n",
+    "unemployment = dict(\n",
+    "    zip(unemployment[\"State\"].tolist(), unemployment[\"Unemployment\"].tolist())\n",
+    ")\n",
+    "layer = ipyleaflet.Choropleth(\n",
+    "    caption ='Unemployment rate',\n",
+    "    geo_data=geo_json_data,\n",
+    "    choro_data=unemployment,\n",
+    "    colormap=linear.YlOrRd_04,\n",
+    "    style={\"fillOpacity\": 0.8, \"dashArray\": \"5, 5\"},\n",
+    ")\n",
+    "marker = ipyleaflet.Marker(location=center, draggable=False)"
    ]
   },
   {
@@ -38,34 +51,54 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "unemployment = dict(\n",
-    "    zip(unemployment[\"State\"].tolist(), unemployment[\"Unemployment\"].tolist())\n",
-    ")"
+    "m.add(marker)\n",
+    "m.add(layer)\n",
+    "m.remove(layer)\n",
+    "m.add(layer)"
    ]
   },
   {
    "cell_type": "code",
    "execution_count": 3,
-   "metadata": {},
-   "outputs": [],
+   "metadata": {
+    "tags": []
+   },
+   "outputs": [
+    {
+     "data": {
+      "application/vnd.jupyter.widget-view+json": {
+       "model_id": "40323a3644a7496598866849740a94cd",
+       "version_major": 2,
+       "version_minor": 0
+      },
+      "text/plain": [
+       "Map(center=[43, -100], controls=(ZoomControl(options=['position', 'zoom_in_text', 'zoom_in_title', 'zoom_out_t…"
+      ]
+     },
+     "metadata": {},
+     "output_type": "display_data"
+    }
+   ],
    "source": [
-    "layer = ipyleaflet.Choropleth(\n",
-    "    geo_data=geo_json_data,\n",
-    "    choro_data=unemployment,\n",
-    "    colormap=linear.YlOrRd_04,\n",
-    "    style={\"fillOpacity\": 0.8, \"dashArray\": \"5, 5\"},\n",
-    ")"
+    "m"
    ]
   },
   {
    "cell_type": "code",
    "execution_count": 4,
    "metadata": {},
+   "outputs": [],
+   "source": []
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 5,
+   "metadata": {},
    "outputs": [
     {
      "data": {
       "application/vnd.jupyter.widget-view+json": {
-       "model_id": "6228f855244746258a6ad0553d1326f4",
+       "model_id": "484d6e62ed954ee4a8279c32a589d623",
        "version_major": 2,
        "version_minor": 0
       },
@@ -77,10 +110,7 @@
      "output_type": "display_data"
     }
    ],
-   "source": [
-    "m.add(layer)\n",
-    "m"
-   ]
+   "source": []
   },
   {
    "cell_type": "code",
@@ -205,7 +235,11 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
+<<<<<<< HEAD
    "version": "3.10.5"
+=======
+   "version": "3.9.13"
+>>>>>>> e5a95b3 (Add subitems to a layer (either layers or controls).)
   }
  },
  "nbformat": 4,

diff --git a/examples/LegendControl.ipynb b/examples/LegendControl.ipynb
@@ -66,7 +66,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."
    ]
   },
   {
@@ -77,7 +77,7 @@
    "source": [
     "a_legend = LegendControl(\n",
     "    {\"low\": \"#FAA\", \"medium\": \"#A55\", \"High\": \"#500\"},\n",
-    "    name=\"Legend\",\n",
+    "    title=\"Legend\",\n",
     "    position=\"bottomright\",\n",
     ")"
    ]
@@ -102,7 +102,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "### Name"
+    "### Title"
    ]
   },
   {
@@ -111,8 +111,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"
    ]
   },
   {
@@ -177,7 +177,11 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
+<<<<<<< HEAD
    "version": "3.10.5"
+=======
+   "version": "3.9.13"
+>>>>>>> e5a95b3 (Add subitems to a layer (either layers or controls).)
   }
  },
  "nbformat": 4,

diff --git a/examples/MarkerCluster-GeoJson.ipynb b/examples/MarkerCluster-GeoJson.ipynb
@@ -107,7 +107,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.9.7"
+   "version": "3.9.13"
   }
  },
  "nbformat": 4,

diff --git a/examples/Test_subitem_dev.ipynb b/examples/Test_subitem_dev.ipynb
@@ -0,0 +1,85 @@
+{
+ "cells": [
+  {
+   "cell_type": "code",
+   "execution_count": 2,
+   "id": "66760b63-9004-4d71-ada9-4060a22d14bf",
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "application/vnd.jupyter.widget-view+json": {
+       "model_id": "f3b845f957084672976f01fff6e5796e",
+       "version_major": 2,
+       "version_minor": 0
+      },
+      "text/plain": [
+       "Map(center=[43, -100], controls=(ZoomControl(options=['position', 'zoom_in_text', 'zoom_in_title', 'zoom_out_t…"
+      ]
+     },
+     "metadata": {},
+     "output_type": "display_data"
+    }
+   ],
+   "source": [
+    "import ipyleaflet\n",
+    "import json\n",
+    "import pandas as pd\n",
+    "from ipywidgets import link, FloatSlider\n",
+    "from branca.colormap import linear\n",
+    "import random\n",
+    "\n",
+    "center = (43, -100)\n",
+    "zoom = 4\n",
+    "geo_json_data = json.load(open(\"us-states.json\"))\n",
+    "m = ipyleaflet.Map(center=center, zoom=zoom)\n",
+    "unemployment = pd.read_csv(\"US_Unemployment_Oct2012.csv\")\n",
+    "unemployment = dict(\n",
+    "    zip(unemployment[\"State\"].tolist(), unemployment[\"Unemployment\"].tolist())\n",
+    ")\n",
+    "layer = ipyleaflet.Choropleth(\n",
+    "    caption ='Unemployment rate',\n",
+    "    geo_data=geo_json_data,\n",
+    "    choro_data=unemployment,\n",
+    "    colormap=linear.YlOrRd_04,\n",
+    "    style={\"fillOpacity\": 0.8, \"dashArray\": \"5, 5\"},\n",
+    ")\n",
+    "marker = ipyleaflet.Marker(location=center, draggable=False)\n",
+    "m.add(marker)\n",
+    "m.add(layer)\n",
+    "m.remove(layer)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "b871daf0-f835-4136-a941-97885d99bbaf",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "m.add(layer)"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3 (ipykernel)",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.9.13"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}