Add a warning and comments

lib/cartopy/__init__.py

@@ -56,6 +56,14 @@
     cartopy will download the appropriate file(s) to a subdirectory of this
     directory, therefore ``data_dir`` should be writable by the user.
 
+``cache_dir``
+    The absolute path to a directory where tiles data are cached when a
+    GoogleWTS sub-class is initialized with `cache=True`. If it is not found
+    cartopy will create it, therefore ``cache_dir`` should be writable by the
+    user. Note that the default cache dir might be accessible by all users,
+    depending on your OS and local configuration. If private cache is mandatory,
+    set cache_dir to a private location.
+
 ``repo_data_dir``
     The absolute path to the directory where the data delivered with the
     cartopy repository is stored.  Typically this will only be set by OS

lib/cartopy/io/img_tiles.py

@@ -37,6 +37,12 @@ class GoogleWTS(metaclass=ABCMeta):
 
     A "tile" in this class refers to the coordinates (x, y, z).
 
+    The tiles can be saved to a cache directory using the cache parameter, so
+    they are downloaded only once. If it is set to True, the default path
+    stored in the cartopy.config dictionary is used. If it is set to a custom
+    path, this path is used instead of the default one. If it is set to False
+    (the default behavior), the tiles are downloaded each time.
+
     """
     _MAX_THREADS = 24
 
@@ -49,7 +55,11 @@ def __init__(self, desired_tile_form='RGB',
         # some providers like osm need a user_agent in the request issue #1341
         # osm may reject requests if there are too many of them, in which case
         # a change of user_agent may fix the issue.
+
+        # Enable a cache mechanism when cache is equal to True or to a path.
+        self._default_cache = False
         if cache is True:
+            self._default_cache = True
             self.cache_path = cartopy.config["cache_dir"]
         elif cache is False:
             self.cache_path = None
@@ -99,9 +109,14 @@ def _cache_dir(self):
     def _load_cache(self):
         """Load the cache"""
         if self.cache_path is not None:
-            if not os.path.exists(self._cache_dir):
-                os.makedirs(self._cache_dir)
-            self.cache = self.cache.union(set(os.listdir(self._cache_dir)))
+            cache_dir = self._cache_dir
+            if not os.path.exists(cache_dir):
+                os.makedirs(cache_dir)
+                if self._default_cache:
+                    warnings.warn(
+                        'Cartopy created the following directory to cache '
+                        'GoogleWTS tiles: {}'.format(cache_dir))
+            self.cache = self.cache.union(set(os.listdir(cache_dir)))
 
     def _find_images(self, target_domain, target_z, start_tile=(0, 0, 0)):
         """Target domain is a shapely polygon in native coordinates."""

lib/cartopy/tests/test_img_tiles.py

@@ -7,6 +7,7 @@
 import hashlib
 import os
 import types
+import warnings
 
 import numpy as np
 from numpy.testing import assert_array_almost_equal as assert_arr_almost
@@ -301,7 +302,8 @@ def test_cache(cache_dir, tmpdir):
         config["cache_dir"] = tmpdir.strpath
 
     # Fetch tiles and save them in the cache
-    gt = cimgt.GoogleTiles(cache=tmpdir_str)
+    with warnings.catch_warnings(record=True) as w:
+        gt = cimgt.GoogleTiles(cache=tmpdir_str)
     gt._image_url = types.MethodType(GOOGLE_IMAGE_URL_REPLACEMENT, gt)
 
     ll_target_domain = sgeom.box(-10, 50, 10, 60)
@@ -315,6 +317,12 @@ def test_cache(cache_dir, tmpdir):
         assert gt.cache_path is None
         return
 
+    # Check that the warning is properly raised (only when cache is True)
+    if cache_dir is True:
+        assert len(w) == 1
+    else:
+        assert len(w) == 0
+
     # Define expected results
     x_y_z_f_h = [
         (30, 18, 6, '30_18_6.npy', '545db25f1aa348ad85e1f437fd0db0d9'),