<p align="center">
<img src="https://github.com/subwaymatch/jupygrader/blob/main/docs/images/logo_jupygrader_with_text_240.png?raw=true" alt="Jupygrader Logo" width="240"/>
</p>
[](https://github.com/pypa/hatch)
[](https://app.codacy.com/gh/subwaymatch/jupygrader/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_grade)
[](https://pypi.org/project/jupygrader)
[](https://pypi.org/project/jupygrader)
---
## 📋 Table of Contents
- [📝 Summary](#-summary)
- [✨ Key Features](#-key-features)
- [📦 Installation](#-installation)
- [🔄 Update Jupygrader](#-update-jupygrader)
- [🚀 Usage](#-usage)
- [Basic usage](#basic-usage)
- [Specify the output directory](#specify-the-output-directory)
- [📒 Create an autogradable notebook](#-create-an-autogradable-notebook)
- [Code cell for learners](#code-cell-for-learners)
- [Graded test cases](#graded-test-cases)
- [Obfuscate test cases](#obfuscate-test-cases)
- [Add hidden test cases](#add-hidden-test-cases)
- [🔧 Utility functions](#-utility-functions)
- [Replace test cases](#replace-test-cases)
- [📄 License](#-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
```console
pip install jupygrader
```
## 🔄 Update Jupygrader
```console
pip install --upgrade jupygrader
```
## 🚀 Usage
### Basic usage
```python
import jupygrader
notebook_file_path = 'path/to/notebook.ipynb'
jupygrader.grade_notebooks(notebook_file_path)
```
Supplying a `pathlib.Path()` object is supported.
```python
import jupygrader
from pathlib import Path
notebook_path = Path('path/to/notebook.ipynb')
jupygrader.grade_notebooks(notebook_path)
```
If the `output_dir_path` is not specified, the output files will be stored to the same directory as the notebook file.
### Specify the output directory
```python
import jupygrader
jupygrader.grade_notebooks([{
"notebook_path": 'path/to/notebook.ipynb',
"output_path": 'path/to/output'
}])
```
## 📒 Create an autogradable notebook
The instructor authors only one "solution" notebook, which contains both the solution code and test cases for all graded parts.
Jupygrader provides a simple drag-and-drop interface to generate a student-facing notebook that removes the solution code and obfuscates test cases if required.
### Code cell for learners
Any code between `# YOUR CODE BEGINS` and `# YOUR CODE ENDS` are stripped in the student version.
```python
import pandas as pd
# YOUR CODE BEGINS
sample_series = pd.Series([-20, -10, 10, 20])
# YOUR CODE ENDS
print(sample_series)
```
nbgrader syntax (`### BEGIN SOLUTION`, `### END SOLUTION`) is also supported.
```python
import pandas as pd
### BEGIN SOLUTION
sample_series = pd.Series([-20, -10, 10, 20])
### END SOLUTION
print(sample_series)
```
In the student-facing notebook, the code cell will look like:
```python
import pandas as pd
# YOUR CODE BEGINS
# YOUR CODE ENDS
print(sample_series)
```
### Graded test cases
A graded test case requires a test case name and an assigned point value.
- The `_test_case` variable should store the name of the test case.
- The `_points` variable should store the number of points, either as an integer or a float.
```python
_test_case = 'create-a-pandas-series'
_points = 2
pd.testing.assert_series_equal(sample_series, pd.Series([-20, -10, 10, 20]))
```
### Obfuscate test cases
If you want to prevent learners from seeing the test case code, you can optionally set \_obfuscate = True to base64-encode the test cases.
Note that this provides only basic obfuscation, and students can easily decode the string to reveal the original code.
We may introduce an encryption method in the future.
**Instructor notebook**
```python
_test_case = 'create-a-pandas-series'
_points = 2
_obfuscate = True
pd.testing.assert_series_equal(sample_series, pd.Series([-20, -10, 10, 20]))
```
**Student notebook**
```python
# DO NOT CHANGE THE CODE IN THIS CELL
_test_case = 'create-a-pandas-series'
_points = 2
_obfuscate = True
import base64 as _b64
_64 = _b64.b64decode('cGQudGVzdGluZy5hc3NlcnRfc2VyaWVzX2VxdWFsKHNhbXBsZV9zZXJpZXMsIHBkLlNlcmllcyhbLT\
IwLCAtMTAsIDEwLCAyMF0pKQ==')
eval(compile(_64, '<string>', 'exec'))
```
### Add hidden test cases
Hidden test cases only run while grading.
#### Original test case
```python
_test_case = 'create-a-pandas-series'
_points = 2
### BEGIN HIDDEN TESTS
pd.testing.assert_series_equal(sample_series, pd.Series([-20, -10, 10, 20]))
### END HIDDEN TESTS
```
#### Converted (before obfuscation)
```python
_test_case = 'create-a-pandas-series'
_points = 2
if 'is_jupygrader_env' in globals():
pd.testing.assert_series_equal(sample_series, pd.Series([-20, -10, 10, 20]))
```
## 🔧 Utility functions
### Replace test cases
If a test case needs to be updated before grading, use the `jupygrader.replace_test_case()` function.
This is useful when learners have already submitted their Jupyter notebooks, but the original notebook contains an incorrect test case.
```python
nb = nbformat.read(notebook_path, as_version=4)
jupygrader.replace_test_case(nb, 'q1', '_test_case = "q1"\n_points = 6\n\nassert my_var == 3')
```
Below is a sample code snippet demonstrating how to replace multiple test cases using a dictionary.
```python
nb = nbformat.read(notebook_path, as_version=4)
new_test_cases = {
'test_case_01': '_test_case = "test_case_01"\n_points = 6\n\npass',
'test_case_02': '_test_case = "test_case_02"\n_points = 3\n\npass'
}
for tc_name, new_tc_code in new_test_cases.items():
jupygrader.replace_test_case(nb, tc_name, new_tc_code)
```
## 📄 License
`jupygrader` is distributed under the terms of the [MIT](https://spdx.org/licenses/MIT.html) license.
Raw data
{
"_id": null,
"home_page": null,
"name": "jupygrader",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "autograder, autograding, grading, jupyter",
"author": null,
"author_email": "Ye Joo Park <subwaymatch@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/f8/ba/99d875a85379b42eb0b6fdd3f21ce81a61ffb4538ea3b494a0c8f20dc5c3/jupygrader-0.3.0.tar.gz",
"platform": null,
"description": "<p align=\"center\">\n <img src=\"https://github.com/subwaymatch/jupygrader/blob/main/docs/images/logo_jupygrader_with_text_240.png?raw=true\" alt=\"Jupygrader Logo\" width=\"240\"/>\n</p>\n\n[](https://github.com/pypa/hatch)\n[](https://app.codacy.com/gh/subwaymatch/jupygrader/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_grade)\n\n[](https://pypi.org/project/jupygrader)\n[](https://pypi.org/project/jupygrader)\n\n---\n\n## \ud83d\udccb Table of Contents\n\n- [\ud83d\udcdd Summary](#-summary)\n- [\u2728 Key Features](#-key-features)\n- [\ud83d\udce6 Installation](#-installation)\n- [\ud83d\udd04 Update Jupygrader](#-update-jupygrader)\n- [\ud83d\ude80 Usage](#-usage)\n - [Basic usage](#basic-usage)\n - [Specify the output directory](#specify-the-output-directory)\n- [\ud83d\udcd2 Create an autogradable notebook](#-create-an-autogradable-notebook)\n - [Code cell for learners](#code-cell-for-learners)\n - [Graded test cases](#graded-test-cases)\n - [Obfuscate test cases](#obfuscate-test-cases)\n - [Add hidden test cases](#add-hidden-test-cases)\n- [\ud83d\udd27 Utility functions](#-utility-functions)\n - [Replace test cases](#replace-test-cases)\n- [\ud83d\udcc4 License](#-license)\n\n## \ud83d\udcdd Summary\n\nJupygrader is a Python package for automated grading of Jupyter notebooks. It provides a framework to:\n\n1. **Execute and grade Jupyter notebooks** containing student work and test cases\n2. **Generate comprehensive reports** in multiple formats (JSON, HTML, TXT)\n3. **Extract student code** from notebooks into separate Python files\n4. **Verify notebook integrity** by computing hashes of test cases and submissions\n\n## \u2728 Key Features\n\n- Executes notebooks in a controlled, temporary environment\n- Preserves the original notebook while creating graded versions\n- Adds grader scripts to notebooks to evaluate test cases\n- Generates detailed grading results including:\n - Individual test case scores\n - Overall scores and summaries\n - Success/failure status of each test\n- Produces multiple output formats for instructors to review:\n - Graded notebook (.ipynb)\n - HTML report\n - JSON result data\n - Plaintext summary\n - Extracted Python code\n- Includes metadata like Python version, platform, and file hashes for verification\n\nJupygrader 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.\n\n## \ud83d\udce6 Installation\n\n```console\npip install jupygrader\n```\n\n## \ud83d\udd04 Update Jupygrader\n\n```console\npip install --upgrade jupygrader\n```\n\n## \ud83d\ude80 Usage\n\n### Basic usage\n\n```python\nimport jupygrader\n\nnotebook_file_path = 'path/to/notebook.ipynb'\njupygrader.grade_notebooks(notebook_file_path)\n```\n\nSupplying a `pathlib.Path()` object is supported.\n\n```python\nimport jupygrader\nfrom pathlib import Path\n\nnotebook_path = Path('path/to/notebook.ipynb')\njupygrader.grade_notebooks(notebook_path)\n```\n\nIf the `output_dir_path` is not specified, the output files will be stored to the same directory as the notebook file.\n\n### Specify the output directory\n\n```python\nimport jupygrader\n\njupygrader.grade_notebooks([{\n \"notebook_path\": 'path/to/notebook.ipynb',\n \"output_path\": 'path/to/output'\n}])\n```\n\n## \ud83d\udcd2 Create an autogradable notebook\n\nThe instructor authors only one \"solution\" notebook, which contains both the solution code and test cases for all graded parts.\n\nJupygrader provides a simple drag-and-drop interface to generate a student-facing notebook that removes the solution code and obfuscates test cases if required.\n\n### Code cell for learners\n\nAny code between `# YOUR CODE BEGINS` and `# YOUR CODE ENDS` are stripped in the student version.\n\n```python\nimport pandas as pd\n\n# YOUR CODE BEGINS\nsample_series = pd.Series([-20, -10, 10, 20])\n# YOUR CODE ENDS\n\nprint(sample_series)\n```\n\nnbgrader syntax (`### BEGIN SOLUTION`, `### END SOLUTION`) is also supported.\n\n```python\nimport pandas as pd\n\n### BEGIN SOLUTION\nsample_series = pd.Series([-20, -10, 10, 20])\n### END SOLUTION\n\nprint(sample_series)\n```\n\nIn the student-facing notebook, the code cell will look like:\n\n```python\nimport pandas as pd\n\n# YOUR CODE BEGINS\n\n# YOUR CODE ENDS\n\nprint(sample_series)\n```\n\n### Graded test cases\n\nA graded test case requires a test case name and an assigned point value.\n\n- The `_test_case` variable should store the name of the test case.\n- The `_points` variable should store the number of points, either as an integer or a float.\n\n```python\n_test_case = 'create-a-pandas-series'\n_points = 2\n\npd.testing.assert_series_equal(sample_series, pd.Series([-20, -10, 10, 20]))\n```\n\n### Obfuscate test cases\n\nIf you want to prevent learners from seeing the test case code, you can optionally set \\_obfuscate = True to base64-encode the test cases.\n\nNote that this provides only basic obfuscation, and students can easily decode the string to reveal the original code.\n\nWe may introduce an encryption method in the future.\n\n**Instructor notebook**\n\n```python\n_test_case = 'create-a-pandas-series'\n_points = 2\n_obfuscate = True\n\npd.testing.assert_series_equal(sample_series, pd.Series([-20, -10, 10, 20]))\n```\n\n**Student notebook**\n\n```python\n# DO NOT CHANGE THE CODE IN THIS CELL\n_test_case = 'create-a-pandas-series'\n_points = 2\n_obfuscate = True\n\nimport base64 as _b64\n_64 = _b64.b64decode('cGQudGVzdGluZy5hc3NlcnRfc2VyaWVzX2VxdWFsKHNhbXBsZV9zZXJpZXMsIHBkLlNlcmllcyhbLT\\\nIwLCAtMTAsIDEwLCAyMF0pKQ==')\neval(compile(_64, '<string>', 'exec'))\n```\n\n### Add hidden test cases\n\nHidden test cases only run while grading.\n\n#### Original test case\n\n```python\n_test_case = 'create-a-pandas-series'\n_points = 2\n\n### BEGIN HIDDEN TESTS\npd.testing.assert_series_equal(sample_series, pd.Series([-20, -10, 10, 20]))\n### END HIDDEN TESTS\n```\n\n#### Converted (before obfuscation)\n\n```python\n_test_case = 'create-a-pandas-series'\n_points = 2\n\nif 'is_jupygrader_env' in globals():\n pd.testing.assert_series_equal(sample_series, pd.Series([-20, -10, 10, 20]))\n```\n\n## \ud83d\udd27 Utility functions\n\n### Replace test cases\n\nIf a test case needs to be updated before grading, use the `jupygrader.replace_test_case()` function.\n\nThis is useful when learners have already submitted their Jupyter notebooks, but the original notebook contains an incorrect test case.\n\n```python\nnb = nbformat.read(notebook_path, as_version=4)\n\njupygrader.replace_test_case(nb, 'q1', '_test_case = \"q1\"\\n_points = 6\\n\\nassert my_var == 3')\n```\n\nBelow is a sample code snippet demonstrating how to replace multiple test cases using a dictionary.\n\n```python\nnb = nbformat.read(notebook_path, as_version=4)\n\nnew_test_cases = {\n 'test_case_01': '_test_case = \"test_case_01\"\\n_points = 6\\n\\npass',\n 'test_case_02': '_test_case = \"test_case_02\"\\n_points = 3\\n\\npass'\n}\n\nfor tc_name, new_tc_code in new_test_cases.items():\n jupygrader.replace_test_case(nb, tc_name, new_tc_code)\n```\n\n## \ud83d\udcc4 License\n\n`jupygrader` is distributed under the terms of the [MIT](https://spdx.org/licenses/MIT.html) license.\n",
"bugtrack_url": null,
"license": null,
"summary": "Grade Jupyter notebooks with Python scripts",
"version": "0.3.0",
"project_urls": {
"Documentation": "https://github.com/subwaymatch/jupygrader#readme",
"Source": "https://github.com/subwaymatch/jupygrader"
},
"split_keywords": [
"autograder",
" autograding",
" grading",
" jupyter"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "28def3c81aa49fe44e50e8deccb9fbb8d3dce7b2f95d21e5423484fa831c6284",
"md5": "20ea1c4a4efdfaf19773873346cd1b64",
"sha256": "ae81d95a32de60dcfae6d8d039714fc207d1c6ff70474f4f5fbc76e918f409c4"
},
"downloads": -1,
"filename": "jupygrader-0.3.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "20ea1c4a4efdfaf19773873346cd1b64",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 31131,
"upload_time": "2025-10-13T12:15:14",
"upload_time_iso_8601": "2025-10-13T12:15:14.236255Z",
"url": "https://files.pythonhosted.org/packages/28/de/f3c81aa49fe44e50e8deccb9fbb8d3dce7b2f95d21e5423484fa831c6284/jupygrader-0.3.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "f8ba99d875a85379b42eb0b6fdd3f21ce81a61ffb4538ea3b494a0c8f20dc5c3",
"md5": "628f8ce5af17a3e2cd3b3384c710365f",
"sha256": "7fcc3fa7f036adae2cd43e558abb9a827c63a11af62cf5e551c67d55c19b1bd2"
},
"downloads": -1,
"filename": "jupygrader-0.3.0.tar.gz",
"has_sig": false,
"md5_digest": "628f8ce5af17a3e2cd3b3384c710365f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 14667885,
"upload_time": "2025-10-13T12:15:15",
"upload_time_iso_8601": "2025-10-13T12:15:15.945209Z",
"url": "https://files.pythonhosted.org/packages/f8/ba/99d875a85379b42eb0b6fdd3f21ce81a61ffb4538ea3b494a0c8f20dc5c3/jupygrader-0.3.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-13 12:15:15",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "subwaymatch",
"github_project": "jupygrader#readme",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "jupygrader"
}
JSON
