Revision: 39715
http://projects.blender.org/scm/viewvc.php?view=rev&root=bf-blender&revision=39715
Author: campbellbarton
Date: 2011-08-26 18:32:23 +0000 (Fri, 26 Aug 2011)
Log Message:
-----------
added a section to gotcha's python bpy docs about unicode encoding problems.
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-08-26 17:55:03 UTC
(rev 39714)
+++ trunk/blender/doc/python_api/rst/info_gotcha.rst 2011-08-26 18:32:23 UTC
(rev 39715)
@@ -8,7 +8,7 @@
Using Operators
***************
-Blender's operators are tools for users to access, that python can access them
too is very useful but does not change the fact that operators have limitations
that can make them cumbersome to script.
+Blender's operators are tools for users to access, that python can access them
too is very useful nevertheless operators have limitations that can make them
cumbersome to script.
Main limits are...
@@ -128,6 +128,84 @@
bpy.ops.wm.redraw_timer(type='DRAW_WIN_SWAP', iterations=1)
+******************************
+Matrix multiplication is wrong
+******************************
+
+Every so often users complain that Blenders matrix math is wrong, the
confusion comes from mathutils matrices being column-major to match OpenGL and
the rest of Blenders matrix operations and stored matrix data.
+
+This is different to **numpy** which is row-major which matches what you would
expect when using conventional matrix math notation.
+
+
+***********************************
+I can't edit the mesh in edit-mode!
+***********************************
+
+Blenders 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.
+
+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.
+
+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.
+
+For the time being this limitation just has to be worked around but we're
aware its frustrating needs to be addressed.
+
+
+****************
+Unicode Problems
+****************
+
+Python supports many different encpdings so there is nothing stopping you from
writing a script in latin1 or iso-8859-15.
+
+See `pep-0263 <http://www.python.org/dev/peps/pep-0263/>`_
+
+However this complicates things for the python api because blend files
themselves dont have an encoding.
+
+To simplify the problem for python integration and script authors we have
decieded all strings in blend files **must** be UTF-8 or ASCII compatible.
+
+This means assigning strings with different encodings to an object names for
instance will raise an error.
+
+Paths are an exception to this rule since we cannot ignore the existane of
non-utf-8 paths on peoples filesystems.
+
+This means seemingly harmless expressions can raise errors, eg.
+
+.. code-block:: python
+
+ >>> print(bpy.data.filepath)
+ UnicodeEncodeError: 'ascii' codec can't encode characters in position
10-21: ordinal not in range(128)
+
+ >>> bpy.context.object.name = bpy.data.filepath
+ Traceback (most recent call last):
+ File "<blender_console>", line 1, in <module>
+ TypeError: bpy_struct: item.attr= val: Object.name expected a string type,
not str
+
+
+Here are 2 ways around filesystem encoding issues.
+
+.. code-block:: python
+
+ >>> print(repr(bpy.data.filepath))
+
+ >>> import os
+ >>> filepath_bytes = os.fsencode(bpy.data.filepath)
+ >>> filepath_utf8 = filepath_bytes.decode('utf-8', "replace")
+ >>> bpy.context.object.name = filepath_utf8
+
+
+Unicode encoding/decoding is a big topic with comprehensive python
documentation, to avoid getting stuck too deep in encoding problems - here are
some suggestions:
+
+* Always use utf-8 encoiding or convert to utf-8 where the input is unknown.
+
+* Avoid manipulating filepaths as strings directly, use ``os.path`` functions
instead.
+
+* Use ``os.fsencode()`` / ``os.fsdecode()`` rather then the built in string
decoding functions when operating on paths.
+
+* 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.
+
+
***************************************
Strange errors using 'threading' module
***************************************
@@ -197,30 +275,6 @@
Pythons threads only allow co-currency and wont speed up you're scripts on
multi-processor systems, the ``subprocess`` and ``multiprocess`` modules can be
used with blender and make use of multiple CPU's too.
-******************************
-Matrix multiplication is wrong
-******************************
-
-Every so often we get complaints that Blenders matrix math is wrong, the
confusion comes from mathutils matrices being column-major to match OpenGL and
the rest of Blenders matrix operations and stored matrix data.
-
-This is different to **numpy** which is row-major which matches what you would
expect when using conventional matrix math notation.
-
-
-***********************************
-I can't edit the mesh in edit-mode!
-***********************************
-
-Blenders 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.
-
-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.
-
-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.
-
-For the time being this limitation just has to be worked around but we're
aware its frustrating needs to be addressed.
-
-
*******************************
Help! My script crashes Blender
*******************************
_______________________________________________
Bf-blender-cvs mailing list
[email protected]
http://lists.blender.org/mailman/listinfo/bf-blender-cvs
