Dev:Py/Scripts/Guidelines/Addons

Requirements for contributed Scripts

To prepare your script for contribution to the Blender Add-ons Catalog (and distributed along with Blender) your script must at least

• contain Add-on Meta Information in a "bl_info" dictionary.
• define register() / unregister() functions.
• be documented on an associated Wiki Page in the Blender Wiki
• be evaluated and approved by another Blender Developer
• pass the Flake8 / other PEP 8 checker Tool For Style Guide Enforcement
• for updating the scripts from the 2.7x series to 2.8 consult this page (Work in Progress)

Style Recommendations

The flake8 Tool

The flake8 tool is currently used as a style checker for the Python code. However, other PEP 8 tools can be used instead, taking in account some scripting specifics / style exemptions used for convinience. flake8 incorporates several scripts into one - providing some additional functionality like checking for unused variables. To install follow the Quickstart instructions from the Flake8 Checker link at the bottom of the page, so it is available system wide. The tool can be run from the command line or setup to run from a specific IDE. For running from a specific editor, please consult the editor's documentation.

Here is the list of Style recommendations for Blender Add-ons:

• Line length must not exceed 120 characters
• Use 4 spaces for indentation. No mixing of tabs and spaces allowed.
• Two lines gap between functions and classes, one maximum between blocks inside a function/class
• Spaces around operators
• No trailing spaces (after the line end, in the empty lines of code)
• If possible, avoid single scripts longer than 1000 lines. Consider breaking them in sub-modules in a folder structure imported from an __init__.py instead.
• All significant functions¹, classes and functions within classes should have a docstring explaining
  • what they do,
  • which parameters they receive,
  • which parameters they return.
• Comments and variable names in US English.
• Constant² variable names all upper case.
• No reliance on deprecated parts of the Blender/Python API.

¹: Significant Functions: For our purposes a significant function is one that is not obvious at a glance to a python programmer who is not experienced in the specifics that the script deals with. Even fairly simple functions should have a docstring if they are more then a few lines

²: Constants: Python has no constants, this refers to variables that do not change in the script, PI, EUL for a small number, RAD_TO_DEG, IDENTITY_MATRIX4X4 are examples of names you might use

Criterias to be checked before evaluation

Below you find a list of evaluation properties which should apply to your Script. Please make sure that your Script matches the points nicely before you contact a reviewer. This will save a lot of time for everybody and it will give you a good chance to get your Work published quickly:

• Robustness
• Maintainability (readability)
• Correctness and completeness
• Functionality
• Documentation
• Consistency, (The interface, and functionality, should try to match the existing feel and conventions of Blender).

How to get your Script published in Blender

If you are finally ready to publish your addon on the Blender Foundation servers, go ahead by reading the formal Process to Submit Addons to Blender repositories.

Special case: Using Custom Icons

If you want to use custom icons in your addon (available from Blender 2.75), you also need to observe these guidelines:

• Do not use this for advertising, logos or other non-functional use cases.
• Use a minimum of custom icons. This helps uncluttering the interface and keeping Blender's interface uniform.
• Only use these images in a way that is compatible with how rest of Blender works - as if it's a default interface we provide for everyone.
• Only use the feature within the context and UI of your own Add-on. You cannot rely on other add-ons to have this already preloaded. This feature also does not allow replacing of the default icons.
• Do not force preview image creation outside of the add-on dir, except when explicitly asked for by the user in the UI.
• The default icon size in Blender is 32x32 and for previews 256x256. Your images will be scaled to fit these sizes on their maximum side.

See also

Addons usage

Addons manual page

Here we collect informations about general addons usage

Coding style

Style Guide for Python Code

Recomended coding conventions for the Python code

Flake8 Checker

A tool to check your Python code against some of the style conventions in PEP 8 just linked above

PYCH

Online PEP 8 Python code checker