Python and the Web Notes Feedback

[cooper-mj]

Another gorgeous set of notes. 🦄👍 (Apologies if any of my comments don't make perfect sense or are poorly worded - it's a bit late and I'm starting to get tired as I'm writing these).

• Line 5: Might be worth a quick explanation of why we need to install this one via pip (as this is the first pip-installed library they will have seen) while the others can just be imported normally.
• Line 29: "That's right!" doesn't seem to fit since there wasn't a question posed immediately prior. Perhaps just omit the exclamation.
• Line 29(ish): Since they've seen (and should be comfortable with) classes already, there might be a clearer way to present this material through the OOP lens of the third set of notes. That is, present the response upfront as an instance of a Response object (which you do), then use subheadings to enumerate useful attributes and methods and present them as you would any other function (like you presented some of the functions in the Data Structures notes set). Perhaps this is just personal preference, but something with a little more structure would clarify my understanding as I went through the description of this object.
• Line 41: Might want to make a quick note here that r.ok is a wrapper for r.status_code <= 200, and indicate that HTTP codes of less than or equal to 200 indicate that a request was successfully processed.
• Line 47: "know that the response probably contains meaningful information" - I'm struggling to think of a counterexample where we make a successful request that doesn't contain any meaningful information. If the request goes through, then isn't r.content always populated with page content?
• Line 65: Small nit - we should refer to HTML as a markup language.
• Line 71: HTML is exciting, but not that exciting. Let's use a period. 😝
• Line 71 (and some prior lines): "but we're not going to do that right now" - this seems like a peculiar detour for something we aren't going to do right now.... or later in this notes set. Here, I'd recommend flagging BeautifulSoup and requests-html, to bring closure to the HTML side of things. Then, perhaps motivate our use of JSON before transitioning to that part of the discussion - explain that lots of APIs use JSON as a way to interact better with programming environments, for example.
• Line 75: I know we do this later, but to start, it could be cool to have a screenshot of this site from the browser, so students can see the content in plaintext in the browser page before querying the site using Python.
• Line 92: Change "to Python code" to "to a Python dictionary," and before you mention that, make the observation that JSON looks really really similar to Python dictionaries.
• Line 136: "This is really useful because most web programming languages aren't as powerful as Python." This is false, if we're going under the assumption that "power" refers to Turing completeness. If there's another definition of "power" that we're using here, let's perhaps add in some more specific phrasing to communicate specific intent. Honestly I'm not entirely sure what you are trying to convey in this statement.
• Line 163: Awesome job with this breakdown. This is really accessible and nice. And great work explaining the role of that decorator in such accessible language.
• Line 176: "The first line tells Flask to start app.py..." This, strictly speaking, isn't true - it sets an environment variable to indicate to Flask which file to run when the server starts up. But the command does not "start" any file such as app.py, so I'd recommend rephrasing to reduce ambiguity.
• Line 236: Perhaps consider a small detailing of the <name> syntax before dropping it straight into the example.
• Line 288: I know we've seen all the pieces before, but since we're putting them together in a new way, it would be nice to have a brief overview (in English) of what's going on before dropping the reader straight into a code example - especially a code example that's just been flagged as "More Complex" by the section header.
• Line 329: This is a neat and fun example, but it's quite unclear to me where Jinja2 comes in. I don't see it imported in either of the files, nor do I see you pip install it anywhere. This should be clarified. Also... what actually is Jinja2? It's never really detailed.
• Line 365: There's all of a sudden a lot going on here, and a couple more links need to be drawn explicitly. I'd make the comparison here between HTML and the .format operator, where you're basically interpreting the Jinja template as a string to which you apply the .format function to fill in certain variables. It might also be good to draw the reader's eye toward the more useful elements of the HTML they see, such as the title and the link (and to explicitly flag what these are and why they're important), rather than the meta charset or the viewport name.

All in all, really excellent work - I love this set of notes! 😊

[parthsarin]

Wanted to start with discussion on some items that could use it:

• Line 41: It's actually a wrapper for r.status_code < 400 but I didn't want to get into the nuances of what different status codes are. Just 200 and 404 because students have probably encountered them naturally.
• Line 47: Well... I mean... That's the definition of an error code. When the program encounters an error, it should just serve an error response (like a 404 page). r.content might be populated (though it's certainly not guaranteed like you suggested) but it's just the same error in the status code.
• Line 71: No. It's awesome!
• "but we're not going to do that right now": I disagree that it's a peculiar detour. In fact, I think it's quite natural. After all, when you learn about web requests, what's the first website you'd try to request? A website you've been to in your browser, which will respond with HTML. So, we start there, realize that it's not easy to deal with, and then move to JSON. Adding in requests-html earlier might encourage students to opt for that route rather than first checking if there is a JSON endpoint which I'm trying to avoid.
• Line 92: It's not always a dictionary, though. It could be a list or a string or a number, etc.
• Line 136: Other languages aren't as "expressible", "developmentally supported", and, well... all of the other benefits we've been studying this quarter. How'd you recommend I write that? I went for powerful intentionally because it's vague. 😃
• Line 176: The language of the official documentation is (I'm rewording slightly): "It tells Flask which application to work with." Better?
• Line 288: In what way is this "new"? I think it's a really straightfoward extension of what we saw in the last several code blocks, especially because students should already be familiar with (1) the idea that you can write Python code in the indented blocks in a function and (2) what a request is. I can add a small clarification, but I just wanted to know your line of thinking.
• Line 329: Ah that's a really good point. Jinja2 is a templating engine which, as I mention, allows you to write HTML code and inject values from Python. It's used when we write {{ name }} in the HTML. I think I do a decent job of making it clear. Could you take another pass at this and tell me if it's still confusing?
• Line 365: I really don't want to make the .format comparison because it breaks down the moment you do anything more complicated in Jinja. I was thinking I'd say something like that in class but then qualify it thoroughly, which I didn't want to do in the notes. Re: "a lot going on" — In Python, there's only one line that's changed from a previous example, and I think it's explained thoroughly. To me, that comment seems more applicable to the HTML portion and, yes, it's a leap. That said, I do not want to talk about HTML in detail at ... well, any length in this course. I agree that the meta tags are unrelated, and I'll remove them. See my earlier comment about how I call out the {{ name }} thing.