Skip to content

IMPORTANT.md

Latest commit

 

History

History
97 lines (62 loc) · 5.85 KB

IMPORTANT.md

File metadata and controls

97 lines (62 loc) · 5.85 KB

Final Project Template

THIS README IS INTENDED TO HELP YOU GET STARTED WITH THE PROJECT.

First Time Setup

  1. Clone the project repository from GitHub

  2. Open the project repository folder using VSCode

  3. Open a VSCode terminal

  4. Create a virtual environment named env in the project repository folder using python

  1. Activate your virtual environment
  1. Install the project dependencies using pip
  • pip install -r requirements.txt
  1. Run the bootstrap.py program
  • This will setup your .env and .flaskenv files
  1. Open the .env file and add the proper information for the:
DATABASE = Name of your database
TEST_DATABASE = Name of your testing database
DBUSERNAME = Your MySQL account username
DBPASSWORD = Your MySQL account password

Running the Project

Ensure that your virtual environment is activated before attempting to run the flask application or your testsuite

Running the Flask webserivce

You can initialize your database using the initdb command (provided by the initdb_cli_command() function in main_app.py) to setup your production database:

$ flask initdb

To start up your flask webserivce, you execute the built-in flask run command:

$ flask run

The flask application runs perpetually in the terminal window will now display all requests to your service in realtime as well as any errors. If you want to stop the application you can press Ctrl+C to terminate the flask application. While your webservice is running you can access it using the address http://localhost:8000. Localhost again meaning your computer (short for the IP address 127.0.0.1) while 8000 is the port being used by your computer to service the website. If for any reason you receive a message that port 8000 is in use, make sure to check that your have stopped all running flask applications. If the problem persists, you can use the .flaskenv file to change the port to a different number (like 5000, or 8080) and use the flask run command again.

Running the testsuite with pytest

To use pytest to run the testsuite, we can use the command:

$ py.test

This will automatically execute all your testcases within the tests folder. Sometimes it is helpful to see more verbose information about the results of the test suite. If you would like to run only a specific test, you can do so by name using the following command:

$ py.test -k test_stuff.py

Pytest can show more specific information about which individual testcases where run from each python testing file and their passing status using the verbose option (-v):

$ py.test -v -s

If you are trying to debug an error it is important to note that by default, pytest does not show the output from print() statments. You can use the -s option to show all output from print() statements to the terminal when the test runs. Remember that print() in your test cases are for debugging purposes only. Use assert to verify the correctness of your testing.

It will likely be necessary to add additional testcases for your program. Pytest will automatically scan the tests folder for other folders, python files, and python functions that start with test_. If you follow this convention your tests should be automatically located when you run py.test

Files and folder structure

IGNORE ANY pycache or .pytest_cache DIRECTORIES. These are autogenerated by python when you run the application

app/                 | The entire flask application is contained in this folder 
|-> api/             | The api folder holds all python files that define routing for your flask API
|-> models/          | This folder hold all classes that are abstractions for the objects your program uses (like our Dogs and DogsDB classes)
|-> static/          | This folder holds content for your html templates that never changes (CSS, Images, Javascript, etc.)
|-> templates/       | This folder holds all of the HTML templates your create to be rendered by flask to display your webpages
|-> utils/           | A folder to hold supporting utility functions like initial database setup or getting a connection object for MySQL
|   |-> db.py        | Collection of functions for setting up and connecting to the database. Will need to be edited to establish your unique database schema.
|-> views/           | All routing that shows your HTML pages for the graphical front end to your webservice goes here
|-> main_app.py      | Launch point for your flask app. Should require minimal edits to connect API and View routing. Most template code can be reused.
|-> tests/           | All your test cases go here
|   |-> test_api/    | All tests for the API go here
|   |-> test_models/ | All tests for classes that represent the objects you create for your system or database intermediary classes go here
|-> .gitignore       | Controls what files are not tracked by Git. This should not require any modification
|-> .env             | Holds all database environment variables (needs to be updated with your MySQL information)
|-> .flaskenv        | Holds configuration data specifically for flask (should need little to no modification)
|-> bootstrap.py     | Simple program to create the .env and .flaskenv files so you only need to edit them
|-> conftest.py      | Contains all the test fixtures for the database and flask application for use with Pytest. Little to no edits required.
|-> README.md        | Contains all documentation for your flask application and API
|-> requirements.txt | List of Python packages necessary for the project
|-> IMPORTANT.md     | This file...I hope you have read it :)