add DeprecationWarning for upcoming change in locationmode 'country names'

Author: emilykl

codegen/datatypes.py

@@ -10,6 +10,10 @@
     "choroplethmapbox",
     "densitymapbox",
 ]
+locationmode_traces = [
+    "choropleth",
+    "scattergeo",
+]
 
 
 def get_typing_type(plotly_type, array_ok=False):
@@ -100,6 +104,7 @@ def build_datatype_py(node):
 
     if (
         node.name_property in deprecated_mapbox_traces
+        or node.name_property in locationmode_traces
         or node.name_property == "template"
     ):
         buffer.write("import warnings\n")
@@ -341,6 +346,27 @@ def __init__(self"""
 constructor must be a dict or
 an instance of :class:`{class_name}`\"\"\")
 
+        """
+    )
+
+    # Add warning for 'country names' locationmode
+    if node.name_property in locationmode_traces:
+        buffer.write(
+            f"""
+        if locationmode == "country names" and kwargs.get("_validate"):
+            warnings.warn(
+                "The library used by the *country names* `locationmode` option is changing in an upcoming version. "
+                "Country names in existing plots may not work in the new version. "
+                "To ensure consistent behavior, consider setting `locationmode` to *ISO-3*.",
+                DeprecationWarning,
+                stacklevel=5,
+            )
+
+            """
+        )
+
+    buffer.write(
+        f"""
         self._skip_invalid = kwargs.pop("skip_invalid", False)
         self._validate = kwargs.pop("_validate", True)
         """

plotly/express/_chart_types.py

@@ -1110,6 +1110,16 @@ def choropleth(
     In a choropleth map, each row of `data_frame` is represented by a
     colored region mark on a map.
     """
+
+    if locationmode == "country names":
+        warn(
+            "The library used by the *country names* `locationmode` option is changing in an upcoming version. "
+            "Country names in existing plots may not work in the new version. "
+            "To ensure consistent behavior, consider setting `locationmode` to *ISO-3*.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+
     return make_figure(
         args=locals(),
         constructor=go.Choropleth,
@@ -1168,6 +1178,16 @@ def scatter_geo(
     In a geographic scatter plot, each row of `data_frame` is represented
     by a symbol mark on a map.
     """
+
+    if locationmode == "country names":
+        warn(
+            "The library used by the *country names* `locationmode` option is changing in an upcoming version. "
+            "Country names in existing plots may not work in the new version. "
+            "To ensure consistent behavior, consider setting `locationmode` to *ISO-3*.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+
     return make_figure(
         args=locals(),
         constructor=go.Scattergeo,

plotly/graph_objs/_choropleth.py

@@ -3,6 +3,7 @@
 
 from plotly.basedatatypes import BaseTraceType as _BaseTraceType
 import copy as _copy
+import warnings
 
 
 class Choropleth(_BaseTraceType):
@@ -1708,6 +1709,15 @@ def __init__(
 constructor must be a dict or
 an instance of :class:`plotly.graph_objs.Choropleth`""")
 
+        if locationmode == "country names" and kwargs.get("_validate"):
+            warnings.warn(
+                "The library used by the *country names* `locationmode` option is changing in an upcoming version. "
+                "Country names in existing plots may not work in the new version. "
+                "To ensure consistent behavior, consider setting `locationmode` to *ISO-3*.",
+                DeprecationWarning,
+                stacklevel=5,
+            )
+
         self._skip_invalid = kwargs.pop("skip_invalid", False)
         self._validate = kwargs.pop("_validate", True)
 

plotly/graph_objs/_scattergeo.py

@@ -3,6 +3,7 @@
 
 from plotly.basedatatypes import BaseTraceType as _BaseTraceType
 import copy as _copy
+import warnings
 
 
 class Scattergeo(_BaseTraceType):
@@ -1804,6 +1805,15 @@ def __init__(
 constructor must be a dict or
 an instance of :class:`plotly.graph_objs.Scattergeo`""")
 
+        if locationmode == "country names" and kwargs.get("_validate"):
+            warnings.warn(
+                "The library used by the *country names* `locationmode` option is changing in an upcoming version. "
+                "Country names in existing plots may not work in the new version. "
+                "To ensure consistent behavior, consider setting `locationmode` to *ISO-3*.",
+                DeprecationWarning,
+                stacklevel=5,
+            )
+
         self._skip_invalid = kwargs.pop("skip_invalid", False)
         self._validate = kwargs.pop("_validate", True)