spe

  Spe Documentation

Contents:


Introduction:

Top


Requirements:

Top


Installation:

Windows
Installation: 

Spe should be installed with the windows binary. It will probably install Spe in C:\PythonXX\lib\site-packages. Afterwards, you can register 'Edit with spe' in the context menu of Windows and create shortcuts, by running the script spe/winInstall.py

Removal: 

If you registered spe in windows explorer context menu or created shortcuts, you have to remove them first with the script spe/winUninstall.py Afterwards, go to Control Panel > Add/Remove Programs and uninstall spe (probably listed with Python).

Linux, FreeBSD, Mac Os X, ...
Installation: 

Run the 'setup.py' script. This will install spe and blenpy in the standard library directory of python:

/usr/local/lib/pythonX.X/site-packages

A wrapper script called 'spe' will be installed to PREFIX/bin. If necessary add PREFIX/bin to your PATH environment variable. PREFIX is determined by the install location of the modules, i.e. for the above PREFIX=/usr/local.

When spe is launched in Blender, what might be missing in the PYTHONPATH, is /usr/local/lib/python2.2/site-packages. If you add this one in your .bashrc/.tcshrc/... to the PYTHONPATH variable everything should be fine (the subdirs spe,sm,etc. aren't needed). Though you must start blender from a bash - e.g. desktop menus usually don't read the .bashrc/.tcshrc/... and therefore blender does not know about your user defined environment variables. If you set the PYTHONPATH in /etc/profile instead of .bashrc/.tcshrc/... then starting spe/blenpy from blender will work also from menus.

Removal: 

Just run the spe/linuxUninstall.py script (use it at your own risk!) or by removing manually the directories spe, blenpy and sm of the standard library directory:

/usr/local/lib/pythonX.X/site-packages

Top


Spe:

Start spe:

Features:
  • Sidebar:
    • class/method browser (jump to source)

    • automatic todo list, highlighting the most important ones (jump to source)

    • automatic alphabetic source index of classes and methods (jump to source)

    • sticky notes

  • Tools:
    • interactive shell

    • locals browser (left click to open, right click to run)

    • seperate session recording

    • quick access to python files in folder and its subfolders (click to open)

    • unlimited recent file list (left click to open, right click to run)

    • automatic todo list of all open files, highlighting the most important ones (jump to source)

    • automatic alphabetic index of all open files (jump to source)

  • Python:
    • sytax-checking

    • syntax-coloring

    • auto-indentation

    • auto-completion

    • call-tips

  • Drag&Drop:
    • drop any amount of files or folders...

    • ... on main frame to open them

    • ... on shell to run them

    • ... on recent files to add them

    • ... on browser to add folders

  • General:
    • context help defined everywhere

    • add your own menus and toolbar buttons

    • exit & remember:all open files will next time automatically be loaded (handy for Blender sessions)

    • wxpython gui, so should be cross-platform (Windows,Linux,Mac)

    • scripts can be executed in different ways: run, run verbose and import

    • after error jump to line in source code

    • remember toggle: remembers open files between sessions (heart icon on toolbar)

  • Blender:
    • redraw the Blender screen on idle (no blackout)

    • Blender object tree browser (cameras,objects,lamps,...)

    • add your favorite scripts to the menu

    • 100% Blender compatible: can run within Blender, so all these features are available within Blender

  • Windows: - spe registers itself in the windows explorer context menu - optional creation of desktop and quick launch shortcuts

Information

It is recommended to check out all the context help, to get familiar with the features of spe. Some information which didn't fit there, comes here:

Customize menus and toolbar:

You can define your own menus and toolbar buttons, which can execute any python code and also external files. Look at 'framework/menus/Extra.py' for an example. Instructions:

  1. Suppose you want to add a new menu with the name 'XXX' to the menubar. Create a new file with the name XXX.py in the 'framework/menus/' directory

  2. Import or define some actions, with the following structure:

    def action(script,app,event):
    ...

    The arguments of the function are:

    script      -> current script window
    app -> application window
    event -> event

    Some usefull stuff:

    script.fileName
    script.source
    script.source.GetText()
    script.source.SetText(text)
    script.source.GetSelectedText()
    script.source.ReplaceSelection(text)
    app.run(fileName) -> runs an external file
    app.new() -> creates a new file
    app.open(fileName,lineno,col) -> opens a file at given position
    app.message(text) -> shows a dialog window with the
    text
    app.messageEntry(text) -> shows a dialog prompting an
    entry
    app.messageError(text) -> shows an error dialog window
    with the text
    app.SetStatus(text) -> sets the status text
  3. Define the 'main' function:

    def main(app):
    menu(app,
    item(label=<str:label that will appear in menu>,
    action=<function:that will be called>),
    item(...),
    SEPARATOR,
    item(...),
    item(...),
    ...
    SEPARATOR,
    item(...),
    ...
    )

    If you want this menu item also to have a toolbar button, than make a 16x16pixels png image (transparency is allowed). The image has to be located in the menu folder. Pass the the fileName with the toolbar keyword:

    item(label=<str:label that will appear in menu>,
    action=<function:that will be called>,
    toolbar=<str:fileName of the toolbar image (optional)>)
Separators:

A separator is a label which appears in the explore tree of the sidebar to help structuring the script. An easy way to add separators is to use the 'Edit'>'Insert colored separator' wizard from the menu.

Syntax:
  • normal: #---label

  • coloured: #---label---#foregroundcolour#backgroundcolour

  • highlighted: # # # #label (4 times #, without spaces)

Foreground and background colour are in html notation, eg:

red on blue label: #---red on blue---#FF0000#0000FF

Shortcuts:

If you want to change the default keyboard shortcuts, open the file spe/framework/shortcuts.py and adapt it to your own taste. Backup this file so that when you install a new version of spe, you can copy it back.

Associate spe with .py (windows only):

Spe registers itself automatically during setup in the window explorer context menu for '.py' and '.pyw' files. If this would fail, you can always do it manually...

In Windows you can associate Spe as an editor for .py files. This adds 'Edit with Spe' as a menu item in the context pop-up of the Windows Explorer:

In the Windows Explorer choose Tools->Folder Options
On the Dialog notebook, click File Types page.
Select PY extension in file types list.
Click the Advanced button to create a new action.
Action:
Edit with Spe
Application uses to perform action:
absolute\path\to\python.exe absolute\path\to\spe.py "%1"
OK all the dialogs
Issues:
  • Undo might sometimes takes big steps back.

  • editors.txt describes possibly installed editors. It may not work 'out of the box' for many people. If so adapt the file to your system.

Top


Blenpy:

Start blenpy_:

Open spe.blend and press Alt+P in the corresponding text window. Above settings you'll find a description of the current tool and in settings you can change the mouse configuration. Important: before using the blenpy gui, save your work. Sometimes blenpy might block/crash Blender. If you want to use the tools in another drawing, just type the following in a Blender Text window:

from blenpy.pyGui import PythonGui
PythonGui()
Modules:
  • blenpy.pyGui:

    blender python gui

    This user interface attempts to integrate as tight as possible existing python editing and introspection tools (Idle, ObjectBrowser, Pycrust, PythonWin, Leo, SciTE...) in Blender. It targets people with yet some python experience. It aim is make developping python programs for Blender more easy. The screenshots might gave a good impression. To fully profit from the benefits of this package, the installation of Wxpython is recommended.

  • blenpy.gui:

    blender gui

    A module to ease the making of gui's (graphical user interface) in Blender, wrapping the most important functions from the Blender BGL and Draw Modules. Features included:relative layout positioning, drawing filled rectangles with optional borders and automated registration of keyboard and button events. Supported are Buttons, Menus, Strings and Texts, rest will follow later. blPyGui was built upon blGui.

Manual:
  • Tools:

    Next to the launch button you can select a tool from the menu. If you select a tool, the description will appear above. Before launching the tool, make sure you have installed the required modules. Tools which have (tk) depend on Tkinter and tools which have (wx) on Wxpython. You don't have to install Tkinter as it is part of the standard python distribution. If extra modules are required, it is displayed in the description. If you have Wxpython installed, check out 'PyCrust >>>'. Press the launch button to launch the Tool. When working with the tool, the Blender application is not accessible (probably turns black). You can only return to Blender by closing ALL the tool windows.

    You can add your own tools by editing pluginstools.py If this tool could be interesting for other users, please send me than a copy. So I can include it in the next release.

  • Browser:

    In the mouse configuration: you can define actions for the mouse buttons. There are now 3 types of actions:editing(see more down), run and import. 'Run' executes the file and returns the exitcode (see Blender console). 'Import' imports the file as if it was a module. Reference is an interesting option if you want to edit the script outside Blender. It doesn't import the source code into Blender, but creates a python shorcut script which will execute the saved file on the disk when you press Alt+P.

    The 'Select here...' button display a path menu. By the default the current drawing directory is added as the 'working directory'. To add a directory, press the 'b' button, which will open a directory select dialog. Select the directory and press 'ok'. The directory is now added to the 'Select here' menu. (If you don't have tkFileDialog installed on your system, type the name in the field which contains '...'. Then press the '+' button. The directory is than added.)

    Before proceeding, remember the configuration of the mouse actions. If you now select a path with the 'Select here...' menu, a table with all python files of that path and all subpaths will be displayed. By clicking above a file, the mouse action will be triggered.

    With the '-' button you can remove the active directory from the path menu.

  • Editing:
    • Strategies:
      1. 'Edit with ...':

        This provides an editor, from which programs can be immediately run in Blender. It also provides a shell which can be used to try out python in Blender interactively. The Shell has access to the Blender Namespace, which makes it possible to type 'import Blender' in the shell and than to use any Blender python command. Spe is probably the best solution with its auto-indentation, calltips and auto-completion. If you want to switch continously between Blender and the editing sessions, turn on the remember toggle on the toolbar (heart icon). This saves you from opening always all the files again. PythonWin (windows only) can only be used once.

      2. 'Reference' & 'Send to ...':

        These two commands are very usefull together. 'Reference' doesn't load the source code in a Blender Text window, but places a short python code to run the script from the file. 'Send to ...' opens the file in an external editor. So you can edit your file and save it. To try the result immediately, just press Alt+P in Blender on the python shortcut.

      3. 'Load as Blender Text':

        The old way of using python in Blender. It loads the source as a Blender Text, adding a comment on the first line: #@filename

        This comment is recognised by the 'Revert All' and 'Save All' buttons and will automatically load/save the source from/to these files. The 'Save All' button won't save the first comment line in the file on disk, so there is no need to remove it from blender. To exclude a file from to the 'Revert All' and 'Save All', just change '#@' in '#'. The 'Revert All' and 'Save All' can be combined with external editing through 'Send to ...' but it can be confusing to have the same file twice opened. It has the risk of overwriting a new file with an old file.

        The Blender Text window is a but 'unpythonic', as it doesn't support auto-indentation, calltips or auto-completion. Its clipboard operations (Cut Alt+X, Copy Alt+C and Paste Alt+V) are only working within Blender and do not interact with other applications. Therefore above strategies are preferable.

    • Extensibility:

      You can add your own editors by editing pluginseditors.py for internal and pluginseditors.txt for external editors. If this change could be interesting for other users, please send me than a copy. So I can include it in the next release.

  • Notations:
    '>>>':

    This means that the tool includes an object Browser with all objects in the drawing, of which all 'get' methods are recursively evaluated (see the '>>>' entries). In this way it is possible to see eg of an [Object 'Camera'] automatically its data by '>>> getData()', which could be [Camera 'Camera']. Although this can be very usefull, it can be too clumbersome for bigger drawings. So it is better to limit its use to light drawings.

    'Light':

    This means that the tool doesn't preload the Blender module and its object browser.

  • Customizing:

    Power users can customize files like mouse.py, tools.py and editors.txt in the plugins folder. If you do, please if you changed these files please send me a copy, so it can be updated for the next release and all users can profit from it.

Appendix:
  • Files:

    gui               General module for creating gui's
    pyGui User interface for python_ devellopers
    doc\ Documentation
    ...
    plugins\ You can edit these to add other editors or tools:
    editors.txt External editors (Send to)
    editors.py Internal editors (Edit)
    mouse.py Mouse button actions (such as run, import,...)
    tools.py Tools
    ...
    sm\ Blender_ independent modules
    tk* Tkinter specific
    wxp* Wxpython_ specific
  • Todo:
    • Better documentation

    • Finish the gui module

    • ...

  • Known issues:
    • Boa Constructor: can only run if you disable all Zope features.

    • pydoc: This will crash Blender. Don't use it, unless you know what you are doing.

    • PythonWin: Edit only works once within one Blender session.

  • Bugs in the Blender API:

    One of these errors might appear in the Blender console, but you can safely ignore them:

    Internal error, Invalid prop entry Trying to access the attribute 'starColNoise' of the World class gives this error statement.

    ipo member access deprecated,use self.getIpo() instead! Trying to access the attribute ipo gives this error statement.

Top


Contact:

Spe is still under development. If you use Spe, please post a message on the appropiate forum on http://projects.blender.org/forum/?group_id=30 describing the platform, the problems that occur and possible solutions if you know. If Spe runs without any problems, I'm also interested to get a notice. I developped spe under windows xp and have no access to Linux, Mac, FreeBsd or any other platform. So any help for these platforms is highly appreciated. If you would like to contribute to spe in any way, send me an email with your skills (programming, graphics,icons,3d,html,...) and I'm sure you can help me out.

If you want to get the last version, which is not yet released publicly, just send me an email.

Top


Credits:

Thanks to the following components Spe was made possible:

Special thanks to Tina Hirsch (Linux feedback).

Python is Copyright (c) 2000-2002 ActiveState Corp:

Copyright (c) 2001, 2002 Python_ Software Foundation.
All Rights Reserved.

Copyright (c) 2000 BeOpen.com.
All Rights Reserved.

Copyright (c) 1995-2001 Corporation for National Research Initiatives.
All Rights Reserved.

Copyright (c) 1991-1995 Stichting Mathematisch Centrum, Amsterdam.
All Rights Reserved.

This program uses IDLE extensions by Guido van Rossum, Tim Peters and others.