From e04512acf64911712c7fed7e7d06884c95a734bd Mon Sep 17 00:00:00 2001 From: Tianyi Zheng Date: Thu, 23 May 2024 05:18:18 -0700 Subject: [PATCH] Update README and rewrite contributing guidelines Update Python version badge in README.md from >= 3.6 to 3.12 Update usage examples in README.md to reflect updated API functions Rewrite CONTRIBUTING.md to extensively document how to set up the development and install required/recommended tooling --- CONTRIBUTING.md | 87 +++++++++++++++++++++++++++++++++++++++++++++++-- README.md | 49 ++++++++++++---------------- 2 files changed, 105 insertions(+), 31 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d0c3979..8d70d2b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,4 +1,85 @@ # Contributing Guidelines -1. Please maintain proper commenting etiquette. Pretend that this is a work environment and that the comments are being reviewed by coworkers. -1. Ensure that your changes compile/work before opening a PR. -1. Follow style guidelines where applicable. + +To get started with contributing to the Pitt API, please read these guidelines in their entirety to set up your development environment and learn our tooling. + +## Initial Setup + +### Setting Up Your Virtual Environment + +The Pitt API uses [`pipenv`](https://pipenv.pypa.io/en/latest/) to manage its dependencies. As such, you should also use `pipenv` for your own Pitt API development rather than the more traditional `pip` and `venv`. + +To set up `pipenv`, first install the package using `pip`: +```sh +pip install --user pipenv +``` +Now install `pipenv` to your local Pitt API git repo: +```sh +pipenv install +``` +This will install all necessary dependencies listed in the [Pipfile](/Pipfile) and also set up your virtual environment. +Start the virtual envionment with +```sh +pipenv shell +``` +and close it down with +```sh +exit +``` + +### Pre-Commit + +We highly encourage you to add [pre-commit](https://pre-commit.com/) to your development workflow in order to help us maintain a high-quality codebase. +We've included several pre-commit hooks in [`.pre-commmit-config.yaml`](/.pre-commit-config.yaml) that we consider to be essential for our purposes. + +pre-commit is installed automatically as a dependency when you set up your virtual environment with `pipenv`. +To add pre-commit to your workflow, run +```sh +pre-commit install +``` +From this point on, pre-commit should run whenever you make a commit. +If it catches any errors, it'll try to fix them automatically or ask you to fix them if it can't. +Make sure to fix all pre-commit errors before you commit. + +By default, pre-commit checks all modified files staged in your commit. +If you want to run pre-commit on the entire repo, including files that you haven't modified, run +```sh +pre-commit run --all-files +``` + +## Contributing to the API + +To make a contribution to the Pitt API, simply open a PR from your local fork of the Pitt API repo. + +Naturally, you should ensure that contributions work and are of high quality before you make a PR. +This includes making sure that your code compiles, passes all unit tests, and adhere to common style guidelines. + +### Unit Testing + +The Pitt API uses `pytest` for unit testing, and like pre-commit it's installed automatically when you set up `pipenv`. +To run all unit tests, run +```sh +pytest --cov=pittapi tests/ +``` + +### Code Styling + +We don't yet require our contributors to run any code formatters as part of our pre-commit workflow or our GitHub workflows. +However, to ensure consistent and readable code, we highly encourage you to use the `black` formatter to help your code adhere to [PEP 8](https://peps.python.org/pep-0008/) style guidelines. +`black` is also installed automatically when you set up `pipenv`. +To use it on the whole codebase, simply run +```sh +black . +``` + +Apart from general code styling, you should also document and commment your code based on general best practices. +This means that most if not all functions should have docstrings explaining their purpose, inputs, and outputs. +This also means that comments should primarily be written to clarify code whose function isn't immediately obvious to the average reader. +We don't have strict rules on the particular formatting of documentation and comments, but we may ask you to make changes to your documentation and comments during PR reviews. + +In terms of writing style, we expect you to write in a professional manner and follow proper commenting etiquette—pretend that this is a work environment and your comments are being reviewed by your manager and coworkers. + +### GitHub Workflows + +Note that we use automated GitHub workflows to check incoming PRs. +For you as a contributor, this means that GitHub will run `pytest` on your PR and verify that all unit tests are passing. +Make sure your code pass all workflows before requesting a review. diff --git a/README.md b/README.md index 5492ad9..adfa4f3 100644 --- a/README.md +++ b/README.md @@ -2,66 +2,60 @@ ![Build Status](https://travis-ci.org/Pitt-CSC/PittAPI.svg?branch=master) ![License](https://img.shields.io/badge/license-GPLv2-blue.svg) -![Python Version](https://img.shields.io/badge/python-%3E%3D%203.6-green.svg) +![Python Version](https://img.shields.io/badge/python-3.12-green.svg) -Made by Ritwik Gupta at the University of Pittsburgh in an effort to get -more open data from Pitt. +The Pitt API is an unofficial Python API made by Ritwik Gupta at the University of Pittsburgh in an effort to get more open data from Pitt. ## Usage examples ```python -from PittAPI import course, dining, lab, laundry, library, news, people, shuttle, textbook +from pittapi import course, dining, lab, laundry, library, news, people, shuttle, textbook ### Courses -# Will return a dictionary of all CS courses +# Returns a dictionary of all courses for a given subject cs_subject = course.get_subject_courses(subject='CS') courses_dict = cs_subject.courses -# Will return a list of sections of a course during a given term +# Returns a list of sections of a course during a given term cs_course = course.get_course_details(term='2244', subject='CS', course='1501') section_list = cs_course.sections ### Textbook -# Will return a list of dictionaries containing textbooks for a class -# term number comes from pitt.verbacompare.com +# Returns a list of dictionaries containing textbooks for a class +# Term number comes from pitt.verbacompare.com small_dict = textbook.get_textbook(term="3150", department="CS", course="445", instructor="RAMIREZ") ### Library -# Will return a dictionary containing results from query +# Returns a dictionary containing results from query big_dict = library.get_documents(query="computer") ### News -# Will return a list of dictionaries containing news from main news feed +# Returns a list of dictionaries containing news from main news feed medium_dict = news.get_news() ### Laundry -# Will return a dictionary with amount of washers and dryers -# in use vs. total washers and dryers at building +# Returns a dictionary with number of washers and dryers in use vs. +# total washers and dryers in building small_dict = laundry.get_status_simple(building_name="TOWERS") ### Computer Lab -# Will return a dictionary with status of the lab, and amount -# of machines with a certain OS +# Returns a dictionary with status of the lab and number of open machines small_dict = lab.get_status(lab_name="ALUMNI") ### Shuttle -# Will return a list of dictionaries containing routes of shuttles +# Returns a list of dictionaries containing routes of shuttles big_dict = shuttle.get_routes() ### People -# Will return a list of people based on the query +# Returns a list of people based on the query list_of_peeps = people.get_person(query="Smith") ### Dining -# Will return a dictionary of dictionaries containing each dining location, -# with its name, its open/closed status, and open times (if it exists) +# Returns a dictionary of dictionaries containing each dining location with its +# name and open/closed status medium_dict = dining.get_locations() -medium_dict = dining.get_locations_by_status(status="open") -medium_dict = dining.get_locations_by_status(status="closed") -# Will return a single dictionary of a dining location, -# with its name, its open/closed status, and open times (if it exists) -one = dining.get_location_by_name("taco_bell-schenley_cafe") -two = dining.get_location_by_name("cup_&_chaucer-hillman") +# Returns a dictionary of a dining location with its hours for a given day +hours = dining.get_location_hours("The Eatery", datetime.datetime(2024, 4, 12)) ``` ## Local Setup @@ -69,11 +63,10 @@ Install Python 3.12 and ``pipenv``. Run ``pipenv install`` and ``pipenv shell`` to create and setup the virtual environment. -## Tests +## Contributing -Run tests with - ``pytest --cov=pittapi tests/`` +Read our [contributing guidelines](/CONTRIBUTING.md) to learn how to contribute to the Pitt API. ## License -This project is licensed under the terms of the [GPLv2 license](/LICENSE) +This project is licensed under the terms of the [GPLv2 license](/LICENSE).