Quick Reference

This page includes reference material with sections that cover all of the operators, functions, and methods you'll need in this class, as well as sections specific to the turtle, wavesynth, and optimism modules, and a section on other built-in modules we'll use. You can think of it like a pocket dictionary for the parts of the Python programming language that we'll cover in this class.

We recommend using the "find" feature of your browser to quickly jump to the function or concept you're looking for.

Operators

Right from the start of the class, we will be dealing with operators in Python, which work somewhat like the same operators you're familiar with from math, like '+' for addition, although while their use in mathematical formulae indicates some kind of relationship between values, in Python, they correspond to simplification steps for the computer to carry out. Python also deals with more than just numbers, and the same operator can have different behavior depending on the types of its operands.

The table below includes very brief reference explanations for every operator that we'll use in this class, along with tiny examples of how they can be used correctly (feel free to paste those examples into your Python shell to see what the results are and double-check your understanding).

import math
math.sin(math.pi)

nums = [1, 2, 3]
x = nums[0]

d = {1: 2, 3: 4}
x = d[3]

Built-in Functions

Besides operators, some of the most important building-blocks of Python programs are built-in functions. These represent important ways to convert or deduce information and a few of them, like print are going to appear in almost every program you write.

To use a function, we write the function name followed by parentheses. Any information that the function needs to work with is placed in the parentheses, separated by commas, these expressions are called the arguments of the function. This notation overall is called a "function call" and it looks like this:

len("hello")

In this example we've used the len function with "hello" as the argument, and the result will be the integer 5. When used as part of a larger program, if the function has a result (which most do) then we'd usually store that result in a variable, like this:

myString = "What a lovely day!"
howLong = len(myString)

Here we also used a variable as the input, rather than a fixed value. You could also use a function as part of a larger expression: the place where you write the function call will eventually be simplified to the result value from that function call. Here's an example of a program that uses several built-in functions:

x = 5
y = 4
z = 10

print(max(x, y, z) + min(x, y, z))

The last expression simplifies as follows:

print(max(x, y, z) + min(x, y, z))
print(max(5, y, z) + min(x, y, z)) # variable substitution for x
print(max(5, 4, z) + min(x, y, z)) # variable substitution for y
print(max(5, 4, 10) + min(x, y, z)) # variable substitution for z
print(10 + min(x, y, z)) # max function result
print(10 + min(5, y, z)) # variable substitution for x
print(10 + min(5, 4, z)) # variable substitution for y
print(10 + min(5, 4, 10)) # variable substitution for z
print(10 + 4) # min function result
print(14) # + operator
None # print function result; this result won't show up

Note that as a side effect of this simplification, the text "14" will be printed.

The table below includes brief explanations for the built-in functions that we'll use in this class, along with tiny examples of how they can be used correctly (feel free to paste those examples into your Python shell to see what the results are and double-check your understanding). Remember you can always use the help function to get more information about another function.

x = 17
dir(x)

print('to', end='')
print('gether')

digits = '123'
num = int(digits)

for item in reversed(stuff):
    print(item)

r = open('f.txt', 'r')
contents = r.read()
r.close()

with open('o.txt', 'w') as w:
    w.write('hello\n')
# closed automatically when
# with block ends

Common Methods

In addition to Python's built-in functions, Python's basic types like strings, lists, and dictionaries have more functions attached to them as "methods" that you'll need to learn about. A "method" is just a function that's attached to a type; to call it we write a specific value of that type (maybe as a variable) and then a period, followed by the method name and any additional arguments. The value before the period always serves as an implicit first argument to the method call. This is what that looks like:

response = input("Do you like ice cream? ")
lowercase = response.lower()
affirmative = lowercase.startswith('y')

Here we used two methods of strings: lower and startswith. The lower method doesn't need any additional arguments beyond the value that it's attached to (but the parentheses are still required to actually call the method), while the startswith method needs one additional argument (which we put inside the parentheses after the method name, just like when we call a regular function). In both cases, the thing before the period (response or lowercase) is functioning like an extra argument to the method (e.g., what are we getting a lowercase version of? The response value).

Why are some functions just built-in and others methods of a particular type? That's because when a function can only work with a specific type of data, making it a method helps prevent errors, because you can't accidentally try to use it with another kind of value. It also helps organize things conceptually. For example, len is a built-in function because it can work with any type of sequence, including strings, lists, etc. On the other hand, lower is a method, because it only makes sense in the context of strings.

The table below includes brief reference explanations for the common methods that we'll use in this class, along with tiny examples of how they can be used correctly (feel free to paste those examples into your Python shell to see what the results are and double-check your understanding). Remember you can always use the help function to get more information about another function; in the case of methods, you could write something like help(str.lower) or help(list.append) because you still need to reference a particular type to get access to a method.

r = input('Ok? [y/n] ')
n = r.lower()

nums = [1, 2]
nums.append(3)

nums = [5, 6]
nums.insert(0, 4)

nums = [1, 2, 3]
last = nums.pop()
first = nums.pop(0)

nums = [1]
nums.extend([2, 3])

nums = [4, 5, 6, 5]
where = nums.index(5)

nums = [1, 2, 3, 2]
nums.remove(2)

l = [3, 2, 4, 1, 5]
l.sort()
print(l)

l = ['cat', 'bat', 'cart']
l.sort()
print(l)

def minus(n):
    return -n

l = [1, 2, 3]
l.sort(key=minus)
print(l)

data = {'a': 1, 'b': 2}
print(data.keys())

data = {'a': 1, 'b': 2}
print(data.values())

data = {'a': 1, 'b': 2}
print(data.items())

data = {'a': 1, 'b': 2}
print(data.get('a'))
print(data.get('c', 'nope'))

data = {'a': 1, 'b': 2}
print(data.pop('a'))

old = {'a': 1, 'b': 2}
new = {'b': 3, 'c': 4}
old.update(new)

with open('f.txt', 'w') as w:
    w.write('hello\ngoodbye\n')

r = open('f.txt', 'r')
text = r.read()
r.close()

Built-in Modules

Besides the turtle/turtleBeads, wavesynth, and optimism modules, for graphics, audio, and testing, there are a huge array of built-in modules in Python, and there are even more available online. In this reference page we only cover a few functions from a couple of built-in modules that we'll use in this class. You can think of these built-in modules as ways to extend the built-in functions that are available.

To use functions or values from a built-in module you will need to import that module (although because it's a built-in module, you won't have to worry about where the code file for that module is). The simplest form is like this:

import math

After that import, you can use functions or values from the math module by writing math. before their name. If you'd like to use those functions or variables directly, you can instead import what you need using from, like this:

from math import ceil, pi

You can list whatever functions or values you want to import, separated by commas, and each of those will become available in the current file, using just its name (e.g, pi instead of math.pi). There's one more way to import things:

from math import *

The * here stands for "everything" and it makes all of the functions and variables from that module available in the current file without the need to write math. every time. Why don't we just always use this version? Sometimes it's nice to have your code show where each value is coming from, so that someone reading it doesn't get confused (e.g., did the 'ceil' function come from a module, or was it defined here?). This gets especially important if you end up importing multiple modules, since there would be no way for someone to look up where a function came from without looking through each imported module to find it. So we generally stick to the first form of import except in cases where we'll be using a lot of different names from a module very frequently, like with turtle, turtleBeads, and wavesynth.

The table below includes brief reference explanations for a few functions and/or values from several built-in modules that we'll use in this class, along with tiny examples of how they can be used correctly (feel free to paste those examples into your Python shell to see what the results are and double-check your understanding). Remember you can always use the help function to get more information about a function or module, and you can also use dir to list the contents of a module.

with open('d.json', 'r') as fR:
    o = json.load(fR)

d = [1, 2, 3]
with open('d.json', 'w') as fW:
    json.dump(d, fW)

import csv
with open('d.csv', 'r', newline='') as fR:
    dR = csv.DictReader(fR)
    d = list(dR)

import csv
cols=['A', 'B']
with open('d.csv', 'w', newline='') as fW:
    dW = csv.DictWriter(fW, cols)
    dW.writeheader()
    dW.writeRow({'A': 'hi', 'B': 'bye'})
    dW.writeRow({'A': 'open', 'B': 'close'})

Turtle Reference

The turtle built-in module is used for drawing graphics in Python. turtleBeads.py is a custom module that adds a few commands to easily draw certain shapes centered on the current turtle position, like circles, ellipses, and polygons. This page covers the core commands from both modules and briefly describes how to use them. If you need more details, remember that you can get help for any Python function by calling the built-in help function, for example, you could get help for the turtle penup command by running:

help(penup)

You can download the latest version of turtleBeads.py at this link:

turtleBeads.py

The colors page has pictures showing all of the color names you can use with turtle.

Getting Started

To draw with turtle graphics, you will need to import the built-in turtle module. To do this, add a line of code at the top of your file that looks like this:

from turtle import *

The '*' here means "everything," and this style of import makes the functions in the turtle module directly available.

If you also want to use turtleBeads functions, you should add:

from turtleBeads import *

to the top of your file as well. Make sure the turtleBeads.py file is in the same directory as the file that you are writing your code in, otherwise Python won't be able to import it and you will get an error.

begin_fill()
fd(100)
lt(90)
fd(100)
end_fill()

t = towards(30, 40)
seth(t)

dist = distance(50, 50)
angle = towards(50, 50)
seth(angle)
fd(distance)

fd(20)
stamp()
fd(20)

speed(3)
circle(110)
noTrace()
circle(100)
showPicture()
doTrace()
circle(90)

Wavesynth Reference

For producing (cheesy) synthesized sounds, we've written a wavesynth module that can be used to build simple music out of notes and beats. The selection of instruments and their quality is extremely limited, but it allows us to make music as an alternative to drawing things with the turtle module.

You can download the latest version of wavesynth.py at this link:

wavesynth.py

An Example

(Keyboard image from p. 49 of PIANO KEYS AND NOTES: The Definitive Guide, downloadable from https://www.musilio.com/)

The following code demonstrates a few of the wavesynth functions, which are explained below. The above piano keyboard image is provided for reference.

from wavesynth import *

addNote(0.25) # Add note at default pitch lasting 1/4 of a second.
              # wavesynth's default pitch is "middle C" (C4), which 
              # is the middle C note (a white key) on a piano keyboard.
climbUp(1) # Move current pitch up to next note in default scale.
           # wavesynth's default scale is C major, which includes only
           # the white keys on the piano. The next note above C4 is D4, 
           # the white key directly to the right of the middle C key. 
addNote(0.25)
climbUp(1) # Move up to next note in C major scale = E4.
addNote(0.25)
climbUp(1) # Move up to next note in C major scale = F4.
addNote(0.25)
climbUp(1) # Move up to next note in C major scale = G4.
addNote(0.25)
climbDown(4) # Move back to original note (C4) 
addNote(0.25)

setTime(0) # Reset time to beginning of song to add drum track 
           # that will be played together with above notes.
quieter(4) # Make following beats quieter than the notes.
addBeat(0.25) # Add beat lasting 1/4 of a second from default drum.
              # wavesynth's default drum is a snare drum. 
addRest(0.25) # Add 1/4 of a second of silence before next drum beat .
addBeat(0.25)
addRest(0.25)
addBeat(0.25)

printTrack() # Display a printed representation of the song's notes and beats.
saveTrack('example.wav') # Save song into an audio file named 'example.wav'.
                         # You can play this audio file using a music app.
playTrack() # simpleaudio package needs to be installed in Python
            # in order to hear the above song played. 
            # This plays the same song as stored in 'example.wav',
            # but does not require it to be stored in a file. 

Note that in order for wavesynth.py to play sounds directly from within Python, you'll need to use the "Manage Packages" feature in the "Tools" menu in Thonny to install the "simpleaudio" package, although you can use wavesynth.py without this feature to produce .wav files that you can use a separate media player program to play back.

Music Concepts

To use this module you will need a basic grasp of some musical concepts, although you will not need to be familiar with music theory or know how to play an instrument. The basic concepts you'll need are:

1. Notes vs. beats vs. rests. A note is a sound that can be higher or lower, like the sound of a piano or the sound of whistling. A beat is a sound that can't be higher or lower, like the sound of a drum or a clap. A rest is just a period of silence. The addNote, addBeat, and addRest functions are used to create these kinds of sounds, and each function requires a duration as the parameter to specify how long the sound lasts. Other aspects of the sound, like how high or low it is (if it's a note) or what instrument it sounds like (for notes and beats) are remembered automatically from sound to sound, and can be changed using specific functions that change them.
2. Time. wavesynth measures time in seconds, and it keeps track of the "current time" behind the scenes. Every note that you create starts at the current time, and when you create a note, beat, or rest, the current time is advanced to the end of that sound, so that calling addNote repeatedly will add notes that follow each other directly in time. If you want to have notes (or beats) that overlap each other, you can use the rewind or fastforward functions to subtract from or add to the current time.
3. Volume. Notes and beats can be louder or quieter, with some limitations. wavesynth keeps track of the "current volume" and this is used for any notes and beats created; it can be changed using the setVolume, louder, and quieter functions.

4. Pitch. Unlike beats and rests, notes can sound "higher" or "lower." "Pitch" refers to how high or low a note is, and we make musical melodies by sequencing notes of different pitches. In between notes, wavesynth remembers the current pitch, and to control the pitches of notes we call pitch-changing functions before calling addNote. There are two ways to change pitch in wavesynth:

   • A "half-step" is the smallest change in pitch that the wavesynth module can easily create, and there are halfStepUp and halfStepDown functions for setting the pitch higher or lower by some number of half steps. Half steps are used as part of the basis for classical music, and there are 12 half-steps in an "octave," and about 4-5 octaves between the highest and lowest notes humans usually sing.

     On a piano keyboard, a half step up corresponds to the next key (white or black) to the right on the keyboard (see image below). E.g., a half step up from the white C key is the black key known both as "C sharp (C#)" and "D flat (Db)". A half step up from that black key is the white D key. In some cases, a half step up goes from one white key to another (e.g., F is a half step up from E, C is a half step up from B). The "12 half steps in an octave" corresponds to the 12 keys (7 white and 5 black) in the keyboard image.

     

     (Keyboard image from p. 44 of PIANO KEYS AND NOTES: The Definitive Guide, downloadable from https://www.musilio.com/)

   • The climbUp and climbDown functions change pitch according to a "scale" which is a pre-selected sequence of pitches. You can change the current scale using either setFundamental to set the base note of the scale, or setScaleType to change what type of scale it is. You don't need to use these functions, but they can help you control things if you know a bit about music. The default scale is "C Major" which corresponds to a fundamental note of "C" with a scale type of "Major". If you're having trouble finding pitches that sound good together, one thing to try to is to change the scale type to "Pentatonic-Major" by using: setScaleType("Pentatonic-Major"). Pentatonic scales have only 6 notes in an octave, and most pairings of pentatonic notes sound good.

   wavesynth also defines some variables representing specific pitches (see the pitch details section for details), and you can use setPitch with these values to set the current pitch regardless of its previous value.

wavesynth functions

What follows is a summary of each of the most important wavesynth functions that you'll need to use, including a brief description of what the function does and examples of how it could be used.

Note that the simplest way to get access to these functions is to use the following import statement (assuming that wavesynth.py is in the same directory as the file you're working on):

from wavesynth import *

setTime(1)
addRest(2)

setDrum('kick')
setVolume(0.8)
addBeat(0.2)

setInstrument('keyboard')
setPitch(C4)
addNote(0.2)

name = pitchName(440)
# will be 'A3'

setPitch(D4)
halfStepUp()
# pitch will now be Eb4

setPitch(D4)
climbUp()
# pitch will now be E4

setPitch(currentFundamental())
climbUp(24) # 3 octaves
addNote(1)

setFundamental('Ab')
setScaleType('Minor-Natural')

setFundamental('Fs')
setScaleType('Major')

addNote(0.5)
setUp(3)
rewind(0.5)
addNote(0.5)

Pitch Details

In addition to moving pitches up and down, we'll sometimes ask you to use specific pitches, and there are two systems that wavesynth provides for this. Scientific pitch notation is a classical pitch system which labels each of the eight steps in an octave using the letters "A" through "G", and then pairs those letters with a number indicating which octave the note is in. So for example, the note B3 is one octave below (i.e. 8 whole steps below, or 1/2 the frequency of) the note B4. Similarly, G4 is 3 steps above D4. The confusing thing about this system is that each octave starts on a C, not an A, so B3 is only one step below C4, which is the first note in octave 4. The wavesynth module makes global variables named for all of the pitches C0 through B9 available. In addition to these variables, there is a set of variables named P0 through P14 which refers to successively higher notes on a pentatonic scale. These have the same values as some of the scientific pitch notation notes, they're just alternate names for them, but they can be used instead for a simpler way of naming higher and lower notes, with larger pitch differences between those notes. For reference, P5 is equal to C4, and that tone is a reasonable "middle" tone that's neither very high nor very low. If you happen to be familiar with musical notation, or if you've seen sheet music and wondered about how it works, here is an image of how these different pitch values map to sheet music notation:

More details about pitches: in fact, the number that represents a pitch tells us how many times per second that sound vibrates the air: "higher" pitches are produced by faster vibrations (meaning more tiny pulses of high-pressure air per second) while "lower" pitches have slower vibrations. The range of frequencies that's comfortable goes from something like 20-30 pulses-per-second on the very low end, all the way up to something like 10,000-20,000 pulses-per-second on the high end, and the range is so large in part because pitch is multiplicative, not additive. In other words, when we go "up" a certain amount in terms of pitch, we're multiplying the frequency of the note, not adding to it. Going up by the same amount again and again represents successive multiplications, which is why there's such a large range of values. Pitches are stored using floating-point numbers (or rarely, integers), and you won't have to do any of the math yourself because of the functions like climbUp or halfStepDown that the wavesynth module provides.

Testing with optimism

The optimism.py module that we provide allows you to easily set up tests for your code, and check their results. It also a trace, expect, and expectType functions which can be useful for debugging. This section provides a brief overview of the functions in that module and how to use them.

You can download the latest version of optimism.py at this link:

optimism.py

Getting Started

To use the module, you will need to import it, like this:

from optimism import *

There are three steps for testing:

1. Create a test manager for the function or file you want to test.
2. Create one or more test cases using the manager. At this step you can specify arguments to a function or inputs that should be provided during the test.
3. Check the results and/or output of your test cases. Here is where you specify what the correct results are.

For step 1, you'll create a TestManager object using testFunction or testFile, which you should store in a variable. That will look like:

def f(a, b):
    print(a * b)
    return a

manager = testFunction(f)

For step 2, you'll use the TestManager.case method to establish one or more test cases. When you create a case for testing a function, you specify the arguments to use. Adding to our previous example, you would now have:

def f(a, b):
    print(a * b)
    return a

manager = testFunction(f)
case1 = manager.case(1, 2)
case2 = manager.case('ha', 3)

For the last step, you can use TestCase.checkResult and/or TestCase.checkOutputLines to check that the result of each test case is what you expect. A complete example would be:

def f(a, b):
    print(a * b)
    return a

manager = testFunction(f)

case1 = manager.case(1, 2)
case1.checkOutputLines('2')
case1.checkResult(1)

case2 = manager.case('ha', 3)
case2.checkOutputLines('hahaha')
case2.checkResult('ha')

If you need to test a program or function that uses the input function to accept user input, you can call the TestCase.provideInputs function to specify what inputs should be provided during a test case.

If your checks don't succeed, the trace, expect, and/or expectType function can be helpful in figuring out more about why.

• trace works a bit like print, but also returns the result it displays, so you can use it in the middle of an expression.
• expect takes two arguments and checks that they're the same. It prints a message indicating success or failure. You can use it to double-check how your program works.
• expectType works like expect, but just checks that a value has a certain type. It can be useful to verify your assumptions about how things work.

An example that uses trace, expect, and expectType:

import optimism as opt

# Tracing
x = opt.trace(1 + 2) * 4
opt.trace(x)

# Correct expectations
opt.expect(x, 12)
opt.expectType(x, int)

# Incorrect expectations
opt.expect(x, 'hi')
opt.expectType(x, str)

This will result in the following output:

4 1 + 2 ⇒ 3
5 x ⇒ 12
✓ t.py:8
✓ t.py:9
✗ t.py:12
  Result:
    12
  was NOT equivalent to the expected value:
    'hi'
  Test expression was:
    x
  Values were:
    x = 12
✗ t.py:13
  The result type (<class 'int'>) was NOT a kind of <class 'str'>.
  Test expression was:
    x
  Values were:
    x = 12

The first two lines are from trace, and they show the line number, the expression used, and then the result of that expression. After that, two lines indicate that our first two expectations were met, and then several more lines show details about the failed expectations.

x = trace(1 + 2)
y = trace(x + 3)
trace(y)

x = 5
y = 2
expect(x + y, 8)

x = 5
y = 2
expect(x + y, str)

def f(a, b):
    return a + b

m = testFunction(f)
c = m.case(1, 2)
c.checkReturnValue(3)

def f(x):
    print(x)
    print(2 * x)

m = testFunction(f)
c = m.case('hi')
c.checkPrintedLines('hi', 'hihi')

def f(c):
    a = input('A? ')
    b = input('B? ')
    print(a, b, c)

m = testFunction(f)
c = m.case('z')
c.provideInputs('x', 'y')
c.checkPrintedLines(
  'A? x',
  'B? y',
  'x y z'
)

def f(x):
    return x + 3

m = testFunction(f)
c = m.case(2)
c.checkReturnValue(5)

def f():
    print('hi')
    print('bye')

m = testFunction(f)
c = m.case()
c.checkPrintedLines('hi', 'bye')

def f():
    print('a\nb\nc')

m = testFunction(f)
m.case().checkPrintedLines('a', 'b', 'c')

def f():
    print('hi')

m = testFunction(f)
showOutput()
c = m.case()
c.checkPrintedLines('hi')

def f(x):
    return x + 1

m = testFunction(f)
m.case(1).checkReturnValue(2)
m.case(2).checkReturnValue(3)
m.case(2).checkReturnValue(100)
showSummary()