Package: unit-grader
Unit Conversion GraderOverviewUnit Conversion Graderis 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 ContentsInstallationMain FeaturesFuture TasksDependenciesCommand UsageAdvanced UsageError HandlingCI/CD PipelineDocumentationContributing GuidelineLicenseDiscussion and HelpInstallationChoose eitherstable releaseordevelopment.Python and Pip InstallationPlease ensure you download and install python3.9+ and pip in sequence.Checkoutpython official websiteandpip official websitefor details on download and installation.Stable ReleaseRunpython -m pip install unit-grader --upgradeTest the CLI to verify the installation via runningunit-grader -i 100  -f Kelvin -t Celsius -s -173.15DevelopmentInstall Python with version 3.9 or higherFollowofficial documentationto install PDMgit clone https://github.com/souyang/unit-grader.gitcd unit-graderpdm installpython3 -m pip install -e .Test the CLI to verify the installation via runningunit-grader -i 100  -f Kelvin -t Celsius -s -173.15Main FeaturesTeacher providesinput-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 outherefor more details.System indicates the response iscorrect,incorrectorinvalid.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 outherefor more details.Unit Testing code coverage is 100%. Commit will fail if code coverage is less than 100%.Sphinxis 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 withmainas the target branch or a commit is merged tomain. CD will be triggered after CI is successful.The executable deployment is onpypiand api documentation deployment is onNetlifyVersioning 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 isinvalid.Informational reporting is provided to the end user when the output isincorrect.User feedback mechanism is set up for future enhancement.Logging is enabled, user will see diagnose information when--verboseor-vas 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 TasksFeature Flag IntegrationInteractive Mode OptionConfiguration ManagementObserveabilityDockerizationLocalizationDependenciesIn 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 thedetailed documentation.Command UsageSyntaxunit-grader-i<input-value>-f<from-unit>-t<to-unit>-s<student-response>General InstructionsProvideinput-value,from-unit,to-unit,student-responseas input.from-unitandto-unitmust be in the same unit meansurement category.Expected output:correct,incorrect,invalid.Supported unit meansurement categories includetemperatureandvolume.units supported in thetemperaturecategory:Kelvin,Celsius,FahrenheitandRankine.units supported in thevolumecategory:liters,tablespoons,cubic-inches,cups,cubic-feet,gallons.Regarding volume units,tablespoonsmeansus tablespoons, cubic-inches meanscupsmeansus cups, gallons meansus 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.ExamplesSample CommandOutputunit-grader -i 50  -f Kelvin -t Celsius -s 30incorrectunit-grader -i 100  -f Kelvin -t Celsius -s -173.15correctunit-grader -i dog  -f Kelvin -t Celsius -s -173.15invalidGet HelpRununit-grader --helpto get informationGet CLI Versionunit-grader --version
unit-grader -VRequired 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 responseSample use cases:Sample CommandInput ValueInput UnitTarget UnitStudent ResponseOutputunit-grader -i 50  -f Kelvin -t Celsius -s 3050KelvinCelsius30incorrectunit-grader -i 50  -f Kelvin -t Celsius -s dog50KelvinCelsiusdogincorrectunit-grader -i 100  -f Kelvin -t Celsius -s -173.15100KelvinCelsius-173.15correctunit-grader -i 100  -f cups -t liters -s 23.66100cupsliters23.66correctunit-grader -i dog  -f Kelvin -t Celsius -s -173.15dogKelvinCelsius30invalidunit-grader -i 100  -f Kelvin -t gallons -s -173.15100Kelvingallons30invalidunit-grader -i 100  -f dog -t gallons -s -173.15100doggallons30invalidunit-grader -i 100  -f Kelvin -t dog -s -173.15100doggallons30invalidAdvanced UsageDetail information in Verbose ModeYou 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 -vwill print out the messagesVerbose mode is enabled.
input-value: 100
from_unit: Celsius
to_unit: Kelvin
student_response: 305.2Error HandlingUse CaseSample CommandExpected Message Reported to userInput numeric valueis not a numberunit-grader -i dog  -f Kelvin -t Celsius -s -173.15Input Error: dog as input_value needs to be a number. Please use --help to see valid options.Input unit of measureis not supported or invalidunit-grader -i 100  -f Test -t Celsius -s -173.15Input 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 measureis not supported or invalidunit-grader -i 100  -f Test -t Celsius -s -173.15Input 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 measureandTarget unit of measureare not in the same categoryunit-grader -i 100  -f cups -t Celsius -s -173.15Input 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 PipelineThis 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:Linting and Formatting: The code is checked for style and formatting usingRuff.Spelling Check: The code is spellchecked usingcodespellUnit Tests: Unit tests are executed to ensure the code functions as expected and coverage reaches 100%.PytestIntegration Test: Integration tests are executed to ensure the CLI App as expected.Typer.CliRunnerContinuous 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:CLI Deployment to pypi.org: After app's version is bumped to the next patch version, the application is deployed to thepypi.Document Generation and Deployment to Netlify: After CLI deployment is successful, api documentation is deployed toNetlify.DocumentationThis project's documentation is automatically generated usingSphinx. The documentation includes details about the API, code structure, and usage.API DocumentationThe API documentation is generated from docstrings in the source code.Sphinxextracts these docstrings and formats them into a user-friendly documentation website. To view the latest documentation, visitDocumentation Link.Doc Generation and Deployment in CI/CD PipelineThe 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:Documentation Build:Sphinxis used to build the documentation from the source code.Deployment: The documentation is deployed to Netlify. Please seehereViewing the Documentation LocallyTo build and view the documentation locally, follow these steps:# Install Sphinx (if not already installed)pdminstall# Build docpdmdoc# View doccddocs&&open_build/html/index.htmlContributing GuidelineWe welcome contributions! Please follow ourcontribution guidelines.LicenseThis project is licensed under theMIT License.DiscussionMost development discussions take place on GitHub in this repo, via theGitHub issue tracker.Go to Top