CanvasAPI

The canvasapi.quiz module provides several classes to interact with Canvas Quizzes. You can use these classes to manage quiz settings, retrieve questions, analyze student submissions, and access quiz statistics or reports.

Key classes include:

• Quiz: Represents a quiz itself.
• QuizQuestion: Represents an individual question within a quiz.
• QuizSubmission: Represents a student's attempt at a quiz.
• QuizSubmissionQuestion: Represents a specific answer provided by a student to a question.
• QuizReport and QuizStatistic: Used for retrieving analytical data about quiz performance.
• QuizAssignmentOverrideSet: Manages overrides for quiz assignments.
• QuizExtension: Handles quiz extensions.
• QuizSubmissionEvent: Represents events related to quiz submissions.

Both exceptions return an HTTP 401 status code, but they indicate different issues:

• InvalidAccessToken: Thrown when the WWW-Authenticate header is present. This means your API key is invalid.
• Unauthorized: Thrown when the WWW-Authenticate header is NOT present. This means your API key is valid, but the user does not have permission to access the specific resource.

The PaginatedList class is used to handle collections of objects returned by the Canvas API that are spread across multiple pages. Instead of manually managing page numbers or tokens, you can iterate over a PaginatedList object as if it were a standard Python list. The class automatically fetches subsequent pages of results as you iterate through the items, making it easy to process large datasets like all users in a course or all assignments in a module.

# Example pattern for iterating over a paginated collection
for item in paginated_list:
    print(item.name)

All exceptions in the canvasapi library inherit from canvasapi.exceptions.CanvasException. You can use this base class to catch any error thrown by the library, or catch specific exceptions to handle different error scenarios (like invalid keys or missing resources) uniquely.

To catch any library-related error, import CanvasException and use a try...except block.

from canvasapi.exceptions import CanvasException

try:
    canvas.get_course(1)
except CanvasException as e:
    print(e)

For parameters requiring multiple levels of nesting, such as user[avatar][url], use nested dictionaries in Python.

# Representing user[avatar][url]
user.edit(
    user={
        'avatar': {
            'url': 'http://example.com/john_avatar.png'
        }
    }
)

To release a new version of CanvasAPI to PyPI, follow these deployment steps:

1. Update Version: Increment the version number in __init__.py.
2. Commit and Push: Commit the changes to __init__.py and push to the repository.
3. Merge to Master: Create a merge request from the develop branch to the master branch and merge it.
4. Tag the Release: Create a signed git tag using the version number and the merge commit hash.
5. Push Tag: Push the tag to the upstream repository. This triggers GitHub Actions to automatically deploy the code to PyPI.
6. GitHub Release: Create a new release on GitHub for the tag, using the content from the CHANGELOG for the release notes.

# Example tagging and pushing a release
git tag -s v0.0.0 -m "Release version 0.0.0" abc1234
git push upstream v0.0.0

When a parameter represents a nested object where one of the properties is a list (e.g., assignment[submission_types][]), pass a dictionary where the key for that property contains a list.

# Representing assignment[submission_types][] and assignment[allowed_extensions][]
course.create_assignment(
    assignment={
        'name': 'Assignment 1',
        'submission_types': ['online_text_entry', 'online_upload'],
        'allowed_extensions': ['doc', 'docx']
    }
)

You can interact with accounts to manage users and list courses. Use canvas.get_account(account_id) to retrieve an account object.

Create a New User

To create a user under a specific account, use account.create_user() providing a user dictionary (e.g., for name) and a pseudonym dictionary (e.g., for password and sis_user_id).

List Courses under an Account

Use account.get_courses() to retrieve a list of courses associated with that account.

# Grab the account to create the user under
account = canvas.get_account(1)

user = account.create_user(
    user={
        'name': 'New User'            
    },
    pseudonym={
        'password': 'secure123',
        'sis_user_id': 'new_user'
    }
)

# List courses
courses = account.get_courses()
for course in courses:
    print(course)