iTunes Proj - Interactive Command Line Search Tool

Objectives

Design a program using object-oriented programming, including class inheritance

Gain experience working with JSON data from a web API



Overview

In this project, you will build a simple command line tool for searching the iTunes store. You will build this application in a series of steps.

Knowledge Required

There are a number of topics you’ll have to master to complete this assignment. Most of them are things you’ve seen before but may need to recall. Some of them are new this semester. And a couple are brand new, but easy to master with a pointer or two.



The following are topics we’ve covered in 507 this semester:

Obtaining, validating, and processing user inputs Functions

Classes and inheritance


Web APIs, JSON, and caching



The following are covered in the textbook, and you have seen them to at least some extent in either 506 or 507.
String manipulation (e.g., extracting substrings) json parsing using the json module Accessing Web APIs using requests

Writing interactive command line programs (prompting for input, allowing user to quit)


The following haven’t been covered in 506, but you’ll learn them through this project:
Named parameters with default values


The webbrowser module (new, but super easy: you just call webbrowser.open(URL))

Importing self-written modules and the meaning of __name__ == “__main__” Understanding the iTunes API (using documentation and “reverse engineering” of json output)


Before you get started

We have given you three files to start with:

iTunesStarterCode.py, iTunesTestCode.py, and sample_json.json.




Here’s how you will use them:

iTunesStarterCode.py is where you will define your classes and write any functions you need to run your program. You will also write your interactive code for Part 4 in this file, in the designated code block.

Sample_json.json provides sample output from the iTunes web API that you will need for Part 3.

iTunesTestCode.py contains test cases for Part 1 and 2. We’ll talk about running test cases in class and discussion sections. Essentially, this is a helper file that checks if your classes can instantiate objects that meet the requirements. You should run the test cases for Part 1 and 2 only when you’re completely done with the respective parts. If you’re done with Part 1 and would like to test it out, you can comment out the test cases for Part 2 and run. How to run the test cases:

Put iTunesStarterCode.py, sample_json.json, and iTunesTestCode.py in the same folder.

Go to your Terminal, cd into the directory that contains the three files, and run:


$ python iTunesTestCode.py
or if you have two versions of Python installed on your machine:


$ python3 iTunesTestCode.py

Part 1: Implement a class system

In this step, you will implement a set of classes to model a part of the iTunes data model.
Develop a base class (“Media”) and two subclasses (“Song” and “Movie”) that represent items in the iTunes store (there are other media types that you do not have to worry about).
Here are some details about each class you’ll need to implement:


Media:

Instance variables: title (default value: “No Title”), author (default value: “No


Author”), release_year (default value: “No Release Year”), url (default value: “No

URL”)

Methods:


__init__: takes title, author, release_year, and url as parameters. Use named parameters with defaults.

info(): returns “<title> by <author> (<release year>)”, filling in the appropriate


instance variables. For example, “Bridget Jones's Diary (Unabridged) by Helen

Fielding (2012)”

length(): returns 0



Song (subclass of Media):

Additional instance variables: album (default value: “No Album”), genre (default


value: “No Genre”), track_length (default value: 0)

Methods:


__init__: takes title, author, release_year, url, album, genre, and track_length as parameters. Use named parameters with defaults. Call super( ) to initialize variables that belong to Media

info(): add “[<genre>]” to the end of the output from Media.info( ). For example “Hey Jude by The Beatles (1968) [Rock]”

length(): return track length in seconds (rounded to nearest second)



Movie (subclass of Media):

Additional instance variables: rating (default value: “No Rating”), movie_length


(default value: 0)

Methods:


__init__: takes title, author, release year, url, rating, and movie_length as parameters. Use named parameters with defaults. Call super( ) to initialize variables that belong to Media.


info(): add “[<rating>]” to the end of the output from Media.info( ). For example “Jaws by Steven Speilberg (1975) [PG]”

length(): returns movie length in minutes (rounded to nearest minute)


Assessment

You will be assessed on:

Whether you have correctly implemented the Media, Song, and Movie classes that have all aforementioned instance variables and methods

Whether you have used inheritance and used super( ) correctly to avoid repeating code


Notes

For this part, you will be creating objects “by hand,” i.e., by passing explicit information into the constructors. You will not be creating objects using JSON. That will be covered in the next part.

You’ll see in Part 2 that song track length and movie length in the raw JSON is in milliseconds. Your track_length and movie_length instance variables should save those raw values in milliseconds, and the length() methods for the Song and Movie classes should return song track length and movie length in seconds and minutes respectively. That is, the length() methods will be responsible for some conversions from milliseconds to seconds or minutes.


Part 2: Create objects from JSON

Now add the ability to create objects using JSON. We have provided sample JSON for three media types that iTunes supports. You will show that you can correctly parse each of these JSON objects into properly constructed objects of the correct type.

To avoid repeating code, you should make sure that the Media class does as much of the parsing as possible, and that each subclass only parses information that is specific to that class.
Suggested approach: Add a named parameter ‘json’ to each constructor. This should have a default value of None. Depending on the value of json, either create the object from the json or from the explicit parameters used in Part 1. (When json is not None, create objects from json. Otherwise, create objects from explicit parameters).
Assessment

You will be assessed on

Whether your classes can create objects from both json and explicit parameters.


Whether your classes can parse json and instantiate correctly from json when json is provided to the constructor.

Whether you have used super( ) correctly to avoid repeating code



Part 3: Create objects from iTunes API

Add the ability to fetch data from the iTunes API, and create lists of objects from the data retrieved. Since the data may change between calls, you will only need to show that the data returned from a set of pre-defined queries (of your choice) is processed by your program without errors, and that the number of objects created is within an expected range (e.g., either 0 or “more than zero but less than or equal to the number of results requested”).

Assessment

You will be assessed on

Whether you successfully fetch data from the iTunes API


Whether you construct the correct type of object given the contents of a JSON object


Notes

The iTunes API limits you to “about 20 calls per minute.” If you don’t make more than 20 API calls in a minute, you should be fine. If this turns out to be a problem, you might consider caching results to use offline while debugging. We will work on caching next week, the week of February 4th. You may refer to the lecture notes and try to adapt and use here. Caching is not required for this assignment and not even particularly recommended unless you are very comfortable with it.

Part 4: Create an interactive search interface

For this last part, you will add the ability for users to enter their own queries and receive nicely formatted results. The output should be formatted as follows:

The results should be grouped into Songs, Movies, and Other Media. In each category, the results should be printed using their respective info() method, one per line.

Each result should be preceded by a number, starting at 1 and going up, printed at the beginning of the line.

When the program first runs, the user should be presented with two options: enter a search term, or enter exit to quit. After a query has been run, a third option becomes available: launch preview. To launch a preview, the user enters the number of the result they want to preview. Your program will then use the webbrowser module to open the trackViewURL embedded in the JSON item description, while also printing the URL to the screen.

Assessment

You will be assessed on:

Whether your program returns expected results (we will compare output with a reference implementation we have built and see if the results are the same) Whether the results are grouped and formatted appropriately

Whether the preview functionality works


Partial credit is possible if you are only able to get parts of this working


Part 4 Sample Output












































Notes

What’s shown above is hypothetical output--not generated by actual code. Your results will almost certainly be different--this is just intended as an example of the format and interaction.

The “...”s that show up above would NOT be part of your program output. We just didn’t want to fill up a lot of space with lots of search results.

There should be no repeated numbers--start with 1 and increment the number for each result.

Your results should be grouped into SONGS, MOVIES, and OTHER MEDIA, and these categories should always appear in the same order

Where it says “Launching XXX in web browser…” above you should actually launch the specified URL in a web browser.


You will need to test if the user’s input is a number (in which case you’d launch the browser) or a string (in which case you’d do a new search). The input ‘3’ would launch the browser, since it can be converted to a number. The input ‘2 Live Crew’, however, should be treated as a string. isnumeric() and int( ) are your friends here.


You will have to think about what to do when there are no results in a category, or no results at all! Your program should give output that will inform the user of what has happened in such cases.


Rubrics

Req
Description

Part
Category
Point





Value





1
Media class is defined with all
1
Code
4

required instance variables









2
Media class’s
method
1
Code
5


info()




returns well-formatted string that




follows instructions









3
Media class’s
method
1
Code
1

returns 0
length()














4
Song class inherits from Media
1
Code
5

class and is defined with all




required additional instance




variables










5
Song class’s
method
1
Code
5

info()




returns well-formatted string that




follows the instructions









6
Song class’s
method
1
Code
5

length ()




returns track length in seconds



7
Movie class inherits from Media
1
Code
5

class and is defined with all




required additional instance




variables


















8




9



10



11



12



13



14



15




16




17



18








19

Movie class’s
method
1
Code
5

info()



returns well-formatted string that



follows the instructions



Movie class’s
method
1
Code
5

length()



returns movie length in minutes



Uses inheritance to avoid repeating
1
Code
5
code




Your Part 1 code passes Part 1 test
1
Behavior
5
cases




Media class can successfully parse
2
Code
10
JSON and construct Media objects



Song class can successfully parse
2
Code
10
JSON and construct Song objects



Movie class can successfully parse
2
Code
10
JSON and construct Movie objects



Uses inheritance - Media class
2
Code
10
should handle as much parsing as



possible




Media, Song, and Movie classes
2
Code
5
can instantiate objects from both



explicit parameters and JSON



Your Part 2 code passes Part 2 test
2
Behavior
5
cases




Fetch data correctly from iTunes
3
Code
20
API based on queries. We will run a



few sample queries and compare



the data you retrieve with that of



our reference implementation.



Your code can construct the
3
Code
10
correct type of object given the



contents of a JSON object from



iTunes










20
Objects created from the fetched
3
Code
10

data are sorted into three groups




(i.e. lists) - other media, songs, and




movies (this will help with Part 4)








21
On program start, user is prompted
4
Behavior
5

with two options: enter a search




term or type “exit” to quit. If user




enters a search term, the program




makes a request to iTunes API and




fetches data according to user




queries. If user enters “exit”, the




program terminates.








22
The data displayed is nicely
4
Behavior
10

formatted and is grouped into




Songs, Movies, and Other Media. In




each category, the results should




be printed using their respective




method, one per line (see




info()




sample output).



23
Each result should be preceded by
4
Behavior
5

a number, starting at 1 and going




up, printed at the beginning of the




line (see sample output).








24
After the first query is run, besides
4
Behavior
5

entering another search term or




exiting, user should have a third




option to launch preview by typing




in the number preceding the




result.








25
If user enters a number within the
4
Behavior
5

range of number of results




returned, your program can launch




preview using webbrowser




module.








26
If user enters something else, it
4
Behavior
5







should be treated as a search term,




and another query would be run




and results based on the search




term would be displayed.








27
Program keeps prompting user to
4
Behavior
5

either enter a search term, enter a




number within range to launch




preview, or enter “exit” to quit until




user quits (i.e. it shouldn’t just run




once)








28
User should be able to quit the
4
Behavior
5

program at any time by entering




“exit”








29
Your program should be able to
4
Behavior
5

handle any queries and parse




returned data gracefully without




throwing errors (hint: each JSON




object returned from iTunes may




have slightly different structures




and some keys could be missing.




How do you handle KeyError?)








30
Well-constructed code that follows
ALL
Code
5

our guidelines








31
Program uses best practices for
ALL
Code
5

defining and using functions (hint:




Parts 3 and 4 should be solved




using at least a few functions)









Total


200