Lab 8: Introduction to
Web Applications

Part 1: Intro to Flask

If you find typos or problems with the lab instructions, please let us know.

Note: Parts 1 and 2 of this lab are individual work. Each of you should do it separately, though you are most welcome (and, in fact, highly encouraged) to help one another if/when you are stuck.


Setting Up Your Repo

Each partner will create a separate repo for this part, and then you and your partner will work together in a new repo for the rest of this lab. Although Lab 8 doesn't have starter code, we do have a repository template that provides the basic infrastructure needed to work in GitHub Codespaces.

Here are the full instructions:


Working with GitHub Codespaces

At this point, we've outgrown what we can do in Colab notebooks, so now we need to switch to a full-fledged development environment. We can do this entirely within GitHub by using Codespaces, a cloud-based development environment that lives on a virtual machine and runs entirely within your web browser. We will interact with the Codespaces by using the VS Code editor in the browser. 

To start a new Codespace, go to the main page for your GitHub repo, and click on the Green "<> Code" button in the upper right corner. Click on the "Codespaces" tab if neccessary, and then click on the big green "Create codespace on main" button. Then wait a little bit for the Codespace to start.

The next time you work on your project, you won't need to create a new Codespace because you can resume using the previous one.  Click on the green "<> Code" button in the upper right. You'll see your codespace listed by name now; click on the name of your Codespace to get started. For example, my codespace was randomly assigned the name Fuzzy Sniffle:

If you close your tab, or leave the Codespace alone for too long, it will automatically stop, but can always be started up again.

Step 1: A basic Hello World webapp using Flask

Flask is a Python module/framework that provides an easy way to get started with web programming.

The easiest way to get started is to try some small examples. Below is a small example of a Python program that uses Flask. There are seven lines of code here (not including the blank lines), and before the end of this document, we’ll explain every single part of every one of these lines.

This web application isn't very interesting — it puts the words “Hello World!” up in the browser every time you send it a request. But it provides a starting point, from which we can begin to do more interesting things. 

To create the simple web app, do this:

from flask import Flask

app = Flask(__name__)


@app.route("/")

def hello():

   return "Hello World!"


if __name__ == "__main__":

   app.run(host='0.0.0.0')


Note that sometimes, depending on browsers, platform, etc., if you copy/paste you may get extra blank lines between your code, i.e. something that looks like the image on the left below nstead of the image on the right.   In that case, please take the time to  remove the extra blank lines.  

Though we won't mention it again, we'd really like you to remove the blank lines any time they pop up in copy/pasted code.

❌ Copy / Pasted, with extra blank lines
(This is what we would prefer not to see)

✅ Typed, or copy/pasted then cleaned up.
This is what we would prefer to see.

Now run the code, and you'll have a web app running!

To get this working, all you have to do is click the play button in the upper right corner. If you mouseover this button, it will say  Run Python File.

Here is what the output in the terminal should look like (there'll probably be some extra output as well, but these lines are the most important):

* Running on http://127.0.0.1:5000/
...
(Press CTRL+C to quit)

If that works, great! This may not be very impressive, but it gets a little more awesome when you realize that you’ve just put up a local web server that you can connect to with a browser! A new browser tab or window should open automatically in your web browser for you to see this -- you should see the message “Hello World” come up in the browser.

Now: check in with your partner and verify that both of you were able to get a simple hello world app running before moving on.

Step 2: Play around with it

If you can, you should arrange your windows so that you can see both the Codespaces tab with your editor and the browser tab with "Hello World!" side by side in separate windows.

Now, here are a few things to try, and some questions to answer. As you try these things and think through what is happening, you should begin to understand a few things about how this code is working:

(1) In the browser window where you see "Hello World!",  click the refresh button.

 What do you see happen in the Terminal portion in the lower-right of the Codespaces VS Code window each time you click the button?

 NOTE: If you look in the address bar of the browser tab with  "Hello World" you'll see an address like 

https://fuzzy-sniffle-rp6469g69643x7r5-5000.app.github.dev/

This URL can be accessed from another device, but you will have to log in to GitHub first.

(3) Click inside the Terminal portion of your VS Code window (in the lower right) and then press either Ctrl-C or Cmd-C to stop the web server.

Once it's stopped, try refreshing the page in the regular browser.

Does the page load? 

And what (if anything) happens in the Terminal window?

Step 3: Understanding all the lines of code

Ok, here is an explanation of each of the lines of code. Then, we’ll walk through how to do a few things that are a bit more interesting.

1) from flask import Flask

This code pulls in the definition of a new datatype called Flask (note the uppercase F) from a module called flask (note the lowercase f.) In Python, when you import something, you are telling the Python interpreter that you want to build your software on top of some software already written by someone else.

2) app = Flask(__name__)

This line of code is an assignment statement. The right hand side is evaluated, and then the variable on the left is set to the result of the right hand side. The right hand side, Flask(__name__), creates a new object of type Flask. The __name__ parameter is explained further in the box “About the First Parameter” on this page of the api documentation. We’ll defer the details for now, and just say: for very simple Flask applications, __name__ is always the correct choice.

3) @app.route("/")

The @ signals that what follows is a Python annotation. It indicates that there is some special way the following function definition should be handled. In this case, the annotation app.route("/") indicates that this function is called whenever we ask for the main page on this web server (i.e. "/". This will make more sense when we add other pages later.

4) def hello():

5)    return "Hello World!"

Lines 4 and 5 are a regular plain old Python function definition. We can see that the function is called hello, and takes no parameters. This function returns a string, "Hello World!", which is used as the page to display for the main page of the web server ("/").

6) if __name__ == "__main__":

Line 6 has an if test that checks the special variable __name__ to see if it has the special value __main__. This is the mysterious “conditional script stanza”, which we aren’t going to explain in detail here (though if you are curious, here's an explanation).

Instead, we’ll just say that whatever “main thing” a Python code is supposed to do when you type python3 main.py, in this case python3 main.py should typically be wrapped in this if test. That makes your file much more useful, because then the definitions it contains can be included as a module in another file.

7)    app.run(host='0.0.0.0')

Line 7 is the line that actually causes our web server to start running. The dot-notation app.run(host='0.0.0.0') tells us that run is a method of the object app. By putting () after it, we are making a function call to that method, and starting things in motion. The host='0.0.0.0' is just a placeholder that tells Flask to listen for web requests on any internal IP address.  

GitHub's Codespaces does some magic so that our web requests to load our site on the domains like https://fuzzy-sniffle-rp6469g69643x7r5-5000.app.github.dev/ will actually be relayed through the virutal machine containing our Codespace so that Flask sees the web requests as coming from the machine it's running on. That's why you see Running on http://127.0.0.1:5000 in the terminal ouput above: 127.0.0.1 is not a "real" IP address but rather a placeholder that stands for "this same machine." And 5000 is the port that our application is running on. We typically pick a special port to run our development servers on; in the real world it's common for a single server (or virtual server) to be running several different development servers at the same time, so we want to pick an arbitrary port for every development server.

It's also possible to directly specify the localhost by writing  app.run(host='127.0.0.1') instead.

Step 4: Recording your Work

Now it's time to commit your work before moving on to Part 2. Before we give those instructions, it's important to understand a few things about how Git and GitHub work in relation to your Codespace:

How to commit and push in VS Code

Next, let's create a branch in Git to keep track of our progress after each part of the lab (so the mentors have an easier time giving feedback).

That's it for Part 1!   Ok, what's next?

Next, we'll try to make an app that can actually run some code instead of just printing Hello.

That's in Part 2. which you may start now!

Links to:  Overview   Part 1    Part 2     Part 3    Part 4    Part 5    Part 6