[Bf-blender-cvs] SVN commit: /data/svn/bf-blender [41953] trunk/blender/doc/python_api/rst/ info_gotcha.rst: document py gotchas

[Campbell Barton]

Revision: 41953
          http://projects.blender.org/scm/viewvc.php?view=rev&root=bf-blender&revision=41953
Author:   campbellbarton
Date:     2011-11-18 04:48:27 +0000 (Fri, 18 Nov 2011)
Log Message:
-----------
document py gotchas
- dont assume you get the data names you ask for
- beware of collisions with library names
- beware of py modules calling sys.exit

Modified Paths:
--------------
    trunk/blender/doc/python_api/rst/info_gotcha.rst

Modified: trunk/blender/doc/python_api/rst/info_gotcha.rst
===================================================================
--- trunk/blender/doc/python_api/rst/info_gotcha.rst	2011-11-17 20:11:20 UTC (rev 41952)
+++ trunk/blender/doc/python_api/rst/info_gotcha.rst	2011-11-18 04:48:27 UTC (rev 41953)
@@ -223,6 +223,86 @@
 This is mainly an issue with editmode since pose data can be manipulated without having to be in pose mode, however for operator access you may still need to enter pose mode.
 
 
+Data Names
+==========
+
+
+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.
+
+.. code-block:: python
+
+	bpy.data.meshes.new(name=meshid)
+	
+	# normally some code, function calls...
+	bpy.data.meshes[meshid]
+
+
+Or with name assignment...
+
+.. code-block:: python
+
+	obj.name = objname
+	
+	# normally some code, function calls...
+	obj = bpy.data.meshes[objname]
+
+
+Data names may not match the assigned values if they exceed the maximum length, are already used or an empty string.
+
+
+Its better practice not to reference objects by names at all, once created you can store the data in a list, dictionary, on a class etc, there is rarely a reason to have to keep searching for the same data by name.
+
+
+If you do need to use name references, its best to use a dictionary to maintain a mapping between the names of the imported assets and the newly created data, this way you don't run this risk of referencing existing data from the blend file, or worse modifying it.
+
+.. code-block:: python
+
+	# typically declared in the main body of the function.
+	mesh_name_mapping = {}
+	
+	mesh = bpy.data.meshes.new(name=meshid)
+	mesh_name_mapping[meshid] = mesh
+	
+	# normally some code, or function calls...
+	
+	# use own dictionary rather then bpy.data
+	mesh = mesh_name_mapping[meshid]
+
+
+Library Collisions
+------------------
+
+Blender keeps data names unique - :class:`bpy.types.ID.name` so you can't name two objects, meshes, scenes etc the same thing by accident.
+
+However when linking in library data from another blend file naming collisions can occur, so its best to avoid referencing data by name at all.
+
+This can be tricky at times and not even blender handles this correctly in some case (when selecting the modifier object for eg you can't select between multiple objects with the same name), but its still good to try avoid problems in this area.
+
+
+If you need to select between local and library data, there is a feature in ``bpy.data`` members to allow for this.
+
+.. code-block:: python
+
+   # typical name lookup, could be local or library.
+   obj = bpy.data.objects["my_obj"]
+
+   # library object name look up using a pair
+   # where the second argument is the library path matching bpy.types.Library.filepath
+   obj = bpy.data.objects["my_obj", "//my_lib.blend"]
+
+   # local object name look up using a pair
+   # where the second argument excludes library data from being returned.
+   obj = bpy.data.objects["my_obj", None]
+
+   # both the examples above also works for 'get'
+   obj = bpy.data.objects.get(("my_obj", None))
+
+
 Relative File Paths
 ===================
 
@@ -230,12 +310,12 @@
 
 Built in python functions don't understand blenders ``//`` prefix which denotes the blend file path.
 
-A common case where you would run into this problem is when exporting a material with assosiated image paths.
+A common case where you would run into this problem is when exporting a material with associated image paths.
 
 >>> bpy.path.abspath(image.filepath)
 
 
-When using blender data from linked libraries there is an unfortunate complication since the path will be relative to the library rather then the open blend file. When the data block may be from an external blend file pass the library argument from the `bpy.types.ID`.
+When using blender data from linked libraries there is an unfortunate complication since the path will be relative to the library rather then the open blend file. When the data block may be from an external blend file pass the library argument from the :class:`bpy.types.ID`.
 
 >>> bpy.path.abspath(image.filepath, library=image.library)
 
@@ -289,7 +369,7 @@
 
 * To print paths or to include them in the user interface use ``repr(path)`` first or ``"%r" % path`` with string formatting.
 
-* **Possibly** - use bytes instead of python strings, when reading some input its less trouble to read it as binary data though you will still need to deciede how to treat any strings you want to use with Blender, some importers do this.
+* **Possibly** - use bytes instead of python strings, when reading some input its less trouble to read it as binary data though you will still need to decide how to treat any strings you want to use with Blender, some importers do this.
 
 
 Strange errors using 'threading' module
@@ -458,3 +538,14 @@
 **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.
+
+
+sys.exit
+========
+
+Some python modules will call sys.exit() themselves when an error occurs, while not common behavior this is something to watch out for because it may seem as if blender is crashing since sys.exit() will quit blender immediately.
+
+For example, the ``optparse`` module will print an error and exit if the arguments are invalid.
+
+An ugly way of troubleshooting this is to set ``sys.exit = None`` and see what line of python code is quitting, you could of course replace ``sys.exit``/ with your own function but manipulating python in this way is bad practice.
+