bartvdbraak/blender
1
0
Fork 4
Code Issues 4 Pull Requests 1 Actions 1 Packages Projects Releases Wiki Activity

Docs: improve bpy.app.driver_namespace, add stub example

Browse Source 
The description first described functionality that doesn't work properly.
Prefer text that is to the point with what works well, elaborating on
error prone & partially working solutions afterwards.

Also include a stub example for script authors who prefer to develop &
maintain their scripts outside of Blender.
This commit is contained in:
Campbell Barton 2023-11-01 13:59:57 +11:00
parent f6c52849b5
commit 960e2c73de
1 changed files with 29 additions and 9 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

38
doc/python_api/examples/bpy.app.driver_namespace.py
View File

@ -1,18 +1,38 @@
"""
File Loading & Order of Initialization
Since drivers are evaluated immediately after loading a blend-file, using the ``--python`` command line argument
to populate name-space often fails to achieve the desired goal because the initial evaluation will lookup a function
that doesn't exist yet, marking the driver as invalid - preventing further evaluation.
Since drivers may be evaluated immediately after loading a blend-file it is necessary
to ensure the driver name-space is initialized beforehand.
This can be done by registering text data-blocks to execute on startup,
which executes the scripts before drivers are evaluated.
See *Text -> Register* from Blender's text editor.
.. hint::
You may prefer to use external files instead of Blender's text-blocks.
This can be done using a text-block which executes an external file.
This example runs ``driver_namespace.py`` located in the same directory as the text-blocks blend-file:
.. code-block::
import os
import bpy
blend_dir = os.path.normalize(os.path.join(__file__, "..", ".."))
bpy.utils.execfile(os.path.join(blend_dir, "driver_namespace.py"))
Using ``__file__`` ensures the text resolves to the expected path even when library-linked from another file.
Other methods of populating the drivers name-space can be made to work but tend to be error prone:
Using The ``--python`` command line argument to populate name-space often fails to achieve the desired goal
because the initial evaluation will lookup a function that doesn't exist yet,
marking the driver as invalid - preventing further evaluation.
Populating the driver name-space before the blend-file loads also doesn't work
since opening a file clears the name-space.
The driver name-space should be populated for newly loaded files using text-block registration.
Text blocks may be marked to execute on startup from the text editor *Text -> Register*.
Scripts that are registered will execute after a blend-file loads & before driver evaluation.
It's also possible to use run a script via the ``--python`` command line argument, before the blend file.
It is possible to run a script via the ``--python`` command line argument, before the blend file.
This can register a load-post handler (:mod:`bpy.app.handlers.load_post`) that initialized the name-space.
While this works for background tasks it has the downside that opening the file from the file selector
won't setup the name-space.