0
# Assignment & Grading
1

2
Assignment creation, submission handling, grading workflows, rubrics, and comprehensive grade management. The Assignment class and related grading functionality provide complete control over assessment and evaluation in Canvas.
3

4
## Capabilities
5

6
### Assignment Management
7

8
Create, edit, and manage course assignments with comprehensive configuration options.
9

10
```python { .api }
11
class Assignment(CanvasObject):
12
    def edit(self, **kwargs) -> Assignment:
13
        """
14
        Edit assignment properties.
15
        
16
        Parameters:
17
        - name: Assignment name
18
        - description: Assignment description (HTML)
19
        - due_at: Due date (ISO 8601 format)
20
        - unlock_at: Date when assignment becomes available
21
        - lock_at: Date when assignment locks
22
        - points_possible: Maximum points for assignment
23
        - grading_type: Grading type ('pass_fail', 'percent', 'letter_grade', 'gpa_scale', 'points')
24
        - submission_types: List of allowed submission types
25
        - allowed_extensions: List of allowed file extensions
26
        - turnitin_enabled: Enable Turnitin plagiarism detection
27
        - group_category_id: ID for group assignments
28
        - peer_reviews: Enable peer reviews
29
        - automatic_peer_reviews: Automatically assign peer reviews
30
        - notify_of_update: Notify students of changes
31
        - grade_group_students_individually: Grade group members individually
32
        
33
        Returns:
34
        Updated Assignment object
35
        """
36
    
37
    def delete(self, **kwargs) -> Assignment:
38
        """Delete the assignment."""
39
```
40

41
### Submission Management
42

43
Handle student submissions, grading, and feedback.
44

45
```python { .api }
46
def get_submissions(self, **kwargs) -> PaginatedList[Submission]:
47
    """
48
    Get all submissions for the assignment.
49
    
50
    Parameters:
51
    - include: Additional data ('submission_history', 'submission_comments', 'rubric_assessment', 'assignment', 'visibility', 'course', 'user', 'group')
52
    - grouped: Group submissions by student
53
    
54
    Returns:
55
    Paginated list of Submission objects
56
    """
57

58
def get_submission(self, user, **kwargs) -> Submission:
59
    """
60
    Get a single submission for a specific user.
61
    
62
    Parameters:
63
    - user: User object or user ID
64
    - include: Additional data to include
65
    
66
    Returns:
67
    Submission object
68
    """
69

70
def get_gradeable_students(self, **kwargs) -> PaginatedList[User]:
71
    """
72
    Get students who can be graded for this assignment.
73
    
74
    Returns:
75
    Paginated list of User objects
76
    """
77
```
78

79
### Assignment Overrides
80

81
Create date and access overrides for specific students or sections.
82

83
```python { .api }
84
def create_override(self, assignment_override: dict, **kwargs) -> AssignmentOverride:
85
    """
86
    Create an assignment override.
87
    
88
    Parameters:
89
    - assignment_override: Dictionary with override attributes:
90
        - student_ids: List of student IDs (for individual overrides)
91
        - group_id: Group ID (for group overrides)  
92
        - course_section_id: Section ID (for section overrides)
93
        - title: Override title
94
        - due_at: Override due date
95
        - unlock_at: Override unlock date
96
        - lock_at: Override lock date
97
    
98
    Returns:
99
    AssignmentOverride object
100
    """
101

102
def get_overrides(self, **kwargs) -> PaginatedList[AssignmentOverride]:
103
    """
104
    List assignment overrides.
105
    
106
    Returns:
107
    Paginated list of AssignmentOverride objects
108
    """
109
```
110

111
### Peer Reviews
112

113
Manage peer review assignments and workflows.
114

115
```python { .api }
116
def get_peer_reviews(self, **kwargs) -> PaginatedList[PeerReview]:
117
    """
118
    List peer reviews for the assignment.
119
    
120
    Parameters:
121
    - include: Additional data ('submission_comments', 'user')
122
    
123
    Returns:
124
    Paginated list of PeerReview objects
125
    """
126

127
def create_peer_review(self, user_id: int, **kwargs) -> PeerReview:
128
    """
129
    Create a peer review assignment.
130
    
131
    Parameters:
132
    - user_id: ID of user who will do the review
133
    - user_id: ID of user whose work will be reviewed (in kwargs)
134
    
135
    Returns:
136
    PeerReview object
137
    """
138
```
139

140
### Grade History and Auditing
141

142
Track grade changes and maintain audit trails.
143

144
```python { .api }
145
def get_grade_change_events(self, **kwargs) -> PaginatedList[dict]:
146
    """
147
    Get grade change events for the assignment.
148
    
149
    Parameters:
150
    - start_time: Start date for events
151
    - end_time: End date for events
152
    
153
    Returns:
154
    Paginated list of grade change event dictionaries
155
    """
156
```
157

158
## Submission Class
159

160
Handle individual student submissions and grading.
161

162
```python { .api }
163
class Submission(CanvasObject):
164
    def edit(self, **kwargs) -> Submission:
165
        """
166
        Edit/grade a submission.
167
        
168
        Parameters:
169
        - comment: Text comment for the submission
170
        - submission: Dictionary with submission updates:
171
            - posted_grade: Grade to assign
172
            - excuse: Whether to excuse the submission
173
            - late_policy_status: Late policy status
174
            - seconds_late_override: Override for seconds late calculation
175
        - rubric_assessment: Rubric assessment data
176
        - include: Additional data to include in response
177
        
178
        Returns:
179
        Updated Submission object
180
        """
181
    
182
    def mark_as_read(self, **kwargs) -> bool:
183
        """Mark submission as read."""
184
    
185
    def mark_as_unread(self, **kwargs) -> bool:
186
        """Mark submission as unread."""
187
```
188

189
## Assignment Groups
190

191
Organize assignments into weighted categories.
192

193
```python { .api }
194
class AssignmentGroup(CanvasObject):
195
    def edit(self, **kwargs) -> AssignmentGroup:
196
        """
197
        Edit assignment group properties.
198
        
199
        Parameters:
200
        - name: Group name
201
        - weight: Weight for weighted grading (0-100)
202
        - drop_lowest: Number of lowest scores to drop
203
        - drop_highest: Number of highest scores to drop
204
        - never_drop: List of assignment IDs to never drop
205
        
206
        Returns:
207
        Updated AssignmentGroup object
208
        """
209
    
210
    def delete(self, **kwargs) -> AssignmentGroup:
211
        """Delete the assignment group."""
212
    
213
    def get_assignments(self, **kwargs) -> PaginatedList[Assignment]:
214
        """Get assignments in this group."""
215
```
216

217
## Rubrics
218

219
Create and manage rubrics for consistent grading.
220

221
```python { .api }
222
class Rubric(CanvasObject):
223
    def edit(self, **kwargs) -> Rubric:
224
        """
225
        Edit rubric criteria and settings.
226
        
227
        Parameters:
228
        - title: Rubric title
229
        - points_possible: Total points possible
230
        - criteria: List of rubric criteria dictionaries
231
        - free_form_criterion_comments: Allow free-form comments
232
        
233
        Returns:
234
        Updated Rubric object
235
        """
236
    
237
    def delete(self, **kwargs) -> Rubric:
238
        """Delete the rubric."""
239

240
class RubricAssociation(CanvasObject):
241
    def edit(self, **kwargs) -> RubricAssociation:
242
        """
243
        Edit rubric association settings.
244
        
245
        Parameters:
246
        - rubric_association: Dictionary with association settings:
247
            - hide_score_total: Hide total score from students
248
            - use_for_grading: Use rubric for grading
249
            - hide_points: Hide points from students
250
            - hide_outcome_results: Hide outcome results
251
        
252
        Returns:
253
        Updated RubricAssociation object
254
        """
255
    
256
    def delete(self, **kwargs) -> RubricAssociation:
257
        """Delete the rubric association."""
258
```
259

260
## Custom Gradebook Columns
261

262
Add custom data columns to the gradebook.
263

264
```python { .api }
265
class CustomGradebookColumn(CanvasObject):
266
    def edit(self, **kwargs) -> CustomGradebookColumn:
267
        """
268
        Edit custom gradebook column.
269
        
270
        Parameters:
271
        - title: Column title
272
        - position: Column position
273
        - hidden: Whether column is hidden
274
        - teacher_notes: Whether this is a teacher notes column
275
        - read_only: Whether column is read-only
276
        
277
        Returns:
278
        Updated CustomGradebookColumn object
279
        """
280
    
281
    def delete(self, **kwargs) -> CustomGradebookColumn:
282
        """Delete the custom gradebook column."""
283
    
284
    def get_column_data(self, **kwargs) -> PaginatedList[ColumnData]:
285
        """Get data entries for this column."""
286
    
287
    def update_column_data(self, user_id: int, content: str, **kwargs) -> ColumnData:
288
        """
289
        Update data for a specific user in this column.
290
        
291
        Parameters:
292
        - user_id: User ID
293
        - content: Data content for the cell
294
        
295
        Returns:
296
        ColumnData object
297
        """
298
```
299

300
## Grading Standards
301

302
Define custom grading scales and letter grades.
303

304
```python { .api }
305
class GradingStandard(CanvasObject):
306
    def edit(self, **kwargs) -> GradingStandard:
307
        """
308
        Edit grading standard.
309
        
310
        Parameters:
311
        - title: Grading standard title
312
        - grading_scheme: List of grade/percentage mappings
313
        
314
        Returns:
315
        Updated GradingStandard object
316
        """
317
    
318
    def delete(self, **kwargs) -> GradingStandard:
319
        """Delete the grading standard."""
320
```
321

322
## Usage Examples
323

324
### Creating and Configuring Assignments
325

326
```python
327
from canvasapi import Canvas
328

329
canvas = Canvas("https://canvas.example.com", "your-token")
330
course = canvas.get_course(12345)
331

332
# Create a comprehensive assignment
333
assignment = course.create_assignment({
334
    'name': 'Research Paper',
335
    'description': '<p>Write a 10-page research paper on the assigned topic.</p>',
336
    'due_at': '2024-12-15T23:59:59Z',
337
    'unlock_at': '2024-11-01T00:00:00Z',
338
    'lock_at': '2024-12-16T00:00:00Z',
339
    'points_possible': 100,
340
    'grading_type': 'points',
341
    'submission_types': ['online_upload', 'online_text_entry'],
342
    'allowed_extensions': ['pdf', 'doc', 'docx'],
343
    'peer_reviews': True,
344
    'automatic_peer_reviews': True,
345
    'peer_review_count': 2,
346
    'peer_reviews_assign_at': '2024-12-16T00:00:01Z'
347
})
348

349
# Create assignment overrides for different sections
350
override = assignment.create_override({
351
    'course_section_id': 456,
352
    'title': 'Section A Extension',
353
    'due_at': '2024-12-17T23:59:59Z'
354
})
355

356
# Create override for specific students
357
student_override = assignment.create_override({
358
    'student_ids': [123, 456, 789],
359
    'title': 'Accommodation Extension',
360
    'due_at': '2024-12-20T23:59:59Z'
361
})
362
```
363

364
### Grading Submissions
365

366
```python
367
# Get all submissions for grading
368
submissions = assignment.get_submissions(
369
    include=['submission_comments', 'rubric_assessment', 'user']
370
)
371

372
for submission in submissions:
373
    print(f"Grading {submission.user['name']}")
374
    
375
    # Grade the submission
376
    graded_submission = submission.edit(
377
        submission={'posted_grade': 85},
378
        comment='Good work! Consider expanding on the conclusion.'
379
    )
380
    
381
    print(f"Graded: {graded_submission.grade}")
382

383
# Get a specific student's submission
384
student_submission = assignment.get_submission(
385
    user=student_id,
386
    include=['submission_comments', 'rubric_assessment']
387
)
388

389
# Grade with detailed rubric assessment
390
rubric_assessment = {
391
    'criterion_123': {
392
        'points': 20,
393
        'comments': 'Excellent analysis'
394
    },
395
    'criterion_456': {
396
        'points': 15,
397
        'comments': 'Could use more supporting evidence'
398
    }
399
}
400

401
graded = student_submission.edit(
402
    submission={'posted_grade': 87},
403
    rubric_assessment=rubric_assessment,
404
    comment='Well done overall. See rubric for specific feedback.'
405
)
406
```
407

408
### Managing Assignment Groups
409

410
```python
411
# Create assignment groups with different weights
412
homework_group = course.create_assignment_group(
413
    name="Homework",
414
    weight=30,
415
    drop_lowest=2  # Drop 2 lowest homework scores
416
)
417

418
exam_group = course.create_assignment_group(
419
    name="Exams", 
420
    weight=50,
421
    drop_lowest=0
422
)
423

424
participation_group = course.create_assignment_group(
425
    name="Participation",
426
    weight=20
427
)
428

429
# Update an assignment group
430
updated_group = homework_group.edit(
431
    weight=25,
432
    drop_lowest=3
433
)
434
```
435

436
### Creating and Using Rubrics
437

438
```python
439
# Create a rubric for the assignment
440
rubric_data = {
441
    'title': 'Research Paper Rubric',
442
    'points_possible': 100,
443
    'criteria': [
444
        {
445
            'description': 'Thesis and Argument',
446
            'points': 30,
447
            'ratings': [
448
                {'description': 'Excellent', 'points': 30},
449
                {'description': 'Good', 'points': 25},
450
                {'description': 'Satisfactory', 'points': 20},
451
                {'description': 'Needs Improvement', 'points': 15}
452
            ]
453
        },
454
        {
455
            'description': 'Research and Sources', 
456
            'points': 25,
457
            'ratings': [
458
                {'description': 'Excellent', 'points': 25},
459
                {'description': 'Good', 'points': 20},
460
                {'description': 'Satisfactory', 'points': 15},
461
                {'description': 'Needs Improvement', 'points': 10}
462
            ]
463
        },
464
        {
465
            'description': 'Writing Quality',
466
            'points': 25,
467
            'ratings': [
468
                {'description': 'Excellent', 'points': 25},
469
                {'description': 'Good', 'points': 20},
470
                {'description': 'Satisfactory', 'points': 15},
471
                {'description': 'Needs Improvement', 'points': 10}
472
            ]
473
        },
474
        {
475
            'description': 'Format and Citations',
476
            'points': 20,
477
            'ratings': [
478
                {'description': 'Excellent', 'points': 20},
479
                {'description': 'Good', 'points': 16},
480
                {'description': 'Satisfactory', 'points': 12},
481
                {'description': 'Needs Improvement', 'points': 8}
482
            ]
483
        }
484
    ]
485
}
486

487
rubric = course.create_rubric(rubric_data)
488

489
# Associate rubric with assignment
490
association = assignment.create_rubric_association(
491
    rubric_id=rubric.id,
492
    rubric_association={
493
        'use_for_grading': True,
494
        'hide_score_total': False,
495
        'purpose': 'grading'
496
    }
497
)
498
```
499

500
### Custom Gradebook Columns
501

502
```python
503
# Create a custom gradebook column for participation tracking
504
participation_column = course.create_custom_gradebook_column(
505
    column={
506
        'title': 'Class Participation',
507
        'position': 1,
508
        'hidden': False,
509
        'teacher_notes': False
510
    }
511
)
512

513
# Update participation data for students
514
students = course.get_users(enrollment_type='student')
515
for student in students:
516
    participation_column.update_column_data(
517
        user_id=student.id,
518
        content='Excellent participation in discussions'
519
    )
520

521
# Get all column data
522
column_data = participation_column.get_column_data()
523
for data in column_data:
524
    print(f"Student {data.user_id}: {data.content}")
525
```