gradescope-utils

0.5.0 verified Fri May 01 auth: no python

Utilities for building Gradescope autograders. Current version 0.5.0, released June 2022. The library provides decorators and a JSON test runner to streamline autograder development. Low release cadence.

pip install gradescope-utils

Common errors

error ImportError: cannot import name 'JSONTestRunner' from 'gradescope_utils' ↓

cause Installed version is too old (pre 0.1).

fix

Upgrade to latest: pip install --upgrade gradescope-utils

error ModuleNotFoundError: No module named 'gradescope_utils' ↓

cause Package not installed or installed in a different environment.

fix

Run: pip install gradescope-utils

error AttributeError: module 'gradescope_utils' has no attribute 'weight' ↓

cause Importing decorator directly from top-level package instead of submodule.

fix

Use: from gradescope_utils.decorators import weight

Warnings

gotcha The @number decorator argument must be a string. In version 0.3.1 it was converted to string automatically, but in earlier versions you had to pass a string explicitly. ↓

fix Update to >=0.3.1 or pass number as a string.

gotcha JSONTestRunner's visibility parameter only works if the test suite top-level visibility is not overridden by individual test visibilities. Use 'visible', 'after_published', or 'hidden'. ↓

fix Set visibility on the runner and ensure individual tests don't override incorrectly.

gotcha The @partial_credit decorator requires you to set the score via the test case's 'score' attribute; it does not automatically compute partial credit. ↓

fix Inside the test method, set self.score to the desired score (float or int).

gotcha The check_submitted_files utility checks for file existence only; it does not check file content or directory structure beyond the base path. ↓

fix For deeper checks, implement custom validation.

Imports

JSONTestRunner

wrong

from gradescope_utils.runner import JSONTestRunner

correct

from gradescope_utils import JSONTestRunner

JSONTestRunner is exposed at the top-level package, not in a submodule.

weight

wrong

from gradescope_utils import weight

correct

from gradescope_utils.decorators import weight

Decorators must be imported from the decorators submodule.

number

wrong

from gradescope_utils.decorators.weight import number

correct

from gradescope_utils.decorators import number

number is a separate decorator in the same module.

partial_credit

from gradescope_utils.decorators import partial_credit

visibility

from gradescope_utils.decorators import visibility

leaderboard
```
from gradescope_utils.decorators import leaderboard
```
Leaderboard decorator is available; leaderboard functionality must be enabled on Gradescope.

check_submitted_files

wrong

from gradescope_utils import check_submitted_files

correct

from gradescope_utils.autograder_utils import check_submitted_files

Utility function is in autograder_utils submodule.

Quickstart

Basic autograder using unittest and gradescope-utils decorators.

import unittest
from gradescope_utils import JSONTestRunner
from gradescope_utils.decorators import weight

class TestHello(unittest.TestCase):
    @weight(1)
    def test_hello(self):
        self.assertEqual('hello', 'hello')

if __name__ == '__main__':
    suite = unittest.defaultTestLoader.discover('tests')
    JSONTestRunner(visibility='visible').run(suite)