`au` Command Line Reference

This page provides documentation for the au command line tool. This tool should be available on all platforms after installation.

Most of the commands assume that you will specify either a ROOT_DIR (most will be the directory into which you will clone or have cloned all student assignment repositories) or a STUDENT_DIR (one student assignment repository). In most cases, if you leave off this argument, the tools assume that you intend to treat the present working directory as the ROOT_DIR or STUDENT_DIR.

Note also that to prevent unintentional loss of work, by default the tools will not overwrite any potentially modified directories or files. You will be given the opportunity to force changes, but the default is to be non-destructive. Likewise, prior to potentially long tasks, by default the tool will prompt for confirmation. This too can be overridden if and as needed.

The tools are intended primarily to be run interactively and thus will prompt for missing information. However, it is possible to pass all required arguments and options from the command line if batch / unattended operation is desired.

The documentation below is identical to that found by running the the specified command with the --help switch.

au assignment

Commands for working with any GitHub Classroom Assignment.

Usage:

au assignment [OPTIONS] COMMAND [ARGS]...

Options:

  --help  Show this message and exit.

Subcommands

accepted: List all students that have accepted an assignment.
clone-all: Clone all student repos for an assignment into ROOT_DIR.
commit-all: Commit and push all "dirty" student repos in ROOT_DIR.
config: Create or change settings for ASSIGNMENT_DIR.
info: Display details for an assignment.
rename-roster: Rename subdirectories to contain students' real names.
time-details: Show submission times for the assignment in ROOT_DIR.

au assignment accepted

List all students that have accepted an assignment.

Usage:

au assignment accepted [OPTIONS]

Options:

  --assignment-id INTEGER  The integer id for the assignment. If not provided,
                           will try to read a value stored in settings. Will
                           prompt for for an assignment interactively if not
                           provided. An assignment is REQUIRED to run this
                           command.
  --roster FILE            A GitHub Classroom roster file, typically named
                           `classroom_roster.csv`. Will prompt for the file if
                           not provided.
  --help                   Show this message and exit.

au assignment clone-all

Clone all student repos for an assignment into ROOT_DIR.

This command will use the specified assignment to query GitHub Classroom for all accepted assignments. For each, it will run the following logic:

if repository directory exists in ROOT_DIR
    if update flag is set
        pull updates from GitHub
    else
        skip
else
    if repository has submissions
        clone repository into ROOT_DIR
    else
        skip

If no roster is provided, directory names will match the students' GitHub login names. If a GitHub Classroom roster is provided using the --roster option and a student name match can be found in the roster, then the directory will be named as follows:

[student_name]@[login_name]

All commas, spaces, and invalid characters in the student name will be replaced with underscores. for example:

York_Paul@ptyork

If the --preserve-prefix flag is set, then the prefix (also called 'slug') will be added to all assignments, as they are in GitHub. This will insure that all student assignment directory names are unique.

If ROOT_DIR is not provided, then the current working directory will be assumed.

Usage:

au assignment clone-all [OPTIONS] [ROOT_DIR]

Options:

  --assignment-id INTEGER  The integer id for the assignment. If not provided,
                           will try to read a value stored in settings. Will
                           prompt for for an assignment interactively if not
                           provided. An assignment is REQUIRED to run this
                           command.
  --roster FILE            A GitHub Classroom roster file, typically named
                           `classroom_roster.csv`. If not provided, will try
                           to read a value stored in settings. Will prompt for
                           the file if not provided.
  --preserve-prefix        set to preserve the prefix (slug) string common to
                           all repositories
  -u, --update             set to pull changes to existing repositories
  -y, --skip-confirm       set to bypass confirmation and overwrite existing
                           CSV
  -p, --preview            set to show changes without actually making them
  -d, --debug              set to enable detailed output
  -q, --quiet              set to reduce output to errors only
  --help                   Show this message and exit.

au assignment commit-all

Commit and push all "dirty" student repos in ROOT_DIR.

Iterate over all immediate subdirectories of ROOT_DIR. If it is found to be a Git repository and if it contains changes, then:

+ add all changes
+ commit using --message
+ push all changes to the remote

If ROOT_DIR is not provided, then the current working directory will be assumed.

If the --message argument is not provided, the script will prompt for one.

Usage:

au assignment commit-all [OPTIONS] [ROOT_DIR]

Options:

  -m, --message TEXT  the message to apply to all `git commit` calls
  -p, --preview       set to show changes without actually making them
  -d, --debug         set to enable detailed output
  -q, --quiet         set to reduce output to errors only
  --help              Show this message and exit.

au assignment config

Create or change settings for ASSIGNMENT_DIR.

Most commands that accept configuration parameters such as an assignment-id or roster file will save this to a local configuration file. However, this command is useful if you need to change the settings or if you are pre-configuring an assignment directory prior to cloning student submissions.

If not specified, ASSIGNMENT_DIR defaults to the current directory.

Usage:

au assignment config [OPTIONS] [ASSIGNMENT_DIR]

Options:

  --assignment-id INTEGER  The integer id for the assignment. Will prompt for
                           for an assignment interactively if not provided. An
                           assignment is REQUIRED to run this command.
  --roster FILE            A GitHub Classroom roster file, typically named
                           `classroom_roster.csv`. Will prompt for the file if
                           not provided.
  --help                   Show this message and exit.

au assignment info

Display details for an assignment.

Details include the due date, assignment type, and a count of accepted and submitted assignments, among others.

If executed inside of a configured assignment directory, it will display the information for the configured assignment. If not, it will prompt the user to select a classroom and assignment.

Usage:

au assignment info [OPTIONS]

Options:

  --assignment-id INTEGER  The integer id for the assignment. If not provided,
                           will try to read a value stored in settings. Will
                           prompt for for an assignment interactively if not
                           provided. An assignment is REQUIRED to run this
                           command.
  --help                   Show this message and exit.

au assignment rename-roster

Rename subdirectories to contain students' real names.

This is generally only useful if student repositories have already been cloned using other means. This command uses the same naming logic as does au classroom clone-all.

This will rename the subdirectories in ROOT_DIR to contain a students real name by matching a the Github ID from the classroom roster to a folder name. Any potentially unsafe characters, as well as commas and spaces, are replaced with an underscore (_). Any characters after the matching github id are preserved in order to prevent possible duplicate directory names.

The purpose is to help with finding and sorting directories by the real names of students.

The resulting name will be:

[real name]@[github id][suffix]/

\For example:

York_Paul@ptyork/

Directories of students that are not in the roster are skipped entirely. If the student's name is found in the directory name, it is likewise skipped as it is assumed that the directory has already been renamed.

If ROOT_DIR is not provided, then the current working directory will be assumed.

Usage:

au assignment rename-roster [OPTIONS] [ROOT_DIR]

Options:

  --roster FILE      A GitHub Classroom roster file, typically named
                     `classroom_roster.csv`. If not provided, will try to read
                     a value stored in settings. Will prompt for the file if
                     not provided. A roster is REQUIRED to run this command.
  --preserve-prefix  set to preserve the prefix (slug) string common to all
                     repositories
  -p, --preview      set to show changes without actually making them
  -d, --debug        set to enable detailed output
  -q, --quiet        set to reduce output to errors only
  --help             Show this message and exit.

au assignment time-details

Show submission times for the assignment in ROOT_DIR.

Details include how long the assignment took to complete and how late (if at all) an assignment was.

If ROOT_DIR is not provided, then the current working directory will be assumed.

Usage:

au assignment time-details [OPTIONS] [ROOT_DIR]

Options:

  --assignment-id INTEGER  The integer id for the assignment. If not provided,
                           will try to read a value stored in settings. Will
                           prompt for for an assignment interactively if not
                           provided.
  --roster FILE            A GitHub Classroom roster file, typically named
                           `classroom_roster.csv`. If not provided, will try
                           to read a value stored in settings. Will prompt for
                           the file if not provided.
  --late-only              set to only show late students
  -d, --debug              set to enable detailed output
  -q, --quiet              set to reduce output to errors only
  --help                   Show this message and exit.

au python

Commands for working with Python assignments.

Usage:

au python [OPTIONS] COMMAND [ARGS]...

Options:

  --help  Show this message and exit.

Subcommands

eval-assignment: Run automated grading tests on a single student directory.
gen-feedback: Generate a feedback file for a single assignment.
gen-grades-csv: Generate grades CSV file from feedback files in ROOT_DIR.
quick-grade: Run tests and generate feedback for all subdirectories of ROOT_DIR.

au python eval-assignment

Run automated grading tests on a single student directory.

Usage:

au python eval-assignment [OPTIONS] STUDENT_DIR

Options:

  --assignment-id INTEGER  The integer id for the assignment. If not provided,
                           will try to read a value stored in settings. Will
                           prompt for for an assignment interactively if not
                           provided.
  --roster FILE            A GitHub Classroom roster file, typically named
                           `classroom_roster.csv`. If not provided, will try
                           to read a value stored in settings. Will prompt for
                           the file if not provided.
  --student-name TEXT      If no roster is provided, you can provide the name
                           of the student. If neither is provided, the name
                           will just be STUDENT_DIR.
  -d, --debug              set to enable detailed output
  -q, --quiet              set to reduce output to errors only
  --help                   Show this message and exit.

au python gen-feedback

Generate a feedback file for a single assignment.

Usage:

au python gen-feedback [OPTIONS] STUDENT_DIR

Options:

  --feedback-filename TEXT     name of markdown file to generate
  -o, --overwrite-feedback     set to override default behavior of not
                               overwriting feedback files
  -max, --max-score FLOAT      the maximum score for this assignment
                               [default: 10]
  -ptw, --pytest-weight FLOAT  the weight to apply to pytest when calculating
                               the overall score (0 to 1)  [default: 1.0]
  -plw, --pylint-weight FLOAT  the weight to apply to pylint when calculating
                               the overall score (0 to 1)  [default: 0.0]
  -d, --debug                  set to enable detailed output
  -q, --quiet                  set to reduce output to errors only
  --help                       Show this message and exit.

au python gen-grades-csv

Generate grades CSV file from feedback files in ROOT_DIR.

Usage:

au python gen-grades-csv [OPTIONS] [ROOT_DIR]

Options:

  --feedback-filename TEXT  name of markdown file to generate
  --grades-filename TEXT    name of CSV file containing student feedback
  -y, --skip-confirm        set to bypass confirmation and overwrite existing
                            CSV
  -d, --debug               set to enable detailed output
  -q, --quiet               set to reduce output to errors only
  --help                    Show this message and exit.

au python quick-grade

Run tests and generate feedback for all subdirectories of ROOT_DIR.

This is essentially the same as:

for SUBDIR in ROOT_DIR
    au python eval-assignment SUBDIR
    au python gen-feedback SUBDIR

If ROOT_DIR is not provided, then the current working directory will be assumed.

Usage:

au python quick-grade [OPTIONS] [ROOT_DIR]

Options:

  --assignment-id INTEGER      The integer id for the assignment. If not
                               provided, will try to read a value stored in
                               settings. Will prompt for for an assignment
                               interactively if not provided.
  --roster FILE                A GitHub Classroom roster file, typically named
                               `classroom_roster.csv`. If not provided, will
                               try to read a value stored in settings. Will
                               prompt for the file if not provided.
  -se, --skip_eval             set to bypass running the evaluations
  -sf, --skip_feedback         set to bypass generating feedback
  --feedback-filename TEXT     name of markdown file to generate  [default:
                               FEEDBACK.md]
  -o, --overwrite-feedback     set to override default behavior of not
                               overwriting feedback files
  -max, --max-score FLOAT      the maximum score for this assignment
                               [default: 10]
  -ptw, --pytest-weight FLOAT  the weight to apply to pytest when calculating
                               the overall score (0 to 1)  [default: 1.0]
  -plw, --pylint-weight FLOAT  the weight to apply to pylint when calculating
                               the overall score (0 to 1)  [default: 0.0]
  -d, --debug                  set to enable detailed output
  -q, --quiet                  set to reduce output to errors only
  --help                       Show this message and exit.

au sql

Commands for working with SQL assignments.

Usage:

au sql [OPTIONS] COMMAND [ARGS]...

Options:

  --help  Show this message and exit.

Subcommands

cat-sql:

au sql cat-sql

Concatenate all text from *.sql files and show them in a pager.

Usage:

au sql cat-sql [OPTIONS] PATH

Options:

  -pc, --preserve-comments  Disable removal of single-line comments.
  --help                    Show this message and exit.

au Command Line Reference

au assignment

au assignment accepted

au assignment clone-all

au assignment commit-all

au assignment config

au assignment info

au assignment rename-roster

au assignment time-details

au python

au python eval-assignment

au python gen-feedback

au python gen-grades-csv

au python quick-grade

au sql

au sql cat-sql

`au` Command Line Reference