unit-grader 1.0.13

Unit Conversion Grader a command-line interface (CLI) program that allows you to convert among units of measurement and grade the users response to determine the result.

Unit Conversion Grader

Overview

Unit Conversion Grader is a command-line interface (CLI) tool that allows teachers to grade the student's response for the result of converting among units of measurement.

Table of Contents

• Installation
• Main Features
• Future Tasks
• Dependencies
• Command Usage
• Advanced Usage
• Error Handling
• CI/CD Pipeline
• Documentation
• Contributing Guideline
• License
• Discussion and Help

Installation

Choose either stable release or development.

Python and Pip Installation

Please ensure you download and install python3.9+ and pip in sequence.

Checkout python official website and pip official website for details on download and installation.

Stable Release

• Run python -m pip install unit-grader --upgrade

• Test the CLI to verify the installation via running unit-grader -i 100 -f Kelvin -t Celsius -s -173.15

Development

• Install Python with version 3.9 or higher
• Follow official documentation to install PDM
• git clone https://github.com/souyang/unit-grader.git
• cd unit-grader
• pdm install
• python3 -m pip install -e .
• Test the CLI to verify the installation via running unit-grader -i 100 -f Kelvin -t Celsius -s -173.15

Main Features

• Teacher provides input-value(input numeric value), from-unit(input unit of measurement), to-unit (a target unit of value), student-response (student's numeric response) as inputs. Check out here for more details.
• System indicates the response is correct, incorrect or invalid.
• Student's response is correct if the response is equal to the answer after the response and the answer are both rounded to tenths place. Check out here for more details.
• Unit Testing code coverage is 100%. Commit will fail if code coverage is less than 100%.
• Sphinx is used in pre-commit hook and CI/CD pipeline for generating api documentation from source code.
• A CI/CD pipeline is created. CI will be triggered when a pull request is created with main as the target branch or a commit is merged to main. CD will be triggered after CI is successful.
• The executable deployment is on pypi and api documentation deployment is on Netlify
• Versioning and Verbose are both implemented.
• Pre-Commit hook is set up to ensure best code quality on grammar check, linting and formatting in every commit.
• Error reporting is provided to the end user when the output is invalid.
• Informational reporting is provided to the end user when the output is incorrect.
• User feedback mechanism is set up for future enhancement.
• Logging is enabled, user will see diagnose information when --verbose or -v as the option is set.
• Output is colorized for user to distinguish between different types of information.
• Progress Bar is enabled for long-running tasks.

Future Tasks

• Feature Flag Integration
• Interactive Mode Option
• Configuration Management
• Observeability
• Dockerization
• Localization

Dependencies

In the development of this project, we've leveraged the following third-party dependencies to enhance functionality and streamline development:

• PDM: A Python project management tool and package installer.
• Typer: A Python library for building command-line applications.
• Pre-Commit: A framework for managing and maintaining multi-language pre-commit hooks.
• codespell: A tool designed to catch spelling mistakes in code.
• Pytest: A testing framework for Python.
• Ruff: A linter and formatter for Python.
• Sphinx: A documentation generator for Python projects.
• bump-my-version: A small command line tool to simplify releasing software by updating all version strings in code by the correct increment and optionally commit and tag the changes.

For detailed information about each tool and why we chose them, refer to the detailed documentation.

Command Usage

Syntax

unit-grader -i <input-value> -f <from-unit> -t <to-unit> -s <student-response>

General Instructions

• Provide input-value, from-unit, to-unit, student-response as input.
• from-unit and to-unit must be in the same unit meansurement category.
• Expected output: correct, incorrect, invalid.
• Supported unit meansurement categories include temperature and volume.
• units supported in the temperature category: Kelvin, Celsius, Fahrenheit and Rankine.
• units supported in the volume category: liters, tablespoons, cubic-inches, cups, cubic-feet, gallons.
• Regarding volume units, tablespoons means us tablespoons, cubic-inches means cups means us cups, gallons means us gallons,
• The name of each unit is case-sensitive.
• Student's response must match the correct answer after both values are rounded to the tenths place.
• The rounding strategy follows round half to even (Banker's rounding). For example round(4.65, 1) == 4.6 and round(4.75, 1) == 4.8.

Examples

Sample Command	Output
unit-grader -i 50 -f Kelvin -t Celsius -s 30	incorrect
unit-grader -i 100 -f Kelvin -t Celsius -s -173.15	correct
unit-grader -i dog -f Kelvin -t Celsius -s -173.15	invalid

Get Help

• Run unit-grader --help to get information

Get CLI Version

unit-grader --version
unit-grader -V

Required input for grading response

  - `input-value (i)`: a numeric value
  - `from-unit (f)`: input unit of measure
  - `to-unit (t)`: target unit of measure
  - `student-response (s)` : student's numeric response

Sample use cases:

Sample Command	Input Value	Input Unit	Target Unit	Student Response	Output
unit-grader -i 50 -f Kelvin -t Celsius -s 30	50	Kelvin	Celsius	30	incorrect
unit-grader -i 50 -f Kelvin -t Celsius -s dog	50	Kelvin	Celsius	dog	incorrect
unit-grader -i 100 -f Kelvin -t Celsius -s -173.15	100	Kelvin	Celsius	-173.15	correct
unit-grader -i 100 -f cups -t liters -s 23.66	100	cups	liters	23.66	correct
unit-grader -i dog -f Kelvin -t Celsius -s -173.15	dog	Kelvin	Celsius	30	invalid
unit-grader -i 100 -f Kelvin -t gallons -s -173.15	100	Kelvin	gallons	30	invalid
unit-grader -i 100 -f dog -t gallons -s -173.15	100	dog	gallons	30	invalid
unit-grader -i 100 -f Kelvin -t dog -s -173.15	100	dog	gallons	30	invalid

Advanced Usage

Detail information in Verbose Mode

You can get detail information about your input in verbose mode for debugging purposes. For example, unit-grader -i 100 -f Kelvin -t dog -s -173.15 -v will print out the messages

Verbose mode is enabled.
input-value: 100
from_unit: Celsius
to_unit: Kelvin
student_response: 305.2

Error Handling

Use Case	Sample Command	Expected Message Reported to user
Input numeric value is not a number	unit-grader -i dog -f Kelvin -t Celsius -s -173.15	Input Error: dog as input_value needs to be a number. Please use --help to see valid options.
Input unit of measure is not supported or invalid	unit-grader -i 100 -f Test -t Celsius -s -173.15	Input Error: Test as from_unit is not supported. Select a conversion unit (Kelvin, Celsius, Fahrenheit, Rankine for temperature; liters, tablespoons, cubic-inches, cups, cubic-feet, gallons for volume). Please note that the unit is case-sensitive.
Target unit of measure is not supported or invalid	unit-grader -i 100 -f Test -t Celsius -s -173.15	Input Error: Test as from_unit is not supported. Select a conversion unit (Kelvin, Celsius, Fahrenheit, Rankine for temperature; liters, tablespoons, cubic-inches, cups, cubic-feet, gallons for volume). Please note that the unit is case-sensitive.
Input unit of measure and Target unit of measure are not in the same category	unit-grader -i 100 -f cups -t Celsius -s -173.15	Input Error: Ensure the selected conversion units match their respective categories for a valid conversion. Select a conversion unit (Kelvin, Celsius, Fahrenheit, Rankine for temperature; liters, tablespoons, cubic-inches, cups, cubic-feet, gallons for volume). Please note that the unit is case-sensitive.

CI/CD Pipeline

This project uses CI/CD pipelines to automate the testing, building, and deployment processes. The main CI/CD tool employed is [GitHub Actions], and the configuration is stored in [.github/workflows/main.yaml, .github/workflows/docs.yaml].

Continuous Integration (CI)

The CI pipeline is triggered on every push to the main branch or when pull requests are submitted. The CI process includes the following steps:

1. Linting and Formatting: The code is checked for style and formatting using Ruff.
2. Spelling Check: The code is spellchecked using codespell
3. Unit Tests: Unit tests are executed to ensure the code functions as expected and coverage reaches 100%. Pytest
4. Integration Test: Integration tests are executed to ensure the CLI App as expected. Typer.CliRunner

Continuous Deployment (CD)

The CD pipeline is triggered when changes are merged into the main branch, and it is responsible for deploying the application. The deployment process typically involves the following steps:

1. CLI Deployment to pypi.org: After app's version is bumped to the next patch version, the application is deployed to the pypi.

2. Document Generation and Deployment to Netlify: After CLI deployment is successful, api documentation is deployed to Netlify.

Documentation

This project's documentation is automatically generated using Sphinx. The documentation includes details about the API, code structure, and usage.

API Documentation

The API documentation is generated from docstrings in the source code. Sphinx extracts these docstrings and formats them into a user-friendly documentation website. To view the latest documentation, visit Documentation Link.

Doc Generation and Deployment in CI/CD Pipeline

The documentation is automatically generated and deployed after the code is deployed. The main steps in the CI/CD pipeline related to documentation are as follows:

1. Documentation Build: Sphinx is used to build the documentation from the source code.
2. Deployment: The documentation is deployed to Netlify. Please see here

Viewing the Documentation Locally

To build and view the documentation locally, follow these steps:

# Install Sphinx (if not already installed)
pdm install
# Build doc
pdm doc
# View doc
cd docs && open _build/html/index.html

Contributing Guideline

We welcome contributions! Please follow our contribution guidelines.

License

This project is licensed under the MIT License.

Discussion

Most development discussions take place on GitHub in this repo, via the GitHub issue tracker.

---

Go to Top