Appendix D. Variable Scope

The rule of variable scope in Python is defined simply: a variable created inside a function exists only inside that function. This means that a variable created inside setup() can be used only within setup(), and likewise, a variable declared inside draw() can be used only inside draw(). The exception to this rule is a variable declared outside of setup() and draw(). These variables can be used in both setup() and draw() (or inside any other function that you create). We call these variables global variables, because they can be used anywhere within the program. We call a variable that is used only within a single function a local variable. Following are a couple of code examples that further explain the concept. First:

i = 12   # Assign value 12 to global variable i

def setup():
  size(480, 320)
  i = 24 # Assign value 24 to local variable i
  print i # Prints 24 to the console

def draw():
  print i # Prints 12 to the console

And second:

def setup():
  size(480, 320)
  i = 24 # Assign 24 to local variable i

def draw():
  print i # ERROR! The variable i is local to setup()

As you can see from the initial example, if you make an assignment to a variable inside a function that has the same name as a global variable, Python assumes that you wanted to create a new (local) variable with the same name. If you wanted instead to change the value of the global variable, you need to declare this variable as global at the beginning of the function using the global keyword:

i = 12   # Assign value 12 to global variable i

def setup():
  global i # "i" now means the global variable, not a new local
  size(480, 320)
  i = 24 # Assign value 24 to global variable i
  print i # Prints 24 to the console

def draw():
  print i # Prints 24 to the console

You need to use the global keyword for any kind of assignment, including the incrementation shortcut operator. Here’s an example to illustrate:

x = 0

def setup():
  size(200, 200)

def draw():
  background(0)
  stroke(255)
  x += 1
  ellipse(x, 100, 15, 15)

The preceding code gives an error when you try to run it (“local variable ‘x’ referenced before assignment”). That’s because we never told Python that we want x inside of the draw() function to refer to the global variable x. As a consequence, when we try to increment the value of x, Python doesn’t know what we mean, as we never created a variable with that name inside of draw()! We can fix the problem by adding global at the beginning of the function:

x = 0

def setup():
  size(200, 200)

def draw():
  global x
  background(0)
  stroke(255)
  x += 1
  ellipse(x, 100, 15, 15)

Note that the global keyword is needed only when you’re planning to overwrite the value assigned to a variable. You don’t need to use the global keyword when performing operations that merely change the object’s internal state. To illustrate, in the following example, you don’t need to use the global keyword, as the value of the variable x (i.e., the list) is not being overwritten. We’re merely calling a method on that object and assigning to one of its indexes. (The global keyword would be needed, however, if we wanted to create an entirely new list and assign it to the same variable x.)

x = []
def setup():
  size(600, 200)
  frameRate(5)

def draw():
  background(0)
  noStroke()
  x.append(random(width))
  fill(255, 16)
  for i in range(len(x) - 1):
    ellipse(x[i], height/2, 25, 25)
  fill(255)
  ellipse(x[-1], height/2, 25, 25)