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 File Loading & Order of Initialization
Since drivers are evaluated immediately after loading a blend-file, using the ``--python`` command line argument Since drivers may be evaluated immediately after loading a blend-file it is necessary
to populate name-space often fails to achieve the desired goal because the initial evaluation will lookup a function to ensure the driver name-space is initialized beforehand.
that doesn't exist yet, marking the driver as invalid - preventing further evaluation.
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 Populating the driver name-space before the blend-file loads also doesn't work
since opening a file clears the name-space. since opening a file clears the name-space.
The driver name-space should be populated for newly loaded files using text-block registration. It is possible to run a script via the ``--python`` command line argument, before the blend file.
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.
This can register a load-post handler (:mod:`bpy.app.handlers.load_post`) that initialized the name-space. 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 While this works for background tasks it has the downside that opening the file from the file selector
won't setup the name-space. won't setup the name-space.