tessl/pypi-canvasapi
API wrapper for the Canvas LMS
—
Pending
Quality
Pending
Does it follow best practices?
Impact
Pending
No eval scenarios have been run
assignments-grading.mddocs/
Assignment & Grading
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.
Capabilities
Assignment Management
Create, edit, and manage course assignments with comprehensive configuration options.
class Assignment(CanvasObject):
def edit(self, **kwargs) -> Assignment:
"""
Edit assignment properties.
Parameters:
- name: Assignment name
- description: Assignment description (HTML)
- due_at: Due date (ISO 8601 format)
- unlock_at: Date when assignment becomes available
- lock_at: Date when assignment locks
- points_possible: Maximum points for assignment
- grading_type: Grading type ('pass_fail', 'percent', 'letter_grade', 'gpa_scale', 'points')
- submission_types: List of allowed submission types
- allowed_extensions: List of allowed file extensions
- turnitin_enabled: Enable Turnitin plagiarism detection
- group_category_id: ID for group assignments
- peer_reviews: Enable peer reviews
- automatic_peer_reviews: Automatically assign peer reviews
- notify_of_update: Notify students of changes
- grade_group_students_individually: Grade group members individually
Returns:
Updated Assignment object
"""
def delete(self, **kwargs) -> Assignment:
"""Delete the assignment."""Submission Management
Handle student submissions, grading, and feedback.
def get_submissions(self, **kwargs) -> PaginatedList[Submission]:
"""
Get all submissions for the assignment.
Parameters:
- include: Additional data ('submission_history', 'submission_comments', 'rubric_assessment', 'assignment', 'visibility', 'course', 'user', 'group')
- grouped: Group submissions by student
Returns:
Paginated list of Submission objects
"""
def get_submission(self, user, **kwargs) -> Submission:
"""
Get a single submission for a specific user.
Parameters:
- user: User object or user ID
- include: Additional data to include
Returns:
Submission object
"""
def get_gradeable_students(self, **kwargs) -> PaginatedList[User]:
"""
Get students who can be graded for this assignment.
Returns:
Paginated list of User objects
"""Assignment Overrides
Create date and access overrides for specific students or sections.
def create_override(self, assignment_override: dict, **kwargs) -> AssignmentOverride:
"""
Create an assignment override.
Parameters:
- assignment_override: Dictionary with override attributes:
- student_ids: List of student IDs (for individual overrides)
- group_id: Group ID (for group overrides)
- course_section_id: Section ID (for section overrides)
- title: Override title
- due_at: Override due date
- unlock_at: Override unlock date
- lock_at: Override lock date
Returns:
AssignmentOverride object
"""
def get_overrides(self, **kwargs) -> PaginatedList[AssignmentOverride]:
"""
List assignment overrides.
Returns:
Paginated list of AssignmentOverride objects
"""Peer Reviews
Manage peer review assignments and workflows.
def get_peer_reviews(self, **kwargs) -> PaginatedList[PeerReview]:
"""
List peer reviews for the assignment.
Parameters:
- include: Additional data ('submission_comments', 'user')
Returns:
Paginated list of PeerReview objects
"""
def create_peer_review(self, user_id: int, **kwargs) -> PeerReview:
"""
Create a peer review assignment.
Parameters:
- user_id: ID of user who will do the review
- user_id: ID of user whose work will be reviewed (in kwargs)
Returns:
PeerReview object
"""Grade History and Auditing
Track grade changes and maintain audit trails.
def get_grade_change_events(self, **kwargs) -> PaginatedList[dict]:
"""
Get grade change events for the assignment.
Parameters:
- start_time: Start date for events
- end_time: End date for events
Returns:
Paginated list of grade change event dictionaries
"""Submission Class
Handle individual student submissions and grading.
class Submission(CanvasObject):
def edit(self, **kwargs) -> Submission:
"""
Edit/grade a submission.
Parameters:
- comment: Text comment for the submission
- submission: Dictionary with submission updates:
- posted_grade: Grade to assign
- excuse: Whether to excuse the submission
- late_policy_status: Late policy status
- seconds_late_override: Override for seconds late calculation
- rubric_assessment: Rubric assessment data
- include: Additional data to include in response
Returns:
Updated Submission object
"""
def mark_as_read(self, **kwargs) -> bool:
"""Mark submission as read."""
def mark_as_unread(self, **kwargs) -> bool:
"""Mark submission as unread."""Assignment Groups
Organize assignments into weighted categories.
class AssignmentGroup(CanvasObject):
def edit(self, **kwargs) -> AssignmentGroup:
"""
Edit assignment group properties.
Parameters:
- name: Group name
- weight: Weight for weighted grading (0-100)
- drop_lowest: Number of lowest scores to drop
- drop_highest: Number of highest scores to drop
- never_drop: List of assignment IDs to never drop
Returns:
Updated AssignmentGroup object
"""
def delete(self, **kwargs) -> AssignmentGroup:
"""Delete the assignment group."""
def get_assignments(self, **kwargs) -> PaginatedList[Assignment]:
"""Get assignments in this group."""Rubrics
Create and manage rubrics for consistent grading.
class Rubric(CanvasObject):
def edit(self, **kwargs) -> Rubric:
"""
Edit rubric criteria and settings.
Parameters:
- title: Rubric title
- points_possible: Total points possible
- criteria: List of rubric criteria dictionaries
- free_form_criterion_comments: Allow free-form comments
Returns:
Updated Rubric object
"""
def delete(self, **kwargs) -> Rubric:
"""Delete the rubric."""
class RubricAssociation(CanvasObject):
def edit(self, **kwargs) -> RubricAssociation:
"""
Edit rubric association settings.
Parameters:
- rubric_association: Dictionary with association settings:
- hide_score_total: Hide total score from students
- use_for_grading: Use rubric for grading
- hide_points: Hide points from students
- hide_outcome_results: Hide outcome results
Returns:
Updated RubricAssociation object
"""
def delete(self, **kwargs) -> RubricAssociation:
"""Delete the rubric association."""Custom Gradebook Columns
Add custom data columns to the gradebook.
class CustomGradebookColumn(CanvasObject):
def edit(self, **kwargs) -> CustomGradebookColumn:
"""
Edit custom gradebook column.
Parameters:
- title: Column title
- position: Column position
- hidden: Whether column is hidden
- teacher_notes: Whether this is a teacher notes column
- read_only: Whether column is read-only
Returns:
Updated CustomGradebookColumn object
"""
def delete(self, **kwargs) -> CustomGradebookColumn:
"""Delete the custom gradebook column."""
def get_column_data(self, **kwargs) -> PaginatedList[ColumnData]:
"""Get data entries for this column."""
def update_column_data(self, user_id: int, content: str, **kwargs) -> ColumnData:
"""
Update data for a specific user in this column.
Parameters:
- user_id: User ID
- content: Data content for the cell
Returns:
ColumnData object
"""Grading Standards
Define custom grading scales and letter grades.
class GradingStandard(CanvasObject):
def edit(self, **kwargs) -> GradingStandard:
"""
Edit grading standard.
Parameters:
- title: Grading standard title
- grading_scheme: List of grade/percentage mappings
Returns:
Updated GradingStandard object
"""
def delete(self, **kwargs) -> GradingStandard:
"""Delete the grading standard."""Usage Examples
Creating and Configuring Assignments
from canvasapi import Canvas
canvas = Canvas("https://canvas.example.com", "your-token")
course = canvas.get_course(12345)
# Create a comprehensive assignment
assignment = course.create_assignment({
'name': 'Research Paper',
'description': '<p>Write a 10-page research paper on the assigned topic.</p>',
'due_at': '2024-12-15T23:59:59Z',
'unlock_at': '2024-11-01T00:00:00Z',
'lock_at': '2024-12-16T00:00:00Z',
'points_possible': 100,
'grading_type': 'points',
'submission_types': ['online_upload', 'online_text_entry'],
'allowed_extensions': ['pdf', 'doc', 'docx'],
'peer_reviews': True,
'automatic_peer_reviews': True,
'peer_review_count': 2,
'peer_reviews_assign_at': '2024-12-16T00:00:01Z'
})
# Create assignment overrides for different sections
override = assignment.create_override({
'course_section_id': 456,
'title': 'Section A Extension',
'due_at': '2024-12-17T23:59:59Z'
})
# Create override for specific students
student_override = assignment.create_override({
'student_ids': [123, 456, 789],
'title': 'Accommodation Extension',
'due_at': '2024-12-20T23:59:59Z'
})Grading Submissions
# Get all submissions for grading
submissions = assignment.get_submissions(
include=['submission_comments', 'rubric_assessment', 'user']
)
for submission in submissions:
print(f"Grading {submission.user['name']}")
# Grade the submission
graded_submission = submission.edit(
submission={'posted_grade': 85},
comment='Good work! Consider expanding on the conclusion.'
)
print(f"Graded: {graded_submission.grade}")
# Get a specific student's submission
student_submission = assignment.get_submission(
user=student_id,
include=['submission_comments', 'rubric_assessment']
)
# Grade with detailed rubric assessment
rubric_assessment = {
'criterion_123': {
'points': 20,
'comments': 'Excellent analysis'
},
'criterion_456': {
'points': 15,
'comments': 'Could use more supporting evidence'
}
}
graded = student_submission.edit(
submission={'posted_grade': 87},
rubric_assessment=rubric_assessment,
comment='Well done overall. See rubric for specific feedback.'
)Managing Assignment Groups
# Create assignment groups with different weights
homework_group = course.create_assignment_group(
name="Homework",
weight=30,
drop_lowest=2 # Drop 2 lowest homework scores
)
exam_group = course.create_assignment_group(
name="Exams",
weight=50,
drop_lowest=0
)
participation_group = course.create_assignment_group(
name="Participation",
weight=20
)
# Update an assignment group
updated_group = homework_group.edit(
weight=25,
drop_lowest=3
)Creating and Using Rubrics
# Create a rubric for the assignment
rubric_data = {
'title': 'Research Paper Rubric',
'points_possible': 100,
'criteria': [
{
'description': 'Thesis and Argument',
'points': 30,
'ratings': [
{'description': 'Excellent', 'points': 30},
{'description': 'Good', 'points': 25},
{'description': 'Satisfactory', 'points': 20},
{'description': 'Needs Improvement', 'points': 15}
]
},
{
'description': 'Research and Sources',
'points': 25,
'ratings': [
{'description': 'Excellent', 'points': 25},
{'description': 'Good', 'points': 20},
{'description': 'Satisfactory', 'points': 15},
{'description': 'Needs Improvement', 'points': 10}
]
},
{
'description': 'Writing Quality',
'points': 25,
'ratings': [
{'description': 'Excellent', 'points': 25},
{'description': 'Good', 'points': 20},
{'description': 'Satisfactory', 'points': 15},
{'description': 'Needs Improvement', 'points': 10}
]
},
{
'description': 'Format and Citations',
'points': 20,
'ratings': [
{'description': 'Excellent', 'points': 20},
{'description': 'Good', 'points': 16},
{'description': 'Satisfactory', 'points': 12},
{'description': 'Needs Improvement', 'points': 8}
]
}
]
}
rubric = course.create_rubric(rubric_data)
# Associate rubric with assignment
association = assignment.create_rubric_association(
rubric_id=rubric.id,
rubric_association={
'use_for_grading': True,
'hide_score_total': False,
'purpose': 'grading'
}
)Custom Gradebook Columns
# Create a custom gradebook column for participation tracking
participation_column = course.create_custom_gradebook_column(
column={
'title': 'Class Participation',
'position': 1,
'hidden': False,
'teacher_notes': False
}
)
# Update participation data for students
students = course.get_users(enrollment_type='student')
for student in students:
participation_column.update_column_data(
user_id=student.id,
content='Excellent participation in discussions'
)
# Get all column data
column_data = participation_column.get_column_data()
for data in column_data:
print(f"Student {data.user_id}: {data.content}")Install with Tessl CLI
npx tessl i tessl/pypi-canvasapi