diff --git a/README.md b/README.md index d91afd9..d374c61 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,5 @@ # BBGradebookOrganiser + Blackboard Gradebook Organiser ## Description @@ -8,6 +9,7 @@ The submission files are organised per student, by extracting the student number Additionally, after organising submissions, you can inspect all submitted files to detect duplicated files from different submissions/students by generating and comparing SHA256 hashes. See section [Inspect submissions](#inspect-submissions-mag) for details. ### Features + - Extracts, and organises per student, the content of submitted compressed files with extensions: .zip, .rar, .7z - Detects invalid/corrupt files - Doesn't extract macOS system generated files (ignores directory *__MACOSX* inside the compressed file) @@ -21,6 +23,7 @@ Additionally, after organising submissions, you can inspect all submitted files ## Instructions ### Download gradebook + - Go to the course page on Blackboard - Go to *Grade Centre -> Full Grade Centre* - Find assignment and click on the arrow for more options, and select *Assignment File Download* @@ -28,9 +31,11 @@ Additionally, after organising submissions, you can inspect all submitted files - Wait for the generated download link to appear, and click to download ### Extract gradebook + - Extract the downloaded gradebook in a new directory inside *BB_gradebooks* ### Run script + - Before running the script for the first time, install the required packages - `python -m pip install -r requirements.txt` - If running on Linux/Mac, you also need to have *unrar* installed in order to be able to extract .rar files @@ -41,6 +46,7 @@ Additionally, after organising submissions, you can inspect all submitted files - While running, the script displays on the terminal information and stats about the gradebook submissions and files ### Post-run + - All submission files can be found - organised in directories per student number - in directory *BB_submissions* under the sub-directory named after the gradebook name provided when running the script - e.g. `python organise_gradebook.py GRADEBOOK_DIR_NAME` creates the directory *GRADEBOOK_DIR_NAME* inside *BB_submissions* - Each student directory contains the student's extracted and individually submitted files, and the text file generated by Blackboard with the submission (which also contains any comments left by the student) @@ -50,13 +56,17 @@ Additionally, after organising submissions, you can inspect all submitted files - any invalid/corrupt compressed files are moved into folder *\_\_BAD\_\_* inside the gradebook directory ## Inspect submissions :mag: -### Description + +### Information + - Generates SHA256 hashes for each submitted file, and outputs list to CSV file - Can exclude files from hashing, if provided with a CSV file listing the file names - Compares the generated hashes and finds any duplicate hashes - ignores duplicates if they are by the same student/submission - Finds all files with a duplicated hash and outputs them to CSV file with the following information: Student ID, file path, file name (without path), SHA256 hash - Further inspection and filtering needs to be done manually, depending on the submission files + ### Usage + - For this feature you also need to install the pandas package - `python -m pip install pandas` - Usage: `python inspect_submissions.py GRADEBOOK_DIR_NAME`