The purpose of this lab time is to give you an introduction to the basic tools we will be using this semester. These tools include a terminal, a text editor, and the python interpreter.

Setup

1. Introduction to the Terminal
   
   Go through this terminal tutorial to get well-acquainted with the terminal interface. (It's okay to get stuck, just ask someone for help.)

   ---

2. Python Interactive Mode
   
   You can program in Python in two ways: by writing programs in separate files (script mode) and by typing commands in one at a time (interactive mode). Interactive mode is a great way to test out small bits of code you might be uncomfortable with. Let's try it out! Fire up the terminal and try this:

   $ python
   >>> 

   The ">>>" is called the chevron. Python allows you to enter lines of code. If the line results in a value, it prints that value out.

   >>> 3 + 55
   58
   >>> (4 - 2) * 6 - 7
   5
   >>> print 'Hello, World!'
   Hello, World!

   Some lines of code do not result in a value!

   >>> x = 55.1
   >>> 

   In this course we'll do lots of art-related things, so let's play around with drawing on the screen. First we'll need to import a bunch of things from the "turtle" package. This is easy to do:

   >>> from turtle import * 
   >>> 

   Now, to bring up a window with a turtle in the middle (okay, it's just an arrow, but pretend) use the following function call:

   >>> from turtle import * 
   >>> reset()
   >>> 

   Move the new window so that it doesn't overlap with your terminal. You'll want to watch what the turtle does as you enter each of the following function calls:

   >>> forward(100)
   >>> right(90)
   >>> forward(100)
   >>> left(90)
   >>> backward(10)
   >>> up()
   >>> backward(90)
   >>> down()
   >>> forward(20)
   >>> 

   Go turtle, go! You'll use these commands later on to draw your own shapes. Interactive mode will be a useful tool during the semester.

   ---

3. Introduction to the file servers
   
   A fileserver is a central file system you can access from any computer. It's like having a virtual USB key you can plug into a computer to store your files. They are backed up regularly so you won't suffer any data loss. Colby maintains several different fileservers we use in this course. Mounting the server sets up the connection so you can access it.
   
   To mount a server on Mac OS X, go to the Finder and either press Command+K or select 'Connect To Server...' from the Go menu. This will bring up a dialog box for you to choose the file server to use.
   
   There are two main servers we will use: files.colby.edu and filer.
   
   
   • files: type in the appropriate path:
     

     Mac 10.6 (CS Computer Lab):	smb://files.colby.edu/MACFiles
     Mac 10.7 and above:	smb://files.colby.edu/MyFiles

     
     and then click on the appropriate directories until you find your personal directory.
     
     
   • filer: smb://filer/personal/students/<first initial>/<username> (so I would type something like: smb://filer/personal/students/k/kgburke )
     
     
   This system is backed up up regularly, and you can access it from any computer on the Colby network. We strongly suggest you store all of your work for this course into your personal directory. You can, in fact, work directly from your personal directory. Let's practice doing that for the first project.
   
   Project Prep:
   
   
   1. Mount your personal directory as described above.
   2. Use the terminal to navigate there. I never remember the path to the file servers, but it doesn't matter. I just type cd, followed by a space:

      $ cd 

      Then drag the appropriate folder from the file server's window into the terminal using the mouse. My terminal then looks something like:

      $ cd /Volumes/personal/students/k/kgburke

   3. Now make a directory (in your personal folder) named Proj1. You can do this using the Finder, or you can type:
      
      $ mkdir Proj1

   ---

4. Introduction to the text editing
   
   Text editors are the workhorse programs for writing code. You don't want fancy fonts or WYSIWYG layouts, you just want to see lines of text, preferably with syntax highlighting, which means that special words in a language are highlighted to make it easer to read the code. There are many editors to choose from.
   
   In lab, I will be using TextWrangler. It is a free text editor for the Mac and it has all the features I need for writing programs. If you would like to install it on your personal computer, go to the TextWrangler website and follow their instructions.
   
   Project Prep:
   1. Open TextWrangler
   2. You will want line numbers. Click the weird light-switchy-boxy-thing in the upper-left corner of TextWrangler to access some preferences. Change the preferences to display line numbers. This will help later, when you encounter error messages that tell you where an error is by supplying the file's name and the line's number.
   3. We also need to tell it to "Auto-expand tabs". Python cares whether you use tabs or spaces. But just by looking at code, it is hard for you to tell whether you used tabs or spaces. So, let's tell the text editor to insert 4 spaces (instead of a tab) when you press the tab button.
   4. Create a new file (Cmd-N). Save it as smart.py in your Proj1 directory. (You can drag the file server's Proj1 directory over from the Finder window into TextWrangler's Save dialog box.)
   5. Put in the line:
      
      print 'You are smart.'
      
      
   6. Save the file (Cmd-S).
   7. Now, you can instruct Python to run the program. In the terminal type
      
      $ python smart.py
      
      Congratulations, you just ran your first python program! (python humor)
      
      Note that it works only if the current working directory is the one that contains the file smart.py. So, one thing you need to do when working on a project is to ensure that your Terminal is in the right directory. Think of it as making sure TextWrangler and Terminal agree about where the programs are. Note that, in general, you run Python programs by typing:
      
      $ python <filename>

   ---

5. Introduction to Python Scripts
   
   Python - a simple yet powerful interpreted language for making computers do stuff.
   
   A script, or program, is a file with a sequence of commands you can edit using a text editor. You've already written one simple script, soon you'll write a program with multiple lines! Let's start that right now. Create a new text file and save it in your Proj1 folder (on the file server) as simpleTurtle.py.
   
   Many people have written modules for python that do some sophisticated things. A module is a python file intended to be used in other scripts. One of those modules, turtle, implements turtle-based graphics (e.g. forward, left, right, pen down, and pen up). To import the turtle graphics module, use exact same line we used in interactive mode:
   
   from turtle import *
   
   Again, you'll want to bring up the window, so add this function call somewhere after the module importing:
   
   reset()
   
   If you save and run the program as it is, the window will appear and immediately disappear. That's because the window closes when the script completes. Add the following line to the end of your code to force it to wait for some input at the terminal before closing:
   
   raw_input('hit Enter to continue')
   
   Save your code, and make sure it works by running it from the terminal like we did before. We can add commands between the call to reset and that last line to draw with the turtle. As a reminder, those commands are:
   
   • forward(x) - move forward x pixels.
   • backward(x) - move backward x pixels.
   • left(a) - turn left a degrees.
   • right(a) - turn right a degrees.
   • up() - pick the pen up (don't draw when the turtle moves).
   • down() - put the pen down (do draw when the turtle moves).
   
   More complete documentation is available on the python documentation site
   
   Now, let's make the program do something. Add some calls to the forward and right functions so that your code looks like this:
   
   from turtle import *

reset()

forward(100)
right(90)
forward(100)
right(90)
forward(100)
right(90)
forward(100)
right(90)

raw_input('hit Enter to continue')
   
   (The extra line breaks are not necessary.)
   
   Run the above program to test it, then change it to draw a hexagon instead.
   
   

   ---

6. Introduction to the Wiki
   
   Colby Wiki - a Wiki is a convenient way to put content up on the web quickly and easily. We'll watch a video on how to create your personal space and then go through the process of creating a new page in your space. (Tutorial Videos)
   
   Log in to the wiki, but wait until Kyle says "Your turn" before clicking on the "Create your personal space" link. The system can't handle more than one space-creation at a time.
   
   For each project, you will create a new page in your wiki space. You can edit any page in your space by going to the Edit tab. There you will find one or two options for editing your page. The Rich-text option (available when using FireFox) lets you do the normal select and point and click type formatting. The wiki markup lets you use the wiki markup language to make your page.
   
   Project Prep:
   1. Make a page for Project 1. Go to the Add menu in the upper right corner, and select the Page option. Replace the "New Page" title with something meaningful, like "Kyle's CS151 Project 1" so that the page content is clear from the title.
   2. Now save your page. Even though it has no content, let's save it -- it is a good idea to save often. After saving your page, it will show up in the list of child pages on the bottom of your home page. You can link to it on your home page by editing the home page, pressing the link button (it looks like a chain) and searching your space for it. But it is also perfectly acceptable to simply leave it as a child page.
   3. In all of you project wiki pages, you will need to include pictures of the images you created with your program. Since this project is an introduction to writing Python turtle code, the first required picture is of the tools you need to write and run the code. And since you have already drawn a hexagon, let's include it. Get your screen set up: Run your simple_turtle.py program and leave the image up. Then make sure the terminal, the hexagon, and TextWrangler are all visible (and make sure TextWrangler has simple_turtle.py displayed). Take a picture of these three things by pressing Shift-Command-4. A cursor will pop up. Draw a box around the hexagon, TextWrangler, and the Terminal. The computer will take a picture of it and place that picture on your desktop. I have found that it is a good idea to make your picture as narrow as possible. Otherwise, it can be hard to view it on the wiki page.
   4. Now let's edit the content of the project 1 wiki page. Click on the link to it, then press Edit. Write a stub for your write-up saying "These are the tools we use." and place the image in the page (press the mountain button and upload the image from your Desktop).
   5. Label the page. The label field is a text field at the bottom of the page, and is different from the title of your page. Each assignment will specify a label, which we will use to find your pages so we can show off your work and so we can grade it. For this project, add the label cs151s14project1.
   6. Save it, sit back and think about how much you have already accomplished.
   For Your Information:
   
   If you ever need to remove a page, go to that page and select "Remove" from the "Tools" menu in the upper right.
   
   Remember to save your wiki page before navigating away from it. The wiki won't detect it and remind you.

   ---

7. How to turn in code
   
   You will turn in your code by putting it in a directory in the Courses server. On the Courses server, you should have access to a directory called CS151, and within that, a directory with your user name. Files that you put into that directory you can edit, read, and write, and the professor can edit, read, and write, but no one else. To hand in your code and other materials, you will create a new directory, such as project1, and then copy your code into the project directory for that week.
   
   As with the Personal server, there are two ways to mount the appropriate directory:
   • Option 1: Load the root server directory and navigate to your directory.
     
     You can mount the Colby fileserver root directory by going to the Finder and typing cmd-K, or selecting 'Connect To Server...' from the Go menu. It will bring up a dialog box, into which you want to enter the following.

     Mac 10.6 (CS Computer Lab):	smb://files.colby.edu/MACFiles
     Mac 10.7 and above (Lion/Mountain Lion):	smb://files.colby.edu/MyFiles
     Windows:	\\files.colby.edu\MyFiles

     
     Then click on the CS151 directory, and then your hand-in directory (it will have your username as its name).
   • Option 2: Mount your directory directly.
     
     You can mount your personal directory explicitly using the the following path in the 'Connect To Server...' dialog.
     
     smb://files.colby.edu/MACFiles/Courses/CS151/<username>/Private/
   
   
   Project Prep:
   
   Practice turning in your code by copying your entire Proj1 directory from your Personal server to the Courses server. The easiest way to do this is to drag and drop the folder from one Finder (one open to Personal) to another (one open to Courses).
   

Assignment

The purpose of this project is to give you chance to break down simple problems (such as drawing a chevron) into precise steps that solve the problem (draw the chevron). In computer science speak, you will be developing algorithms. In this case you will write your algorithms as sequences of Python turtle commands that make the turtle draw complicated shapes for you.

1. If you haven't already set yourself up for working on the project, then do so now.
   1. Mount your directory on the Personal server.
   2. Open the Terminal and navigate to your Proj1 directory on the Personal server.
   3. Open TextWrangler. If you want to look at any of the files you have already created, then open them.
2. Invent a shape, such as a cross, or an L or a simple chair. The next instruction is to write Python code to make the turtle draw the shape, so you will want to keep the shape fairly simple.
3. Create a file named shapeA.py in your Proj1 directory. It should follow the same basic format as simple_turtle.py, so make sure the first and last lines in shapeA.py are the same as the first and last lines in simple_turtle.py. Between those lines, put the turtle commands to draw the shape you just invented. Run the program:
   $ python shapeA.py
   and take a picture of the shape (i.e. Shift-Cmd-4). Include a picture of this shape in your write-up. This is required image 2 (the first is the one we took in lab).
4. Repeat your process for a second shape, putting its code in a file named shapeB.py. Include a picture of the new shape in your write-up. This is required image 3.
5. Make a new Python file called shapes.py. As the name implies, this file will have code that draws more than one shape. We will begin by putting the shapeA and shapeB code into it. We will then create a shapeC that is composed of shapes A and B.
   1. Create two functions shapeA and shapeB. A function is simply a collection of Python commands with a label, just like our lists above. For example, you can make a function that draws a triangle with the following code.
      
      def triangle():
    forward(100)
    left(120)
    forward(100)
    left(120)
    forward(100)
    left(120)
      
      Note how the commands that make up the function are all indented (the same amount) relative to the function definition. That is how you tell Python those commands are part of the function.
      
      Your shapeA and shapeB functions should draw the shapeA and shapeB shapes you defined in the prior step. You can copy and paste that code into the functions, tabbing appropriately.
   2. Add docstrings to your shapes. A docstring is a triple-quoted string that describes what the function does (but not how it does it). It should always be included directly after the function def line, and indented like the body of the function. Here a sample docstring added to triangle:

      def triangle():
          '''Draws an equilateral triangle with sides of length 100.'''
          forward(100)
          ...

      Add a docstring for each of shapeA and shapeB. For the rest of this course, you will be expected to have a docstring for each of your functions. A docstring helps other programmers understand what your code is supposed to do. It can also be used to create nice documentation for your code, which anyone can access from the command line. If I had my triangle function in shapes.py, I could do the following:

      $ pydoc shapes

      Then some information is displayed including the docstring definition of triangle. Press q to exit that window. The docstrings can also be used to create a new .html page for our file:

      $ pydoc -w shapes
      wrote shapes.html

      Use finder to browse to the directory to find the file and open it to see what it looks like! It should look something like this. (Except with definitions for shapeA and shapeB.)
   3. Invent a shape C that is composed of shapeA and shapeB. The code for shapeC will call the functions for shapeA and shapeB. You can call a function in Python by using the function name followed by parentheses. For example:
      
      

      def shapeC():
          '''Put a meaningful description of shapeC here!'''
          shapeA()
          forward(100)
          shapeB()
      
      shapeC()
      raw_input('Press Return to continue')

   4. At the end of your shapes.py file, put a call to the shapeC function, as in the example above, so that it will call the function when you run the shapes.py program. Note that the call to shapeC is not tabbed in and will therefore be executed by Python when you run your file as below. Recall that the role of the final line of code is to keep the turtle window open until you are ready to let it go away. It does so by preventing the program from ending without you pressing Enter.
   5. Test your code (i.e. run it by typing python shapes.py). If it doesn't work, then carefully read any error message. It should direct you to the line of the file that failed to work. Some common errors include:
      • Forgetting the colon at the end of a function definition line.
      • Forgetting to pair all parentheses. (Python really hates it when you have more left/open parentheses than right/close parentheses.)
      • Misspelling a turtle commmand or function name.
      • Having inconsistent tabbing. All code should be lined up carefully. The main code should have no spaces or tabs at the beginning of the line. The code "inside" the function definition should be tabbed in once, with all lines tabbed in the same amount.
6. We can add a docstring for the entire file by putting it at the top like this:

   '''This contains code to draw a triangle.
      Author: Kyle Burke.'''
   
   def triangle():
   ...

   Add a docstring comment for your file, then build the .html file again:

   $ pydoc -w shapes
   wrote shapes.html

   Open your new file in a web browser. It should look something like this.
7. The final task is to make your shape-drawing functions more flexible by enabling the caller to specify how many pixels forward to travel. For example, consider the triangle-drawing function above. Each triangle side is always 100 pixels long.
   
   But it would be better to have a triangle that could be drawn many different sizes. In other words, instead of using a raw number to indicate the forward distance, it would be better to have the distance be adjustable. In programming terminology, this means we would like to use a variable for the distance instead of a hard-coded number. You can create parameters for functions that allow you to pass information into a function. In the function definition, you put a list of variable names inside the parentheses. You can then use the parameter variables within the function.
   
   When you call a function with parameters, you put the value of the parameters in the parentheses. For example, the following code defines a triangle and then calls it with two different values.
   
   def triangle(sideLength):
    '''Draws a triangle with the given sideLength.'''
    forward(sideLength)
    left(120)
    forward(sideLength)
    left(120)
    forward(sideLength)
    left(120)

triangle(50)
triangle(100)
   
   1. Create a shapeD function that draws a (non-triangle) shape (like shapeA or shapeB) and uses one or more variables in the forward commands, just like the triangle function above.
   2. Then write a shapeE function that calls the shapeD function multiple times with different parameters. At the end of your file, make sure to put a call to shapeE.
   3. Test your code. Another common error you might experience is having a mismatch between the number of values passed in to a function when it is called and the number of parameters that function has (e.g. the triangle function needs 1 parameter, so both of these lines will cause errors:

      triangle()
      triangle(4, 3)

   4. Include a picture of the new shape in your write-up. This is required image 4.

Extensions

Each assignment will have a set of suggested extensions. The required tasks constitute about 85% of the assignment, and if you do only the required tasks and do them well you will earn a B+. To earn a higher grade, you need to undertake one or more extensions. The difficulty and quality of the extension or extensions will determine your final grade for the assignment. One complex extension, done well, or 2-3 simple extensions are typical.

The following are a few suggestions on things you can do as extensions to this assignment. You are free to choose other extensions.

• Create some additional functions that draw different shapes. Create a function that calls all of them to make an interesting graphic.
• Write a function that will draw an N-gon. It should take in the distance of a side and the number of sides.
• Figure out how to have a set of instructions repeat a certain number of times.
• Build a hierarchy of functions. For example, suppose you already have a function shapeG that draws one shape. Make a new function shapeH that calls function shapeG multiple times, but in different places, so that you get multiple shapes. Then make another function shapeJ that calls shapeH multiple times. Go up one more level of complexity.

Writeup and Hand-in

Turn in your code by putting it into your private directory on the Courses server. During lab you simulated turning in simple_turtle.py. Now, copy shapeA.py, shapeB.py, and shapes.py to your Proj1 directory on the Courses server. If you wrote additional Python files, you may turn them in as well. We will grade all files turned in, so please do not turn in old, non-working, versions of files.

Next, expand on the wiki page your began in lab. In general, your intended audience for your write-up is your peers not in the class. Your goal should be to be able to use it to explain to friends what you accomplished in this project and to give them a sense of how you did it. Follow the outline below.

• A brief summary of the task, in your own words. This should be no more than a few sentences. Give the reader context and identify the key purpose of the assignment.
• A description of your solution to the tasks, including any images you created. This should be a description of the form and functionality of your final code. For this project, you should also include a description of the programming process, and refer to your first image. You may want to incorporate code snippets in your description to point out relevant features. Note any unique computational solutions you developed. Code snippets should be small segments of code--usually less than a whole function--that demonstrate a particular concept. If you find yourself including more than 5-10 lines of code, it's probably not a snippet.
• A description of any extensions you undertook, including images demonstrating those extensions. If you added any modules, functions, or other design components, note their structure and the algorithms you used.
• A brief description (1-3 sentences) of what you learned.
• Double-check the label. In lab, you should have added the label cs151s14project1 to your wiki page. Make sure it is there.