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

Project 4

MCS 275 Spring 2021 - Emily Dumas

Instructions:

Deadline

This project must be submitted to Gradescope by 6:00pm CDT on Friday, April 30, 2021.

Collaboration and academic honesty

NOTE THAT THESE INSTRUCTIONS DIFFER FROM PROJECTS 1, 2, and 3. You need to design, complete, submit, and understand your own project. You can discuss your work with other students, or even seek advice and assistance from them, or from anyone else. You can even search for ideas and answers online, and adapt code from any source that allows it, e.g. open source licensed software. However, you need to carefully document your personal contribution and cite sources for everything else. In particular you must give a detailed citation for any code you reuse or adapt, and there is a section in the documentation where you must list every person you asked for advice (with details about how their advice was used in your work) and every resource (book, web site, etc.) you consulted. Submitting a project that lacks proper citations or claiming another's work as your own constitutes academic misconduct and may result in a grading penalty and/or referral to the dean of students for investigation.

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.)

Project summary

Develop a web application or API that uses Flask and a SQLite database. It can be a new one you build from scratch, an extension of one of the examples from lecture (yellaro & whinge), 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

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.

Grading breakdown

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
5 Autograder
This covers required files (1pt), syntax (2pt), docstrings (2pt)
4 Project description
Quality of the description in README.txt
4 Your contribution
Is it described in detail in README.txt? Is the description accurate? Is it substantial?
4 Citation quality
Covers README.txt and citation comments in the source code
4 Functional testing
Was it clear how to test it? Does it do what was promised? Does it demonstrate your contribution?
4 Code review
The same type of manual code quality checks as in Projects 1-3
25 Total points on Project 4

What to submit

Submit the following to Gradescope:

  • 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.

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.

License check: Stack Overflow answers are licensed under a Creative Commons attribution-sharealike license (CC-BY-SA) as explained at https://stackoverflow.com/help/licensing, so you can incorporate a modified version of code from an answer you found there into your program as long as you cite the answer's author and apply a Creative Commons attribution-sharealike license to your program if it is ever distributed.

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
# https://stackoverflow.com/questions/64717714/implement-simple-login-page-using-cookie-with-flask
# answer by Grey Li

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

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.

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.
  • 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 the chat application I wrote in lecture. (Don't reuse text from this example in your work. If you base your project on the chat application, you need to write a README.txt that focuses on the changes you made.)

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!

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.

What about group projects?

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.

Idea grader service

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

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 proper authentication to Yellaro or Whinge, where user account information (username and password hash) are stored in a database table. There is a login page that sets a session cookie in the user's browser upon successful login. The feed view and posting pages require a valid session cookie to exist, and redirect the user to the login page if it is not present.

  2. Admin interface. Add a separate view to one of our demo apps that presents additional options that are intended for use by administrators or moderators, such as the ability to delete a submission or change its score in an arbitrary way, or to flag it as one that will remain in the database but never show up on the main page. There is also a form that allows a user to be "shadowbanned", so attempts to post under that username appear successful to the user, but don't actually do anything.

  3. Comment threads. Whinging is more fun when you can commiserate. Make it so that individual submissions to Whinge each have their own "comment thread"---a separate discussion room specific to that submission which behaves like a copy of Yellaro. In the database, one table holds submissions, and another holds all of the comments (with a column containing the id of the submission the comment pertains to).

  4. Whinge analytics. Add a page to the Whinge app that allows a user to see the progress of their submission as a function of time. This is displayed as an image of a matplotlib plot that shows the total score as a function of time as a line plot. (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.)

  5. Whinge advanced scoring. Make it so that the score of a submission is not a simple tally of votes, and instead favors the recent votes. That is, the amount that a given vote contributes to the total score (positively or negatively) starts very high but decays as the time passes, eventually approaching a limit that is not zero but is pretty small. This way, a huge positive or negative response to a post retains some strength forever, but recent posts usually have a chance to take a top spot on the front page. Experiment with giving a score boost just based on how long a post has existed, for the same purpose. Note that this scoring idea requires a change to the way votes are recorded; you need to have a table of all votes ever cast, and query that table to compute scores whenever displaying the main page. Even without any new votes, the rankings on the main page may change over time.

  6. JSON API. We built a chat app that works in the browser. But what if you wanted to write a command line Python interface to the same chat app, so some users could read and post in the terminal? Or, what if you wanted to create a mobile app for Android or iOS? In either case you'd want to have a way for programs to request application data (like the recent messages) in a structured format, and request application-related actions (like creating a new message). Add an API like this to Yellaro or Whinge, that would for example make it possible to retrieve the message feed as a JSON object by requesting a certain URL. Use the API to make a command line (text-based) client for the service.

  7. 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.

  8. 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.

  9. MCS 260 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.
  10. 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.

  11. 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.

  12. 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

  • 2021-04-13 Initial publication