Featured post

new redirect for blender.org bpy docs.

http://www.blender.org/api/blender_python_api_current/ As of 10/11 november 2015 we can now link to the current api docs and not be worr...

August 20, 2012

Blender Python BPY Frequently Asked Questions

Q. What is a good way to learn scripting / python / BPY / programming?
A. By reading code, by opening up the /scripts directory of blender and looking at the /addons and addons_contrib directories. This will introduce you to what the code looks like and likely demystify the concepts involved. Even if you only understand 2 out of every 100 lines in those files you will gain understanding and experience by reading them and thinking about the content.

If you are not already an experienced python coder you should learn python outside of the blender context. Know python, preferably inside out, the journey is fun and full of interesting landscapes - and worth all the effort you put into it. Here are a few links that I know will help you on this journey. (Yes, none of them relate directly to Blender.. but once you understand python you will write blender scripts confidently). Maybe you don't know this, but python is used often to teach programming because it is easy to read and predictable.

A quick note before diving into these links; Python comes in two main flavours. Python2.x and Python3.x, they are almost the same. I'll elaborate on this in the differences between py2 and py3 section.
  • Google Python Classes (with video) [lecturer info] Do the class quizzes and stick with it - don't look at the answers until you have a working version - then look at how different your solution is to the proposed solution. You might find that the instructor writes the answers in 10 lines where you need 40 lines. This is a massive learning experience, the page has examples that help with understanding the concepts. Take your time, If you have really put in effort and still don't understand it, then look at the answers
  • Udacity cs101 (if the link isn't valid, search for cs101 on udacity. I hear from many people that this course helped them understand more about the logic needed to write computer programs. Udacity also offers Design of Computer Programs (cs212), which is a big leap from cs101 but WOW will it blow your mind!
  • Python.org has a list of tutorials too, and plenty of hyperlinks for elaborations on topics. Worth spending time at and a source of a great many brilliant ways of thinking about python - it seems people often overlook this part of python.org.
  • PythonChallenge offers about 32 challenges, ranging from weird, to completely impossible (yet somehow possible!). These quizzes might really suck away your free time, I would recommend this as a pass-time instead of any computer game - in the very least you will learn how to google python related topics and think laterally (beware: python 2.x).
  • Free python (e)Books, I like to encourage reading and getting the story as a narrative.
  • For the bandwidth challenged, codecademy offers a wide range of javascript / python lessons with very active forums.
You have no reason to not learn python. It's all there, everything you need - attention span and motivation not included :).

Q. I know a little python now, but have tried writing blender scripts and it's a little confusing. What should I focus on?
Know how to write python the clean way, and follow the style recommendations here. If you write according to the style guide there then people will find it more pleasant to read your code.

The following list is a guide to test your familiarity with Python. If a few are still intimidating then use it as a check list for more directed study of those specific topics.
  • [ ] python print
  • [ ] python integer
  • [ ] python float
  • [ ] python string
  • [ ] python tuple
  • [ ] python list
  • [ ] python dictionary
  • [ ] python boolean
  • [ ] python if statements
  • [ ] python standard library
  • ----------------------------
  • [ ] python string manipulation
  • [ ] python for loop
  • [ ] python list comprehensions
  • [ ] python while loop
  • [ ] python flow control
  • [ ] python try except
  • [ ] python functions
  • [ ] python import libraries
  • [ ] python classes
  • ----------------------------
  • [ ] python decorators

Q. How do i do X in Blender Python BPY?
A. At this point you should know Python and be familiar with how to write it and how to string all that syntax into a meaningful routine. If you are not comfortable with Python then read the answer to the previous question again, and stop reading this answer,yes - seriously.

To proceed as smoothly as possible you need a working understanding of Blender and the interface. When you start out learning about BPY it is insanely useful to realize all of the following things.
  • By dragging down the info panel you will see a report window. That window gives most of the code that generated your actions in the 3dview. It might be intimidating and confusing because it spits out all the default values of functions as well. (more about that here)
  • The Interactive Python Console has an auto-complete and dir() and help() can be performed on bpy.thing.entity.part[index] work too. (more about this here)
  • The Text Editor has a list of templates for a plethora of scripting needs, but of course not everything is going to be covered.

Q. Why is the BPY documentation so poor?
A. As it stands the documentation is quite good, there is of course always room for improvement. Mostly if you can't find answers, then it's either a very specific nook you've found yourself in, or you have trouble finding the right documentation, or the topic is itself rather complicated.

The online documentation discusses content, style and best practices for your scripts. If you took the time to read the Python.org tutorials then a lot of the Blender Python documentation will reinforce the same sentiments. BPY specific documentation can usually be inferred by doing a help() or dir() on the part of code you have issues with. A vast majority of functions in BPY have docstrings that offer a reasonable description of the input and output values of a function, and when to use it.

Very often you can get a variety of answers by doing a (insert your favourite internet search engine here or Google) for Blender bpy [topic] [specific function], hit that search engine for a while and do a forum search before posting questions - not doing so is a universal sign of laziness and people are less inclined to answer these kinds of questions.

Q. How do i do UI scripts for blender?
A. Read scripts/../bl_ui and look at the source of any script that has a UI. If you find a script with a UI element that you want to use, then view the source of that script and chop away at the stuff you don't need until you are left with the kernel/essential part of that script. Once you've done that a few times with various scripts you will see a pattern emerge and you will get much faster at it.

Once you have reduced a few scripts to their essentials you will have a better idea of how to write a UI layout from scratch without stripping existing layouts. There is a lot of UI code explained in the cookbook, it's not an exhaustive introspection of the UI but it will help for a vast majority of layout concepts. There are limitations to UI layout grammar, but they shouldn't be showstoppers if you're starting out.

Q. Help i'm writing this script but could someone help with this one part?
A. Sure! But make it easy for people who are not familiar with your script by providing the code in question. We have no way of knowing what your code looks like or what kind of crazy assumptions it makes - if we can't see all of it.

If you can't show all of it, then it's up to you to post the smallest amount of code possible that still does something meaningful by demonstrating the problem. A snippet that can be run by someone who wants to help you, but doesn't require your fellow scripter to start his own debug script from scratch. The only person that really benefits from this would be the samaritan scripter. I've had quite a few interactions with people who when asked to write a smaller script to demo the problem - suddenly figure out their own problem by narrowing down the issue.

Bottom line, if you want help with code: show code, not too much, not too little.

Q. Differences between Py2 and Py3
A. Mostly the print statement and try/except error handling syntax. [unfinished content on blog] most of the above links discuss python 2.x but Blender 2.6x uses python 3.x. If I only say one thing about python 2.x it is, always use the parenthesis version of print: print('print me') - you will thank yourself later.