Refs #35058 -- Deprecated OGRGeometry.coord_dim setter.

Reflecting a change in the underlying GDAL library (since GDAL 2.1)
using coord_dim to set a geometries dimensions is deprecated in favor
of set_3d().

5 files changed, 31 insertions, 6 deletions

diff --git a/django/contrib/gis/gdal/geometries.py b/django/contrib/gis/gdal/geometries.py
index 516c6c7113..57f81ca476 100644
--- a/django/contrib/gis/gdal/geometries.py
+++ b/django/contrib/gis/gdal/geometries.py
@@ -39,6 +39,7 @@
   True True
 """
 import sys
+import warnings
 from binascii import b2a_hex
 from ctypes import byref, c_char_p, c_double, c_ubyte, c_void_p, string_at
 
@@ -50,6 +51,7 @@ from django.contrib.gis.gdal.prototypes import geom as capi
 from django.contrib.gis.gdal.prototypes import srs as srs_api
 from django.contrib.gis.gdal.srs import CoordTransform, SpatialReference
 from django.contrib.gis.geometry import hex_regex, json_regex, wkt_regex
+from django.utils.deprecation import RemovedInDjango60Warning
 from django.utils.encoding import force_bytes
 
 
@@ -206,18 +208,21 @@ class OGRGeometry(GDALBase):
         "Return 0 for points, 1 for lines, and 2 for surfaces."
         return capi.get_dims(self.ptr)
 
-    def _get_coord_dim(self):
+    @property
+    def coord_dim(self):
         "Return the coordinate dimension of the Geometry."
         return capi.get_coord_dim(self.ptr)
 
-    def _set_coord_dim(self, dim):
+    # RemovedInDjango60Warning
+    @coord_dim.setter
+    def coord_dim(self, dim):
         "Set the coordinate dimension of this Geometry."
+        msg = "coord_dim setter is deprecated. Use set_3d() instead."
+        warnings.warn(msg, RemovedInDjango60Warning, stacklevel=2)
         if dim not in (2, 3):
             raise ValueError("Geometry dimension must be either 2 or 3")
         capi.set_coord_dim(self.ptr, dim)
 
-    coord_dim = property(_get_coord_dim, _set_coord_dim)
-
     @property
     def geom_count(self):
         "Return the number of elements in this Geometry."
diff --git a/docs/internals/deprecation.txt b/docs/internals/deprecation.txt
index 07e0f46856..e91ac062cb 100644
--- a/docs/internals/deprecation.txt
+++ b/docs/internals/deprecation.txt
@@ -71,6 +71,9 @@ details on these changes.
 * Support for passing positional arguments to ``Model.save()`` and
   ``Model.asave()`` will be removed.
 
+* The setter for ``django.contrib.gis.gdal.OGRGeometry.coord_dim`` will be
+  removed.
+
 .. _deprecation-removed-in-5.1:
 
 5.1
diff --git a/docs/ref/contrib/gis/gdal.txt b/docs/ref/contrib/gis/gdal.txt
index c98c76cd10..4b7a706fc4 100644
--- a/docs/ref/contrib/gis/gdal.txt
+++ b/docs/ref/contrib/gis/gdal.txt
@@ -553,8 +553,12 @@ coordinate transformation:
 
     .. attribute:: coord_dim
 
-    Returns or sets the coordinate dimension of this geometry. For example, the
-    value would be 2 for two-dimensional geometries.
+    Returns the coordinate dimension of this geometry. For example, the value
+    would be 2 for two-dimensional geometries.
+
+    .. deprecated:: 5.1
+
+        The ``coord_dim`` setter is deprecated. Use :meth:`.set_3d` instead.
 
     .. attribute:: is_3d
 
diff --git a/docs/releases/5.1.txt b/docs/releases/5.1.txt
index be609cea7f..0cf249f3cf 100644
--- a/docs/releases/5.1.txt
+++ b/docs/releases/5.1.txt
@@ -378,6 +378,9 @@ Miscellaneous
 * Passing positional arguments to :meth:`.Model.save` and :meth:`.Model.asave`
   is deprecated in favor of keyword-only arguments.
 
+* Setting ``django.contrib.gis.gdal.OGRGeometry.coord_dim`` is deprecated. Use
+  :meth:`~django.contrib.gis.gdal.OGRGeometry.set_3d` instead.
+
 Features removed in 5.1
 =======================
 
diff --git a/tests/gis_tests/gdal_tests/test_geom.py b/tests/gis_tests/gdal_tests/test_geom.py
index 9d62bcd07b..13e7d3e70d 100644
--- a/tests/gis_tests/gdal_tests/test_geom.py
+++ b/tests/gis_tests/gdal_tests/test_geom.py
@@ -11,6 +11,7 @@ from django.contrib.gis.gdal import (
 from django.template import Context
 from django.template.engine import Engine
 from django.test import SimpleTestCase
+from django.utils.deprecation import RemovedInDjango60Warning
 
 from ..test_data import TestDataMixin
 
@@ -810,3 +811,12 @@ class OGRGeomTest(SimpleTestCase, TestDataMixin):
                 g = OGRGeometry(geom)
                 self.assertEqual(g.wkt, geom)
                 self.assertEqual(g.wkb.hex(), wkb)
+
+
+class DeprecationTests(SimpleTestCase):
+    def test_coord_setter_deprecation(self):
+        geom = OGRGeometry("POINT (1 2)")
+        msg = "coord_dim setter is deprecated. Use set_3d() instead."
+        with self.assertWarnsMessage(RemovedInDjango60Warning, msg):
+            geom.coord_dim = 3
+        self.assertEqual(geom.coord_dim, 3)