rename_like warns about conflicting variables

cf_xarray/accessor.py

@@ -1346,6 +1346,17 @@ def rename_like(
             theirs = _single(_get_all)(other, key)[0]
             renamer[ours] = theirs
 
+        conflicts = {
+            k: v for k, v in renamer.items() if list(renamer.values()).count(v) > 1
+        }
+        if conflicts:
+            renamer = {k: v for k, v in renamer.items() if k not in conflicts}
+            warnings.warn(
+                "Conflicting variables skipped:\n"
+                + "\n".join([f"{k}: {conflicts[k]}" for k in sorted(conflicts)]),
+                UserWarning,
+            )
+
         newobj = self._obj.rename(renamer)
 
         # rename variable names in the coordinates attribute

cf_xarray/tests/test_accessor.py

@@ -249,6 +249,10 @@ def test_rename_like():
     assert "temp" not in renamed
     assert "TEMP" in renamed
 
+    # skip conflicting variables
+    with pytest.warns(UserWarning, match="Conflicting variables skipped:.*"):
+        popds.cf["TEMP"].cf.rename_like(airds)
+
 
 @pytest.mark.parametrize("obj", objects)
 @pytest.mark.parametrize(

doc/examples/introduction.ipynb

@@ -582,13 +582,31 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "## Feature: Renaming coordinate variables\n",
+    "## Feature: Renaming variables\n",
     "\n",
-    "`cf_xarray` lets you rewrite coordinate variables in one dataset to like\n",
-    "variables in another dataset. This can only be done when a one-to-one mapping is\n",
-    "possible\n",
+    "`cf_xarray` lets you rewrite variables in one dataset to like variables in\n",
+    "another dataset.\n",
     "\n",
-    "In this example, `TLONG` and `TLAT` are renamed to `lon` and `lat` i.e. their\n",
+    "In this example, a one-to-one mapping is not possible and the coordinate\n",
+    "variables are not renamed.\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "da = pop.cf[\"TEMP\"]\n",
+    "da.cf.rename_like(ds)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "If we drop the `X` and `Y` axes, a one-to-one mapping is possible. In this\n",
+    "example, `TLONG` and `TLAT` are renamed to `lon` and `lat` i.e. their\n",
     "counterparts in `ds`. Note the the `coordinates` attribute is appropriately\n",
     "changed.\n"
    ]
@@ -604,7 +622,8 @@
    },
    "outputs": [],
    "source": [
-    "pop.cf[\"TEMP\"].cf.rename_like(ds)"
+    "da = da.cf.drop_vars([\"X\", \"Y\"])\n",
+    "da.cf.rename_like(ds)"
    ]
   },
   {