Dev:2.5/Source/Python/API

Python (API)
Owner(s)	Campbell Barton
Member(s)	Andrew Hale

Blender 2.5 Python API

This page is an effort to start discussion regarding future of the python API in Blender 2.5.

The blender python api (BPY) is a very useful part of blender but maintaining the current API is time consuming and involves duplicating blenders functionality along with a lot of C/Python api code to interface python with blender. This code needs to be kept up to date with blenders internal functionally but remains incomplete because it relies on a hand written interface to blender which has its own bugs and al.

If anyone who is not aware, blender does not have a generic C api that can be automatically wrapped via swig or similar tools

With blender 2.5 we will be able to use a "data api" to give us access to get/setting properties, buttions and IPO's will also use this api.

"operators" will be used to manipulate the context, allowing python to have macro style access to blenders tools.

These 2 api's can have thin C/Python wrappers that are simple to maintain, since they only forward calls to C.

• I would like to first define a good spec and focus. One thing that bothers me is lack of context-sensitivity in Blender's py API. Based on where a script within Blender is being called, specific modules should be disabled, and print errors. That way you can separate event-handling from drawing for example. Another crucial spec is to only allow Python to do what Blender can. Any python wrapped function should make use of Blender's API, and when there's no proper Blender API it should be created first. --Ton 19:10, 25 November 2008 (UTC)

Some Big Questions

There are some fairly important decisions to make before nutting out the details. These don't need to be answered now, but we should start planning.

• Would the current BPy API (Blender.Object, Blender.Mesh etc) even work with 2.5 context changes.
  (if so, is it worth the effort to move it across and keep maintaining it)
• Could a data & operator API completely replace BPY?
  (Assuming the replacement api does not have to function in exactly the same way as BPY)
  • No, I think we'll need 3 api's. Next to RNA and Operator (auto generated) we still need a manual wrapper to Blender calls. It's not likely to presume *every* data manipulation to become wrapped as operator... There's also a BPY api needed for things like "Add keymap handler" and such. --Ton 19:02, 25 November 2008 (UTC)
• Should move to python 3.0? - internal changes for 2.5 are likely to break scripts (even if we try to provide a compatible api), this would be a good chance to move to a new python version. This isn't such a big issue since other decisions don't rely on it, just keep in mind since Python 3.0 may be beta/released by the time blender 2.5 is out.

Other Questions (postponed for now)

There are some other issues we need to resolve but first we should decide on the bigger topics.

• How will blender intergration work in 2.5?
  • Scriptlinks? Space handlers? Should we keep them?
    • Scriptlinks probably yes, space handlers will become generic handler API --Ton 19:07, 25 November 2008 (UTC)
  • PyDrivers & PyConstraints? - a new BPy api will probably break these.
  • User interfaces? - Will these work the same way as they do now.
    (I hope not --Ideasman42 10:59, 27 October 2008 (UTC))
    • Preferably not :) --Ton 19:07, 25 November 2008 (UTC)
• Will the BGE Python API Have any changes?
  • Id propose some minor API changes, remove the 'OB' and 'ME' prefix from object & mesh names (somebody forgot to do id.name+2) and some consistency improvements but leave largely the same --Ideasman42 10:59, 27 October 2008 (UTC)
  • Should we keep utility modules from Blender? - Mathutils, Geometry, Blender.sys?
    • It would be great if BGE functions returned proper Mathutils types (eg Vector) instead of plain lists. Also I think currently BGE matrices need to be transposed for use with Mathutils, which is a bit cumbersome. So, +1 for improved consistency too. --Z0r 06:36, 4 December 2008 (UTC)(Sign)

Data API

The python interface to the data api can be autogenerated, as the data api its self will be.

Most blender data types map fairly simply into python types so there are not too many problems here.

Operator API

pythons operator access can use ID properties (as blenders internals will), however there are still some issues to be resolved.

Operators use a context, from the user interface perspective this context could be the current view the mouse is over, however from python, it could be too limiting to confine scripts to the current user context.

the context contains information like current scene, 3d layers and editmode object.

• Would python pass the context as an argument to operators?
• Will python scripts be able to have their own context?
  Python tools could operate on a copy of the user context
• Could python scripts deal with more then one context at a time?
  Python tools could get and set the context commands run in, This would be needed if you wanted to operate on 2 objects at once, without continuously switching between active objecst

• • I think the Context design isn't finished yet, so it needs some time. However, a Python script should be able to replace Context itterators like "get all selected objects". A script should not be able to move WM level context (to other areas or windows).--Ton 19:13, 25 November 2008 (UTC)

Options for the 2.5 API

Assuming we don't keep the current BPy API, what could the 2.5 api look like?

How far can the DataAPI and Operators take us?

There are some workflows that arnt so easy to perform with a macro style api and vice-vercer.

Add a triangle face:

 # BPy (existing api)
 me = bpy.data.scenes.active.objects.active.getData(mesh=1)
 me.verts.extend([(0,0,0), (1,0,0), (0,1,0)])
 me.faces.extend([0,1,2])

 # Macro Style (imaginary api)
 editmode_select_all()
 editmode_hide()
 editmode_addvert(loc=(0,0,0))
 editmode_addvert(loc=(1,0,0))
 editmode_addvert(loc=(0,1,0))
 editmode_select_all()
 editmode_makeFace()
 editmode_unhide()

Move the selected verts up by 1

 # BPy (existing api)
 me = bpy.data.scenes.active.objects.active.getData(mesh=1)
 for v in me.verts:
   if v.sel:
     v.co.z += 1.0

 # Macro Style (imaginary api)
 transform(translate=(0,0,1))

But Macro Style API is horrible in some cases

Yes, the adding a face example is very verbose and quite command intensive compared to BPy.

There are a number of ways we could work around the fact that some tasks are not so well suited to a macro style api.

• Add an api written in python that gives an interface similar to the BPY api. This can still use operators internally.
• Add operators especially for making this easier.
  editmode_addface(...) for example, we could have operators that expose functionality the user interface does not make use of.
• Keep parts of the BPy api for fast data access.
  The disadvantage with this is that we then have to maintain API's for each data type, there are also problems with pointers becoming outdated when data is freed, causing crashes, Id only consider this as a last resort --Ideasman42 07:38, 24 October 2008 (UTC)

Style and PEP-8

Would be good if we could follow the official python style guide (PEP-8) closer for new python code... maintaining consistency with the official python style guide should help make blender's API a bit more accessible for seasoned python hackers who are new to blender's API. (Note that the RNA naming conventions already seem to be following this)