Dev:2.4/Source/Python/API/bpy api

New developments in the Blender Python API

Note The previous version of this page was moved to its discussion page (click on the "discussion" button above). Please check it for the actual discussions and much more info than found here. - Willian

In this page (and its discussion page) we are considering additions for BPython. Below, we list the main specific points, mentioning their current state (implemented/under discussion).

Decided

Topics here have either not been discussed enough yet or we didn't reach an agreement and are still researching what to do. In a future meeting we can decide about them.

Integrating Other Modules - part II

Decision: bpy module We will develop a new module alongside the existing 'Blender' module called bpy. the existing bpy module will go into bpy.data and we will be able to have bpy.config and bpy.classes. We will have a new directory for these called 'bpy'

We have the old Blender module and its submodules and now we have the bpy module.

Since it was decided "bpy" will only be a representation of the database in Blender (bpy.meshes, bpy.scenes, etc.), we have now two "root" modules, Blender and bpy and won't include new submodules like Classes, Config, etc. in bpy.

So our alternatives for structuring (module hierarchy) are:

1. Have Blender and bpy separated, add new submodules to Blender: Blender.Classes, Blender.Config, etc.
2. Put bpy inside Blender: Blender.bpy (so ending with: Blender.bpy.meshes, etc.)
3. Create a new "blender" module (jumping on the lowercase modules bandwagon): blender.bpy, blender.classes, blender.config, maybe blender.constants, someday blender.gui, etc.
4. Something else?

Classes module

Decision: Classes Classes will be in their own submodule bpy.classes.Mesh for example

We still didn't define where the classes module will be. It was decided that it shouldn't be bpy.classes and that Blender.Classes was a good candidate. See previous topic for other possibilities...

Also, is "classes" the best name?

Constants

Decision: Constants Constants will be under their respective classes - bpy.classes.Mesh.TWOSIDE

At the moment bpy.* has no access to constants. These are some favored possibilities:

1. Class.constant
2. dataseq.constants.* -- example: bpy.meshes.constants.MODE_TWOSIDED.
3. A new module to group all constants.

Status: still investigating / discussing.

The decisions here are based on voting during a meeting on Sunday (March 25, 2007).

Khughes has written a proposal for a special PyType for Constants and has implemented it in prototype, but until then we will use what is there.

Current API documentation generated and hosted by Ideasman42.

Automatic importing

Adding important names (modules, variables, functions) to the builtin Python dictionary on startup.

Pros:

• simplicity: more results with less typing.

Cons:

• namespace pollution;
• could bring issues in the future (e.g. if it ever becomes possible to run such scripts from a standalone Python interpreter).

Decision: No automatic importing We will try other ways to achieve simplicity and less verbose scripts: A simple wrapper API on top of BPython, written in Python; Text templates for scripts in Blender's Text Editor.

Status: implemented by Ideasman42.

The bpy module

Decision: bpy this new module is, like Theeth mentioned: a "representation of the current state in Blender" (of the "database", as Stivs complemented. We should not add arbitrary modules or variables to it.

Related decision: we will make bpy, etc. replace the old object data modules (Mesh, Lamp, Camera, etc. etc.) completely, no need for them anymore.

Status: bpy implemented by Ideasman42. Rest of the work requires more investigation about sceneRender, etc. (where / how will these be reimplemented).

dataseq.load() VS dataseq.new()

All object types can be created with a dataseq.new() method. But some object types can be created from data loaded from disk: texts, images, sounds. Do we need a separate .load() method for these or is it ok to add the option for loading directly in their .new() methods?

Decision: No need for .load() methods We can add a "filename" parameter to dataseq.new to be used by those objects where it is needed.

Status: implemented by Ideasman42.

Integrating Other Modules - part I

At the moment bpy has support for all datatypes (bpy.meshes, bpy.scenes etc) as well as bpy.libraries and bpy.config. But how should we go about adding less data centric modules like Blender.Window, Draw, BGL, sys etc.

Decision: we still need these old modules Draw, BGL and Window should stay as they are, for now, in the Blender module.

Constructors VS dataseq.new()

Example:something.Mesh(name) VS bpy.meshes.new(name)

A key point here is to avoid troubles we've had with the older BPython ways, like being able to create objects without data or not linked to any scene.

Decision: It's desirable to have both alternatives During the meeting we agreed that constructors are needed, but that the current dataseq.new() way could stay as alternative.

Ascotan suggested a module named classes as a place for the constructors. Blender.Classes was mentioned by Theeth during the meeting. No decision yet.

Status: still investigating / discussing.

Documentation

Deprecation

Since we're remodeling the API, it may be a good idea, only this time, to simply remove *from the documentation* all parts we decide to deprecate in the old API.

Decision: remove deprecated parts the docs To favor the new API developments, we plan to remove from our main documentation references to deprecated parts of the API. An older version of the reference guide will be kept so users can still find information about those parts, since they won't be removed from the API itself for now.

Status: We can only do this once we finish our current work. So it's not clear now if we will do this for 2.44 or later.

Focus

Our main document is an API Reference Guide. Its purpose is to list everything available in the BPython API, but it also contains many code samples and we try to explain things well.

Still, many users complain that it is not user-friendly enough, that it needs more examples, a more gentle introduction, whatever.

Decision: reference guide separated from user manual In the meeting we decided to split our documentation in ref guide + user manual. Details will be discussed / defined later.

Programming Model For Error Handling

Programming models for error handling come in two basic flavors: One is based on return codes, the other on exceptions.

• Return Codes - Each function call returns a status code or special value to indicate whether the call succeeded. Programming in this environment is like a mountain climber negotiating a glacier where each step is carefully tested. This style is well suited for systems programming or system integration where the return types are not uniform. Passing values back up thru layers of calls is difficult however.

• Exceptions - Programming with exceptions is more like a walk in the park where everything is assumed to be OK all the time. Functions always return useful values or they raise an exception. This style is more suited for a scripting language. The scripter does not need to remember details like whether a return value of zero means success or failure. It is never necessary to check if a returned value is valid.

It also makes it easier to pass errors back up thru a chain of function calls.

Decision: We favor exceptions being a guideline, we'll follow this on future developments and "fix" parts of the current API where this is not happening.

Status: We need to list our guidelines somewhere :) .