update to python api Gotcha docs to reflect changes to the api. also add a section about modifying linked library data.

doc/python_api/rst/info_gotcha.rst

@@ -118,18 +118,19 @@ If you insist - yes its possible, but scripts that use this hack wont be conside
    bpy.ops.wm.redraw_timer(type='DRAW_WIN_SWAP', iterations=1)
 
 
-I can't edit the mesh in edit-mode!
+Modes and Mesh Access
-===================================
+=====================
 
-Blender's EditMesh is an internal data structure (not saved and not exposed to python), this gives the main annoyance that you need to exit edit-mode to edit the mesh from python.
+When working with mesh data you may run into the problem where a script fails to run as expected in edit-mode. This is caused by edit-mode having its own data which is only written back to the mesh when exiting edit-mode.
 
-The reason we have not made much attempt to fix this yet is because we
+A common example is that exporters may access a mesh through ``obj.data`` (a :class:`bpy.types.Mesh`) but the user is in edit-mode, where the mesh data is available but out of sync with the edit mesh.
-will likely move to BMesh mesh API eventually, so any work on the API now will be wasted effort.
 
-With the BMesh API we may expose mesh data to python so we can
+In this situation you can...
-write useful tools in python which are also fast to execute while in edit-mode.
 
-For the time being this limitation just has to be worked around but we're aware its frustrating needs to be addressed.
+* Exit edit-mode before running the tool.
+* Explicitly update the mesh by calling :class:`bmesh.types.BMesh.to_mesh`.
+* Modify the script to support working on the edit-mode data directly, see: :mod:`bmesh.from_edit_mesh`.
+* Report the context as incorrect and only allow the script to run when editmode is disabled.
 
 
 .. _info_gotcha_mesh_faces:
@@ -311,7 +312,7 @@ Naming Limitations
 
 A common mistake is to assume newly created data is given the requested name.
 
-This can cause bugs when you add some data (normally imported) and then reference it later by name.
+This can cause bugs when you add some data (normally imported) then reference it later by name.
 
 .. code-block:: python
 
@@ -557,6 +558,21 @@ This example shows how you can tell undo changes the memory locations.
 As suggested above, simply not holding references to data when Blender is used interactively by the user is the only way to ensure the script doesn't become unstable.
 
 
+Undo & Library Data
+^^^^^^^^^^^^^^^^^^^
+
+One of the advantages with Blenders library linking system that undo can skip checking changes in library data since it is assumed to be static.
+
+Tools in Blender are not allowed to modify library data.
+
+Python however does not enforce this restriction.
+
+This can be useful in some cases, using a script to adjust material values for example.
+But its also possible to use a script to make library data point to newly created local data, which is not supported since a call to undo will remove the local data but leave the library referencing it and likely crash.
+
+So it's best to consider modifying library data an advanced usage of the API and only to use it when you know what you're doing.
+
+
 Edit Mode / Memory Access
 -------------------------
 
@@ -616,7 +632,28 @@ Removing Data
 
 **Any** data that you remove shouldn't be modified or accessed afterwards, this includes f-curves, drivers, render layers, timeline markers, modifiers, constraints along with objects, scenes, groups, bones.. etc.
 
-This is a problem in the API at the moment that we should eventually solve.
+The ``remove()`` api calls will invalidate the data they free to prevent common mistakes.
+
+The following example shows how this precortion works.
+
+.. code-block:: python
+
+   mesh = bpy.data.meshes.new(name="MyMesh")
+   # normally the script would use the mesh here...
+   bpy.data.meshes.remove(mesh)
+   print(mesh.name)  # <- give an exception rather then crashing:
+
+   # ReferenceError: StructRNA of type Mesh has been removed
+
+
+But take care because this is limited to scripts accessing the variable which is removed, the next example will still crash.
+
+.. code-block:: python
+
+   mesh = bpy.data.meshes.new(name="MyMesh")
+   vertices = mesh.vertices
+   bpy.data.meshes.remove(mesh)
+   print(vertices)  # <- this may crash
 
 
 sys.exit

source/blender/bmesh/intern/bmesh_queries.c

@@ -1420,7 +1420,7 @@ int BM_face_exists_multi_edge(BMEdge **earr, int len)
 	return ok;
 }
 
-/* convenience functiosn for checking flags */
+/* convenience functions for checking flags */
 int BM_edge_is_any_vert_flag_test(BMEdge *e, const char hflag)
 {
 	return (BM_elem_flag_test(e->v1, hflag) ||