Deprecated django.contrib.gis.geoip2.GeoIP2.coords().

The `ordering` argument is undocumented and of limited use, so this is
effectively the same as `GeoIP2.lon_lat()`.

5 files changed, 25 insertions, 3 deletions

diff --git a/django/contrib/gis/geoip2/base.py b/django/contrib/gis/geoip2/base.py
index 10c9bdbcfd..b9c3027668 100644
--- a/django/contrib/gis/geoip2/base.py
+++ b/django/contrib/gis/geoip2/base.py
@@ -1,4 +1,5 @@
 import socket
+import warnings
 
 import geoip2.database
 
@@ -6,6 +7,7 @@ from django.conf import settings
 from django.core.exceptions import ValidationError
 from django.core.validators import validate_ipv46_address
 from django.utils._os import to_path
+from django.utils.deprecation import RemovedInDjango60Warning
 
 from .resources import City, Country
 
@@ -199,6 +201,11 @@ class GeoIP2:
         return Country(self._country_or_city(enc_query))
 
     def coords(self, query, ordering=("longitude", "latitude")):
+        warnings.warn(
+            "GeoIP2.coords() is deprecated. Use GeoIP2.lon_lat() instead.",
+            RemovedInDjango60Warning,
+            stacklevel=2,
+        )
         data = self.city(query)
         return tuple(data[o] for o in ordering)
 
diff --git a/docs/internals/deprecation.txt b/docs/internals/deprecation.txt
index edda364b73..0067c8fbf5 100644
--- a/docs/internals/deprecation.txt
+++ b/docs/internals/deprecation.txt
@@ -64,6 +64,8 @@ details on these changes.
 * The undocumented ``django.utils.itercompat.is_iterable()`` function and the
   ``django.utils.itercompat`` module will be removed.
 
+* The ``django.contrib.gis.geoip2.GeoIP2.coords()`` method will be removed.
+
 .. _deprecation-removed-in-5.1:
 
 5.1
diff --git a/docs/ref/contrib/gis/geoip2.txt b/docs/ref/contrib/gis/geoip2.txt
index 5468cff29d..dc735ff13e 100644
--- a/docs/ref/contrib/gis/geoip2.txt
+++ b/docs/ref/contrib/gis/geoip2.txt
@@ -133,6 +133,10 @@ Coordinate Retrieval
 
 Returns a coordinate tuple of (longitude, latitude).
 
+.. deprecated:: 5.1
+
+    Use :meth:`.GeoIP2.lon_lat` instead.
+
 .. method:: GeoIP2.lon_lat(query)
 
 Returns a coordinate tuple of (longitude, latitude).
diff --git a/docs/releases/5.1.txt b/docs/releases/5.1.txt
index 4c95e4677f..33b4f1c491 100644
--- a/docs/releases/5.1.txt
+++ b/docs/releases/5.1.txt
@@ -307,6 +307,9 @@ Miscellaneous
   ``django.utils.itercompat`` module are deprecated. Use
   ``isinstance(..., collections.abc.Iterable)`` instead.
 
+* The ``django.contrib.gis.geoip2.GeoIP2.coords()`` method is deprecated. Use
+  ``django.contrib.gis.geoip2.GeoIP2.lon_lat()`` instead.
+
 Features removed in 5.1
 =======================
 
diff --git a/tests/gis_tests/test_geoip2.py b/tests/gis_tests/test_geoip2.py
index 163ba4887d..1a8773a6d7 100644
--- a/tests/gis_tests/test_geoip2.py
+++ b/tests/gis_tests/test_geoip2.py
@@ -6,6 +6,7 @@ from django.conf import settings
 from django.contrib.gis.geoip2 import HAS_GEOIP2
 from django.contrib.gis.geos import GEOSGeometry
 from django.test import SimpleTestCase
+from django.utils.deprecation import RemovedInDjango60Warning
 
 if HAS_GEOIP2:
     from django.contrib.gis.geoip2 import GeoIP2, GeoIP2Exception
@@ -71,8 +72,6 @@ class GeoIPTest(SimpleTestCase):
         # No city database available, these calls should fail.
         with self.assertRaises(GeoIP2Exception):
             cntry_g.city("tmc.edu")
-        with self.assertRaises(GeoIP2Exception):
-            cntry_g.coords("tmc.edu")
 
         # Non-string query should raise TypeError
         with self.assertRaises(TypeError):
@@ -139,7 +138,6 @@ class GeoIPTest(SimpleTestCase):
 
             for e1, e2 in (
                 geom.tuple,
-                g.coords(query),
                 g.lon_lat(query),
                 g.lat_lon(query),
             ):
@@ -182,3 +180,11 @@ class GeoIPTest(SimpleTestCase):
             g._check_query("2002:81ed:c9a5::81ed:c9a5"), "2002:81ed:c9a5::81ed:c9a5"
         )
         self.assertEqual(g._check_query("invalid-ip-address"), "expected")
+
+    def test_coords_deprecation_warning(self):
+        g = GeoIP2()
+        msg = "GeoIP2.coords() is deprecated. Use GeoIP2.lon_lat() instead."
+        with self.assertWarnsMessage(RemovedInDjango60Warning, msg):
+            e1, e2 = g.coords(self.fqdn)
+        self.assertIsInstance(e1, float)
+        self.assertIsInstance(e2, float)