choice(sequence)

Returns one random item from the sequence parameter (a tuple, list, or string). The choice() command is syntactic sugar for the comparatively awkward incantation:

sequence[random(len(sequence)]

files(pattern, case=True)

Retrieves the names of all files at a given path matching a wildcard pattern. By default a case-sensitive search is performed but this can be relaxed by passing False as the case parameter.

fonts(like=None, western=True)

Searches the fonts installed on the system and can filter the list in a few ways. When called with no arguments, the list contains all fonts on the system with a latin character set. To retrieve the set of non-latin fonts, pass False as the western parameter. To filter the list through a (case-insensitive) font name match, pass a substring as the like parameter.

romans = fonts() # Get a list of all the text-friendly families on the system
jenson = fonts(like="jenson") # returns ["Adobe Jenson Pro"]

eastern = fonts(western=False) # all asian-character fonts, math fonts, etc.
kozuka = fonts(western=False, like="koz") # the Kozuka Gothic & Mincho families

grid(cols, rows, colsize=1, rowsize=1)

The grid() command returns an iteratable object, something that can be traversed in a for-loop. You can think of it as being quite similar to the range() command. But rather than returning a series of ‘index’ values, grid() returns pairs of ‘row’ and ‘column’ positions.

The first two parameters define the number of columns and rows in the grid. The next two parameters are optional, and set the width and height of one cell in the grid. In each iteration through the for-loop, your counters are updated with the position of the next cell in the grid.

measure(grob)
measure(image="path", width=None, height=None)
measure("text", width=None, height=None, **fontstyle)

Returns width & height for graphics objects, strings, or images. If the first argument is a string, the size will reflect the current font() settings and will layout the text using the optional width and height arguments (as well as any keyword arguments supported by the text() command).

If called with an image keyword argument, PlotDevice will expect it to be the path to an image file and will return its pixel dimensions.

If called with a Bezier, returns its ‘bounding box’ dimensions.

a Point tuple with the object’s dimensions

ordered(list, *names, reverse=False)

Creates a sorted copy of a list of objects (similar to Python’s built-in sorted function). Lists of dictionaries or objects can be sorted based on a common key or attribute if any name strings are provided. If more than one name is present, they will be used (in order) as primary, secondary, tertiary, etc. sorting criteria.

Lists are returned in ascending order unless the reverse parameter is True.

a sorted copy of the original sequence

random(v1=None, v2=None)

Returns a random number that can be assigned to a variable or a parameter. The random() command is useful for all sorts of operations, from picking colors to setting pen widths.

When no parameters are supplied, returns a floating-point (decimal) number between 0.0 and 1.0 (inclusive). When one parameter is supplied, returns a number between 0 and this parameter. When two parameters are supplied, returns a number between the first and the second parameter.

Note that whether the boundaries are integers or floating point values is significant. See the example code for the differing behaviors that result.

New random values are returned each time the script runs. A particular sequence of random values can be locked-in by supplying a custom random seed:

from random import seed
seed(0)

read(path, format=None, encoding='utf-8', cols=None, dict=dict)

Returns the contents of a file located at path as a unicode string or format-dependent data type (with special handling for .json and .csv files).

The format will either be inferred from the file extension or can be set explicitly using the format arg. Text will be read using the specified encoding or default to UTF-8.

JSON files will be parsed and an appropriate collection type will be selected based on the top-level object defined in the file. The optional keyword argument dict can be set to adict or odict if you’d prefer not to use the standard Python dictionary when decoding pairs of {}’s.

CSV files will return a list of rows. By default each row will be an ordered list of column values. If the first line of the file defines column names, you can call read() with cols=True in which case each row will be a dictionary using those names as keys. If the file doesn’t define its own column names, you can pass a list of strings as the cols parameter.

a unicode string, list of rows (for CSV files), or Python collection object (for JSON)

lipsum = read('lorem.txt')
print lipsum[:11]        # lorem ipsum
print lipsum.split()[:3] # [u'Lorem', u'ipsum', u'dolor']

rows = read('related/months.csv', cols=True)
print rows[0]['english'], rows[0]['days'] # January 31
print rows[1]['french'] # Février
print rows[2]['german'] # März

oracle = read('8ball.json')
prognosis = choice(oracle.keys())
outcome = choice(oracle[prognosis])
print (prognosis, outcome) # (u'neutral', u'Better not tell you now')

data: lorem.txt, months.csv, and 8ball.json

shuffled(sequence)

Scrambles the order of a sequence without modifying the original. The sequence argument can be a list, tuple, or string and the return value will be of the same type.

var(name, type, default, min, max)

The variables sheet creates connections between a variable and a user interface control, such as a slider, textfield or check box. Variables created with the var() command become part of the global namespace, meaning you can access them just like any other variable.

The name parameter must be a string, but thereafter can be referred to as a plain variable (without quoting). The variable’s type must be NUMBER, TEXT, BOOLEAN, or BUTTON. Unless a default value is passed, the variable will be initialized to 50 for numbers, True for checkboxes, or ‘hello’ for text. The min and max set the range for number-type variables and default to the range 0–100.