jupygrader 0.1.5

Grade Jupyter notebooks with Python scripts

---

Table of Contents

• Summary
• Key Features
• Installation
• Update Jupygrader
• Usage
  • Specifying the output directory
• Development
  • Test project
  • Build artifact
  • Publish to PyPI
• License

Summary

Jupygrader is a Python package for automated grading of Jupyter notebooks. It provides a framework to:

1. Execute and grade Jupyter notebooks containing student work and test cases
2. Generate comprehensive reports in multiple formats (JSON, HTML, TXT)
3. Extract student code from notebooks into separate Python files
4. Verify notebook integrity by computing hashes of test cases and submissions

Key Features

• Executes notebooks in a controlled, temporary environment
• Preserves the original notebook while creating graded versions
• Adds grader scripts to notebooks to evaluate test cases
• Generates detailed grading results including:
  • Individual test case scores
  • Overall scores and summaries
  • Success/failure status of each test
• Produces multiple output formats for instructors to review:
  • Graded notebook (.ipynb)
  • HTML report
  • JSON result data
  • Plaintext summary
  • Extracted Python code
• Includes metadata like Python version, platform, and file hashes for verification

Jupygrader is designed for educational settings where instructors need to grade student work in Jupyter notebooks, providing automated feedback while maintaining records of submissions and grading results.

Installation

pip install jupygrader

Update Jupygrader

pip install --upgrade jupygrader

Usage

Basic usage

import jupygrader

notebook_file_path = 'path/to/notebook.ipynb'
jupygrader.grade_notebook(notebook_file_path)

Supplying a pathlib.Path() object is supported.

import jupygrader
from pathlib import Path

notebook_path = Path('path/to/notebook.ipynb')
jupygrader.grade_notebook(notebook_path)

If the output_dir_path is not specified, the output files will be stored to the same directory as the notebook file.

Specifying the output directory

import jupygrader

notebook_path = 'path/to/notebook.ipynb'
output_path = 'path/to/output'

jupygrader.grade_notebook(
    notebook_path=notebook_path,
    output_path=output_path
)

Development

Test project

hatch uses pytest as the test runner. All tests are defined in the tests/ directory.

hatch test

Print a code coverage table by using the --cover flag.

hatch test --cover

Generate a code coverage report

hatch run test:cov-html

# Output:
# Wrote HTML report to htmlcov\index.html

Build artifact

This creates a distribution package, which can be uploaded to PyPI.

• Source distribution (sdist): dist\jupygrader-...tar.gz
• Wheel distribution (wheel): dist\jupygrader-...-py3-none-any.whl

hatch build

Installing the built package locally

pip install dist\jupygrader-...-py3-none-any.whl

Publish to PyPI

hatch publish

# username: __token__
# password: [your-token-value]

Alternatively, you can create a ~/.pypirc file with the token credentials.

~/.pypirc

[pypi]
username = __token__
password = [your-token-value]

License

jupygrader is distributed under the terms of the MIT license.