[Bf-blender-cvs] SVN commit: /data/svn/bf-blender [52128] trunk/blender: update to python api `Gotcha` docs to reflect changes to the api.

[Campbell Barton]

Revision: 52128
          http://projects.blender.org/scm/viewvc.php?view=rev&root=bf-blender&revision=52128
Author:   campbellbarton
Date:     2012-11-12 03:23:47 +0000 (Mon, 12 Nov 2012)
Log Message:
-----------
update to python api `Gotcha` docs to reflect changes to the api. also add a section about modifying linked library data.

Modified Paths:
--------------
    trunk/blender/doc/python_api/rst/info_gotcha.rst
    trunk/blender/source/blender/bmesh/intern/bmesh_queries.c

Modified: trunk/blender/doc/python_api/rst/info_gotcha.rst
===================================================================
--- trunk/blender/doc/python_api/rst/info_gotcha.rst	2012-11-12 02:52:24 UTC (rev 52127)
+++ trunk/blender/doc/python_api/rst/info_gotcha.rst	2012-11-12 03:23:47 UTC (rev 52128)
@@ -118,18 +118,19 @@
    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
-will likely move to BMesh mesh API eventually, so any work on the API now will be wasted effort.
+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.
 
-With the BMesh API we may expose mesh data to python so we can
-write useful tools in python which are also fast to execute while in edit-mode.
+In this situation you can...
 
-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 @@
 
 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 @@
 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,9 +632,30 @@
 
 **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
 ========
 

Modified: trunk/blender/source/blender/bmesh/intern/bmesh_queries.c
===================================================================
--- trunk/blender/source/blender/bmesh/intern/bmesh_queries.c	2012-11-12 02:52:24 UTC (rev 52127)
+++ trunk/blender/source/blender/bmesh/intern/bmesh_queries.c	2012-11-12 03:23:47 UTC (rev 52128)
@@ -1420,7 +1420,7 @@
 	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) ||