API Doc: Gotcha: add section about 'exceptions to the rules' known crashing cases.
authorBastien Montagne <montagne29@wanadoo.fr>
Tue, 12 Mar 2019 13:09:41 +0000 (14:09 +0100)
committerBastien Montagne <montagne29@wanadoo.fr>
Tue, 12 Mar 2019 13:12:46 +0000 (14:12 +0100)
As exposed in T62406, we can have some rare cases of crashes due to
memory re-allocation happening outside of expected scenarii.

Ideally this should be re-designed, but at least keep track of those
known exceptions to general rules...

doc/python_api/rst/info_gotcha.rst

index d9238e0..fd978e2 100644 (file)
@@ -633,6 +633,7 @@ Here are some general hints to avoid running into these problems.
   fetch data from the context each time the script is activated.
 - Crashes may not happen every time, they may happen more on some configurations/operating-systems.
 - Be wary of recursive patterns, those are very efficient at hiding the issues described here.
+- See last sub-section about `Unfortunate Corner Cases`_ for some known breaking exceptions.
 
 .. note::
 
@@ -827,6 +828,17 @@ the next example will still crash.
    print(vertices)  # <- this may crash
 
 
+Unfortunate Corner Cases
+------------------------
+
+Besides all expected cases listed above, there are a few others that should not be
+an issue but, due to internal implementation details, currently are:
+
+- ``Object.hide_viewport``, ``Object.hide_select`` and ``Object.hide_render``:
+  Setting any of those booleans will trigger a rebuild of Collection caches, hence breaking
+  any current iteration over ``Collection.all_objects``.
+
+
 sys.exit
 ========