Fixed #32670 -- Allowed GDALRasters to use any GDAL virtual filesystem.

3 files changed, 65 insertions, 3 deletions

diff --git a/docs/ref/contrib/gis/gdal.txt b/docs/ref/contrib/gis/gdal.txt
index e3d8b70ced..7d5a205c1e 100644
--- a/docs/ref/contrib/gis/gdal.txt
+++ b/docs/ref/contrib/gis/gdal.txt
@@ -1111,9 +1111,9 @@ blue.
     raster should be opened in write mode. For newly-created rasters, the second
     parameter is ignored and the new raster is always created in write mode.
 
-    The first parameter can take three forms: a string representing a file
-    path, a dictionary with values defining a new raster, or a bytes object
-    representing a raster file.
+    The first parameter can take three forms: a string representing a file path
+    (filesystem or GDAL virtual filesystem), a dictionary with values defining
+    a new raster, or a bytes object representing a raster file.
 
     If the input is a file path, the raster is opened from there. If the input
     is raw data in a dictionary, the parameters ``width``, ``height``, and
@@ -1164,6 +1164,10 @@ blue.
         >>> rst.name  # Stored in a random path in the vsimem filesystem.
         '/vsimem/da300bdb-129d-49a8-b336-e410a9428dad'
 
+    .. versionchanged:: 4.0
+
+        Creating rasters in any GDAL virtual filesystem was allowed.
+
     .. attribute:: name
 
         The name of the source which is equivalent to the input file path or the name
@@ -1772,6 +1776,13 @@ Key              Default                           Usage
 Using GDAL's Virtual Filesystem
 -------------------------------
 
+GDAL can access files stored in the filesystem, but also supports virtual
+filesystems to abstract accessing other kind of files, such as compressed,
+encrypted, or remote files.
+
+Using memory-based Virtual Filesystem
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
 GDAL has an internal memory-based filesystem, which allows treating blocks of
 memory as files. It can be used to read and write :class:`GDALRaster` objects
 to and from binary file buffers.
@@ -1817,6 +1828,53 @@ Here's how to create a raster and return it as a file in an
     ... })
     >>> HttpResponse(rast.vsi_buffer, 'image/tiff')
 
+Using other Virtual Filesystems
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. versionadded:: 4.0
+
+Depending on the local build of GDAL other virtual filesystems may be
+supported. You can use them by prepending the provided path with the
+appropriate ``/vsi*/`` prefix. See the `GDAL Virtual Filesystems
+documentation`_ for more details.
+
+.. warning:
+
+    Rasters with names starting with `/vsi*/` will be treated as rasters from
+    the GDAL virtual filesystems. Django doesn't perform any extra validation.
+
+Compressed rasters
+^^^^^^^^^^^^^^^^^^
+
+Instead decompressing the file and instantiating the resulting raster, GDAL can
+directly access compressed files using the ``/vsizip/``, ``/vsigzip/``, or
+``/vsitar/`` virtual filesystems::
+
+   >>> from django.contrib.gis.gdal import GDALRaster
+   >>> rst = GDALRaster('/vsizip/path/to/your/file.zip/path/to/raster.tif')
+   >>> rst = GDALRaster('/vsigzip/path/to/your/file.gz')
+   >>> rst = GDALRaster('/vsitar/path/to/your/file.tar/path/to/raster.tif')
+
+Network rasters
+^^^^^^^^^^^^^^^
+
+GDAL can support online resources and storage providers transparently. As long
+as it's built with such capabilities.
+
+To access a public raster file with no authentication, you can use
+``/vsicurl/``::
+
+   >>> from django.contrib.gis.gdal import GDALRaster
+   >>> rst = GDALRaster('/vsicurl/https://example.com/raster.tif')
+   >>> rst.name
+   '/vsicurl/https://example.com/raster.tif'
+
+For commercial storage providers (e.g. ``/vsis3/``) the system should be
+previously configured for authentication and possibly other settings (see the
+`GDAL Virtual Filesystems documentation`_ for available options).
+
+.. _`GDAL Virtual Filesystems documentation`: https://gdal.org/user/virtual_file_systems.html
+
 Settings
 ========
 
diff --git a/docs/releases/4.0.txt b/docs/releases/4.0.txt
index ee3aa6cc70..45dc67203d 100644
--- a/docs/releases/4.0.txt
+++ b/docs/releases/4.0.txt
@@ -102,6 +102,9 @@ Minor features
 
 * Added support for SpatiaLite 5.
 
+* :class:`~django.contrib.gis.gdal.GDALRaster` now allows creating rasters in
+  any GDAL virtual filesystem.
+
 :mod:`django.contrib.messages`
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
diff --git a/docs/spelling_wordlist b/docs/spelling_wordlist
index c65722cd5b..a1ace59a0f 100644
--- a/docs/spelling_wordlist
+++ b/docs/spelling_wordlist
@@ -217,6 +217,7 @@ fieldsets
 filename
 filenames
 filesystem
+filesystems
 fk
 flatpage
 flatpages