diff options
Diffstat (limited to 'doc/python_api/rst/info_tips_and_tricks.rst')
| -rw-r--r-- | doc/python_api/rst/info_tips_and_tricks.rst | 130 |
1 files changed, 61 insertions, 69 deletions
diff --git a/doc/python_api/rst/info_tips_and_tricks.rst b/doc/python_api/rst/info_tips_and_tricks.rst index 7a2e8206c72..0b5e1910902 100644 --- a/doc/python_api/rst/info_tips_and_tricks.rst +++ b/doc/python_api/rst/info_tips_and_tricks.rst @@ -4,23 +4,22 @@ Tips and Tricks *************** 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. +Some of these are just Python features that you may not have thought to use with Blender, +others are Blender-specific. .. _use_the_terminal: -Use The Terminal +Use the Terminal ================ When writing Python scripts, it's useful to have a terminal open, this is not the built-in Python console but a terminal application which is used to start Blender. -There are 3 main uses for the terminal, these are: +The three main use cases for the terminal are: - You can see the output of ``print()`` as your script runs, which is useful to view debug info. -- The error trace-back is printed in full to the terminal which won't always generate an error popup in +- The error traceback is printed in full to the terminal which won't always generate an report message in Blender's user interface (depending on how the script is executed). - If the script runs for too long or you accidentally enter an infinite loop, :kbd:`Ctrl-C` in the terminal (:kbd:`Ctrl-Break` on Windows) will quit the script early. @@ -28,26 +27,25 @@ There are 3 main uses for the terminal, these are: .. note:: For Linux and macOS users this means starting the terminal first, then running Blender from within it. - On Windows the terminal can be enabled from the help menu. + On Windows the terminal can be enabled from the Help menu. Interface Tricks ================ - Access Operator Commands ------------------------ -You may have noticed that the tooltip for menu items and buttons includes the ``bpy.ops.[...])`` command +You may have noticed that the tooltip for menu items and buttons includes the ``bpy.ops.[...]`` command to run that button, a handy (hidden) feature is that you can press :kbd:`Ctrl-C` over -any menu item/button to copy this command into the clipboard. +any menu item or button to copy this command into the clipboard. Access Data Path ---------------- -To find the path from an :class:`ID` datablock to its setting isn't always so simple since it may be nested away. -To get this quickly you can right click on the setting and select select **Copy Data Path**, +To find the path from an :class:`ID` data-block to its setting isn't always so simple since it may be nested away. +To get this quickly open the context menu of the setting and select *Copy Data Path*, if this can't be generated, only the property name is copied. .. note:: @@ -62,11 +60,10 @@ if this can't be generated, only the property name is copied. Show All Operators ================== -While Blender logs operators in the Info space, -this only reports operators with the ``REGISTER`` option enabeld so as not to flood the *Info* view +While Blender logs operators in the Info editor, +this only reports operators with the ``REGISTER`` option enabled so as not to flood the *Info* view with calls to ``bpy.ops.view3d.smoothview`` and ``bpy.ops.view3d.zoom``. - -However, for testing it can be useful to see **every** operator called in a terminal, +Yet for testing it can be useful to see **every** operator called in a terminal, do this by enabling the debug option either by passing the ``--debug-wm`` argument when starting Blender or by setting :mod:`bpy.app.debug_wm` to ``True`` while Blender is running. @@ -74,20 +71,18 @@ or by setting :mod:`bpy.app.debug_wm` to ``True`` while Blender is running. Use an External Editor ====================== -Blenders text editor is fine for small changes and writing tests but its not full featured, +Blender's 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. - -Using the following examples you'll still need textblock in Blender to execute, +Editing a text file externally and having the same text open in Blender does work +but isn't that optimal so here are two ways you can use an external file from Blender. +Using the following examples you'll still need text data-block in Blender to execute, but reference an external file rather than including it directly. Executing External Scripts -------------------------- -This is the equivalent to running the script directly, referencing a scripts path from a 2 line text-block. +This is the equivalent to running the script directly, referencing a scripts path from a two line code block. .. code-block:: python @@ -95,7 +90,7 @@ This is the equivalent to running the script directly, referencing a scripts pat exec(compile(open(filename).read(), filename, 'exec')) -You might want to reference a script relative to the blend file. +You might want to reference a script relative to the blend-file. .. code-block:: python @@ -128,9 +123,10 @@ has to call a function in the module, in this case ``main()`` but it can be any 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. +The other issue with this is the script has to be in Python's module search path. +While this is not best practice -- for testing purposes you can extend the search path, +this following example adds the current blend-files directory to the search path +and then loads the script as a module. .. code-block:: python @@ -148,42 +144,40 @@ this example adds the current blend files directory to the search path, then loa myscript.main() -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. adds overhead. +Use Blender without it's User Interface +======================================= +While developing your own scripts Blender's 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 more efficient not to use -Blenders interface at all and instead execute the script on the command line. +Blender's interface at all and instead execute the script on the command line. .. code-block:: sh blender --background --python myscript.py -You might want to run this with a blend file so the script has some data to operate on. +You might want to run this with a blend-file so the script has some data to operate on. .. code-block:: sh blender myscene.blend --background --python myscript.py - .. note:: Depending on your 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. +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. +- 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 Blender's exporters. +- If the results can be displayed as text then print them or write them to a file. While this can take a little time to setup, it can be well worth the effort -to reduce the time it takes to test changes - you can even have +to reduce the time it takes to test changes. You can even have Blender running the script every few seconds with a viewer updating the results, so no need to leave your text editor to see changes. @@ -200,7 +194,7 @@ but to quickly setup your own custom pipeline or writing one-off scripts this ca Examples include: -- Run The Gimp in batch mode to execute custom scripts for advanced image processing. +- Run 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. @@ -209,15 +203,16 @@ 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 your systems Python won't be found by Blender. +this has the disadvantage that any extensions you have installed on your system's Python environment +will not be found by Blender. -There are 2 ways around this: +There are two ways to work around this: -- Remove Blender Python sub-directory, Blender will then fallback on the systems Python and use that instead. +- Remove Blender Python subdirectory, Blender will then fallback on the system's Python and use that instead. Depending on your platform, - you may need to explicitly reference the location of your Python installation using the - ``PYTHONPATH`` environment variable, eg: + you may need to explicitly reference the location of your Python installation using + the ``PYTHONPATH`` environment variable, e.g: .. code-block:: sh @@ -226,21 +221,21 @@ There are 2 ways around this: .. warning:: The Python (major, minor) version must match the one that Blender comes with. - Therefor can't use Python 3.6 with Blender built to use Python 3.7. + Therefor you can't use Python 3.6 with Blender built to use Python 3.7. -- Copy or link 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, +- Copy or link the extensions into Blender's Python subdirectory so Blender can access them, + you can also copy the entire Python installation into Blender's subdirectory, 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 including any extensions you rely on. -Drop Into a Python Interpreter in Your Script -============================================= +Insert a Python Interpreter into your Script +============================================ -In the middle of a script you may want to inspect some variables, -run some function and generally dig about to see what's going on. +In the middle of a script you may want to inspect variables, +run functions and inspect the flow. .. code-block:: python @@ -248,7 +243,7 @@ run some function and generally dig about to see what's going on. code.interact(local=locals()) -If you want to access both global and local variables do this... +If you want to access both global and local variables run this: .. code-block:: python @@ -266,7 +261,7 @@ The next example is an equivalent single line version of the script above which ``code.interact`` can be added at any line in the script -and will pause the script an launch an interactive interpreter in the terminal, +and will pause the script to launch an interactive interpreter in the terminal, when you're done you can quit the interpreter and the script will continue execution. @@ -279,13 +274,14 @@ The IPython prompt has auto-complete and some useful features that the standard IPython.embed() -Admittedly this highlights the lack of any Python debugging support built into Blender, but its still handy to know. +Admittedly this highlights the lack of any Python debugging support built into Blender, +but its still a handy thing to know. + Advanced ======== - -Blender as a module +Blender as a Module ------------------- From a Python perspective it's nicer to have everything as an extension @@ -293,26 +289,22 @@ which lets the Python script combine many components. Advantages include: -- you can use external editors/IDE's with Blenders Python API and execute scripts within the IDE +- You can use external editors or IDEs with Blender's Python API and execute scripts within the IDE (step over code, inspect variables as the script runs). -- editors/IDE's can auto complete Blender modules & variables. -- existing scripts can import Blender API's without having to run inside Blender. - +- Editors or IDEs can auto-complete Blender modules and variables. +- Existing scripts can import Blender APIs without having to be run inside of Blender. This is marked advanced because to run Blender as a Python module requires a special build option. - For instructions on building see -`Building Blender as a Python module <https://wiki.blender.org/wiki/Building_Blender/Other/BlenderAsPyModule>`_ +`Building Blender as a Python module <https://wiki.blender.org/wiki/Building_Blender/Other/BlenderAsPyModule>`__. Python Safety (Build Option) ---------------------------- -Since it's possible to access data which has been removed (see Gotcha's), -this can be hard to track down the cause of crashes. - +Since it's possible to access data which has been removed (see :doc:`Gotchas <info_gotcha>`), +can make it hard to track down the cause of crashes. To raise Python exceptions on accessing freed data (rather than crashing), enable the CMake build option ``WITH_PYTHON_SAFETY``. - -This enables data tracking which makes data access about 2x slower +This enables data tracking which makes data access about two times slower which is why the option isn't enabled in release builds. |