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
main-client.mddocs/
Main API Client
The Canvas class serves as the primary entry point for all Canvas API operations. It handles authentication, provides access to all Canvas resources, and manages global operations like searching and GraphQL queries.
Capabilities
Initialization
Initialize the Canvas API client with your Canvas instance URL and access token.
class Canvas:
def __init__(self, base_url: str, access_token: str):
"""
Initialize Canvas API client.
Parameters:
- base_url: The base URL of the Canvas instance's API (without /api/v1)
- access_token: The API key to authenticate requests with
"""Current User Operations
Get information about the currently authenticated user.
def get_current_user(self) -> CurrentUser:
"""Return details of the current user."""Course Operations
Access and manage courses across the Canvas instance.
def get_course(self, course, use_sis_id: bool = False, **kwargs) -> Course:
"""
Retrieve a course by its ID.
Parameters:
- course: The object or ID of the course to retrieve
- use_sis_id: Whether course_id is an SIS ID (default: False)
Returns:
Course object
"""
def get_courses(self, **kwargs) -> PaginatedList[Course]:
"""
Return a list of active courses for the current user.
Returns:
Paginated list of Course objects
"""
def get_course_nickname(self, course, **kwargs) -> CourseNickname:
"""Return the nickname for the given course."""
def get_course_nicknames(self, **kwargs) -> PaginatedList[CourseNickname]:
"""Return all course nicknames set by the current account."""
def set_course_nickname(self, course, nickname: str, **kwargs) -> CourseNickname:
"""
Set a nickname for the given course.
Parameters:
- course: The Course object or ID
- nickname: The nickname for the course
"""
def clear_course_nicknames(self, **kwargs) -> bool:
"""Remove all stored course nicknames."""User Operations
Access user information and profiles.
def get_user(self, user, id_type: str = None, **kwargs) -> User:
"""
Retrieve a user by their ID.
Parameters:
- user: The user's object or ID
- id_type: The ID type (sis_user_id, login_id, etc.)
Returns:
User object
"""Account Operations
Manage Canvas accounts and institutional data.
def get_account(self, account, use_sis_id: bool = False, **kwargs) -> Account:
"""
Retrieve information on an individual account.
Parameters:
- account: The object or ID of the account to retrieve
- use_sis_id: Whether account_id is an SIS ID (default: False)
Returns:
Account object
"""
def get_accounts(self, **kwargs) -> PaginatedList[Account]:
"""
List accounts that the current user can view or manage.
Returns:
Paginated list of Account objects
"""
def get_course_accounts(self, **kwargs) -> PaginatedList[Account]:
"""
List accounts through admin course enrollments.
Returns:
Paginated list of Account objects
"""
def create_account(self, **kwargs) -> Account:
"""Create a new root account."""
def search_accounts(self, **kwargs) -> dict:
"""Return up to 5 matching account domains."""Communication Operations
Manage conversations and messaging across Canvas.
def get_conversation(self, conversation, **kwargs) -> Conversation:
"""Return single conversation."""
def get_conversations(self, **kwargs) -> PaginatedList[Conversation]:
"""Return list of conversations for the current user."""
def create_conversation(self, recipients: list, body: str, **kwargs) -> list[Conversation]:
"""
Create a new conversation.
Parameters:
- recipients: Array of recipient IDs (can include course_ or group_ prefixes)
- body: The body of the message being added
Returns:
List of Conversation objects
"""
def conversations_batch_update(self, conversation_ids: list, event: str, **kwargs) -> Progress:
"""
Batch update conversations.
Parameters:
- conversation_ids: List of conversations to update (max 500)
- event: Action to take ('mark_as_read', 'mark_as_unread', 'star', 'unstar', 'archive', 'destroy')
Returns:
Progress object tracking the operation
"""
def conversations_mark_all_as_read(self, **kwargs) -> bool:
"""Mark all conversations as read."""
def conversations_unread_count(self, **kwargs) -> dict:
"""Get the number of unread conversations for the current user."""
def conversations_get_running_batches(self, **kwargs) -> dict:
"""Returns currently running conversation batches."""Group Operations
Manage groups and group categories.
def get_group(self, group, use_sis_id: bool = False, **kwargs) -> Group:
"""Return data for a single group."""
def get_group_category(self, category, **kwargs) -> GroupCategory:
"""Get a single group category."""
def create_group(self, **kwargs) -> Group:
"""Create a group."""Calendar and Appointment Operations
Manage calendar events and appointment scheduling.
def get_calendar_event(self, calendar_event, **kwargs) -> CalendarEvent:
"""Return single calendar event by ID."""
def get_calendar_events(self, **kwargs) -> PaginatedList[CalendarEvent]:
"""List calendar events."""
def create_calendar_event(self, calendar_event: dict, **kwargs) -> CalendarEvent:
"""
Create a new calendar event.
Parameters:
- calendar_event: Dictionary with event attributes including 'context_code'
Returns:
CalendarEvent object
"""
def get_appointment_group(self, appointment_group, **kwargs) -> AppointmentGroup:
"""Return single appointment group."""
def get_appointment_groups(self, **kwargs) -> PaginatedList[AppointmentGroup]:
"""List appointment groups."""
def create_appointment_group(self, appointment_group: dict, **kwargs) -> AppointmentGroup:
"""
Create new appointment group.
Parameters:
- appointment_group: Dictionary with 'context_codes' and 'title' keys
Returns:
AppointmentGroup object
"""
def reserve_time_slot(self, calendar_event, participant_id: str = None, **kwargs) -> CalendarEvent:
"""Reserve a time slot in a calendar event."""File and Content Operations
Access files and folders across Canvas.
def get_file(self, file, **kwargs) -> File:
"""Return the standard attachment json object for a file."""
def get_folder(self, folder, **kwargs) -> Folder:
"""Return the details for a folder."""Announcement Operations
Access announcements across multiple contexts.
def get_announcements(self, context_codes: list, **kwargs) -> PaginatedList[DiscussionTopic]:
"""
List announcements.
Parameters:
- context_codes: Course IDs or Course objects to request announcements from
Returns:
Paginated list of DiscussionTopic objects
"""Search Operations
Search for courses, users, and other Canvas resources.
def search_all_courses(self, **kwargs) -> list:
"""List all courses visible in the public index."""
def search_recipients(self, **kwargs) -> list:
"""Find valid recipients that the current user can send messages to."""Section Operations
Access course sections.
def get_section(self, section, use_sis_id: bool = False, **kwargs) -> Section:
"""
Get details about a specific section.
Parameters:
- section: The Section object or ID
- use_sis_id: Whether section_id is an SIS ID (default: False)
Returns:
Section object
"""Outcome Operations
Access learning outcomes and outcome groups.
def get_outcome(self, outcome, **kwargs) -> Outcome:
"""
Return details of outcome with given ID.
Parameters:
- outcome: Outcome object or ID
Returns:
Outcome object
"""
def get_outcome_group(self, group, **kwargs) -> OutcomeGroup:
"""
Return details of outcome group with given ID.
Parameters:
- group: OutcomeGroup object or ID
Returns:
OutcomeGroup object
"""
def get_root_outcome_group(self, **kwargs) -> OutcomeGroup:
"""
Redirect to root outcome group for context.
Returns:
OutcomeGroup object
"""Planner Operations
Create and manage planner notes and overrides.
def create_planner_note(self, **kwargs) -> PlannerNote:
"""Create a planner note for the current user."""
def create_planner_override(self, plannable_type: str, plannable_id: int, **kwargs) -> PlannerOverride:
"""
Create a planner override for the current user.
Parameters:
- plannable_type: Type of object being overridden
- plannable_id: ID of the object being overridden
Returns:
PlannerOverride object
"""
def get_planner_note(self, planner_note, **kwargs) -> PlannerNote:
"""
Retrieve a planner note for the current user.
Parameters:
- planner_note: PlannerNote object or ID
Returns:
PlannerNote object
"""
def get_planner_notes(self, **kwargs) -> PaginatedList[PlannerNote]:
"""
Retrieve paginated list of planner notes.
Returns:
Paginated list of PlannerNote objects
"""
def get_planner_override(self, planner_override, **kwargs) -> PlannerOverride:
"""
Retrieve a planner override for the current user.
Parameters:
- planner_override: PlannerOverride object or ID
Returns:
PlannerOverride object
"""
def get_planner_overrides(self, **kwargs) -> PaginatedList[PlannerOverride]:
"""
Retrieve planner overrides for the current user.
Returns:
Paginated list of PlannerOverride objects
"""Poll Operations
Create and manage polls.
def create_poll(self, polls: list, **kwargs) -> Poll:
"""
Create a new poll for the current user.
Parameters:
- polls: List of poll dictionaries, each with 'question' key
Returns:
Poll object
"""
def get_poll(self, poll, **kwargs) -> Poll:
"""
Get a single poll based on poll ID.
Parameters:
- poll: Poll object or ID
Returns:
Poll object
"""
def get_polls(self, **kwargs) -> PaginatedList[Poll]:
"""
Return paginated list of polls for the current user.
Returns:
Paginated list of Poll objects
"""Additional Content Operations
Access various Canvas content types.
def get_eportfolio(self, eportfolio, **kwargs) -> EPortfolio:
"""
Get an eportfolio by ID.
Parameters:
- eportfolio: EPortfolio object or ID
Returns:
EPortfolio object
"""
def get_epub_exports(self, **kwargs) -> PaginatedList[CourseEpubExport]:
"""
Return list of epub exports for associated course.
Returns:
Paginated list of CourseEpubExport objects
"""
def get_comm_messages(self, user, **kwargs) -> PaginatedList[CommMessage]:
"""
Retrieve paginated list of messages sent to a user.
Parameters:
- user: User object or ID
Returns:
Paginated list of CommMessage objects
"""
def get_account_calendars(self, **kwargs) -> PaginatedList[AccountCalendar]:
"""
Return paginated list of account calendars available to user.
Returns:
Paginated list of AccountCalendar objects
"""
def get_user_participants(self, appointment_group, **kwargs) -> PaginatedList[User]:
"""
List user participants in appointment group.
Parameters:
- appointment_group: AppointmentGroup object or ID
Returns:
Paginated list of User objects
"""
def get_group_participants(self, appointment_group, **kwargs) -> PaginatedList[Group]:
"""
List student group participants in appointment group.
Parameters:
- appointment_group: AppointmentGroup object or ID
Returns:
Paginated list of Group objects
"""Utility Operations
Additional utility functions for Canvas operations.
def get_activity_stream_summary(self, **kwargs) -> dict:
"""Return summary of current user's global activity stream."""
def get_brand_variables(self, **kwargs) -> dict:
"""Get account brand variables."""
def get_todo_items(self, **kwargs) -> PaginatedList[Todo]:
"""Return current user's list of todo items."""
def get_upcoming_events(self, **kwargs) -> dict:
"""Return current user's upcoming events."""
def graphql(self, query: str, variables: dict = None, **kwargs) -> dict:
"""
Make a GraphQL formatted request to Canvas.
Parameters:
- query: The GraphQL query to execute as a string
- variables: The variable values required by the query
Returns:
Dictionary with GraphQL response
"""Progress Tracking
Monitor long-running operations.
def get_progress(self, progress, **kwargs) -> Progress:
"""Get a specific progress object for monitoring operations."""JWT Operations
Create and refresh JSON Web Tokens for Canvas services.
def create_jwt(self, **kwargs) -> JWT:
"""Create a unique JWT to use with other Canvas services."""
def refresh_jwt(self, jwt, **kwargs) -> JWT:
"""
Refresh a JWT for reuse with other Canvas services.
Parameters:
- jwt: An existing JWT string or JWT object to refresh
Returns:
New JWT object
"""Usage Examples
Basic Setup and Course Access
from canvasapi import Canvas
# Initialize Canvas connection
canvas = Canvas("https://canvas.instructure.com", "your-access-token")
# Get current user info
user = canvas.get_current_user()
print(f"Logged in as: {user.name}")
# Get all courses for current user
courses = canvas.get_courses()
for course in courses:
print(f"Course: {course.name} (ID: {course.id})")
# Get specific course by ID
course = canvas.get_course(12345)
print(f"Course name: {course.name}")Communication Example
# Create a new conversation
recipients = ['123', '456', 'course_789'] # User IDs and course ID
conversation = canvas.create_conversation(
recipients=recipients,
body="Hello everyone! This is a test message.",
subject="Test Message"
)
# Get unread conversation count
unread_info = canvas.conversations_unread_count()
print(f"Unread conversations: {unread_info['unread_count']}")
# Mark all conversations as read
canvas.conversations_mark_all_as_read()GraphQL Example
# Execute a GraphQL query
query = """
query GetCourse($courseId: ID!) {
course(id: $courseId) {
name
enrollmentsConnection {
nodes {
user {
name
}
}
}
}
}
"""
variables = {"courseId": "12345"}
result = canvas.graphql(query, variables)
print(result)Install with Tessl CLI
npx tessl i tessl/pypi-canvasapi