A document from MCS 275 Spring 2022, instructor David Dumas. You can also get the notebook file.

# Project 4¶

## Instructions:¶

This project must be submitted to Gradescope by 6:00pm CDT on Friday 29 April 2022.

### Detailed timeline¶

• 6 April - Posted
• 13 April - Deadline to request an alternative non-SQL topic, if desired (see below)
• 13 April - Date by which I think you should have decided on your specific topic and started working
• 25 April - Autograder opens (which just checks syntax and docstrings)
• 29 April, 6:00pm CDT - Project deadline
• 6 May - Project scores will be posted

### What to do if you're stuck¶

Talk to someone. Email or chat with me. Come to office hours. Talk to your TA. Ask another student for advice. Search online and see if you can find open source examples that accomplish something like what you're trying to do. (And in every case, follow the citation guidelines given below.)

## The most important thing to know¶

This project gives you a lot of flexibility in choosing your topic and using external resources (including working with other students). However, you will also be evaluated differently than in previous projects.

A lot of your grade will depend on how effectively you document the purpose of your project, what resources you used, and what your personal contribution was. Expect that writing and revising the documentation is going to take a similar amount of time to actually writing code.

## Project summary¶

Develop a Python application that uses an SQLite database in an essential way.

One possibility---and probably the one which best fits the current course material---is to write a web application or API that uses Flask in combination with a SQLite database for data persistence. You can build such an application from scratch, or make it an extension of one of the examples from lecture (e.g. the big web app example we'll build this month), or a modification of an existing open source project. There are some ideas below, but I encourage you to try draw on your own interests to develop a unique topic.

Whatever it is, it needs to:

• Solve a specific problem that you can describe clearly and succinctly
• Involve a significant programming contribution (Python and optionally HTML/CSS) that is your original work, even if it contains pieces that were created by others
• Be something I can test on a single computer, using a database file you provide, using no special tools other than Python, a terminal, and a browser. (A basic test of its functionality must not take more than 10 minutes.)

When I grade your project, the overall quality of the final product is not the main consideration. If you choose an intrinsically complicated design and decide to build everything from scratch, with no assistance, you might end up with a barely-working prototype that has lots of rough edges. If you choose to use a bunch of off-the-shelf components and textbook examples, then the same amount of effort might allow you to produce something that is more impressive at a superficial level. What I care about is the part that is your own work, and that it uses either

• major components of the MCS 275 course material, or
• new material related to MCS 275 that you learned on your own in order to complete the project.

There's a more detailed breakdown of the grading scheme and what you need to submit below.

### Note: Not expected to be bigger than previous projects¶

You have a bit more time to work on Project 4 than you did for Projects 1, 2, and 3, but I don't intend for it to take longer than those projects did. I want it to be a comparable effort, and to give you much greater flexibility in deciding where to direct that effort.

## Wait, I have a great project idea, but I don't want to use SQL at all!¶

If you have a specific idea for a substantial programming project you'd like to do for this assignment that doesn't quite fit because it doesn't use a SQLite database, you can ask for permission to pursue your idea instead. However, you need to act fast: The deadline for such requests is 13 April 2022. To make such a request, email me a description of what you want to do and what parts of the course material it will involve. Use subject line

Project 4 variant request

Be sure to check the rest of the document for additional explanation of some of these elements (e.g. what is README.txt?).

Points Item
This covers required files (5pt), syntax (5pt), docstrings (5pt)
Does the README.txt included with your project follow the format of the template I provide below, with clearly indicated sections for description, contribution, and citations
15 Project description
Quality of the of the description in README.txt
Is it described in detail in README.txt? Can I understand what you did based on what you say, and without looking at the code? Is it accurate? Is it substantial?
15 Citation quality
Do you give complete, clear citations to the sources you used (in README.txt and/or in the source, as appropriate)
15 Functional testing
Does it do what was promised? Does it demonstrate your contribution? (Not eligible for any points here if I could not understand what it was supposed to do by reading README.txt.)
10 General code review
The same type of manual code quality checks as in Projects 1-3
Here, points will be deducted if your project contains comments that are not accurate, for example because you adapted code from another source (such as your own previous work) and failed to update the comments to remain accurate.
100 Total points on Project 4

## What to submit¶

• All of the code and related resources needed to run your application, including a database file (so I don't need to do any initial setup or data entry to start testing)
• A document README.txt (a text file) that you create from a supplied template, whose format is described in detail below.

## README.txt¶

This required documentation file must use the format of the template document available here:

You'll want to download this, make a copy of it called README.txt in your project directory, and edit that copy to fill in the relevant documentation for your project. **Do not include a file with the original name README-TEMPLATE-MUST-RENAME.txt in your submission.((

The template has sections for

• A project title
• A project description, in the form of an assignment. Communicates the purpose of your work.
• A clear, succinct description of what I need to do to test your project. (Must make sense without looking at the code.)
• A statement detailing your contribution to the project, as distinct from anything you reused or adapted from another source.
• The list of all sources and credits for advice and assistance you received and resources you consulted, with details about how they assisted your work.

These sections are described in more detail in the template. When editing the template, keep the section headings but replace the placeholder contents (between parentheses) with the actual documentation that applies to your project.

In addition to the template, I thought it might be helpful to see an example of a finished README.txt. The example linked below documents a chat application I wrote in MCS 275 lectures in 2021. (Don't reuse text from this example in your work. If you make a chat application for your project, you need to write a README.txt yourself.)

Because I wrote the chat app from scratch, the section on individual contribution is rather short. For an app that includes code from other sources, giving a full description of your individual contribution will probably take more space.

The README.txt document is a very important part of your project submission. A significant part of your score depends on its contents (either alone, or in relation to the code you submit). Plan for the significant amount of time that writing and revising it will take!

## Citations¶

As mentioned in the summary, you can use any materials you want (subject to whatever licensing rules may apply), and you can seek advice and suggestions from others, but you need to cite your sources. The requirements for those citations depend on the type of usage in your project. There are three main cases to consider:

### Case 1: You talked to someone about your project and their advice contributed to your work. They didn't write or give you any code.¶

Example: You can't get your login page to work. You talk to your friend Greta who built something like this in IT 202 last semester. She suggests the problem is that you are storing data that needs to persist across requests in a local variable, which disappears as soon as it goes out of scope. You didn't realize this was happening, and the advice helps you fix the problem.

Required citation: List Greta in your "Sources and credits" section of README.txt with an explanation of her contribution, e.g.

Greta X. Oppenheimer reviewed an early prototype of the login page and helped me find and fix a troublesome bug related to the scope of local variables.

### Case 2: You consulted a resource like a textbook or tutorial, and things you learned there helped with your project work, but you did not copy or modify anyone else's code.¶

Example: You read about using CSS media queries in a book. Based on what you learned there, you made the chat application from lecture easier to use on mobile devices by editing the stylesheet. You didn't copy any CSS code from online examples.

Required citation: List the book and how it was used in the part of README.txt titled "Sources and credits". The citation should be specific enough that I can locate the book, e.g.

The media queries for mobile usability in my stylesheet were based on material from Chapter 11 of "Modern CSS: Master the Key Concepts of CSS for Modern Web Development" by Joe Attardi, Apress, 2020. ISBN: 9781484262948 https://link.springer.com/chapter/10.1007%2F978-1-4842-6294-8_11

### Case 3: Part of the source code of your project was derived from existing code.¶

You can't use someone else's code unless it is provided under a license that lets you do so, and you can't use it at all in this project if you don't understand it. But if the license allows it, and you understand what it does, you can use it provided you give a detailed citation.

Example: You searched Stack Overflow for information about how to create a login page with Flask, because you were having trouble getting a technique you saw in the Flask tutorial to work with the rest of the application you've built. An answer you found on Stack Overflow does what you want, and after making a few changes based on the database tables and column names you're using, you have it working as part of your project.

Required citation: You need to list this in two places. First, this use of Stack Overflow should appear in README.txt under "Sources and credits". Second, the section of the source code that is adapted from that source must be labeled with comments that provide a a precise citation, including a complete URL. The citation in the source code might look like this:

# The next function implements the /login/ route and is adapted from
# answer by Grey Li

which also satisfies the requirements of the CC-BY-SA license.

## Coding standards¶

Like everything you submit for credit, your code must follow the rules in the course coding standards document. The only difference this time is that it is acceptable to incorporate code from other sources. If you do so, the authorship declaration in the header of the source file should reflect that.

I'm not creating a special category or procedures for group projects. I think it will probably work best for everyone to work mostly on their own, seeking advice and assistance when it is helpful, but not forming a team.

However, the rules for this project do allow two or more people to submit exactly the same code, as long as they document their contribution carefully, cite the others who worked on it as required by the rules, and only expect to be evaluated on the basis of their individual contributions. The main problem with this is that elements that can't be clearly given individual attribution won't be considered. This makes it difficult for a true collaborative work (where everyone is involved in every part of it) to receive a good score. While such true collaborations are great, and often important, they are not suitable for this assignment.

But to be clear, if you are determined to split a big project into clearly delineated parts, and have two or more people work on those separate parts, that is acceptable. The only elements of the README.txt that would be expected to be identical or collaboratively written in that case would be: The project title, the project description, and possibly the testing instructions. Everything else in README.txt pertains to the submitter's individual contribution and the resources they consulted, and thus would be different for each participant.

You can always come to office hours, make an appointment to meet me at another time, or send an email to request help with your project. (And, of course, it is best to not wait until the last minute to ask for help.)

In addition to this sort of open-ended help, I am offering a service where you can "spot check" the project description that you plan to include in README.txt. As indicated in the grading breakdown, this section accounts for 4 points of the overall score and must give a brief description of the problem your project solves. Finalizing this section early in your project work is a good idea, since it lays out exactly what you need to do.

Any time before the project deadline, you can send me a draft of your project description (not the entire README.txt document, just the project description section). I will reply with the score (out of 4 points) that I would assign it. If the score is less than 4, I'll indicate why. In this way, I hope everyone can quickly get to the point where they have a project description to work from that will receive 4 points.

If you email me to request such a spot check, please use the subject line

Project 4 idea grader request

As with all course emails, I will do my best to reply within 24 hours, and can often reply much sooner. And between now and the project 4 deadline, I will prioritize giving quick answers to idea grader requests.

There is no limit to how many times you can ask for this, but the rate at which I can answer messages provides some practical limitations. If you send more than one request like this before receiving an answer, I'll only reply to the one most recently received when I get a chance to write back.

## Project seeds¶

These are not fully-developed ideas, but they provide some directions you could develop into a project. In some cases I warn about the parts that I think will be tricky.

You don't need to base your project on anything in this list. In fact, I encourage you to develop your own idea!

1. Authentication. Add a proper login system to the web app we developed in lecture. That means there is a concept of a user account, which can be of various types (corresponding to the different user roles in the app). User account information is stored in a database table separate from the main data of the application. New views exist in the app to create an account, to log in, to log out, and to change password. A session cookie (something you'll need to learn about) is set in the user's browser upon successful login so subsequent pages they visit know they are logged in. Other parts of the app cannot be seen unless the user is logged in.

2. Web app analytics. Add a page to the web app we developed in lecture that lets you view a visualization of the evolution of various measures of its persistent data over time. For example, if the web app is a ticket tracker, you might make the app keep track of how long tickets are open, and the analytics page would make graphs of numbers of open tickets by week, and the average time to close a ticket by week. (The tricky part here is figuring out how to generate a plot with matplotlib and include it as an image embedded in an HTML page served by Flask.)

3. JSON API. We built a web app that works in the browser. But what if you wanted to write a command line Python interface to the same application? In that case you'd want to have a way for programs to request application data (like a list of open tickets) in a structured format, and request application-related actions (like assigning yourself to a ticket). Add an API like this that would make it possible to do anything that's possible in the browser interface directly from a Python program that communicates with the web app over HTTP.

4. Collective story writing. A database holds partially-written stories. Initially it just contains a bunch of open-ended first lines for stories (e.g. "The internet stopped working today. Or maybe yesterday, I don’t know.") When you visit this site, one of the partial stories in the database is selected at random and "checked out" to you (i.e. temporarily reserved so that you are the only one working on it). The text of the story is displayed, and you are invited to write the next sentence. When you submit your work, it is checked back into the database. You can optionally declare the story done (if you've written a nice conclusion). Finished stories can be viewed in a separate page. There is an option to also show who wrote each line.

5. Meme maker. A web form lets you choose a background image from a fixed collection (e.g. https://en.wikipedia.org/wiki/Success_Kid) and enter text to draw onto the image as an amusing caption. Upon submission of the form, Pillow (or another image manipulation library) is used to draw the requested text and provide the annotated image for the user to download. In addition, the final captioned image then becomes an entry in a voting system similar to Whinge. Users who visit another page in the application can either browse and vote on newly created memes, or view a list of memes ranked according to score.

6. MCS 260 Fall 2020 Project 0 autograder. A web app offers a form with a field for entering a username, and a large text entry box where the user is expected to paste a Python script that solves the simple coding exercise described here. Upon submission, the application runs the script on the server with several inputs and checks the output against the expected results. A report indicating the result for each test case (pass or fail) is shown to the user, and both the total score and individual test results are stored in a database. A different page in the same application allows the instructor to view a table of scores for all users who have submitted programs.

• Running code submitted by a user on the web application server is very dangerous. In a real application of this sort, you'd use some kind of "sandbox" to isolate the user code from the application server. You don't need to handle any such isolation in this project, but you should know that it is important in real world applications.
7. Flash cards web app. This web application is designed to help humans memorize key-value mappings (such as the definitions of a collection of terms, or the translations of a set of words from one language to another). The core feature is a test: The "front" of a card (i.e. the key) is shown and the user is asked to enter the contents of the "back" of the card (i.e. remember the value). Right and wrong answers are tracked. There is a definite probability that any card will be shown, but cards that haven't been seen are much more likely to show up, as are cards that haven't been seen too recently which have a low success rate in recent trials. A database stores all results with timestamps, so work can resume at any time from any device able to connect and render the HTML. A separate page within the app can be used to add or remove individual cards, reset the statistics, or clear out all existing cards.

8. What are you working on? A web application that provides a way to share a short description of what you're working on that others can view at any time. To post, a user visits a certain URL and enters their username and a short description of what they're doing (e.g. "Writing the Project 4 description for my class") into a HTML form. After submitting the form, the application will respond to requests at a certain URL involving the username (e.g. "/status/ddumas") and serve a page that displays that user's most recent submission in large text. The page showing a user's current status also has a link to a page which gives the history of their past submissions, listed with their dates and times of posting.

9. Event tracker. This application is for people who want to track how often (or for how long) they do something. For example, it might be used to track exercise or sleep. The main interface has a big button that a user can press to indicate either the start of an event (e.g. I'm about to start exercising) or the end of an event (e.g. I just finished exercising). The interface shows whether an event is currently underway, to make the current function of the button (start or stop) clear. A database stores the event history. Events that are started but not stopped after a certain amount of time are marked as "incomplete". Using a separate configuration page, the user can indicate whether incomplete events are ignored, or if they are assigned a default duration (like 45 minutes), and how long the application waits before declaring an event incomplete. A reporting page provides lots of information about the recent history, such as the longest event, shortest event, average event duration, average number of events per day, events per week, longest streak of days with at least one event, length of current streak, etc.

• Note: Without the logic to handle incomplete events in a user-configurable way, this application idea would probably be too simple to make a suitable project.

Course staff may add new ideas to this section from time to time. Such additions won't be listed in the revision history at the bottom of the document, since they don't change project policy. But if an important correction is made to one of these suggestions, or if anything outside of the list of project ideas changes, that will be listed as a revision.

## Revision History¶

• 2022-04-06 Initial publication