Simplified coordinate retrieval routines for GeoIP2.

django/contrib/gis/geoip2/base.py

@@ -1,11 +1,13 @@
 import socket
+import warnings
 
 import geoip2.database
 
 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
 
@@ -198,32 +200,31 @@ def country(self, query):
         enc_query = self._check_query(query, city_or_country=True)
         return Country(self._country_or_city(enc_query))
 
-    # #### Coordinate retrieval routines ####
     def coords(self, query, ordering=("longitude", "latitude")):
-        cdict = self.city(query)
-        if cdict is None:
-            return None
-        else:
-            return tuple(cdict[o] for o in ordering)
+        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)
 
     def lon_lat(self, query):
         "Return a tuple of the (longitude, latitude) for the given query."
-        return self.coords(query)
+        data = self.city(query)
+        return data["longitude"], data["latitude"]
 
     def lat_lon(self, query):
         "Return a tuple of the (latitude, longitude) for the given query."
-        return self.coords(query, ("latitude", "longitude"))
+        data = self.city(query)
+        return data["latitude"], data["longitude"]
 
     def geos(self, query):
         "Return a GEOS Point object for the given query."
-        ll = self.lon_lat(query)
-        if ll:
-            # Allows importing and using GeoIP2() when GEOS is not installed.
-            from django.contrib.gis.geos import Point
+        # Allows importing and using GeoIP2() when GEOS is not installed.
+        from django.contrib.gis.geos import Point
 
-            return Point(ll, srid=4326)
-        else:
-            return None
+        return Point(self.lon_lat(query), srid=4326)
 
     @classmethod
     def open(cls, full_path, cache):

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

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).

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
 =======================
 

tests/gis_tests/test_geoip2.py

@@ -6,6 +6,7 @@
 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 @@ def test02_bad_query(self):
         # 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 @@ def test04_city(self, gethostbyname):
 
             for e1, e2 in (
                 geom.tuple,
-                g.coords(query),
                 g.lon_lat(query),
                 g.lat_lon(query),
             ):
@@ -182,3 +180,11 @@ def test_check_query(self, gethostbyname):
             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)