Skip to main content

Chalk classroom manager

Chalk is a command line tool to grade quizzes and keep track of students and grades. Everything lives in plain text files in a directory: a roster, one directory per quiz, the submissions and the grades. Chalk grades what was answered outside of it (a paper exam, a Moodle or Google Forms export, GitHub Classroom repositories), either automatically or by hand.

Chalk can share a repository with a codehood course: both read the same roster.csv, and chalk codehood grades writes the quiz grades to the grades.csv that codehood publishes. When the classroom sits in a directory with a codehood.toml, chalk init and chalk quiz create add their paths (chalk.toml, each quiz directory) to the course's .codehoodignore, so codehood push skips them.

Installation

uvx chalk  # or pipx run chalk

Chalk needs Python 3.13 or newer.

Getting started

chalk init                          # creates chalk.toml and roster.csv
chalk quiz create p1 --questions 3  # creates p1/conf.yaml
# write the questions in p1/questions/ and the answers in p1/submissions.csv
chalk autograde p1/q1               # grades q1 with its answer key
chalk grade p1/q3                   # grades q3 by hand
chalk show p1 --grades              # shows the grades table

Directory structure

classroom/
├── chalk.toml           # classroom configuration
├── roster.csv           # students
├── conf.py              # optional: final_grade() and other hooks
└── p1/                  # a quiz: any directory with a conf.yaml
    ├── conf.yaml        # name, dates, weight and chalk settings of questions
    ├── questions/       # question documents in the mdq format
    │   ├── q1.md
    │   └── q2.yaml
    ├── q3/              # files of question q3: autograder script, template/
    ├── submissions.csv  # one row per student, one column per question
    └── grades.csv       # written by chalk

Questions

Objective questions are mdq documents in <quiz>/questions/, named after the question id. The document may be Markdown (.md, .mdq.md) or the parsed form of mdq in YAML or JSON. It holds the stem, the choices and the answer key, and chalk grades responses with mdq.

---
id: q1
title: Capital
---

What is the capital of Brazil?

- [*] [df] Brasília
- [ ] [sp] São Paulo

conf.yaml lists the questions in order and keeps what is specific to chalk:

name: Exam 1
weight: 1
questions:
  - id: q1             # mdq document in questions/q1.md
  - id: q2
    value: 2           # weight of the question in the quiz
  - id: q3             # no document: an open question, graded by hand
  - id: q4
    type: text         # free text, graded by an autograder script or a regex
    format: python
  - id: q5
    type: repo         # the answer is a directory, graded by a script
  - id: q6
    source: ../questions/recursion/01.md  # mdq document from elsewhere

source points to an mdq file outside <quiz>/questions/, relative to the quiz directory. Use it to reuse questions from the questions/ bank of a codehood course without copying them. The quiz refers to the question by the id of its entry, whatever id the file declares.

Answers in submissions.csv follow the mdq responses: the id of a choice (or its text) for multiple choice, a list of ids such as a, c or [a, c] for multiple selection, a number for numeric questions and text for the others.

id,q1,q2,q3
1234,df,"a, c",An open answer

Roster

roster.csv uses the columns that codehood also uses. Every column is optional, and other columns are kept.

school_id,username,name,email,github,status
1234,jdoe,John Doe,john.doe@example.com,jdoe,active

The student id is school_id. Set student_id = "username" (or another column) in the [chalk] section of chalk.toml to use another column. Rosters with an id column instead of school_id also work.

Documentation

uv sync --group dev
uv run mkdocs serve

Metadata

Release files for chalk-classroom 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for chalk-classroom 0.1.0
File Size Uploaded Provenance Actions
chalk_classroom-0.1.0.tar.gz 117.1 kB Without provenance Details for chalk_classroom-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for chalk-classroom 0.1.0
File Interpreter ABI Platform Actions
chalk_classroom-0.1.0-py3-none-any.whl Python 3 none any Details for chalk_classroom-0.1.0-py3-none-any.whl

Total release size: 262.2 kB

Release files / chalk_classroom-0.1.0.tar.gz

Download URL chalk_classroom-0.1.0.tar.gz
Size 117.1 kB
Tags Source
SHA-256 checksum
How to use checksums
603127460a4f1f0f9f77c975554bf7167cc2ccd1feb68bb669c250d3f01b63c1
BLAKE2b-256 checksum
How to use checksums
5f238de466535abfcf1f79367cb9c6a7ad31ee61998b4464f12e6b9bffcacc15
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.8 {"installer":{"name":"uv","version":"0.13.8","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / chalk_classroom-0.1.0-py3-none-any.whl

Download URL chalk_classroom-0.1.0-py3-none-any.whl
Size 145.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
47404ef8352e8a10afda23ebedac9fe52124582839b054b0eab0c42a7f943fcf
BLAKE2b-256 checksum
How to use checksums
48279358e25125bf1b917da6b5bba354a3d987b55483ca2cec3432502112256d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.8 {"installer":{"name":"uv","version":"0.13.8","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Security for chalk-classroom 0.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page