From BlenderWiki

End-user spec

WARNING: this is a work in progress!

bpy API from user's point of view?

how to access Blender data for reading? for writing?

The 2.5 API

Overview

Why new API?

Creating objects

How to create meshes, armatures, cameras, lamps, other objects.

Manipulating object data

How to add/remove verts, faces, edges, uvs from mesh, add/remove bones from armature, etc.

The old API

Overview

Why replace it?

Creating objects

How meshes, armatures, cameras, lamps, other objects were created.

Manipulating object data

How mesh verts, faces, edges, uvs, armature bones, etc were removed/added.

TODO: restructure this section

Geometry

Export

object = bpy.data.objects["name"]
mesh = object.data # or bpy.data.meshes["name"]
mesh = bpy.data.objects["name"].data
mesh.verts
mesh.faces
mesh.uv_layers["UVTex"].data # a collection of MeshTextureFaces

Import

The way it was in 2.48

# add things
mesh = bpy.data.meshes.new(name)
object = bpy.data.objects.new(mesh)

# set geometry
me.verts.extend(verts)
me.faces.extend(faces)

In 2.5 it will be

mesh.verts.extend(verts)

or

mesh.verts.extend(verts, faces)

or

kaito (IRC): the simplest way for import now would be to code a C function for 'add primitive' with as args a list of verts & face indices, then api can say 'add empty object mesh' -> enter editmode for it -> add prim -> leave editmode

or

object = bpy.data.add_object(name)
object.data = bpy.data.add_mesh(verts, faces, ...)

add_mesh would enter editmode, create editmesh, set geometry, free editmesh, exit editmode.

Transforms

object.location
object.rotation
object.scale

more?

TODO

• add/remove scene, camera, lamp, mesh, mesh data (verts, faces, edges, uvs), armature, armature data, other object types - these ask for generic functions - possible?
  
• materials
  
• understand uv_layers (see old api?)