0
# CanvasAPI
1

2
A comprehensive Python library that provides programmatic access to Instructure's Canvas Learning Management System API. CanvasAPI enables developers to manage courses, users, gradebooks, assignments, and other Canvas resources with a chainable interface, automatic pagination handling, and robust error management.
3

4
## Package Information
5

6
- **Package Name**: canvasapi
7
- **Language**: Python
8
- **Installation**: `pip install canvasapi`
9
- **Dependencies**: requests, arrow, pytz
10

11
## Core Imports
12

13
```python
14
from canvasapi import Canvas
15
```
16

17
Import specific classes as needed:
18

19
```python
20
from canvasapi import Canvas
21
from canvasapi.course import Course
22
from canvasapi.user import User
23
from canvasapi.assignment import Assignment
24
from canvasapi.discussion_topic import DiscussionTopic
25
from canvasapi.file import File
26
from canvasapi.folder import Folder
27
from canvasapi.group import Group
28
from canvasapi.account import Account
29
from canvasapi.enrollment import Enrollment
30
from canvasapi.quiz import Quiz
31
from canvasapi.page import Page
32
from canvasapi.module import Module
33
from canvasapi.section import Section
34
from canvasapi.submission import Submission
35
from canvasapi.conversation import Conversation
36
from canvasapi.calendar_event import CalendarEvent
37
from canvasapi.paginated_list import PaginatedList
38
```
39

40
Direct class imports from main package:
41

42
```python
43
from canvasapi.exceptions import (
44
    CanvasException, 
45
    BadRequest, 
46
    Unauthorized, 
47
    Forbidden, 
48
    ResourceDoesNotExist,
49
    RequiredFieldMissing
50
)
51
```
52

53
## Basic Usage
54

55
```python
56
from canvasapi import Canvas
57

58
# Initialize Canvas API connection
59
canvas = Canvas("https://your-canvas-url.com", "your-access-token")
60

61
# Get current user
62
user = canvas.get_current_user()
63
print(f"Hello, {user.name}!")
64

65
# Get user's courses
66
courses = canvas.get_courses()
67
for course in courses:
68
    print(f"Course: {course.name}")
69

70
# Get a specific course and its assignments
71
course = canvas.get_course(12345)
72
assignments = course.get_assignments()
73
for assignment in assignments:
74
    print(f"Assignment: {assignment.name} (Due: {assignment.due_at})")
75

76
# Create a new assignment
77
new_assignment = course.create_assignment({
78
    'name': 'New Assignment',
79
    'description': 'This is a new assignment',
80
    'due_at': '2024-12-31T23:59:59Z',
81
    'points_possible': 100
82
})
83
```
84

85
## Architecture
86

87
CanvasAPI uses an object-oriented design that mirrors Canvas's API structure:
88

89
- **Canvas**: Main API client that provides entry points to all Canvas resources
90
- **CanvasObject**: Base class for all Canvas entities with automatic attribute mapping
91
- **PaginatedList**: Handles Canvas API pagination transparently with Python iteration
92
- **Requester**: HTTP client handling authentication, rate limiting, and error management
93

94
The library converts JSON API responses into Python objects with a chainable interface, enabling intuitive navigation between related Canvas entities (e.g., course.get_assignments() or user.get_enrollments()).
95

96
## Capabilities
97

98
### Main API Client
99

100
The primary Canvas class that provides access to all Canvas resources including accounts, courses, users, and global operations.
101

102
```python { .api }
103
class Canvas:
104
    def __init__(self, base_url: str, access_token: str): ...
105
    def get_current_user(self) -> CurrentUser: ...
106
    def get_course(self, course, use_sis_id: bool = False) -> Course: ...
107
    def get_courses(self, **kwargs) -> PaginatedList[Course]: ...
108
    def get_user(self, user, id_type: str = None) -> User: ...
109
    def get_account(self, account, use_sis_id: bool = False) -> Account: ...
110
    def get_accounts(self, **kwargs) -> PaginatedList[Account]: ...
111
```
112

113
[Main API Client](./main-client.md)
114

115
### Course Management
116

117
Comprehensive course operations including content creation, enrollment management, assignments, quizzes, and gradebook functionality.
118

119
```python { .api }
120
class Course(CanvasObject):
121
    def get_assignments(self, **kwargs) -> PaginatedList[Assignment]: ...
122
    def create_assignment(self, assignment: dict, **kwargs) -> Assignment: ...
123
    def get_users(self, **kwargs) -> PaginatedList[User]: ...
124
    def enroll_user(self, user, enrollment_type: str, **kwargs) -> Enrollment: ...
125
    def get_modules(self, **kwargs) -> PaginatedList[Module]: ...
126
    def create_module(self, module: dict, **kwargs) -> Module: ...
127
```
128

129
[Course Management](./course-management.md)
130

131
### User Management
132

133
User profile operations, enrollment handling, file management, and communication channel administration.
134

135
```python { .api }
136
class User(CanvasObject):
137
    def get_profile(self, **kwargs) -> dict: ...
138
    def edit(self, **kwargs) -> User: ...
139
    def get_courses(self, **kwargs) -> PaginatedList[Course]: ...
140
    def get_enrollments(self, **kwargs) -> PaginatedList[Enrollment]: ...
141
    def get_files(self, **kwargs) -> PaginatedList[File]: ...
142
    def create_folder(self, name: str, **kwargs) -> Folder: ...
143
```
144

145
[User Management](./user-management.md)
146

147
### Assignment & Grading
148

149
Assignment creation, submission handling, grading workflows, rubrics, and grade management.
150

151
```python { .api }
152
class Assignment(CanvasObject):
153
    def get_submissions(self, **kwargs) -> PaginatedList[Submission]: ...
154
    def get_submission(self, user, **kwargs) -> Submission: ...
155
    def create_override(self, assignment_override: dict, **kwargs) -> AssignmentOverride: ...
156
    def edit(self, **kwargs) -> Assignment: ...
157
    def delete(self, **kwargs) -> Assignment: ...
158
```
159

160
[Assignment & Grading](./assignments-grading.md)
161

162
### Communication
163

164
Conversations, announcements, messaging, and notification management within Canvas.
165

166
```python { .api }
167
def get_conversations(self, **kwargs) -> PaginatedList[Conversation]: ...
168
def create_conversation(self, recipients: list, body: str, **kwargs) -> list[Conversation]: ...
169
def get_announcements(self, context_codes: list, **kwargs) -> PaginatedList[DiscussionTopic]: ...
170
def conversations_mark_all_as_read(self, **kwargs) -> bool: ...
171
```
172

173
[Communication](./communication.md)
174

175
### Content Management
176

177
Pages, files, folders, modules, external tools, and content organization within courses.
178

179
```python { .api }
180
class Course(CanvasObject):
181
    def get_pages(self, **kwargs) -> PaginatedList[Page]: ...
182
    def create_page(self, page: dict, **kwargs) -> Page: ...
183
    def get_files(self, **kwargs) -> PaginatedList[File]: ...
184
    def get_folders(self, **kwargs) -> PaginatedList[Folder]: ...
185
    def create_folder(self, name: str, **kwargs) -> Folder: ...
186
```
187

188
[Content Management](./content-management.md)
189

190
### Quizzes & Assessments
191

192
Quiz creation, question management, submissions, and both Classic Quizzes and New Quizzes support.
193

194
```python { .api }
195
class Course(CanvasObject):
196
    def get_quizzes(self, **kwargs) -> PaginatedList[Quiz]: ...
197
    def create_quiz(self, quiz: dict, **kwargs) -> Quiz: ...
198
    def create_new_quiz(self, **kwargs) -> NewQuiz: ...
199

200
class Quiz(CanvasObject):
201
    def get_questions(self, **kwargs) -> PaginatedList[QuizQuestion]: ...
202
    def create_question(self, question: dict, **kwargs) -> QuizQuestion: ...
203
```
204

205
[Quizzes & Assessments](./quizzes-assessments.md)
206

207
### Account Administration
208

209
Account management, user creation, role administration, SIS imports, and institutional-level operations.
210

211
```python { .api }
212
class Account(CanvasObject):
213
    def create_user(self, user: dict, **kwargs) -> User: ...
214
    def get_users(self, **kwargs) -> PaginatedList[User]: ...
215
    def create_course(self, **kwargs) -> Course: ...
216
    def create_subaccount(self, account: dict, **kwargs) -> Account: ...
217
    def create_admin(self, user_id: int, **kwargs) -> Admin: ...
218
```
219

220
[Account Administration](./account-administration.md)
221

222
## Exception Handling
223

224
```python { .api }
225
class CanvasException(Exception):
226
    """Base exception for all Canvas API errors"""
227

228
class BadRequest(CanvasException):
229
    """HTTP 400 Bad Request errors"""
230

231
class Unauthorized(CanvasException):
232
    """HTTP 401 Unauthorized errors"""
233

234
class Forbidden(CanvasException):
235
    """HTTP 403 Forbidden errors"""
236

237
class ResourceDoesNotExist(CanvasException):
238
    """HTTP 404 Not Found errors"""
239

240
class RequiredFieldMissing(CanvasException):
241
    """Missing required parameters"""
242
```
243

244
## Common Types
245

246
```python { .api }
247
class PaginatedList:
248
    """Handles Canvas API pagination automatically"""
249
    def __iter__(self): ...
250
    def __getitem__(self, index): ...
251

252
class CanvasObject:
253
    """Base class for all Canvas API objects"""
254
    def set_attributes(self, attributes: dict): ...
255

256
class CurrentUser(User):
257
    """Extended user class for the currently authenticated user"""
258

259
class Section(CanvasObject):
260
    """Course section representation"""
261

262
class Outcome(CanvasObject):
263
    """Learning outcome representation"""
264

265
class OutcomeGroup(CanvasObject):
266
    """Learning outcome group representation"""
267

268
class PlannerNote(CanvasObject):
269
    """Planner note representation"""
270

271
class PlannerOverride(CanvasObject):
272
    """Planner override representation"""
273

274
class Poll(CanvasObject):
275
    """Poll representation"""
276

277
class EPortfolio(CanvasObject):
278
    """Electronic portfolio representation"""
279

280
class CourseEpubExport(CanvasObject):
281
    """Course EPUB export representation"""
282

283
class CommMessage(CanvasObject):
284
    """Communication message representation"""
285

286
class AccountCalendar(CanvasObject):
287
    """Account calendar representation"""
288

289
class AppointmentGroup(CanvasObject):
290
    """Appointment group representation"""
291

292
class CalendarEvent(CanvasObject):
293
    """Calendar event representation"""
294

295
class JWT(CanvasObject):
296
    """JSON Web Token representation"""
297

298
class Progress(CanvasObject):
299
    """Progress tracking for asynchronous operations"""
300

301
class Todo(CanvasObject):
302
    """Todo item representation"""
303

304
class OutcomeLink(CanvasObject):
305
    """Outcome link representation"""
306

307
class OutcomeResult(CanvasObject):
308
    """Outcome result representation"""
309

310
class Rubric(CanvasObject):
311
    """Rubric representation"""
312

313
class RubricAssociation(CanvasObject):
314
    """Rubric association representation"""
315

316
class BlueprintTemplate(CanvasObject):
317
    """Blueprint template representation"""
318

319
class BlueprintSubscription(CanvasObject):
320
    """Blueprint subscription representation"""
321

322
class LatePolicy(CanvasObject):
323
    """Late policy representation"""
324

325
class GradingStandard(CanvasObject):
326
    """Grading standard representation"""
327

328
class CourseStudentSummary(CanvasObject):
329
    """Course student summary analytics representation"""
330

331
class ExternalTool(CanvasObject):
332
    """External tool representation"""
333
```