Guidelines¶
Process and recommendations to help with extension submit approval review. This can also guide extension authors to make sure their submissions are up to the highest standards.
General¶
-
Make sure the Terms of Service are respected. (example)
-
Check if it works in Blender (run some basic functionality)
-
Check the manifest, common problems:
- Permissions are not correct (
files
is expected for most I/O add-ons). - Optional arguments left in with default values (it shouldn't happen anymore since the guide was updated)
- Permissions are not correct (
-
Python: Make sure there is no auto-updater on the code (example).
-
Python: pip dependencies should be bundled as wheels or vendorized.
-
Python: If using
network
permission, the add-on is expected to check forbpy.app.online_access
. -
Interface: When possible, it is nice to share some advice on following UI's guidelines (example).
-
Check the overall quality of the images.
-
Make sure there are no heavy image (
.gif
images in particular) on the image description, making the page massive to load. -
Make sure the author is the owner/maintainer of the extension.
-
Make sure the add-on is self-contained.
- This is the most delicate one and if in doubt ask on the #extension-moderators room.
- It should not have functionality which is extended by external software.
- It should not depend on external servers (
localhost
is fine).
Violations in Code¶
-
Check all uses of
__file__
, this relates to two common mis-uses of this:- Manually constructing paths to add to
sys.path
and import modules into the global module name-space. Instead, sub-modules or wheels must be used. - Constructing paths to write to, when it must not be assumed the add-on directory is writable.
Instead
bpy.utils.extension_path_user
must be used.
- Manually constructing paths to add to
-
Check all uses of
open
, especially writing files to ensure the script is writing to a valid location. -
Check all uses of
__name__
, for legacy add-ons this matches the add-on ID. For extensions__package__
is used for the add-on identifier, e.g.context.preferences.addons[__package__]
will return the add-on. The following expression is a common mistake:context.preferences.addons[__name__].preference
-
Check for all uses of the
sys
module. In general it should only be considered read-only. Direct manipulation or assignment of any of it's values is a hint that the extension may be making global changes that impact other modules. -
Check there are no hard coded repository module names
user_repository
orblender_org
.
Also check the literalbl_ext
is never used as this is practically always a bad sign that an extension is either manipulating another extensions or not using relative imports when it should. -
Check access to
bpy.context.window_manager.keyconfigs.addon
accounts for None (in background mode). -
Check online access.
- Search for imports:
requests
&urllib
. - Search for
http
literal. - Double check all access first checks
bpy.app.online_access
and sending any data to a 3rd party is an explicit user action.
- Search for imports:
Code Quality¶
Some extensions have low quality code, while not violating any rules, it's likely to cause problems and can be noted in review.
-
Check for back-slash characters (
\
) use as path separators (that aren't used for escaping or line continuations).
These wont work on Linux or macOS. -
Check direct access to Blender data:
bpy.data.[a-z_]+\.
This often hints at weak logic, for example:bpy.data.scenes[bpy.context.scene.name]
This can be a bug as two data-blocks may have the same name when one is from a library.bpy.data.worlds["World"]
Hard coded data-block names may not exist. In general it's a bad sign if scripts are assuming data-blocks with special names exist.
-
Check access of
bpy.data.objects
. This is rarely useful, in most cases the current scenes objects should be accessed instead. -
Incorrect Quoting (Python expression)
When generating Python expressions...
file.write('open("' + path + '")'
should be:
file.write('open(' + repr(path) + ')'
Or use the
repr
formatting specifiers forstr.format
or percentage-formatting:{!r}
or%r
respectively. -
Incorrect Quoting (Blender's Data-Paths)
insert_keyframe('"pose.bones["' + bone.name + '"].property')
wherebone.name
should be
bpy.utils.escape_identifier(bone.name)
-
Incorrect Quoting (Command Line Arguments)
os.system('some_command --path "' + filepath + '"')
should be:
os.system(shlex.join(["some_command", "--path", filepath])
-
Run a linter on all scripts:
find "." -iname "*.py" | xargs ruff check --output-format=concise --ignore=E402,E741,E731
While this doesn't need to pass without warnings: large numbers of unused imports, undefined variables or invalid syntax are a bad sign and might hint at inclusion of outdated/unused code.