Installation and Usage

This document describes the differences between the Ruby and Python scripting environments. It assumes that you have some familiarity with Python and with the Ruby API for scripting Sketchup.


To use SuPy, you need to put the following items from the 'plugins' folder of the SuPy distribution into your Sketchup plugins folder. (The location of the Sketchup plugins folder depends on which version of Sketchup you have. Consult the Ruby API documentation for your Sketchup version to find out where it is.)

python.bundle (for MacOSX) (for Windows)
python folder and its contents
supy folder and its contents
supyboot.rb file

Locations for Python Modules

The python folder is where you put your Python scripts. It's placed on the search path for Python modules, and furthermore, any files there whose names end in .py will be automatically imported when Sketchup starts.

The python folder contains another folder called lib that is also placed on the import path. If you have any files that you want to be able to import but don't want loaded automatically on startup, you should place them in there.

The Sketchup Environment as seen from Python

All of the Sketchup-related Ruby modules and classes are available in the Python builtin namespace, so you can use them from any Python file without having to import anything.

How Ruby objects look to Python

For the most part, you can use Ruby classes and objects in a Pythonic way as you would expect. There are a few things to keep in mind, however.

Parentheses on method calls

Remember that Ruby has no notion of accessing an attribute of an object from outside that object. Things that often look like attribute accesses in Ruby are actually method calls, and must be written that way in Python. For example,

model = Sketchup.active_model()  # Parentheses required!

There is one exception to this, and that's when calling a method whose name in Ruby ends in '='. SuPy lets you invoke this kind of method using an attribute assignment, e.g.

my_face.material = my_material  # invokes 'material='

Names ending in ? or !

Some Ruby methods have names ending in '?' or '!'. When calling these from Python, as long as there's no ambiguity, you can just leave off the punctuation, e.g.

my_face.reverse()  # invokes 'reverse!'

If there is more than one method with the same name but different punctuation, you can use the following translations.

Ruby Python
xxx? is_xxx()
xxx! xxx_ip()for "in-place"

Calling and Instantiation

Calling a Ruby object will invoke its call method if it has one, otherwise new. This lets you instantiate most Ruby classes just by calling them, as you would a Python class:

p = Point3d(1, 2, 3)

Constructors named something other than 'new' will need to be called explicitly, however.

Passing Blocks

A Ruby method that expects a block argument can be passed a callable Python object by using the keyword body. For example,

def print_ent(ent):
    print ent

ents = Sketchup.active_model().active_entities()
ents.each(body = print_ent)

The number of parameters passed to the Python function depends on what kind of value the Ruby method sends to it. If it sends a Ruby nil value, the function is called with no arguments. If it sends a Ruby list, the list is unpacked and passed as separate arguments. Any other kind of value is passed as a single argument.

Methods requiring Arrays

Python tuples are converted to Ruby arrays, so you can pass them directly to methods that require an array. If you want to pass any other kind of sequence (including a list) you will have to convert it using the Array() function, which works like its Ruby counterpart.


Be careful with boolean values! Only the Python values True and False are properly converted into Ruby booleans. Since Ruby regards almost everything as true, including zeros, empty strings and empty collections, this can easily get you into trouble. If in doubt, use bool() on values passed to Ruby methods expecting a boolean.

Unit Conversions

The Ruby trick of using things like 5.feet to convert units needs to be converted into a multiplication in Python, e.g. 5 * feet. Suitably-named conversion factors are available as builtins.

Parsing Lengths

There is a to_length() function that parses a string as a length and returns a number. It is equivalent to calling the to_l method of a Ruby number.

Implementing Tool Classes in Python

The modules tool and observer contain Python classes that you need to inherit from if you want to implement a custom tool class or an observer class, for example,
from tool import Tool
class MyTool(Tool):
    # Implement tool methods here

Calling Python from the Ruby Console

There's currently no direct way to enter a Python expression interactively, but you can access Python modules and their contents through the Ruby Console.

Firstly, there is a Ruby module called Py that contains all of the standard Python builtins, e.g. entering


into the Ruby Console will invoke the Python abs() function.

The Py module also contains all of the currently imported Python modules. For example, the file that comes with the SuPy distribution can be referenced using the Ruby expression


The example module defines a function called 'cylinder' which you can call as follows:

Py.example.cylinder(0, 0, 0, 10, 30)

Python files in the 'lib' subfolder are not automatically imported, but you can cause any Python file on the import path to be imported using a Ruby require command with a name  of the form 'python/modulename'. For example, if you have a file '' in the python/lib folder, you can import it using

require 'python/mystuff'

and then reference it as
Note that if you're importing a module from a package, the components of the module name should be separated with dots, not slashes, e.g.
require 'python/my_pkg.my_module'
Short expressions and statements can be evaluated using the methods Py.eval and Py.exec:
spams = Py.eval("3 * 'Spam!'")

Py.exec("print 42")
You can also use these features from any Ruby script to access Python functionality.

Reloading Python Files

If you make changes to your Python files, you can reload them without restarting Sketchup by entering the following command at the Ruby Console:


This will unload any modules imported from the python or python/lib folders and then reload any scripts in the
python folder.

You can also attempt to reload a specific module using the normal Python reload() function, i.e.


but this is risky, because other modules that have previously imported from the module being reloaded may not see the new definitions. It's safer to start with a clean slate and reload everything.

Preserving Data

Sometimes you may want to keep data in a module-level variable that won't get lost when the module is reloaded using Py.refresh. SuPy provides a builtin function keep() to facilitate this. You call it immediately after the module code that initialises the variables you want to keep, passing their names as arguments. For example,
my_cache = {} 
precious = []

keep('my_cache', 'precious')
When you call keep() with a particular name for the first time in a Sketchup session, its current value is stored away in a safe place. The next time you call it with that name, any value currently in the module under that name is replaced with the stored value.

The stored names are associated with the name of the module from which the keep() function is called, so that kept variables with the same names in different modules will not be confused.

Bear in mind that if you store any instances of your own classes this way, and you subsequently change the definition of those classes, the preserved objects will still be instances of the old classes, and won't see any of the changes. The same thing applies to any objects that manage to survive some other way.

If you want to re-initialise a kept variable, you can use the clear_keep() function to remove the stored value. You pass it the fully-qualified name of the module (as a string) and a series of variable names to be cleared. E.g. from the Ruby console,
Py.clear_keep 'my_module', 'precious'
You will then need to reload the module concerned to establish a new initial value.

Python Standard I/O

Python's standard output and standard error channels are connected to the Ruby Console.

There is currently no usable standard input for Python. If you try to read from standard input, your script will probably either hang or raise an exception.


There is an example script called in the python folder that illustrates how to add a menu item and execute some Sketchup operations in response to it.

There is also a package called more_examples containing some additional example scripts. To use these, either move them into the main python folder, or load them explicitly using

require 'python/more_examples.modulename'