Add GDALDatasetRunCloseWithoutDestroying() and use it Python bindings Dataset.Close()

Author: rouault

gcore/gdal.h

@@ -1315,6 +1315,7 @@ GDALDriverH CPL_DLL CPL_STDCALL GDALGetDatasetDriver(GDALDatasetH);
 char CPL_DLL **CPL_STDCALL GDALGetFileList(GDALDatasetH);
 void CPL_DLL GDALDatasetMarkSuppressOnClose(GDALDatasetH);
 CPLErr CPL_DLL CPL_STDCALL GDALClose(GDALDatasetH);
+CPLErr CPL_DLL GDALDatasetRunCloseWithoutDestroying(GDALDatasetH hDS);
 int CPL_DLL CPL_STDCALL GDALGetRasterXSize(GDALDatasetH);
 int CPL_DLL CPL_STDCALL GDALGetRasterYSize(GDALDatasetH);
 int CPL_DLL CPL_STDCALL GDALGetRasterCount(GDALDatasetH);

gcore/gdaldataset.cpp

@@ -394,6 +394,8 @@ GDALDataset::~GDALDataset()
  * If a driver implements this method, it must also call it from its
  * dataset destructor.
  *
+ * This is the equivalent of C function GDALDatasetRunCloseWithoutDestroying().
+ *
  * A typical implementation might look as the following
  * \code{.cpp}
  *
@@ -475,6 +477,37 @@ CPLErr GDALDataset::Close()
     return CE_None;
 }
 
+/************************************************************************/
+/*                   GDALDatasetRunCloseWithoutDestroying()             */
+/************************************************************************/
+
+/** Run the Close() method, without running destruction of the object.
+ *
+ * This ensures that content that should be written to file is written and
+ * that all file descriptors are closed.
+ *
+ * Note that this is different from GDALClose() which also destroys
+ * the underlying C++ object. GDALClose() or GDALReleaseDataset() are actually
+ * the only functions that can be safely called on the dataset handle after
+ * this function has been called.
+ *
+ * Most users want to use GDALClose() or GDALReleaseDataset() rather than
+ * this function.
+ *
+ * This function is equivalent to the C++ method GDALDataset:Close()
+ *
+ * @param hDS dataset handle.
+ * @return CE_None if no error
+ *
+ * @since GDAL 3.12
+ * @see GDALClose()
+ */
+CPLErr GDALDatasetRunCloseWithoutDestroying(GDALDatasetH hDS)
+{
+    VALIDATE_POINTER1(hDS, __func__, CE_Failure);
+    return GDALDataset::FromHandle(hDS)->Close();
+}
+
 /************************************************************************/
 /*                UnregisterFromSharedDataset()                         */
 /************************************************************************/

swig/include/Dataset.i

@@ -283,6 +283,16 @@ public:
      return GDALClose(self);
   }
 
+#ifdef SWIGPYTHON
+  CPLErr _RunCloseWithoutDestroying() {
+     CPLErr eErr = GDALDatasetRunCloseWithoutDestroying(self);
+     if (eErr != CE_None && CPLGetLastErrorType() == CE_None ) {
+       CPLError(CE_Failure, CPLE_AppDefined, "Error occurred in GDALDatasetRunCloseWithoutDestroying()");
+     }
+     return eErr;
+  }
+#endif
+
   GDALDriverShadow* GetDriver() {
     return (GDALDriverShadow*) GDALGetDatasetDriver( self );
   }

swig/include/python/gdal_python.i

@@ -2066,12 +2066,22 @@ CPLErr ReadRaster1( double xoff, double yoff, double xsize, double ysize,
     def Destroy(self):
         import warnings
         warnings.warn("Destroy() is deprecated; use a context manager or Close() instead", DeprecationWarning)
-        self.Close()
+        self._invalidate_children()
+        try:
+            return _gdal.Dataset_Close(self)
+        finally:
+            self.thisown = 0
+            self.this = None
 
     def Release(self):
         import warnings
         warnings.warn("Release() is deprecated; use a context manager or Close() instead", DeprecationWarning)
-        self.Close()
+        self._invalidate_children()
+        try:
+            return _gdal.Dataset_Close(self)
+        finally:
+            self.thisown = 0
+            self.this = None
 
     def SyncToDisk(self):
         return self.FlushCache()
@@ -2176,17 +2186,23 @@ CPLErr ReadRaster1( double xoff, double yoff, double xsize, double ysize,
         reachable. If :py:meth:`Close` is never called, the dataset will
         be closed automatically during garbage collection.
 
+        It is illegal to call any method on the dataset or objects derived
+        from it (bands, layers, etc.) afterwards.
+
         In most cases, it is preferable to open or create a dataset
         using a context manager instead of calling :py:meth:`Close`
         directly.
         """
 
         self._invalidate_children()
-        try:
-            return _gdal.Dataset_Close(self, *args)
-        finally:
-            self.thisown = 0
-            self.this = None
+        if self.GetRefCount() == 1 and self.thisown:
+            try:
+                return _gdal.Dataset_Close(self, *args)
+            finally:
+                self.thisown = 0
+                self.this = None
+        else:
+            return _gdal.Dataset__RunCloseWithoutDestroying(self, *args)
 %}
 
 %feature("shadow") ExecuteSQL %{