[Bf-blender-cvs] SVN commit: /data/svn/bf-blender [40022] trunk/blender/doc/python_api: finished tips and tricks section of blender/python api docs, now included in generated docs.
Campbell Barton
ideasman42 at gmail.com
Thu Sep 8 03:26:26 CEST 2011
Revision: 40022
http://projects.blender.org/scm/viewvc.php?view=rev&root=bf-blender&revision=40022
Author: campbellbarton
Date: 2011-09-08 01:26:23 +0000 (Thu, 08 Sep 2011)
Log Message:
-----------
finished tips and tricks section of blender/python api docs, now included in generated docs.
Modified Paths:
--------------
trunk/blender/doc/python_api/rst/info_tips_and_tricks.rst
trunk/blender/doc/python_api/sphinx_doc_gen.py
Modified: trunk/blender/doc/python_api/rst/info_tips_and_tricks.rst
===================================================================
--- trunk/blender/doc/python_api/rst/info_tips_and_tricks.rst 2011-09-07 23:36:32 UTC (rev 40021)
+++ trunk/blender/doc/python_api/rst/info_tips_and_tricks.rst 2011-09-08 01:26:23 UTC (rev 40022)
@@ -2,9 +2,11 @@
Tips and Tricks
***************
-Some of these are just python features that scripters may not have thaught to use with blender.
+Here are various suggestions that you might find useful when writing scripts.
+Some of these are just python features that scripters may not have thought to use with blender, others are blender specific.
+
Use The Terminal
================
@@ -14,45 +16,37 @@
* You can see the output of `print()` as you're script runs, which is useful to view debug info.
-* The error tracebacks are printed in full to the terminal which wont always generate an error popup in blenders user interface (depending on how the script is executed).
+* The error trace-back is printed in full to the terminal which wont always generate an error popup in blenders user interface (depending on how the script is executed).
-* If the script runs for too long or you accidentally enter an infinate loop, Ctrl+C in the terminal (Ctrl+Break on Windows) will quit the script early.
+* If the script runs for too long or you accidentally enter an infinite loop, Ctrl+C in the terminal (Ctrl+Break on Windows) will quit the script early.
.. note::
For Linux and OSX users this means starting the terminal first, then running blender from within it. On Windows the terminal can be enabled from the help menu.
-Run External Scripts
-====================
+Use an External Editor
+======================
-Blenders text editor is fine for edits and writing small tests but it is not a full featured editor so for larger projects you'll probably want to use an external editor.
+Blenders text editor is fine for small changes and writing tests but its not full featured, for larger projects you'll probably want to use a standalone editor or python IDE.
Editing a text file externally and having the same text open in blender does work but isn't that optimal so here are 2 ways you can easily use an external file from blender.
Executing External Scripts
-^^^^^^^^^^^^^^^^^^^^^^^^^^
+--------------------------
-This is the equivilent to running the script directly, referencing a scripts path from a 2 line textblock.
+This is the equivalent to running the script directly, referencing a scripts path from a 2 line textblock.
-.. code-block::
+.. code-block:: python
filename = "/full/path/to/myscript.py"
exec(compile(open(filename).read(), filename, 'exec'))
-You might also want to reference the file relative to the blend file.
+You might want to reference a script relative to the blend file.
-.. code-block::
+.. code-block:: python
- filename = "/full/path/to/script.py"
- exec(compile(open(filename).read(), filename, 'exec'))
-
-
-You might want to reference a script thats at the same location as the blend file.
-
-.. code-block::
-
import bpy
import os
@@ -61,11 +55,11 @@
Executing Modules
-^^^^^^^^^^^^^^^^^
+-----------------
This example shows loading a script in as a module and executing a module function.
-.. code-block::
+.. code-block:: python
import myscript
import imp
@@ -74,18 +68,18 @@
myscript.main()
-Notice that the script is reloaded every time, this forces an update, normally the module stays cached in `sys.modules`.
+Notice that the script is reloaded every time, this forces use of the modified version otherwise the cached one in `sys.modules` would be used until blender was restarted.
-The main difference between this and executing the script directly is it has to call a function in the module, in this case `main()` but it can be any function, an advantage with this is you can pass argumnents to the function from this small script which is often useful for testing differnt settings quickly.
+The important difference between this and executing the script directly is it has to call a function in the module, in this case `main()` but it can be any function, an advantage with this is you can pass arguments to the function from this small script which is often useful for testing different settings quickly.
The other issue with this is the script has to be in pythons module search path.
While this is not best practice - for testing you can extend the search path, this example adds the current blend files directory to the search path, then loads the script as a module.
-.. code-block::
+.. code-block:: python
import sys
import os
- impory bpy
+ import bpy
blend_dir = os.path.basename(bpy.data.filepath)
if blend_dir not in sys.path:
@@ -100,39 +94,105 @@
Don't Use Blender!
==================
-While developing your own scripts blenders interface can get in the way, manually reloading, running the scripts, opening file import etc is just overhead.
+While developing your own scripts blenders interface can get in the way, manually reloading, running the scripts, opening file import etc. adds overhead.
-For scripts that are not interactive it can end up being easier not to use blender at all and run blender from a terminal, without opening a window and execute the script on the command line.
+For scripts that are not interactive it can end up being more efficient not to use blenders interface at all and instead execute the script on the command line.
-.. code-block::
+.. code-block:: python
- blender --backgruond --python myscript.py
+ blender --background --python myscript.py
-You might want to run this with a blend file too.
+You might want to run this with a blend file so the script has some data to operate on.
-.. code-block::
+.. code-block:: python
- blender myscene.blend --backgruond --python myscript.py
+ blender myscene.blend --background --python myscript.py
+.. note::
+ Depending on you're setup you might have to enter the full path to the blender executable.
+
+
+Once the script is running properly in background mode, you'll want to check the output of the script, this depends completely on the task at hand however here are some suggestions.
+
+* render the output to an image, use an image viewer and keep writing over the same image each time.
+
+* save a new blend file, or export the file using one of blenders exporters.
+
+* if the results can be displayed as text - print them or write them to a file.
+
+
+This can take a little time to setup, but it can be well worth the effort to reduce the time it takes to test changes - you can even have blender running the script ever few seconds with a viewer updating the results, so no need to leave you're text editor to see changes.
+
+
Use External Tools
==================
+When there are no readily available python modules to perform specific tasks its worth keeping in mind you may be able to have python execute an external command on you're data and read the result back in.
-Bundled Python
-==============
+Using external programs adds an extra dependency and may limit who can use the script but to quickly setup you're own custom pipeline or writing one-off scripts this can be handy.
-Blender from blender.org includes a compleate python installation on all platforms, this has the disadvantage that any extensions you have installed in you're systems python wont be found by blender.
+Examples include:
+* Run The Gimp in batch mode to execute custom scripts for advanced image processing.
+
+* Write out 3D models to use external mesh manipulation tools and read back in the results.
+
+* Convert files into recognizable formats before reading.
+
+
+Bundled Python & Extensions
+===========================
+
+The Blender releases distributed from blender.org include a complete python installation on all platforms, this has the disadvantage that any extensions you have installed in you're systems python wont be found by blender.
+
There are 2 ways around this:
-* remove blender python subdirectory, blender will then look for the systems python and use that instead **python version must match the one that blender comes with**.
+* remove blender python sub-directory, blender will then fallback on the systems python and use that instead **python version must match the one that blender comes with**.
-* copy the extensions into blender's python subdirectry so blender can access them, you could also copy the entire python installation into blenders subdirectory, replacing the one blender comes with. This works as long as the python versions match and the paths are created in the same location relative locations. Doing this has the advantage that you can redistribute this bundle to others with blender and/or the game player, including any extensions you rely on.
+* copy the extensions into blender's python sub-directory so blender can access them, you could also copy the entire python installation into blenders sub-directory, replacing the one blender comes with. This works as long as the python versions match and the paths are created in the same relative locations. Doing this has the advantage that you can redistribute this bundle to others with blender and/or the game player, including any extensions you rely on.
+Drop Into a Python Interpreter in You're Script
+===============================================
+
+In the middle of a script you may want to inspect some variables, run some function and generally dig about to see whats going on.
+
+.. code-block:: python
+
+ import code
+ code.interact(locals=locals())
+
+
+If you want to access both global and local variables do this...
+
+.. code-block:: python
+
+ import code
+ namespace = globals().copy()
+ namespace.update(locals())
+ code.interact(locals=namespace)
+
+
+The next example is an equivalent single line version of the script above which is easier to paste into you're code:
+
+.. code-block:: python
+
+ __import__('code').interact(locals={k: v for ns in (globals(), locals()) for k, v in ns.items()})
+
+
+`code.interact` can be added at any line in the script and will pause the script an launch an interactive interpreter in the terminal, when you're done you can quit the interpreter and the script will continue execution.
+
+
@@ Diff output truncated at 10240 characters. @@
More information about the Bf-blender-cvs
mailing list