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

MCS 260 Fall 2021 Project 4

  • Course instructor: Emily Dumas


Deadline is 6pm CDT on Friday December 3, 2021

Detailed schedule:

  • Nov 9: Project description released
  • Nov 17: Last date to submit topic proposal (meeting this deadline counts toward project score)
  • Nov 22: Autograder opens (basic syntax checks only)
  • Nov 23: If revisions to your proposal are requested, a revised version meeting the conditions must be submitted by this date (meeting this deadline counts toward project score)
  • Dec 1: Date by which you should make your first autograder submission (if you're following the schedule I suggest)
  • Dec 3, 6:00pm Central time: Deadline to submit complete project to Gradescope, which is also the last activity of MCS 260 Fall 2021

Collaboration policy and academic honesty

This project must be completed individually. Seeking or giving aid on this assignment is prohibited; doing so constitutes academic misconduct which can have serious consequences. The only resources you are allowed to consult are the ones listed below. If you are unsure about whether something is allowed, ask. The course syllabus contains more information about the course and university policies regarding academic honesty.

Resources you are allowed to consult

  • Documents and videos posted to the course web page (slides, worksheets, homework, solutions, sample code, lecture videos, etc.)
  • Any of the optional textbooks listed on the course web page
  • Instructor or TA

Ask if you are unsure whether a resource falls under one of these categories.

Overview and grading

Projects 1, 2, and 3 in MCS 260 asked you to write programs following a precise specification, and these were primarily evaluated by the autograder.

Project 4 is different: It is an open-ended programming project where you have a lot of flexibility to determine what kind of program you'd like to write. What is important is that the program you choose to write:

  • Is of significant complexity
  • Involves concepts from MCS 260 (and not just through its use of the Python language)

Like the other projects, Project 4 will be collected in Gradescope, which will perform some basic checks to make sure the filenames meet the specifications given below. Manual review will account for the majority of the points on this assignment.

The overall grade breakdown is:

  • 5 points - Given if a complete topic proposal was submitted by 11:59pm on Nov 17 (details below)
  • 5 points - Given if the initial proposal was approved, or if a revision was requested and you submit a revised version with the requested changes 11:59pm on Nov 23
  • 15 points - Assigned by the autograder based on basic checks (e.g. are the required filenames present? Is every .py file syntactically valid?)
  • 75 points - Assigned by the instructor based on manual review and testing, broken down as:
    • 25 points - accuracy and completeness of README.txt
    • 25 points - functional testing (does it work? does it do what you promised?)
    • 25 points - code review (could I understand your code? did you follow the requirements in the project description?)

Proposing a project

Please do it soon

The sooner you decide on your project topic, the sooner you can start working, and the more time you will have to complete Project 4. In order to receive full credit on the project, you must submit a project proposal by 11:59pm on Nov 17. The project proposal received by that time must show that you made a real attempt at a complete proposal; a submission that is woefully incomplete will not count for the purposes of grading.

The proposal form

Project proposals must be submitted using this online form, but don't submit the form until you read the rest of this document:

To access the form, you will need to be logged in with your netid@uic.edu Google account. Try to open it now, so that you can determine whether you need any help with this.

The form asks you several questions about your project. In particular it asks for a:

  • title and short description of your project
  • list of some concepts from MCS 260 that will be used in your program (e.g. object-oriented programming, modules, regular expressions, recursion, ...)
  • brief description of how I will test your program (e.g. Do I just run one Python file? Or do I run a pytest test suite? Or is the main component of the project a module, and I should run a program that demonstrates how that module can be used? Are there input data files I need?)

Approvals and revision requests

Within a day or two of submitting your project proposal, you will receive email notification either approving the proposal or indicating that some type of revision is needed.

If the initial submission results in a request for revision, you need to act promptly. To receive full credit on the project, you must submit a proposal by 11:59pm on Nov 23 that is ultimately approved.

To submit a revised proposal, use the same form as for the initial proposal.

Submitting your completed project

When you submit to Gradescope, there are just two required files:

Depending on your topic, you may need to submit many files, including files of other types (e.g. JSON or CSV files, additional text files, many .py files, ...).

Requirements for the Python source you submit

Required header

The first three lines of every .py file you submit must consist of comments in the format:

# MCS 260 Fall 2021 Project 4
# Full Name

In the second line, replace Full Name with your full name.

In the third line, replace the all-caps comment with a single full sentence, written in your own words, explaining that makes an accurate statement about whether or not you completed the project individually and followed the rules in the syllabus and project description. If the all-caps placeholder sentence (REPLACE THIS WITH YOUR...) is left in your final submission, there will be a significant point deduction, equivalent to omitting the entire header.

These comments should be immediately followed by a file-level docstring (as explained below).

Use of docstrings

Every .py file, function, and class must have a docstring that describes its purpose.

Don't write docstrings in the style of "This program does X, Y, Z". Instead, shorten to "X, Y, and Z". Similarly, don't start a docstring with "This function" or "This class", but instead shorten to whatever you'd put after that phrase.

Use good variable names

You are expected to choose variable names that communicate a variable's purpose in a concise way, but without being too terse. Uninformative low-effort names like intvar or mystring are not acceptable. Single-letter variable names can be used, but sparingly, and should usually be avoided for lists or other complex data structures. Most of the time, a good variable name will be a single word, compound word, or multiword name with _ separators, e.g. upcoming_events or ingredients or cyclelength.

Use comments to explain, not to disable code

You are encouraged, but not required, to include comments that contain explanatory text.

Do not use comments to disable code that you don't want to run. Instead, remove such code before submitting.

No range(len(...))

If you find yourself tempted to write range(len(...)) in your code, there is almost always a better way to accomplish the same thing. Contact the instructor for help with this, or to get permission if you are in one of the very unusual situations where range(len(...)) is a good idea.

Documentation required

Your submission to Gradescope must include a file named README.txt.

That file must be a text file, written in full sentences, that describes the project in at least as much detail as the proposal, and which documents how it should be tested. This last point is extremely important:

When grading your project, I will look at README.txt to determine what it is about and how I can try it out. I will not look at the source code or proposal you submitted until later in the grading process.

If README.txt is missing, or if I read README.txt and cannot figure out how to use your program rather quickly, there will be a significant grading penalty.

You must be the sole author of the documentation. It should not consist primarily of quotations from documents of which you are not the author.

General requirements of any project 4 submission

Must work on a computer I have access to

It must be possible to test your project using Python 3.9 on Windows 10 or Ubuntu Linux 20.04. If you know that your program requires one of these platforms (and doesn't work on the other), that should be indicated in the README.txt file. The program's operation must not depend on any system-specific details such as the exact operating system version, the user name, or the name of the directory in which the program is run. If you have an explicit directory name in your code, such as C:\Users\jdoe47\Documents\mcs260\project4, that probably won't work on my computer!

(If you develop on MacOS, it is very likely that your program will run on Ubuntu Linux 20.04 with no changes.)

May only modify files in current directory or user-specified locations

Your program must not alter or write any files except:

  • Files in the current working directory, or any subdirectory thereof
  • Files whose names or parent directories are provided as input to the program in some way (e.g. command line argument, keyboard input, text contained in an input file), and where the need for such a name or path as input is explained clearly in README.txt

External modules require approval

Your program can use modules that are in Python's standard library or which we discussed in MCS 260 lectures.

If you want to use any other module, you need to mention this in your proposal and receive approval.

Not a standard exercise

Some programming projects (e.g. write a tic-tac-toe game) are so often assigned in introductory courses that hundreds of solutions and lots of related discussion can be found online. If you propose one of these "standard" topics, you will be asked to choose another topic or revise your proposal significantly. Basically, if an idea shows up prominently in a web search for something like "Python beginner project ideas", it will probably not be acceptable. This kind of web search is permissible to decide whether to rule out a project idea.

Limited overlap with other students

If many students submit a request for the same topic (or very similar topics), the latest-received proposal(s) will be asked to revise their topic. The goal is to avoid having large groups of students working on the same topic.

Project seeds

Here is a list of some "seeds" for projects that you could expand and develop into a proposal. You are not required to use one of these, and proposals based on a completely different topic of your own choosing are welcome. You are also free to modify any aspect of one of these ideas when you create your proposal, but be careful to avoid making a project idea dramatically simpler than the ones listed here. If your proposal falls below a certain minimum complexity threshold, I will request that you revise it.

  • Expanded geometry module - Add several new shapes to the geometry.py module we built in Lecture. Also make it so that all shapes support addition to compute the bounding box of a pair of objects. Include a script demonstrating the features along with the module itself.
  • Interactive fiction - An expanded version of project 2 where you add additional features to the interactive fiction and create your own custom map. For example, you might add an inventory system, so the game has a concept of "objects" that can be present in rooms, can be picked up using commands, and which may be required to complete certain actions.
  • Catalog - A program to catalog a collection (e.g. of books), storing its data in a file (e.g. CSV). The program would use a keyboard interface and offer commands to locate (search), print, modify, and delete records. The search command should allow searching for text contained in a specified field, e.g. find all books whose title contains "shark".
  • A basic Python web application - This would only work if you have existing knowledge of HTML that you want to apply in this project. Building on the Python API example from lecture 35, make a Python application that serves an HTML document meant to be viewed in the browser. The document should be dynamically generated and support interaction of some kind, so that the same could not be easily achieved with a static HTML file.
  • Todo list - A program that maintains a list of tasks and due dates. It can display tasks in the order added, or in order of how soon they are due. It supports adding or removing tasks, or changing the deadline for a task. The task list is stored in a file, so that it is maintained between different sessions of running the program.
  • Open data analysis - Use public data sets from a source such as the Chicago Data Portal, the Illinois Data Portal, data.gov, or a federal agency. Write programs to extract useful information from these data sets and display or save it in a convenient format. Document exactly where you downloaded the datasets, and what commands are used to process each one. Example: List the street names of Chicago in order of decreasing numbers of parking tickets issued in 2018. Document what you learned from your analysis of the data.
  • Random text - The program accepts an input text file which should be a very large document written in a natural language (e.g. English). A novel from Project Gutenberg would be a good start. It then produces a bunch of "random" text where the likelihood of any two words appearing next to each other is similar to the input file (but where the actual words are selected randomly). This output text will be meaningless, but at a quick glance it might look like real prose. (This project requires some learning or knowledge of probability and statistics.)
  • Code filer - Imagine someone has a directory (e.g. mcs260) full of Python source files for various purposes:

    • Sample code from lectures
    • Work from worksheet problems
    • Work on homework assignments

    Write a program that finds all such .py files and examines each one to try to determine where it should be filed in a more organized storage scheme, e.g.

    • If the filename looks like worksheet6prob2.py or ws6prob2.py, or if it has a name like asdf.py but mentions Worksheet 6 in a comment, then it should go in a directory named worksheet6
    • Similarly for homework, where either filename or comment within the file would signal which assignment it belongs to
    • If the patterns above don't apply, but if it contains a comment mentioning some Lecture number, then it should be filed in a directory corresponding to the week of class containing that lecture

    The program would be expected to copy files (e.g. using shutil.copyfile) to new locations, rather than moving them. A good way to handle this would be to have the current directory with all the .py files and the new directory where an organized hierarchy is to be created given as two command line arguments.

  • Python source stats - A program that reads a single Python source file and prints some statistics about the contents, including the number of lines that are not blank and not entirely comments (true "source lines"), the number of function definitions, number of function calls, the average and maximum line length, etc.. You could use the regular expression module to search for function definitions, or learn about parsing Python source in Python using the ast module.
  • Recursively find large files - Recursively search through a directory specified on the command line for files and then print a list of all files found in order of increasing size. For each one, also indicate a percentage of the total size of all files found that it accounts for. Also report on all the directories found in the search, indicating the total size of each directory's contents (the sum of sizes of all files it contains), with directories listed in order of increasing size. Also allow the user to specify a minimum size (e.g. as a second command line argument) so that no items smaller than this theshold are printed. Read about os.stat() to learn how to get the size of a file.
  • Net present value calculator - Build a tool for analyzing projected profit/loss data for a company taking into account inflation. On the command line, the user provides an input file name and a list of estimated rates of inflation for the next few years. The file should contain a list of estimated profits (positive numbers) or losses (negative numbers), with each line corresponding to one year. The program then computes and prints the net present value of the income stream. (Note: Requires knowledge or learning of the concept of net present value!)
  • Personal expense tracker - A simple program for tracking personal income and expenses. It stores data in a JSON file, and when run prompts the user for commands. Commands can specify spending (with amount, category, and optional date) or income to be recorded, or can ask for a summary of spending and income for the last month, year, or other time period. Such a summary would indicate spending in each category and total spending, each in absolute numbers and as a fraction of income for the same period. (Note: Handling dates/times will be a tricky part of this project, and we don't cover that until Lecture 37.)
  • Fake code typist - A program that lets an actor who doesn't know Python appear to be typing Python code in the terminal for cinematic purposes. First, learn how to detect individual key presses in the terminal in Windows or Linux. Then, make a program that will allow the user to type garbage text (random letters) on the keyboard and have nice Python source code show up on the screen. One character of source code should appear for each key pressed. The code displayed should come from some pre-loaded sample code files that are written by you, are provided as examples in MCS 260, or are in the public domain.
  • Recipe multiplier / unit converter - A program that reads the ingredients for a cooking recipe from a text file, with lines like 11 oz powdered bhut jolokia chilies or 1.5 c butter and extracts the quantity, unit, and ingredient name from each line. Then, upon request, the program can do any of these things: (1) Convert from US/imperial units (cup, ounce, pound,...) to metric units (ml, g, ...), (2) Convert from metric to US/imperial units, (3) Multiply the recipe quantities by a given float (e.g. double or halve).
  • Location guessing game - A one-player game displays a grid using text printed to the terminal. Each square in the grid might contain an obstacle (a sinkhole, an enemy, etc.) and the user is allowed to test locations by entering coordinates. The game provides some feedback about each guess, such as the distance to an obstacle, the number of nearby obstacles, or something else. The next time the grid is printed, it also reflects what the player has learned about the contents of the grid squares. You can determine the best win/loss logic, based on what turns out to be fun; examples: (1) Must locate an obstacle within a fixed number of moves to win; (2) Must avoid all obstacles and find all other squares to win; (3) After a limited number of moves, the number of obstacles found is the score.
  • Interactive fiction bot - A program that reads a JSON file in the format used for the world map in Project 2 and determines whether or not it is possible to win the game. If it is possible, the program prints a list of commands that will result in a win. If it is not possible, the program prints a message to that effect. Along with the actual program, two JSON data files are included: A map where winning is possible, and another where it is not.
  • Digging around in the standard library - Select a module from the Python standard library that we don't cover in class. Learn about it and write a program that demonstrates its major features in a natural, coherent way. (The details will depend on the module, but what you submit shouldn't be a random assortment of lines of code involving that module. Instead, it should do something in which the use of the module arises naturally.) It would be a very good idea to check with the instructor by email when you're considering a specific module and before writing the full proposal. Some of the standard library modules would work well, others less so.
  • Lexicon hornet - The New York Times has an online spelling game called Spelling Bee in which players must spell words using a given collection of 7 letters, one of which is required to be used. Make a game similar in concept, but distinct in the details. For example, it might provide 8 letters the player is allowed to use to make words while designating two of them that are required to be present. You will need to find an open source dictionary text file to use in checking answers, and will need to manually decide on some sample letter sets to provide with the game. While the NYT game is played in a browser, a project on this topic would be expected to use a terminal (text + keyboard) interface instead.

Bonus opportunities

If the project you submit has any of the following characteristics, it will receive a small bonus (up to 5 points) in the grading. The application of the bonus is at the discretion of the instructor, and the bonuses don't stack (you can't satisfy both and get 10 points). The final score will still be capped at 100%, but this bonus can make up for deficiencies elsewhere.

  • Topic coverage bonus - Given to a project that uses a lot of the major concepts from the course, especially ones covered after the due date of Project 2. E.g. JSON + HTTP requests + OOP might qualify.
  • Use of advanced features bonus - There are certain concepts in MCS 260 that beginners sometimes shy away from. If you use these extensively and properly, you will qualify for the bonus. These topics are:
    • Object-oriented programming
    • Organization into modules
    • Tests included with the source (e.g. using pytest)

Revision history

  • 2021-11-09 Initial publication