Suggestions concerning the python API documentation

Documentation
#1

Hello, I am not going to lie the python API documentation is unusable. I am going to try to explain what my problem is with it.

So, let us say you want to learn how to use a screwdriver and you have some manual that says it can teach you about it. It goes in details about what the screwdriver is made of, what colour it is and all that but it never explains you how to actually use it, e.g. telling you that it can be used only on certain types of screws, or that if you want to use it on nails you should go grab a hammer instead, that if you are doing some work involving electricity you should use a special kind of screwdriver, etc.

This is exactly how the current documentation feels to me. I have a complete description of everything the API is made of but nothing to tell me how I should use it. For instance if I delete an object, what does that do? Does it leave some memory behind that I can reuse, or do I have to manually clear it? In the case I want to keep some of the memory, what should I do? Which calls should I use? If I want to use a BMesh instead of a Mesh to generate 3D data like normals, tangents, bitangents etc., how do I go about it? What should I do in what order, what should I be aware of? When applying operators that use the current context how should I set the context? What is necessary for an object to be placed in the context?

Every time I am trying to do something like this I need to google it because there is just no information provided in the documentation which makes it useless at this point. I appreciate that there are templates and small examples, but these do not help when you get down to serious scripting. The kind of information I talked about above is what I would actually like to get.

If you want an idea of what kind of good API documentation I have in mind, check out the STB libraries (STB image for instance: https://github.com/nothings/stb/blob/master/stb_image.h). The documentation is directly provided in the source files.

1 Like
#2

Well, most of the API docs is reference documentation, so they will not tell you how to do something, merely what is available. Those parts of the docs are auto-generated as well (luckily, as that saves a ton of developer time).

In general the API reference documentation is okay for looking up the specifics of using a particular part of the Python API, but I agree that more how-to documentation would be very useful. Searching this forum (or things like stackoverflow, where some of the Blender devs have answered Python API questions in the past) can be another source of useful information. One challenge is that the Python API (as is the rest of Blender) is always in flux and so older documentation/examples might not be (fully) applicable anymore.

Reusing memory is a bit strange in the context of Python, where memory is managed automatically. I.e. if you remove the last reference to an object then it’s gone on the Python level and there’s no way to reuse it. But on the Blender level deleting an object can mean several things, as there’s the data-block layer which also does garbage collection. So at which level of “delete an object” do you mean and what memory would you like to reuse (and for what and why)?

An example like BMesh Module (bmesh) — Blender Python API will give you an idea how to use the BMesh module. The BMesh.verts reference can then tell you more how to access/set things like normals.

You don’t have so set the context when calling an operator in all cases. It’s just that in certain situations you might have to override it to get the operator to work. This part is clearly under-documented, even with respect to auto-generating information on which context members are used by operators.

Finally, I’m not a Blender dev, so take the above as my view on things. For the Blender for sciviz course we provide I’ve written a sort of beginner’s summary of often used parts of the Python API. It might be of help to you, it’s at The Python API - Introduction to Scientific Visualization with Blender

Edit: another good source of API examples is the many Python scripts that come bundled with Blender itself. You can search for a particular API part in those and get a good feel of how to use it, or even copy it to get working code to start from and adapt to your own goal.

#3

Thank you for the clarifications. The links you provided are helpful.

One challenge is that the Python API (as is the rest of Blender) is always in flux and so older documentation/examples might not be (fully) applicable anymore.

Indeed : )

Reusing memory is a bit strange in the context of Python, where memory is managed automatically. I.e. if you remove the last reference to an object then it’s gone on the Python level and there’s no way to reuse it. But on the Blender level deleting an object can mean several things, as there’s the data-block layer which also does garbage collection. So at which level of “delete an object” do you mean and what memory would you like to reuse (and for what and why)?

I basically use the API to export meshes in a custom format, so I need everything in the way of 3D data information that can be used to render meshes.
From what I understand so far Blender does not provided direct access to that kind of data (basically a list of triangles with usefull information for UV mapping, lighting calculations etc.) so I need to ask it to generate it for me in a way that lets me keep a non-destructive workflow.

So I take a copy of the objects I want to export (that part is thankfully quite straightforward) and then I try to generate that list of triangles for every object after applying the objects’s modifiers. For this latter part though I need to use an operator which is context-based (bpy.ops.object.modifier_apply(…)) and I need to set the object I want to use the operator on, like so (maybe there are alternative ways to do this):
bpy.context.view_layer.objects.active = new_object
The problem is that because this is a copy of the original object, it is not in the view layer (that is what I understand from the error I get). Now, I do not know how to set things so that I can use the copy object, so I was thinking maybe the copy should just be a reference for the original object and we just work directly with the original instead as it is in the view layer, and when the work is done we set the original data back from the copy, which is why I was thinking about reusing memory to avoid unnecessary copying. At the same time, I do not want to keep the copy when I am done with it.

Edit: another good source of API examples is the many Python scripts that come bundled with Blender itself. You can search for a particular API part in those and get a good feel of how to use it, or even copy it to get working code to start from and adapt to your own goal.

This sounds like a good source to learn from, I will look into it.

#4

I would suggest looking closer at one of the export addons included with Blender that provide an “apply modifiers” option, such as for PLY, OBJ or glTF (in increasing order of file format complexity). It seems the existing exporters need to do the exact same steps you want to perform, but for well-known formats. Plus, you have full access to their Python code.

#5

Will do, thank you for the tips!