[Bf-python] Better integration of Python in Blender

[Willian Padovani Germano]

Hi,

I've talked to Ton about this next "hot" issue and he showed me it's
simpler to start it than I thought.  I'll try to cover the basics here,
considering also input we've got from Rick Kimball (AerobicsBoy on irc)
and dwarf / Jacques.  It's all from memory, so excuse (and point!) any
mistakes, please, guys.

My only real experience with gui programming was with tkinter (python)
and I thought we couldn't pass parameters with callback functions, but
Blender has nice functions for this, e.g.:

void uiButSetFunc(uiBut *but, void (*func)(void *arg1, void *arg2), void
*arg1, void *arg2)

So the basic hook can be easily done: given a list of python script
files, make each of them an entry in a menu and execute the script when
its entry is selected by the user.  The callback is a function that
calls PyRun_File(filename) or some similar function with the script
filename as argument.

The idea is to put the menu in the main Blender menu (File, Edit, Add,
View, Game, Tools).

------------------------------
Ok, now specific details open for discussion:

0) The mechanism.
1) How easy for the user should adding a new script be?
2) How transparent we want the integration to be?
3) Can we find a suitable, clear classification for script types?
4) Persistence of script data (variables).
------------------------
0) The mechanism

When Blender starts, it will scan the default scripts dir (or better, as
Ton pointed, it will do it everytime the menu is redrawn, since Blender
widgets are recreated everytime) and add the scripts to a menu.  Ton was
wandering where to put this, I guess the place is the main menu and Rick
pointed that this should be as natural as: import scripts going into the
File->Import submenu, for example, etc. (perfect integration, based on
functionality, instead of having a specific menu for everything python).

Ton mentioned we can have subdirs and make them submenus in the main
script menu.  Rick suggested explicitly we could put import scripts in a
import/ dir, etc.  This brings us to another question: can we find a
suitable, clear classification for script types?  It'd be useful to have
one.
-----------------------

****************
** Let's step aside to consider important implementation details:

Ok, we scan dirs for scripts, but how will Blender know if that script
is directly "callable"?  I mean: take script MyScript, that is actually
composed of three files: Main.py, Functions.pyc, Scanner.pyc, for
example.  Only Main.py is to be put in a menu, the others are "internal"
to MyScript.  How will Blender know this if they are all in a same
folder?  And what's the role of folders?  Separate script types, like
mentioned above or also hold individual packages, like the example
MyScript?  How will Blender know if we allow both?

And more: what string do we put in the menu entry?  The filename minus
the extension, simply?

To solve this I suggest we define a header for scripts (the first line
in the file, of course), like:

# [IMPORT], "Wings 3d", V0.10, B2.28

This tells Blender that this script is "executable" (not internal), that
it should be put in an import menu as "Wings 3d", that its version is
0.10 and that it needs at least Blender 2.28.  Don't pay attention to
the syntax, it's really just an example.

Another advantage is that we can collect (copy) these headers in a
single file and use that instead of re-scanning the dir(s) everytime we
recreate the menus.
**********************
---------------------------
1) How easy for the user should adding a new script be?

We'll have a default dir for python scripts.  A user downloads some
script from the net and puts this script there.  The easier we make this
process for the user, the better.

If we have a main dir: python/ and subdirs: python/import/ ,
python/export , python/apps/ , python/functionality/ , whatever, should
the user have to find the right place to save the script?  Think about
it and you'll probably agree that it's better to automate this for them:

a) First alternative: create a "Registry" system in Blender.  The user
downloads a script, fires up Blender, select "Register New Script" and
selects the relevant file in the file selector.  After this, Blender by
itself "registers" the script: moves it to the right folder (according
to the header in the script) and possibly add info about it to a file
that can be scanned instead of the dirs themselves, for faster creation
of the menus.

b) We don't use subdirs, but rather use the first line in each script to
encode data to tell Blender about that script.  All scripts go into the
same python/ dir and by their headers Blender knows in which menu to put
them.  This way we don't need a Registry system, the user simply drops
new scripts to the default folder, no subdirs.
---------------------------

Ok, enough for a start, I'll send the rest tomorrow.
Opinions, please : ).  Feel free to complain if something is not clear. 
Later we'll format all suggestions in a clearer, structured way, before
taking this to the bf-committers list.

Jacques: would you like to take care of collecting the notes and
presenting them to the committers later, as I had suggested before?

--
Willian, wgermano at ig.com.br