[](https://pypi.python.org/pypi/canvasapi)
[](https://pypi.python.org/pypi/canvasapi)
[](https://pypi.python.org/pypi/canvasapi)
[](http://canvasapi.readthedocs.io/en/stable/?badge=stable)
[](https://github.com/ucfopen/canvasapi/actions)
[](https://codecov.io/gh/ucfopen/canvasapi)
[](https://dl.ucf.edu/join-ucfopen)
[](https://github.com/psf/black)
# CanvasAPI
CanvasAPI is a Python library for accessing Instructure’s [Canvas LMS API](https://canvas.instructure.com/doc/api/index.html). The library enables developers to programmatically manage Canvas courses, users, gradebooks, and more.
## Table of Contents
- [CanvasAPI](#canvasapi)
- [Table of Contents](#table-of-contents)
- [Installation](#installation)
- [Documentation](#documentation)
- [Contributing](#contributing)
- [Quickstart](#quickstart)
- [Working with Canvas Objects](#working-with-canvas-objects)
- [Course objects](#course-objects)
- [User objects](#user-objects)
- [Paginated Lists](#paginated-lists)
- [Keyword arguments](#keyword-arguments)
- [CanvasAPI Projects](#canvasapi-projects)
- [Contact Us](#contact-us)
## Installation
You can install CanvasAPI with pip:
`pip install canvasapi`
## Documentation
Full documentation is available at [Read the Docs](http://canvasapi.readthedocs.io/).
## Contributing
Want to help us improve CanvasAPI? Check out our [Contributing Guide](.github/CONTRIBUTING.md) to learn about running CanvasAPI as a developer, picking issues to work on, submitting bug reports, contributing patches, and more.
## 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:
```python
# 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](http://canvasapi.readthedocs.io/en/stable/class-reference.html). Below, you’ll find a few examples of common CanvasAPI use cases.
#### Course objects
Courses can be retrieved from the API:
```python
# 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](#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:
```python
# 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:
```python
# 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.
```python
# Get all of the active courses a user is currently enrolled in
>>> courses = user.get_courses(enrollment_state='active')
```
For a more detailed description of how CanvasAPI handles more complex keyword arguments, check out the [Keyword Argument Documentation](http://canvasapi.readthedocs.io/en/stable/keyword-args.html).
## CanvasAPI Projects
Since its initial release in June 2016, CanvasAPI has amassed over 100 [dependent repositories](https://github.com/ucfopen/canvasapi/network/dependents). Many of these include various tools used to enhance the Canvas experience for both instructors and students. Here are a few popular repositories that use CanvasAPI:
- [Canvas Grab](https://github.com/skyzh/canvas_grab)
- Canvas Grab is the most popular project using CanvasAPI. This tool, with one click, copies all files from Canvas LMS to local directory. CanvasAPI is used in this project to connect to a course and grab its files.
- [Clanvas](https://github.com/marklalor/clanvas)
- Clanvas is a command-line client for Canvas. It uses the already available bash commands plus some additional ones to interact with various features of Canvas from the commmand line.
- [CS221Bot](https://github.com/Person314159/cs221bot)
- CS221Bot is a Discord bot for the CPCS 221 course at University of British Columbia. CanvasAPI is used in this project to connect to and synchronize with a course and get its data, such as announcements, new assignments, and more.
If you have a project that uses CanvasAPI that you'd like to promote, please contact us!
## Contact Us
Need help? Have an idea? Feel free to check out our [Discussions](https://github.com/ucfopen/canvasapi/discussions) board. Just want to say hi or get extended spport? Come join us on the [UCF Open Slack Channel](https://dl.ucf.edu/join-ucfopen) and join the `#canvasapi` channel!
Raw data
{
"_id": null,
"home_page": "https://github.com/ucfopen/canvasapi",
"name": "canvasapi",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "",
"author": "University of Central Florida - Center for Distributed Learning",
"author_email": "techrangers@ucf.edu",
"download_url": "https://files.pythonhosted.org/packages/2a/68/316c1778181b175a1cf139c20f795da0f4164e7da9ef31d8f3652c182358/canvasapi-3.2.0.tar.gz",
"platform": null,
"description": "[](https://pypi.python.org/pypi/canvasapi)\n[](https://pypi.python.org/pypi/canvasapi)\n[](https://pypi.python.org/pypi/canvasapi)\n[](http://canvasapi.readthedocs.io/en/stable/?badge=stable)\n[](https://github.com/ucfopen/canvasapi/actions)\n[](https://codecov.io/gh/ucfopen/canvasapi)\n[](https://dl.ucf.edu/join-ucfopen)\n[](https://github.com/psf/black)\n\n# CanvasAPI\n\nCanvasAPI is a Python library for accessing Instructure\u2019s [Canvas LMS API](https://canvas.instructure.com/doc/api/index.html). The library enables developers to programmatically manage Canvas courses, users, gradebooks, and more.\n\n## Table of Contents\n\n- [CanvasAPI](#canvasapi)\n - [Table of Contents](#table-of-contents)\n - [Installation](#installation)\n - [Documentation](#documentation)\n - [Contributing](#contributing)\n - [Quickstart](#quickstart)\n - [Working with Canvas Objects](#working-with-canvas-objects)\n - [Course objects](#course-objects)\n - [User objects](#user-objects)\n - [Paginated Lists](#paginated-lists)\n - [Keyword arguments](#keyword-arguments)\n - [CanvasAPI Projects](#canvasapi-projects)\n - [Contact Us](#contact-us)\n\n## Installation\n\nYou can install CanvasAPI with pip:\n\n`pip install canvasapi`\n\n## Documentation\n\nFull documentation is available at [Read the Docs](http://canvasapi.readthedocs.io/).\n\n## Contributing\n\nWant to help us improve CanvasAPI? Check out our [Contributing Guide](.github/CONTRIBUTING.md) to learn about running CanvasAPI as a developer, picking issues to work on, submitting bug reports, contributing patches, and more.\n\n## Quickstart\n\nGetting started with CanvasAPI is easy.\n\nLike most API clients, CanvasAPI exposes a single class that provides access to the rest of the API: `Canvas`.\n\nThe first thing to do is instantiate a new `Canvas` object by providing your Canvas instance\u2019s root API URL and a valid API key:\n\n```python\n# Import the Canvas class\nfrom canvasapi import Canvas\n\n# Canvas API URL\nAPI_URL = \"https://example.com\"\n# Canvas API key\nAPI_KEY = \"p@$$w0rd\"\n\n# Initialize a new Canvas object\ncanvas = Canvas(API_URL, API_KEY)\n```\n\nYou can now use `canvas` to begin making API calls.\n\n### Working with Canvas Objects\n\nCanvasAPI 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](http://canvasapi.readthedocs.io/en/stable/class-reference.html). Below, you\u2019ll find a few examples of common CanvasAPI use cases.\n\n#### Course objects\n\nCourses can be retrieved from the API:\n\n```python\n# Grab course 123456\n>>> course = canvas.get_course(123456)\n\n# Access the course's name\n>>> course.name\n'Test Course'\n\n# Update the course's name\n>>> course.update(course={'name': 'New Course Name'})\n```\n\nSee our documentation on [keyword arguments](#keyword-arguments) for more information about how `course.update()` handles the `name` argument.\n\n#### User objects\n\nIndividual users can be pulled from the API as well:\n\n```python\n# Grab user 123\n>>> user = canvas.get_user(123)\n\n# Access the user's name\n>>> user.name\n'Test User'\n\n# Retrieve a list of courses the user is enrolled in\n>>> courses = user.get_courses()\n\n# Grab a different user by their SIS ID\n>>> login_id_user = canvas.get_user('some_user', 'sis_login_id')\n```\n\n#### Paginated Lists\n\nSome calls, like the `user.get_courses()` call above, will request multiple objects from Canvas\u2019s 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.\n\n**Warning**: `PaginatedList` lazily loads its elements. Unfortunately, there\u2019s no way to determine the exact number of records Canvas will return without traversing the list fully. This means that `PaginatedList` isn\u2019t aware of its own length and negative indexing is not currently supported.\n\nLet\u2019s look at how we can use the `PaginatedList` returned by our `get_courses()` call:\n\n```python\n# Retrieve a list of courses the user is enrolled in\n>>> courses = user.get_courses()\n\n>>> print(courses)\n<PaginatedList of type Course>\n\n# Access the first element in our list.\n#\n# You'll notice the first call takes a moment, but the next N-1\n# elements (where N = the per_page argument supplied; the default is 10)\n# will be instantly accessible.\n>>> print(courses[0])\nTST101 Test Course (1234567)\n\n# Iterate over our course list\n>>> for course in courses:\n print(course)\n\nTST101 Test Course 1 (1234567)\nTST102 Test Course 2 (1234568)\nTST103 Test Course 3 (1234569)\n\n# Take a slice of our course list\n>>> courses[:2]\n[TST101 Test Course 1 (1234567), TST102 Test Course 2 (1234568)]\n```\n\n#### Keyword arguments\n\nMost of Canvas\u2019s API endpoints accept a variety of arguments. CanvasAPI allows developers to insert keyword arguments when making calls to endpoints that accept arguments.\n\n```python\n# Get all of the active courses a user is currently enrolled in\n>>> courses = user.get_courses(enrollment_state='active')\n```\n\nFor a more detailed description of how CanvasAPI handles more complex keyword arguments, check out the [Keyword Argument Documentation](http://canvasapi.readthedocs.io/en/stable/keyword-args.html).\n\n## CanvasAPI Projects\n\nSince its initial release in June 2016, CanvasAPI has amassed over 100 [dependent repositories](https://github.com/ucfopen/canvasapi/network/dependents). Many of these include various tools used to enhance the Canvas experience for both instructors and students. Here are a few popular repositories that use CanvasAPI:\n\n- [Canvas Grab](https://github.com/skyzh/canvas_grab)\n - Canvas Grab is the most popular project using CanvasAPI. This tool, with one click, copies all files from Canvas LMS to local directory. CanvasAPI is used in this project to connect to a course and grab its files.\n- [Clanvas](https://github.com/marklalor/clanvas)\n - Clanvas is a command-line client for Canvas. It uses the already available bash commands plus some additional ones to interact with various features of Canvas from the commmand line.\n- [CS221Bot](https://github.com/Person314159/cs221bot)\n - CS221Bot is a Discord bot for the CPCS 221 course at University of British Columbia. CanvasAPI is used in this project to connect to and synchronize with a course and get its data, such as announcements, new assignments, and more.\n\nIf you have a project that uses CanvasAPI that you'd like to promote, please contact us!\n\n## Contact Us\n\nNeed help? Have an idea? Feel free to check out our [Discussions](https://github.com/ucfopen/canvasapi/discussions) board. Just want to say hi or get extended spport? Come join us on the [UCF Open Slack Channel](https://dl.ucf.edu/join-ucfopen) and join the `#canvasapi` channel!\n",
"bugtrack_url": null,
"license": "MIT License",
"summary": "API wrapper for the Canvas LMS",
"version": "3.2.0",
"project_urls": {
"Homepage": "https://github.com/ucfopen/canvasapi"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "2a68316c1778181b175a1cf139c20f795da0f4164e7da9ef31d8f3652c182358",
"md5": "aae63daf0f4f156455a297e82a540146",
"sha256": "7cf97ad1ddc860e250c3453e229897ed1273095ad061c34baf651bf1b0e5a9c7"
},
"downloads": -1,
"filename": "canvasapi-3.2.0.tar.gz",
"has_sig": false,
"md5_digest": "aae63daf0f4f156455a297e82a540146",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 87042,
"upload_time": "2023-05-25T14:45:54",
"upload_time_iso_8601": "2023-05-25T14:45:54.522603Z",
"url": "https://files.pythonhosted.org/packages/2a/68/316c1778181b175a1cf139c20f795da0f4164e7da9ef31d8f3652c182358/canvasapi-3.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-05-25 14:45:54",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ucfopen",
"github_project": "canvasapi",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "canvasapi"
}
JSON
