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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.