Python API wrapper for Instructure's Canvas LMS
Clone or download
Thetwam Merge pull request #220 from wjw27/develop
add kwargs to section.edit() #219
Latest commit 70f66de Dec 4, 2018
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
canvasapi Make edit alter existing object. Remove extra newline. Dec 4, 2018
docs Fix code format Aug 15, 2018
scripts (re-)added path manipulation to get imports to work for docval script… Jun 1, 2018
tests Change assertTrue(type == type) to assertIsInstance Nov 21, 2018
.gitignore Add env3 to .gitignore Sep 17, 2018
.mdlrc Placeholder for custom Markdownlint style definition Aug 26, 2017
.travis.yml Set travis ubuntu distro to xenial. Jul 17, 2018
AUTHORS.md Add bugfix to changelog. Add Bill and Tyler to authors. Dec 4, 2018
CHANGELOG.md Add bugfix to changelog. Add Bill and Tyler to authors. Dec 4, 2018
CONTRIBUTING.md Update CONTRIBUTING.md May 15, 2018
DEPLOY.md Update deploy doc Jun 11, 2018
Dockerfile Updated setup.py for open source release. Small tweak to Dockerfile. Mar 28, 2017
LICENSE Added license file Mar 28, 2017
README.md Add more detailed documentation for Keyword Arguments Aug 15, 2018
_config.yml Set theme jekyll-theme-cayman Aug 22, 2017
cmd_docker_build.sh Renaming canvas-api/canvas_api to canvasapi Mar 31, 2017
cmd_run_tests.sh Renaming canvas-api/canvas_api to canvasapi Mar 31, 2017
dev_requirements.txt Streamlining dev_requirements.txt. Swapped pycodestyle and pyflakes f… Sep 25, 2017
markdown-style.rb Don't require that the first line be a top-level header Aug 26, 2017
requirements.txt When creating datetime instances, set their time zones appropriately Aug 27, 2017
setup.cfg Use flake8 for Python linting instead of pyflakes and pycodestyle Aug 28, 2017
setup.py Added support for Python 3.7 Jul 12, 2018
tests_requirements.txt Streamlining dev_requirements.txt. Swapped pycodestyle and pyflakes f… Sep 25, 2017

README.md

CanvasAPI on PyPI License Python Versions Documentation Status Build Status Coverage Status Join UCF Open Slack Discussions

CanvasAPI

CanvasAPI is a Python library for accessing Instructure’s Canvas LMS API. The library enables developers to programmatically manage Canvas courses, users, gradebooks, and more.

Table of Contents

Installation

You can install CanvasAPI with pip:

pip install canvasapi

Documentation

Full documentation is available at Read the Docs.

Quickstart

Getting started with CanvasAPI is easy.

Like most API clients, CanvasAPI exposes a single class that provides access to the rest of the API: Canvas.

The first thing to do is instantiate a new Canvas object by providing your Canvas instance’s root API URL and a valid API key:

# Import the Canvas class
from canvasapi import Canvas

# Canvas API URL
API_URL = "https://example.com"
# Canvas API key
API_KEY = "p@$$w0rd"

# Initialize a new Canvas object
canvas = Canvas(API_URL, API_KEY)

You can now use canvas to begin making API calls.

Working with Canvas Objects

CanvasAPI converts the JSON responses from the Canvas API into Python objects. These objects provide further access to the Canvas API. You can find a full breakdown of the methods these classes provide in our class documentation. Below, you’ll find a few examples of common CanvasAPI use cases.

Course objects

Courses can be retrieved from the API:

# Grab course 123456
>>> course = canvas.get_course(123456)

# Access the course's name
>>> course.name
'Test Course'

# Update the course's name
>>> course.update(course={'name': 'New Course Name'})

See our documentation on keyword arguments for more information about how course.update() handles the name argument.

User objects

Individual users can be pulled from the API as well:

# Grab user 123
>>> user = canvas.get_user(123)

# Access the user's name
>>> user.name
'Test User'

# Retrieve a list of courses the user is enrolled in
>>> courses = user.get_courses()

# Grab a different user by their SIS ID
>>> login_id_user = canvas.get_user('some_user', 'sis_login_id')

Paginated Lists

Some calls, like the user.get_courses() call above, will request multiple objects from Canvas’s API. CanvasAPI collects these objects in a PaginatedList object. PaginatedList generally acts like a regular Python list. You can grab an element by index, iterate over it, and take a slice of it.

Warning: PaginatedList lazily loads its elements. Unfortunately, there’s no way to determine the exact number of records Canvas will return without traversing the list fully. This means that PaginatedList isn’t aware of its own length and negative indexing is not currently supported.

Let’s look at how we can use the PaginatedList returned by our get_courses() call:

# Retrieve a list of courses the user is enrolled in
>>> courses = user.get_courses()

>>> print(courses)
<PaginatedList of type Course>

# Access the first element in our list.
#
# You'll notice the first call takes a moment, but the next N-1
# elements (where N = the per_page argument supplied; the default is 10)
# will be instantly accessible.
>>> print(courses[0])
TST101 Test Course (1234567)

# Iterate over our course list
>>> for course in courses:
         print(course)

TST101 Test Course 1 (1234567)
TST102 Test Course 2 (1234568)
TST103 Test Course 3 (1234569)

# Take a slice of our course list
>>> courses[:2]
[TST101 Test Course 1 (1234567), TST102 Test Course 2 (1234568)]

Keyword arguments

Most of Canvas’s API endpoints accept a variety of arguments. CanvasAPI allows developers to insert keyword arguments when making calls to endpoints that accept arguments.

# Get all of the active courses a user is currently enrolled in
>>> courses = user.get_courses(enrollment_status='active')


# Fetch 50 objects per page when making calls that return a PaginatedList
>>> courses = user.get_courses(per_page=50)

For a more detailed description of how CanvasAPI handles more complex keyword arguments, check out the Keyword Argument Documentation.

Contact Us

Need help? Have an idea? Just want to say hi? Come join us on the UCF Open Slack Channel and join the #canvasapi channel!