[Bf-blender-cvs] [971fe43d06d] master: Fix T63651: ImagePreviewCollection.new, load don't work as documented

[Campbell Barton]

Commit: 971fe43d06ddad94933666c89c40ed345338992a
Author: Campbell Barton
Date:   Thu Sep 17 12:42:07 2020 +1000
Branches: master
https://developer.blender.org/rB971fe43d06ddad94933666c89c40ed345338992a

Fix T63651: ImagePreviewCollection.new,load don't work as documented

Update doc-strings, add note for why this decision was made.

===================================================================

M	release/scripts/modules/bpy/utils/previews.py
M	source/blender/python/intern/bpy_utils_previews.c

===================================================================

diff --git a/release/scripts/modules/bpy/utils/previews.py b/release/scripts/modules/bpy/utils/previews.py
index 511df853d66..7402dbb6c0c 100644
--- a/release/scripts/modules/bpy/utils/previews.py
+++ b/release/scripts/modules/bpy/utils/previews.py
@@ -65,6 +65,10 @@ class ImagePreviewCollection(dict):
 
     # Internal notes:
     # - Blender's internal 'PreviewImage' struct uses 'self._uuid' prefix.
+    # - Blender's preview.new/load return the data if it exists,
+    #   don't do this for the Python API as it allows accidental re-use of names,
+    #   anyone who wants to reuse names can use dict.get() to check if it exists.
+    #   We could use this for the C API too (would need some investigation).
 
     def __init__(self):
         super().__init__()
diff --git a/source/blender/python/intern/bpy_utils_previews.c b/source/blender/python/intern/bpy_utils_previews.c
index 81b44dd5c43..32cd7bdddc3 100644
--- a/source/blender/python/intern/bpy_utils_previews.c
+++ b/source/blender/python/intern/bpy_utils_previews.c
@@ -49,15 +49,20 @@
 
 #define STR_SOURCE_TYPES "'IMAGE', 'MOVIE', 'BLEND', 'FONT'"
 
-PyDoc_STRVAR(bpy_utils_previews_new_doc,
-             ".. method:: new(name)\n"
-             "\n"
-             "   Generate a new empty preview, or return existing one matching ``name``.\n"
-             "\n"
-             "   :arg name: The name (unique id) identifying the preview.\n"
-             "   :type name: string\n"
-             "   :return: The Preview matching given name, or a new empty one.\n"
-             "   :rtype: :class:`bpy.types.ImagePreview`\n");
+PyDoc_STRVAR(
+    bpy_utils_previews_new_doc,
+    ".. method:: new(name)\n"
+    "\n"
+    "   Generate a new empty preview.\n"
+    "\n"
+    /* This is only true when accessed via 'bpy.utils.previews.ImagePreviewCollection.new',
+     * however this is the public API, allow this minor difference to the internal version here. */
+    "   If ``name`` already exists a KeyError exception is raised.\n"
+    "\n"
+    "   :arg name: The name (unique id) identifying the preview.\n"
+    "   :type name: string\n"
+    "   :return: The Preview matching given name, or a new empty one.\n"
+    "   :rtype: :class:`bpy.types.ImagePreview`\n");
 static PyObject *bpy_utils_previews_new(PyObject *UNUSED(self), PyObject *args)
 {
   char *name;
@@ -78,7 +83,11 @@ PyDoc_STRVAR(
     bpy_utils_previews_load_doc,
     ".. method:: load(name, filepath, filetype, force_reload=False)\n"
     "\n"
-    "   Generate a new preview from given file path, or return existing one matching ``name``.\n"
+    "   Generate a new preview from given file path.\n"
+    "\n"
+    /* This is only true when accessed via 'bpy.utils.previews.ImagePreviewCollection.load',
+     * however this is the public API, allow this minor difference to the internal version here. */
+    "   If ``name`` already exists a KeyError exception is raised.\n"
     "\n"
     "   :arg name: The name (unique id) identifying the preview.\n"
     "   :type name: string\n"