best practice for add-on generation with many functions single file or split it up?

Question

This is quite a theoretical question.

A simple function can remain inside an add-on text file. But what if you have many functions and your text file gets very long. Would it be better to split each function into logical segments lets say one file for modifiers, one file for mesh editing and such and then have one add-on file that calls / loads the code from those text files?

Or, is it better to keep everything in one file?

Are there facts I should be aware of to help me make a choice?

Answer 1

In my opinion you should always use multiple files for non-trivial addons (e.g. more than one operator).

I agree that it can be complicated in at first and I have to admit that it took me quite some time until I was able to create multi-file addons in a nice way. BUT, a few months ago I developed an addon template for my Code Autocomplete addon that allows you to create multi-file addons very easily. Without having to care about reloading etc.

Since then I always use this template. Even as large addons as Animation Nodes and Code Autocomplete use it (and some others as well, e.g. this one).

Here is how I setup a new addon:

1. Create a new folder in Blenders addons directory. It's not super important but I suggest to use a name that can be a python identifier and all lower case.

2. Inside of this folder I create a _ init _.py file with this content.

3. Create a developer_utils.py file with this content.

4. Setup a git repository in that folder.

That's it. You can simply create more .py files in the folder now and all of them will be loaded and reloaded automatically. If you define operators, panels, ... inside of one of these files they will be registered as well (by the bpy.utils.register_module(_ name _) statement in the main file). Ah and don't forget to create a _ init _.py file in each subdirectory. I generally keep them empty.

The Code Autocomplete addon can do the first 3 steps for you.

http://code-autocomplete-manual.readthedocs.org/en/latest/addon_development.html

So why should you use multiple files:

• Much better support by version control systems like GIT.
• The dependencies in your code are much clearer, because you have to import functions you want to use in a file. That makes refactoring much easier.
• Easier to extend without cluttering existing code.
• Better separation between parts of you addon like operators and ui.
• Makes it possible to write reusable modules.
• Easier to manage in modern code editors, because most of them use a folder as project (I personally use Atom atm and like it very much!).

In summary: I only see benefits in using multi-file addons and using the template I developed most of the difficulties are gone.

Answer 2

If you can - keep it single file and only when you have reasons - go multi-file.

Benefits of single-file:

• it requires less code
• other people better understand it as it is less complicated
• it works better inside Blender environment
• there is beauty in nicely formatted single-file Blender addon. It is nicely packed together.

When to split:

• When your addon is a larger project (50kb+) and when you are editing with external tools. When I know a function will be shared/reused I put it inside (for example) mesh_utils.py file, then such addons become multi-file in a folder and I link the function with:

  from .mesh_utils import function
  

• I do not split the file just because the length. Having more files over one long file is no win, both are problems to deal with. When you keep your file clean and organized, even several thousand lines long files are no problem (you can also collapse things in external editors). If the file is long I put a dictionary at the top to mark where things are (mainly their order as when you write code the lines change):

  # Contents:
  #  - naming utils
  #  - constraints utils
  #  - driver/keyframe utils
  #  - opengl
  #  - operators
  #  - handlers
  #  - ui/panels
  #  - addon prefs
  #  - properties
  #  - register
  

  Inside the code I mark each category with headline like this:

  # =====================================================
  #                       OPERATORS
  # =====================================================
  

  Inside an editor with a mini-map it can be seen and also you easily notice them when scrolling through the file helping you be oriented.

  CtrlF for search in long files is your friend and a way to be fast.

  CtrlSpacebar (Autocomplete inside Text editor) lists used text in an open text file - a reason to keep your functions inside one file when working inside Blender.

In the end it's you who will determine if the code structure is good or bad. You can make terrible multi-file mess and a symphony-like single-file and vice-versa. The key is good documentation/comments and format consistency. Keep all files and addons the same structure and name everything properly so it can be searched.

Answer 3

single-file -- vs -- multi-file

I think if you're looking for a Blender centric answer it's a good idea to look through the scripts that come with Blender by default. The addons folder has quite a few multi-file add-ons (as directories) and only a few long .py files -- most single-file add-ons are short.

The single file approach in general is fine for non-complicated add-ons, like a few short Operators with a Menu or Panel. Historically single file add-ons where easier to download/install by Blender newcomers. When the Install from File feature was added, which takes a zip, the single file approach lost that excuse.

Remaining reasons to use the single file approach for large add-ons are down to how comfortable someone is with Python. It's easy to write single file code, but adding a directory structure does require investing time in reading / understanding how that works. Luckily, the add-on directory has many working examples to show how you might organize a multi-file add-on. So "it's difficult" is not an excuse either.

---

Text Editor

More important than single or multifile is what are you coding with, a Text Editor equipped with features that help you code?

• Does your Text Editor have plugins for checking if your code conforms to Python's "pep8" style guide? For instance this screenshot shows what I get from SublimeText when I hit save on a file with many violations of pep-8.
• Is it easy to make and trigger snippets? -- snippets are templates of reusable code which form the basis of Operators / Panels / Menus / general code patterns. Save us retyping the boilerplate.

GIT

More important still is: are you using some kind of source-code version control, (git, svn) so you can easily keep track of changes, and revert/correct with ease when code modifications cause unwanted side effects. source control systems give convenient ways to see the differences between two updates sideby side or in the form of a .diff file.