Dev:2.5/Source/Python/API/Ideasman

Python API for Blender 2.5

This document is a proposal for a new Python API for Blender 2.50. It assumes you are familiar with RNA and Operators.

Im available to write these API's and organizing moving existing scripts to a new Blender 2.50 API --Ideasman42 04:22, 1 December 2008 (UTC)

Goals

Goals for the new api to solve issues we currently have with the Python 2.4x API.

• Feature Parity
  Features available in blender should also be available in python
• Maintainable API & No Duplication
  Most functionality should be exposed through RNA or operators, python gains automatic access to these API's.
• Python Respecting Context
  If the user cant do somthing based on the current context, python must respect this too.
• No Dangling Pointers
  2.4x API can be easily made to crash blender by accessing data that has been removed, such as Text, verts, scenes etc. (fixing this in the 2.4x api is not trivial)

PyRNA (data api)

• Thin API, easy to maintain since its just a python interface to RNA.
• Wraps the C RNA-data-api, giving access to all data the user interface and animation system uses.
• Write access works for editing numbers, strings, layers, dropdown options.
  but not for more complex operations like duplicating data (see PyOperators)
• PyRNA is mostly complete - see http://wiki.blender.org/index.php/BlenderDev/Blender2.5/PyRNA

PyOperator (tools api)

• Thin wrapped or auto-generated API, no need to maintain lists of python operators and their settings.
• Provides access to blender tools such as transform, extrude, duplicate, select, hide, save, apply modifiers etc.
• Most/All? user operations can be reproduced in a script.
• Operators are limited to the current context.
• Operators accessed that cannot run in the current context will raise a python exception.
• PyOperators will not be limited to acting on the user selection, python will be able define its own selection.
• This way user actions can be re-produced as a script (not started yet)
• work on PyOperator has not started yet.

Extending Thin API's

The automatically wrapped api's will not give us all the utility functions we'd like. Especially PyRNA since it only exposes blenders data, and without functions python scripters would find helpful.

Python can be used to subclass PyRNA adding utility functions where needed.

Examples of utility functions that could be added to access info that isn't stored internally...

• face.normal
• mesh.bounds
• object.children

Accessing subclassed types could be default, This means script writers get useful functionality. Since its written in python, more people are able to contribute to this extended api.

Other APIs

Whilst the bulk of functionality should be covered by RNA + Operators, some functions are only relevant to python.

• Dealing with paths, make path relative/absolute, check if it exists.
• Dealing with keymaps, loading in new keymaps.
• User Interface API
• Math Utilities

However I think we should be very careful with this, since it could easily grow too big if people just add functions without investigating how they might be accessed through PyRNA or PyOperators.

As mentioned above we will need a user interface API, when the 2.5 api is more complete this can be planned.

Integration

Current implementations of script-links and space-handlers may not fit into 2.50 design. We will also need to review how PyDrivers, PyNodes, PyConstraints and PyText plugins should work in 2.5.

Backwards Compatibility

No matter what we do, many scripts are going to break, simply because blenders internals will behave differently, removing some functions cant be avoided.

I propose dropping the existing 2.4x API, existing scripts can be updated...

• The first Blender 2.50 release does not need to have every script from 2.4x running, importers, exporters and popular utilities can be ported first.
• A "Blender" API written in python can ease migration, often used functions can be added here, that work like the 2.4x API, using PyRNA and PyOperators internally.

Why not keep the 2.4x API

I would argue against this because...

• There already minimal interest in maintaining this API. If included its likely not to have the same level as support as the rest of blender (bugfixes, supporting new blender options etc)
• While being useful it is error prone and incomplete. This is unlikely to change.
• Keeping it wont ensure scripts stay running, any scripts will break even if we try to keep the API stable
  As has happened before to the Py API in previous blender releases, with much smaller changes then we expect in 2.50
• There is nothing wrong with users sticking to Blender 2.48/2.49 for some months if they rely on specific python tools.
• Having the 2.4x API run in blender 2.50 may not be trivial task, who is interested in doing this?

Risks

With moving to a new API we risk breaking scripts that cannot be ported to a new API. In the worst case we'll need to keep the 2.4x API running in Blender 2.50, this will become obvious before 2.50 so I think its an acceptable one.