Tasks¶

Attendance¶

class guv.tasks.attendance.PdfAttendance(planning, uv, info)¶

PDF file of attendance sheets

This task generates a PDF file or a zip archive of PDF files containing attendance sheets.

Options

-h, --help : show this help message and exit
-t TITLE, --title TITLE : Specifies a title that will be used in the attendance sheets and the name of the generated file. By default, it is Attendance sheet.
-g GROUP, --group GROUP : Allows creating groups to make as many attendance sheets. You must specify a column from the central file effectif.xlsx.
-b, --blank : Do not display the names of the students (useful only with –group).
-c [COUNT ...], --count [COUNT ...] : Uses a list of staff instead of --group. The group names can be specified by --names. Otherwise, the group names are in the form Group 1, Group 2,…
-n [NAMES ...], --names [NAMES ...] : Specifies the names of the groups corresponding to --count. The list must be the same size as --count.
-e EXTRA, --extra EXTRA : Allows adding additional empty lines in addition to those already present induced by --group or set by --count.
--tiers-temps [TIERS_TEMPS] : Specifies the column for students placed in a dedicated room. If the column is not specified, None.
--latex-template PATH : Path to a custom LaTeX template file. If not specified, uses the default template.
--save-tex : Allows leaving the generated .tex files for possible modification.

Examples

Named attendance sheet:
```
guv pdf_attendance --title "Exam"
```

Named attendance sheets by lab group:

guv pdf_attendance --title "Lab exam" --group "Lab group"

Blank attendance sheets by lab group:

guv pdf_attendance --title "Lab exam" --group "Lab group" --blank

Named attendance sheets divided across three rooms:

guv pdf_attendance --title "Lab exam" --count 24 24 24 --name "Room 1" "Room 2" "Room 3"

class guv.tasks.attendance.PdfAttendanceFull(planning, uv, info)¶

Zip file of personalized attendance sheets by group and semester

Generates a zip file containing one attendance sheet per group for the entire semester. This makes it possible to have a single document for attendance tracking over the semester.

Options

-h, --help : show this help message and exit
--title TITLE : Specifies a title that will be used in the attendance sheets and the name of the generated file. By default, it is Attendance sheet.
-g GROUP, --group GROUP : Allows specifying a group column to make attendance sheets by groups.
-n SLOTS, --slots SLOTS : Allows specifying the number of sessions for the semester, i.e., the number of columns in the attendance sheet.
-t TEMPLATE, --template TEMPLATE : Template to set the name of successive sessions in the attendance sheet. By default, it is S{{number}}. The only supported keyword is number which starts at 1.
--latex-template PATH : Path to a custom LaTeX template file. If not specified, uses the default template.
--save-tex : Allows leaving the generated .tex files for possible modification.

Examples

guv pdf_attendance_full -n 7
guv pdf_attendance_full --group "Lab work" --template "Session {{number}}"

Grades¶

class guv.tasks.gradebook.XlsGradeBookGroup(planning, uv, info)¶

Excel grade file by group

This task generates an Excel file for grading by groups, avoiding the need to copy the same grade for each member of a group. Student groups are specified using the --group-by argument. One or more detailed marking schemes can be provided with the --marking-scheme argument.

The Excel file can also be split into multiple worksheets based on a column from the effectif.xlsx file, using the --worksheets argument. Within each group, students can be ordered according to the --order-by argument.

You can add extra columns to the first worksheet using the --extra-cols argument.

The path(s) to a detailed marking scheme file can be specified via --marking-scheme. If this argument is not used, the marking schemes will be requested interactively. The marking scheme file must be in YAML format.

The assignment structure is defined hierarchically, ending with a list of questions specifying the number of points awarded and optionally a scale (default is 1) and details (not included in the Excel file).

For example:

Exercise 1:
  Question 1:
    - points: 1
Problem:
  Part 1:
    Question 1:
      - points: 2
    Question 2:
      - points: 2
      - coeff: 3
    Question 3:
      - points: 2
      - details: |
          Difficult question, don't grade too harshly.
  Part 2:
    Question 1:
      - points: 2
    Question 2:
      - points: 2

Final grades can then be easily merged into the central file using the DOCS variable.

Options

-h, --help : show this help message and exit
--name NAME : Name of the grade sheet
--marking-scheme MARKING_SCHEME,[MARKING_SCHEME,...] : Files containing the detailed grading scales
-o colname, --order-by colname : Column used to order the names in each sheet
-w colname, --worksheets colname : Column used to group into multiple sheets
-e COL,[COL,...], --extra-cols COL,[COL,...] : Additional columns to include in the grade sheet
-g colname, --group-by colname : Group column used to grade groups of students

Examples

Grade file by lab group:

guv xls_grade_book_group \
  --name Assignment1 \
  --marking-scheme documents/marking_scheme1.yml \
  --group-by 'Lab group'

With the YAML file containing, for example:

Exercise 1:
  Question 1:
    - points: 1
Exercise 2:
  Question 1:
    - points: 1

class guv.tasks.gradebook.XlsGradeBookJury(planning, uv, info)¶

Excel file for managing a UV jury

This task generates an Excel file for managing a UV/UE jury. The optional --name argument allows you to specify a name for the file (default is jury).

The optional --config argument allows you to provide a configuration file with the data needed for the jury. If not provided, the configuration will be requested interactively.

More specifically, the created workbook contains two sheets. The first sheet includes:

the name, last name and email columns as specified in config.py from the central effectif.xlsx file,
the grades specified in the configuration file (via --config or interactively) that contribute to the final grade,
a special column named “Aggregated Grade” containing a grade out of 20, with a default formula using the weights and maximum scores from the configuration,
an automatically calculated ECTS grade (A–F) representing the aggregated grade based on percentiles,
other useful columns for the jury that are not grades.

The second sheet provides admission thresholds for each grade, the coefficients of each grade, the maximum scores, the thresholds used to convert the aggregated grade to an ECTS grade, and some statistics on grade distribution.

The configuration file must be in YAML format. The grades to be included are listed under the grades section. For each grade, you must specify a column name and optionally:

a passing grade (default: -1),
a coefficient (default: 1),
a maximum grade (default: 20),

Columns that are not grades can be listed under others. For example:

grades:
  - name: grade1
    passing grade: 8
    coefficient: 2
  - name: grade2
  - name: grade3
others:
  - info

The ECTS grade and aggregated grade can then be easily merged into the central file using the DOCS variable:

DOCS.aggregate_jury("generated/jury_gradebook.xlsx")

Options

-h, --help : show this help message and exit
--name NAME : Name of the grade sheet
--config CONFIG : Configuration file specifying the grades to use

Examples

Grade sheet with the quiz, median and final grade (with a threshold of 6), and the Branche info column:

guv xls_grade_book_jury --config documents/config_jury.yml

with the YAML file containing, for example:

grades:
  - name: quiz
    coefficient: 0.2
    maximum grade: 10
  - name: median
    coefficient: 0.3
  - name: final
    coefficient: 0.5
    passing grade: 6
others:
  - Branche

class guv.tasks.gradebook.XlsGradeBookNoGroup(planning, uv, info)¶

Excel file for individual grading

This task generates an Excel file to easily input individual grades using one or more detailed marking schemes.

The Excel file can also be split into multiple worksheets based on a column in the effectif.xlsx file using the --worksheets argument. Within each worksheet, students can be ordered using the --order-by argument. Additional columns can be included in the first sheet using the --extra-cols argument. The path(s) to one or more detailed marking schemes can be provided via the --marking-scheme argument. If this argument is not provided, the marking scheme(s) will be requested interactively.

The marking scheme file must be in YAML format. The structure of the assignment is specified hierarchically, with final-level lists containing the number of points assigned to each question, optionally followed by a scale (default is 1), and optional details (not shown in the Excel file).

For example:

Exercise 1:
  Question 1:
    - points: 1
Problem:
  Part 1:
    Question 1:
      - points: 2
    Question 2:
      - points: 2
      - scale: 3
    Question 3:
      - points: 2
      - details: |
          Difficult question, don't grade too harshly.
  Part 2:
    Question 1:
      - points: 2
    Question 2:
      - points: 2

Final grades can then be easily merged into the central file by configuring the DOCS variable.

Options

-h, --help : show this help message and exit
--name NAME : Name of the grade sheet
--marking-scheme MARKING_SCHEME,[MARKING_SCHEME,...] : Files containing the detailed grading scales
-o colname, --order-by colname : Column used to order the names in each sheet
-w colname, --worksheets colname : Column used to group into multiple sheets
-e COL,[COL,...], --extra-cols COL,[COL,...] : Additional columns to include in the grade sheet

Examples

Grade file with a marking scheme defined interactively, on a single Excel sheet:
```
guv xls_grade_book_no_group --name Exam1
```

Grade file for an assignment using a provided marking scheme, split by tutorial groups:

guv xls_grade_book_no_group \
  --name Exam1 \
  --marking-scheme documents/marking_scheme_exam1.yml \
  --worksheets "tutorial_groups"

with the YAML file containing, for example:

Exercise 1:
  Question 1:
    - points: 1
Exercise 2:
  Question 1:
    - points: 1

Grade file for an individual oral exam, split by exam day (column Exam day in effectif.xlsx), and ordered by speaking order (column Speaking order in effectif.xlsx):
```
guv xls_grade_book_no_group \
  --name OralExam1 \
  --marking-scheme documents/marking_scheme.yml \
  --worksheets "Exam day" \
  --order-by "Speaking order"
```
with the YAML file containing, for example:
```
Content:
Form:
```

Groups¶

class guv.tasks.moodle.CsvCreateGroups(planning, uv, info)¶

Random creation of student groups

This task creates a CSV file assigning students to groups, ready to be uploaded to Moodle. If the --grouping option is provided, groups are created within each subgroup.

The number of groups created (globally or per subgroup depending on --grouping) is controlled by one of the mutually exclusive options: --proportions, --group-size, or --num-groups:

--proportions: specify the group count via a list of proportions.
--group-size: specify the maximum size of each group.
--num-groups: specify the desired number of groups.

Group names are controlled using the --template option. The following substitutions are available in --template:

{title}: replaced by the title (first argument)
{grouping_name}: replaced by the subgroup name (if --grouping is used)
{group_name}: name of the current group (if --names is used)
#: sequential group number (used if --names is not specified)
@: sequential group letter (used if --names is not specified)

The --names option may be a list of names to use or a file containing names line by line. These are selected randomly if the --random flag is set.

The --global flag prevents the group name generation from resetting when switching subgroup (useful with --grouping).

By default, the student list is shuffled before creating contiguous groups. Use --ordered to create groups alphabetically. You may also provide a list of columns for sorting.

Group creation constraints:

--other-groups: names of existing group columns to avoid re-forming
--affinity-groups: names of group columns to try to preserve

Options

-h, --help : show this help message and exit
title : Name associated with the set of created groups. Included in the name of the created file and in the name of the created groups following the used template.
-G GROUPING, --grouping GROUPING : Pre-groups in which to make sub-groups
-n NUM_GROUPS, --num-groups NUM_GROUPS : Number of groups to create (per sub-groups if specified)
-s GROUP_SIZE, --group-size GROUP_SIZE : Group size: pairs, trios or more
-p PROPORTIONS [PROPORTIONS ...], --proportions PROPORTIONS [PROPORTIONS ...] : List of proportions to create the groups
-t _TEMPLATE, --template _TEMPLATE : Template to give names to the groups with {title}, {grouping_name} or {group_name}
-l NAMES [NAMES ...], --names NAMES [NAMES ...] : List of keywords to build the group names
-o [COL,...], --ordered [COL,...] : Order the list of students alphabetically or by columns
-g, --global : Do not reset the sequence of group names between each grouping
-r, --random : Randomly permute the group names
--other-groups COL,[COL,...] : List of columns of already formed groups that should not be reformed.
--affinity-groups COL,[COL,...] : List of columns of affinity groups.
--max-iter MAX_ITER : Maximum number of attempts to find groups with constraints (default 1000).

Examples

Create groups of 3 within each TD subgroup:

guv csv_create_groups Project1 -G TD --group-size 3

Create new trios in each TD subgroup, avoiding those already grouped in Project1:

guv csv_create_groups Project2 -G TD --group-size 3 --other-groups Project1

Split each TD subgroup in half using group names like D1i, D1ii, D2i, D2ii:

guv csv_create_groups HalfGroup -G TD --proportions .5 .5 --template '{grouping_name}{group_name}' --names i ii

Divide the class into two parts alphabetically with group names First and Second:

guv csv_create_groups Half --proportions .5 .5 --ordered --names First Second --template '{group_name}'

Notes

To be Moodle-compatible, the generated file does not include a column header. To merge this group file with the main dataset, use the kw_read argument as follows:

DOCS.aggregate(
    "generated/Project1_groups.csv",
    on="Email",
    kw_read={"header": None, "names": ["Email", "Group"]},
)

class guv.tasks.moodle.CsvGroups(planning, uv, info)¶

CSV files of groups from effectif.xlsx for Moodle

This task generates CSV files containing group assignments based on the data from effectif.xlsx, suitable for import into Moodle.

The --groups option allows you to select which group columns to export. By default, the exported columns are Lecture, Tutorial, and Practical work.

The --long option enables exporting TD/TP group names in a long format, i.e., TP1, TD1 instead of T1, D1.

The --single option allows generating a single combined file.

Options

-h, --help : show this help message and exit
-g COL,[COL,...], --groups COL,[COL,...] : List of groupings to consider via a column name. By default, the groupings Lecture, Tutorial and Practical work are used.
-l, --long : Use the names of Lecture/Tutorial/Practical work groups in long format, i.e., “TP1” and “TD1” instead of “T1” and “D1”
-s, --single : Create a single file

Examples

guv csv_groups --groups Project_Group

class guv.tasks.moodle.CsvGroupsGroupings(planning, uv, info)¶

CSV file of groups and groupings for Moodle import

This task generates a CSV file to create groups and groupings directly in Moodle.

You must specify:

the number of groups per grouping using the -g option,
the number of groupings using the -G option.

The name of the groupings is controlled by a pattern given via -F (default: D##_P1). The available substitutions are:

##: replaced by numbers,
@@: replaced by letters.

The name of the groups is controlled by a pattern given via -f (default: D##_P1_@). The available substitutions are:

#: replaced by numbers,
@: replaced by letters.

Options

-h, --help : show this help message and exit
-g N_GROUPS : Number of groups in each grouping
-f FORMAT : Format of the group name (default: D##_P1_@)
-G N_GROUPINGS : Number of different groupings
-F FORMAT : Format of the grouping name (default: D##_P1)

Examples

guv csv_groups_groupings -G 3 -F Grouping_P1 -g 14 -f D##_P1_@
guv csv_groups_groupings -G 2 -F Grouping_D1 -g 14 -f D1_P##_@
guv csv_groups_groupings -G 2 -F Grouping_D2 -g 14 -f D2_P##_@
guv csv_groups_groupings -G 2 -F Grouping_D3 -g 14 -f D3_P##_@

Students¶

class guv.tasks.students.SendEmail(planning, uv, info)¶

Send an email to each student.

The only required argument is a path to a file used as the email template. If the file does not exist, a default template is created. The template follows the Jinja2 format, and the available replacement variables for each student correspond to the column names in the effectif.xlsx file.

To enable email sending, you must set the LOGIN (SMTP server login), FROM_EMAIL (sender email address), SMTP_SERVER and PORT (default: 587) variables in the config.py file.

The task automatically tracks successfully sent emails in a hidden file. If the sending process is interrupted (network issue, spam filter, etc.), simply run the same command again and it will automatically skip already-sent emails and resume from where it left off. Use the --reset option to clear the tracking file and send emails to everyone again.

Use the --delay option to add a pause (in seconds) between each email. This is useful to avoid hitting rate limits on email servers.

Options

-h, --help : show this help message and exit
template : The path to a Jinja2 template
--delay DELAY : Number of seconds to wait between sending each email
--reset : Reset the list of sent emails and start fresh

Examples

Basic usage:

guv send_email documents/email_body

with documents/email_body containing:

Subject: Note

Hello {{ Name }},

You are part of the group {{ group_project }}.

Cheers,

guv

Wait 2 seconds between each email to avoid rate limiting:

guv send_email documents/email_body --delay 2

Clear the sent emails list and send to everyone again:

guv send_email documents/email_body --reset

Combine both options:

guv send_email documents/email_body --delay 1.5 --reset

class guv.tasks.students.ZoomBreakoutRooms(planning, uv, info)¶