One template for all scripts

Objectives

Entering individual commands in the interpreter or the console is tedious and error prone. Therefore it is better to save the instructions to a file and run that file in the interpreter. As a quick start we present and discuss a template.

Exercises

Tasks:

1. Open the editor in Blender, add a new file and copy the template.
2. Start customizing the template.
3. Replace the default name »Text« with a useful name. The name should have the extension »py«.
4. Activate one of the three functions and run the script.

Template for exercises

First of all we show the template as a whole. The same template is listed in the appendix, so if you need a new fresh file also have a look there sample code (snippets).

#!bpy
"""
Name: 'Template'
Blender: 2.69
Group: 'Sample'
Tooltip: 'Template for new scripts, copy it and start coding...'
"""
import bpy


def function_1():
    """ One line describing the task of this function  """
    pass


def function_2():
    """ One line describing the task of this function  """
    print(__name__)
    print(50 * '*')


def function_3():
    """ One line describing the task of this function  """
    bpy.ops.mesh.primitive_cone_add(location=(1, 2, 1))


if __name__ == '__main__':
    # call the function for testing
    function_1()
    #function_2()
    #function_3()

Comments and documentation

If you count the lines in the template (31) and the lines used as comments (10) you can see that documentation is important. If your code is not documented, it is broken!

Read the following tips for a good programming style:

• Filenames: use a name that describes what the file is used for. Just open the file if you want to see what it does.
• Comments are used to automatically generate the documentation of a project.
• You have a better understanding what other authors have written.
• With comments you can describe algorithms and use cases.

Two kinds of comments are possible:

'''
This one liner says all about a module (file) in one sentence.

After an empty line, more text as documentation is possible.
Instead triples of »'«, also »"« can be used.
'''

In our template the lines 2-7, 12, 17 and 23 are comments. In big projects often a style guide is used. Most of them follow the guidelines in PEP-0257 und PEP-0008.

http://www.python.org/peps/pep-0008.html

http://www.python.org/peps/pep-0257.html

The second type of comments starts with a hash or number sign (#). In our template lines 28, 30 and 31 are examples for these kinds of comments. Line 28 is a real comment. On lines 30 and 31 the code is commented out, which prevents its execution.

Functions

Functions group code together to help organize it. A function has a name by which it can be called to execute the containing code. Not every task can be completed in one line and a function with a good name can make code easier to understand by describing what a specific piece of code does.

Three functions are defined in the template, each starts with the keyword def followed by the name of the function.

After the name of the function a list of parameters in braces is possible, if left empty (like in our template), the definition of the function ends with a pair of empty braces. The colon at the end of the line starts a new code block - this is not only true for functions - all kinds of blocks can be started with a colon.

All following lines (but at least one line) are indented with four spaces. If you want to end the block (in this case the function) you do that by unindenting the code that should not be part of the block anymore.

With this cool indentation trick it is not necessary to use curly braces or other constructs to define code blocks.

Have a look to the lines 10 to 13:

def function_1():
    """ One line describing the task of this function  """
    pass

This function consists of two lines. The first is a so called »docstring« followed by the command pass. Because of the rule: every block needs at least one line, we use the keyword pass and it does what it should do: nothing, but the block building rule is satisfied.

Calling a function

A function is called by writing its name followed by a pair of braces like in line 29-31. The last two lines thought are commented out and won’t be executed. If you remove the number signs (#) at the beginning of the line, those functions will also be executed.

    function_1()
    #function_2()
    #function_3()

Function print

In the function named »function_2« we use the function print. The result is visible in a console.

    print(__name__)
    print(50 * '*')

The first print gives us the name of our script, the second returns fifty stars.

Two ways to use a script

Line number 27 contains a little bit of magic! In the if-statement we check the content of a variable named »__name__«. This variable is set automatically by the Python interpreter depending on how the file is run. Two values are possible:

1. the name of the file
2. the name »__main__«

If the value is »__main__«, all indented commands after the colon are executed - so the colon starts a new block here. If the value is different the commands in the block are not executed. With this trick you are able to run your file as a script that calls the functions directly and reuse the functions defined in your script from a different file by importing it.

Module specific functions

In the function »function_3«. we call a special Blender function. its name is »primitive_cone_add« and part of an object hierarchy. The path to the function is constructed with dots as delimiters. functions which are part of objects are called method. The method »primitive_cone_add« needs one parameter to place the result of the method call in our 3D-World. Have a look in the 3D Window after execution.

    bpy.ops.mesh.primitive_cone_add(location=(1, 2, 1))

Import modules

You can use elements from other files by importing them. This helps you to organize your code in several files and makes code reusable. This also gives you the possibility to use e.g. the function of Blender in your modules by importing them:

import bpy