There are activities in this walk-through which count towards your L01 and H01 grades this week, so pay very close attention!
Part 1: Overview
Becoming a Modern programmer
Programming is more than just writing code and solving problems. Modern programming is a collaborative activity. For instance, so many people contribute code to the Linux kernel, the number of contributors is too high to count! This is why one of the learning objectives of this course is to:
"Understand how to code in teams, collaborate with others and manage source code."
To do that we need to learn and use the same tools and techniques that actual programmers use. It’s going to steepen our learning curve a bit, but trust us when we say it’s worth it!
Remember. Today’s programmers:
- Use the command line to operate their computer.
- Use git (or some other source code manager) manage their code.
- Write code that is easily understood by others
- Can explain their code to others (including non-programmers)
You’ll do each of these, many times throughout this course. You’ll start some of them RIGHT NOW!
Goals of this walk-through
The goal of this exercise is to get you acquainted with the process of “how we will code” in this class. It DOES NOT focus at all on programming itself. In fact all the code will be written for you. Instead we will focus on the PROCESS of coding.
We will cover the tools you will use throughout the course such as the command line, git, GitHub, and Jupyter Notebook to write our programs, execute them, then commit your work so your others can view it.
Upon the completion of this walk-through you should be able to:
- Locate your Learn-Python code repository on your computer and open the command line in the repository folder.
- Start and stop Python’s Jupyter Notebook environment.
- Write and execute a simple Python program in the Jupyter Notebook environment.
gitto commit your code changes and push them over the Internet to GitHub.
gitto undo changes you’ve made to code.
- View your code changes locally and on the GitHub website.
After you complete this walk-through you should have a good idea how to work on your code in-class and save your work to GitHub.
Before You Begin
Before you complete this walk-through you should need to make sure you’ve completed the course setup checklist. You cannot complete this walk-through without it! If for some reason you’ve haven’t completed the course setup checklist (ahem… shame on you!) then you should do so NOW.
NOTE: You cannot complete the lab or homework without first following the course setup checklist to set up your laptop.
Part 2: The Programming Process [L01]
In this part we will guide you through the programming process step-by-step. When you are finished with the process you will have completed your first lab, L01, and handed it in to Github for a grade!
In this walk-through we will simulate your typical workflow when working on labs, recitations, or homework assignments in this course. Specifically we will:
- Open the command line in our Learn-Python git repository
- Open, Edit, and Execute a Python program using Jupyter Notebook
- Save our code changes to git, then push them to GitHub
- View our saved code locally and on the GitHub website.
Step 2.1: Opening the command line in your Learn-Python git repository.
If you followed the course setup checklist, you will have cloned your Learn-Python git repository from GitHub to the Documents folder on your computer.
Before you start ANY coding activity, whether its a Coding Lab, Recitation, Homework, or one of the examples during lecture, first you’ll need to open the command line from inside the repository.
YOU NEED TO KNOW HOW TO DO THIS IN YOUR SLEEP WITH HANDS TIED BEHIND YOUR BACK.
There’s excellent instructions for how to do this on our course FAQ: How do I open the command line in my Learn-Python git repository folder? as well as some videos for Mac OSX and Windows.
Follow them at this time and don’t continue until you have completed the steps and you’re at the command line:
You can verify you’re in the right place by typing the following at the command prompt:
This tells you the status of your repository. The output should look similar to this:
If it says Not a git repository then you’re not in the correct folder!
git statusis your friend. It tells you 3 important things:
- On branch master tells you this folder is a git repository and you’re on the master branch. Git allows us to branch our code by name and go off on programming “tangents”. Right now we’ll live in a single branch, master.
- Your branch is up-to-date with ‘origin/master’ lets you know that the code on your computer matches the code on GitHub.
- nothing to commit, working tree clean informs you that you’ve made no changes to the code on your computer.
Step 2.2: Open, Edit, and Execute a Python program using Jupyter Notebook
One of the tools we will use to program in Python is called Jupyter Notebook. This is the preferred development environment of Scientists, Data Analysts, and of course Data Scientists. The notebook environment is beneficial to these disciplines because you can combine instructions with code and intermix visualizations such as tables, map and graphs. Jupyter runs as a mini web server on your computer and therefore to view, execute and edit your code you’ll need to use a web browser.
- Let’s start the Jupyter Notebook service. At your command prompt, type:
After you type this command, you’ll see messages on the console, similar to this:
The last two messages are the most important. The second to last line tells you the notebook is running and provides the website for you (in this case it’s http://localhost:8888) The last line provides instructions for shutting down the notebook.
- Jupyter Notebook will automatically open up in your default browser.
We strongly recommend using Chrome or Firefox as your computer’s default web browser in place of Edge (Internet Explorer) or Safari.
- Next, we have to navigate to our code. We’re in Lesson 01, so we have to find that folder:
- Double-click on the content folder.
- Double-click on the lessons folder.
- Double-click on the 01 folder.
- You should now see the folders pertinent to this lesson:
NOTE: There are typically 4 folders per lesson, defined as follows:
- Watch-Me-Code This folder contains the code demos as part of lecture day.
- End-To-End-Example This folder contains the end to end examples as part of lecture day.
- Class-Coding-Lab This folder contains the class coding lab and supporting files.
- Now-You-Code This folder contains the homework exercises. One will be worked on during recitation, the other must be finished by the end of the week.
- The code we will write is in the Class-Coding-Lab folder. Double-click on that folder. You should see the file:
Files ending with .ipynb are Jupyter Notebook files.
- Double-click on CCL-walkthrough.ipynb to open the notebook file. Notice this opens a new Tab in your browser window:
- Let’s write some code! Click on empty cell beneath the text. It should now be outlined in GREEN. Type the following code in the cell:
print("Hello, Python!")your screen should look like this:
- To execute the code from the current cell, press Shift+Enter or press the play button beneath the menu item named “Cell”. The code in the cell will execute, and underneath it you will see the output:
Jupyter then places you in a new cell where you can write additional code.
NOTE: There are also menu and button options for running code in a cell that you can find by exploring…
- The next thing to understand about the Jupyter notebook is that it uses a modal editing system. This means that the effect of typing at the keyboard depends on which mode you are in. The two modes are:
- Edit mode: Indicated by a green border around one cell. Whatever you type appears as is in that cell. This is how you code.
- Command mode: The green border is replaced by a Blue and grey border. Key strokes are interpreted as commands — for example, typing
ltoggles line numbers.
- To switch to command mode from edit mode, hit the Esc keyboard
- To switch to edit mode from command mode, hit Enter or click in a cell
The modal behavior of the Jupyter notebook is a little tricky at first but very efficient when you get used to it. In this screenshot, I’ve toggle line numbers on for cell with code in it:
PRO TIP: Need a list of commands? Open the command pallette from the toolbar. It lists all the available commands! What key do you press to save the notebook? Press it now!
- Let’s finish with some sample code which really shows off the power of Jupyter notebook. This code, taken from http://matplotlib.org/1.4.1/examples/pie_and_polar_charts/polar_bar_demo.html will generate a polar chart of random data. Copy and paste the following code into the cell beneath your Hello, Python! program:
%matplotlib inline import numpy as np import matplotlib.pyplot as plt N = 20 theta = np.linspace(0.0, 2 * np.pi, N, endpoint=False) radii = 10 * np.random.rand(N) width = np.pi / 4 * np.random.rand(N) ax = plt.subplot(111, polar=True) bars = ax.bar(theta, radii, width=width, bottom=0.0) for r, bar in zip(radii, bars): bar.set_facecolor(plt.cm.jet(r / 10.)) bar.set_alpha(0.5) plt.show()
Don’t worry about what this code is doing right now. You’ll learn to understand it in time!
When you paste and execute the code you should see this:
NOTE: The chart will be different each time it runs as its based on random data.
We’re done with Jupyter, so how do we save and close out?
- Save your work. Enter command mode and press
- Exit the notebook page. From the Jupyter menu select File then Close and Halt:
NOTE: It is important to exit the notebook this way or else it will continue to execute in the background.
- Close the browser window.
- Back in the command prompt window, press CTRL+C TWO TIMES to Halt Jupyter Notebook.
- You are now back at the command prompt.
Step 2.3: Save our code changes to git, then push them to GitHub
During this walk-through we’ve made changes to the file: CCL-1st.ipynb. Those files are saved on our computer, but how do we record the changes we’ve made using git and then push those changes up to the GitHub website? We’ll walk-through this process next.
- We’ve made some changes, let’s see what git has to say about them.
to check the state of our repository. The output should look something like this:
Git tells us we have changes which are not staged for commit. This means we’ve made changes and git doesn’t know about them yet.
- You must tell git which changes to files you want to commit. This is called staging the commit.
Let’s tell git to stage all the changed files in the repository folder.
git add --all
99% of the time this is what we want.
NOTE: After you stage the files for commit, you might see some warning message, especially on Windows, about CRLF. This has to do with how the Windows platforms handle end-of-line characters in text in contrast to other platforms, like OSX or Linux. These can be ignored as git safely handles this for you.
- Let’s check the status of the repository now that we’ve staged our files.
again to see what’s happening in our repository.
Now git tells us the two files we’ve changed are now ready to be committed.
- Let’s commit the changes to git. What does this mean exactly?
Git Commit Explained: When you commit files, you’re saving the history of them to git repository. It’s like taking a snapshot of your repository folders’ contents at that point in time. Because you have this snapshot you are able to revert the files back to this point whenever you desire. As you can imagine, this is an extremely useful feature for programming teams who are making changes (good and bad) to their code. Think of the commit as an insurance policy: You hope you never need to use it, but it’s there for you just in case you do! Whenever we commit we should should add a message: something to remind us of the changes we’ve made. This is helpful in the event you need to cash in on that insurance policy!
Enough talk. Time to commit our changes.
git commit -m "Completed programming walk through lab"
-mrepresents the message part of the commit.
The output says there we 1 files changed, and 56 insertions, meaning we added 56 lines of code since the last commit. Yes, git makes managing your team easy because it tracks not only who worked on what but also quantifies their contributions. Your information may vary slightly, of course.
- Let’s check the status of the repository files now.
Now our local branch is ahead of ‘origin/master’ by 1 commit. This tells us our local git repository is newer than our remote copy on GitHub. We also have nothing to commit meaning our files are in sync with our local copy of git. This makes sense: we just committed!
- The last step in the process is to get our local copy of git, up on GitHub. Before we do that let’s explain the process.
The status message says Your branch is ahead of ‘origin/master’ by 1 commit. What exactly does this mean? Well, when we initially cloned the repository off GitHub, it made two versions of the repository. One is still on GitHub (git calls this one ‘origin/master’) the other is on your computer. When the two repositories get out-of-sync, we can reconcile them in two ways:
- When the the local branch is ahead of ‘origin/master’ we need to execute a push to synchronize the two repositories, re-playing the local commits remotely on GitHub.
- When the the local branch is behind ‘origin/master’ we need to execute a pull to synchronize the two repositories, re-playing the commits on GitHub in our local repository.
- Since we’re ahead we should push.
git push origin master
You should see output similar to the following: (again your message might be different depending on what was changed)
- An one final check of the repository status:
Which is the same status from the beginning of the walk-through! It tells us nothing had changed locally and we’re in sync with GitHub.
IMPORTANT: You’ll execute step 2.3 every time you code.
The commands are summarized here IST256 FAQ: How do I save my changes to GitHub?
You should get in the habit of following this procedure after each coding session. Class is over? commit code and push to GitHub. Work on your homework for an hour? commit your code and push to GitHub. Not only will it record your changes for you in the event you need to “undo” a change, but it also “backs up” your work to the cloud in the event that your computer has a problem or becomes lost / broken! It’s great insurance against disasters and its so, so easy to do.
Step 4: Visualizing your commits, locally and on GitHub
Once you get rolling with a few commits it might be useful to look back at the history of changes you’ve made. Let’s demonstrate that locally and on GitHub.
Viewing your commits locally.
To view your git commits locally,
This brings up a GUI window where you can easily view the commits.
The top section of gitk has 3 cells where you can select a particular commit to view.
- In the first cell, you can select it by commit message.
- In the second cell you can select the commit by author (Who made the commit).
- In the third cell you can select the commit by date and time. IMPORTANT: we use this to ensure you’ve completed your homework on time!
The bottom section of *gitk has 2 cells:
- the right cell let’s you select the file changed as part of the commit.
- the left cell let’s you see what changed in the commit
- lines in red beginning with a
- lines in green beginning with a
- lines in red beginning with a
Viewing your commits on GitHub.
Likewise, you can view the commits you’ve made locally and pushed to GitHub.
- Open your repository website on https://github.com. If you don’t remember what it is from the command line in your local repository
git remote -v
to display it.
- From the GitHub repository Website, select commits
- From the commits page, select the commit for which you would like to view the changes
In this example you want to select the commit with message Completed programming walk through lab
- You will then see a web of all the files changed in that commit. In this example we should see the file CCL-walkthrough.ipynb.
- On the left is the file before the commit
- On the right is the file after the commit
- Github uses the familiar red/green and
+ / -syntax as gitk
Part 3: On Your Own [H01]
You must now repeat this process, on your own as homework. Here’s a set of high-level steps that you must do.
- Open the following file in Jupyter Notebook: lessons/01/Now-You-Code/NYC1-walkthrough.ipynb
- You’ll see the homework assignments consist of a problem definition, problem analysis, and section to write code. Each of these sections should be completed before you hand in a homework assignment.
- Double click on the Problem analysis section to edit the markdown. When you’re in edit mode it looks like this:
- Add the following to the markdown, outlining the inputs, output, and process for this program. This is a common problem solving approach.
- When you are finished press
SHIFT+ENTERto execute the cell and save your documentation.
- Next, move into the code cell:
- And write the Python program:
print("Python Check Divider") people = int(input("How many people are dining? ")) check_total = float(input("What is the total amount of the check? ")) contribution = check_total / people print("Each person should contribute", contribution, "dollars.")
- When you are finished the cell should look like this:
SHIFT+ENTERto execute the code. Try the same inputs as in the example run at the top. Do you get the same outputs?
- When you are confident the program is correct you are finished writing the program. Exit Jupyter notebook.
- Add your change to your local git repository.
- Commit your change with the message “Completed NYC 1 walkthough”
- Push your code to Github.
- Wait a minute, then verify your code, including proof it was executed is on the Github website.
We hope this walk-through clarified the programming tools we will use throughout the course. Below are a some tips and references to the 4 tools demonstrated in this walk-through.
- How to open the command line from Learn Python repository: IST256 FAQ: How do I open a command line?
- Jupyter Notebook Command Cheat Sheet: https://www.cheatography.com/weidadeyue/cheat-sheets/jupyter-notebook/
- How to commit your code and push to GitHub: IST256 FAQ: How do I save my changes to GitHub?