| Name | edq-canvas JSON |
| Version |
0.0.5
JSON |
| download |
| home_page | None |
| Summary | A suite of tools and Python interface for Instructure's Canvas LMS. |
| upload_time | 2024-04-11 23:02:32 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.8 |
| license | MIT License Copyright (c) 2023 Eriq Augustine Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. |
| keywords |
education
lms
canvas
api
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
json5
platformdirs
requests
build
packaging
twine
vermin
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Canvas Tools
A suite of tools and Python interface for Instructure's Canvas LMS.
This project is not affiliated with Instructure.
Documentation Table of Contents:
- [Installation](#installation)
- [CLI Configuration](#cli-configuration)
- [Usage Notes](#usage-notes)
- [User Queries](#user-queries)
- [Assignment Queries](#assignment-queries)
- [CLI Tools](#cli-tools)
- [List Course Users](#list-course-users)
- [Fetch a Single User](#fetch-a-single-user)
- [List Assignments](#list-assignments)
- [Fetch a Single Assignment](#fetch-a-single-assignment)
- [Fetch Assignment Scores](#fetch-assignment-scores)
- [Upload Assignment Scores](#upload-assignment-scores)
- [Upload Single Assignment Score](#upload-single-assignment-score)
- [Fetch Gradebook](#fetch-gradebook)
- [Upload Gradebook](#upload-gradebook)
## Installation
The project (tools and API) can be installed from PyPi with:
```
pip install edq-canvas
```
Standard Python requirements are listed in `pyproject.toml`.
The project and Python dependencies can be installed from source with:
```
pip3 install .
```
### CLI Configuration
Before discussing specific tools, you should know some general information about
configuring and sending options to each CLI tool.
To know who you are and what you are working on the package needs a few configuration options:
- `server` -- The Canvas server to connect to.
- `course` -- The Canvas ID for the course you are working with.
- `token` -- Your Canvas API token (see the [Canvas documentation](https://community.canvaslms.com/t5/Admin-Guide/How-do-I-manage-API-access-tokens-as-an-admin/ta-p/89).
- `assignment` -- A query for the current assignment you are working on (does not always apply).
All these options can be set on the command line when invoking on of these tools, e.g.,:
```sh
python3 -m canvas.cli.user.list --server canvas.test.com --course 12345 --token abc123
```
However, it will generally be more convenient to hold these common options in a more reusable location.
There are several other places that config options can be specified,
with each later location overriding any earlier options.
Here are the places options can be specified in the order that they are checked:
1. `./edq-canvas.json` -- If a `edq-canvas.json` exists in the current directory, it is loaded.
2. `<platform-specific user config location>/edq-canvas.json` -- A directory which is considered the "proper" place to store user-related config for the platform you are using (according to [platformdirs](https://github.com/platformdirs/platformdirs)). Use `--help` to see the exact place in your specific case. This is a great place to store login credentials.
3. Files specified by `--config` -- These files are loaded in the order they appear on the command-line.
4. Bare Options -- Options specified directly like `--course` or `--token`. These will override all previous options.
Using the default config file (`edq-canvas.json`):
```sh
# `./edq-canvas.json` will be looked for and loaded if it exists.
python3 -m canvas.cli.user.list
```
Using a custom config file (`my_config.json`):
```sh
# `./my_config.json` will be used.
python3 -m canvas.cli.user.list --config my_config.json
```
A sample config file is provided in this repo at [sample-edq-canvas.json](./sample-edq-canvas.json).
For brevity, all future commands in this document will assume that all standard config options are in the default
config files (and thus will not need to be specified).
## Usage Notes
### User Queries
When a user is required, tools and API functions accept a "user query" (unless specified).
A user query is any object that can be used to uniquely identify a user.
Valid user queries are:
- Canvas User ID (as an integer or string of digits)
- Email
- Full Name
- "email (id)" where "email" is an email and "id" is a Canvas ID
User queries must be unambiguous within the pool of possible users (e.g., students in a course).
It is recommended to use an email or Canvas ID as a user query.
Resolving a user query that is not a Canvas ID will take longer,
because a list of users must be fetched from Canvas.
### Assignment Queries
When an assignment is required, tools and API functions accept an "assignment query" (unless specified).
An assignment query is any object that can be used to uniquely identify an assignment.
Valid assignment queries are:
- Canvas Assignment ID (as an integer or string of digits)
- Full Name
- "name (id)" where "name" is a full assignment name and "id" is a Canvas ID
Assignment queries must be unambiguous within the pool of possible assignments (e.g., assignments in a course).
Resolving an assignment query that is not a Canvas ID will take longer,
because a list of assignments must be fetched from Canvas.
## CLI Tools
All CLI tools can be invoked with `-h` / `--help` to see the full usage and all options.
### List Course Users
Course users can be listed using the `canvas.cli.user.list` tool.
For example:
```
python3 -m canvas.cli.user.list
```
To list each user as a tab-separated row, use the `-t` / `--table` option:
```
python3 -m canvas.cli.user.list --table
```
### Fetch a Single User
To fetch information about a single course user, use the `canvas.cli.user.fetch` tool.
For example:
```
python3 -m canvas.cli.user.fetch 12345
```
### List Assignments
Course assignments can be listed using the `canvas.cli.assignment.list` tool.
For example:
```
python3 -m canvas.cli.assignment.list
```
To list each assignment as a tab-separated row, use the `-t` / `--table` option:
```
python3 -m canvas.cli.assignment.list --table
```
### Fetch a Single Assignment
Fetch information about a single assignment using the `canvas.cli.assignment.fetch` tool.
For example:
```
python3 -m canvas.cli.assignment.fetch 123456
python3 -m canvas.cli.assignment.fetch 'My Assignment'
```
### Fetch Assignment Scores
To fetch the scores for a specific assignment, use the `canvas.cli.assignment.fetch-scores` tool.
For example:
```
python3 -m canvas.cli.assignment.fetch-scores 123456
python3 -m canvas.cli.assignment.fetch-scores 'My Assignment'
```
The student's email and score will be written to stdout as a tab-separated row.
### Upload Assignment Scores
Uploading scores for an assignment can be done with the `canvas.cli.assignment.upload-scores` tool:
```
python3 -m canvas.cli.assignment.upload-scores <assignment query> <path>
```
Where `<path>` points to a tab-separated file where each row has 2-3 columns: email, score, and comment (optional).
Each row does not need to have the same length (i.e., some rows can have comments where others do not).
Empty comments are ignored.
The `--skip-rows` argument can be used to skip a specified number of header rows.
For example:
```
python3 -m canvas.cli.assignment.upload-scores 'My Assignment' grades.txt --skip-rows 1
```
Where `grades.txt` looks like:
```
user score comment?
1001 75
alice@uni.edu 100 Great Job!
```
### Upload Single Assignment Score
To upload just one assignment score without a file, you can use the `canvas.cli.assignment.upload-score` tool:
```
python3 -m canvas.cli.assignment.upload-score <assignment query> <user query> <score> [comment]
```
Note that the comment is optional.
For example:
```
python3 -m canvas.cli.assignment.upload-score 'My Assignment' alice@uni.edu 100 'Great Job!'
```
### Fetch Gradebook
To fetch the full gradebook for a course, use the `canvas.cli.gradebook.fetch` tool.
For example:
```
python3 -m canvas.cli.gradebook.fetch
```
A gradebook will be written to stdout as a tab-separated file.
To output the gradebook to a file, you can redirect stdout to a file.
Expect this command to take a few minutes for larger classes.
You can limit to gradebook to only specific students by specifying their IDs on the command line.
Any number of students can be specified.
```
python3 -m canvas.cli.gradebook.fetch 12345 67890
```
By default, assignments and users without submissions will be pruned.
They can be included by using the respective `--include-empty-assignments` and `--include-empty-users` flags.
For example, you can write a gradebook with all assignments and users to `grades.txt` using the following command:
```
python3 -m canvas.cli.gradebook.fetch --include-empty-assignments --include-empty-users > grades.txt
```
### Upload Gradebook
To upload a gradebook, use the `canvas.cli.gradebook.upload` tool:
```
python3 -m canvas.cli.gradebook.upload <path>
```
Where `<path>` points to a gradebook file that has the same format as the output from `canvas.cli.gradebook.fetch`:
a tab-separated file with users down the rows and assignments along the columns.
The first column is user queries where the first cell is ignored,
the first row is assignment queries where the first cell is ignored,
and the remaining cells are the associated scores.
Any number of users and assignments can be specified as long as they exist in the course.
Empty cells will not be uploaded.
A gradebook file can look like:
```
user 98765 Assignment 2
1001 1 2
alice@uni.edu 3
```
Raw data
{
"_id": null,
"home_page": null,
"name": "edq-canvas",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "education, lms, canvas, api",
"author": null,
"author_email": "Eriq Augustine <eaugusti@ucsc.edu>",
"download_url": "https://files.pythonhosted.org/packages/24/8e/c5d99ba26d1a4c9e41889f4746abf6a8d99e2106cc3471d95d437367b5c7/edq-canvas-0.0.5.tar.gz",
"platform": null,
"description": "# Canvas Tools\n\nA suite of tools and Python interface for Instructure's Canvas LMS.\n\nThis project is not affiliated with Instructure.\n\nDocumentation Table of Contents:\n - [Installation](#installation)\n - [CLI Configuration](#cli-configuration)\n - [Usage Notes](#usage-notes)\n - [User Queries](#user-queries)\n - [Assignment Queries](#assignment-queries)\n - [CLI Tools](#cli-tools)\n - [List Course Users](#list-course-users)\n - [Fetch a Single User](#fetch-a-single-user)\n - [List Assignments](#list-assignments)\n - [Fetch a Single Assignment](#fetch-a-single-assignment)\n - [Fetch Assignment Scores](#fetch-assignment-scores)\n - [Upload Assignment Scores](#upload-assignment-scores)\n - [Upload Single Assignment Score](#upload-single-assignment-score)\n - [Fetch Gradebook](#fetch-gradebook)\n - [Upload Gradebook](#upload-gradebook)\n\n## Installation\n\nThe project (tools and API) can be installed from PyPi with:\n```\npip install edq-canvas\n```\n\nStandard Python requirements are listed in `pyproject.toml`.\nThe project and Python dependencies can be installed from source with:\n```\npip3 install .\n```\n\n### CLI Configuration\n\nBefore discussing specific tools, you should know some general information about\nconfiguring and sending options to each CLI tool.\n\nTo know who you are and what you are working on the package needs a few configuration options:\n - `server` -- The Canvas server to connect to.\n - `course` -- The Canvas ID for the course you are working with.\n - `token` -- Your Canvas API token (see the [Canvas documentation](https://community.canvaslms.com/t5/Admin-Guide/How-do-I-manage-API-access-tokens-as-an-admin/ta-p/89).\n - `assignment` -- A query for the current assignment you are working on (does not always apply).\n\nAll these options can be set on the command line when invoking on of these tools, e.g.,:\n```sh\npython3 -m canvas.cli.user.list --server canvas.test.com --course 12345 --token abc123\n```\nHowever, it will generally be more convenient to hold these common options in a more reusable location.\n\nThere are several other places that config options can be specified,\nwith each later location overriding any earlier options.\nHere are the places options can be specified in the order that they are checked:\n 1. `./edq-canvas.json` -- If a `edq-canvas.json` exists in the current directory, it is loaded.\n 2. `<platform-specific user config location>/edq-canvas.json` -- A directory which is considered the \"proper\" place to store user-related config for the platform you are using (according to [platformdirs](https://github.com/platformdirs/platformdirs)). Use `--help` to see the exact place in your specific case. This is a great place to store login credentials.\n 3. Files specified by `--config` -- These files are loaded in the order they appear on the command-line.\n 4. Bare Options -- Options specified directly like `--course` or `--token`. These will override all previous options.\n\nUsing the default config file (`edq-canvas.json`):\n```sh\n# `./edq-canvas.json` will be looked for and loaded if it exists.\npython3 -m canvas.cli.user.list\n```\n\nUsing a custom config file (`my_config.json`):\n```sh\n# `./my_config.json` will be used.\npython3 -m canvas.cli.user.list --config my_config.json\n```\n\nA sample config file is provided in this repo at [sample-edq-canvas.json](./sample-edq-canvas.json).\n\nFor brevity, all future commands in this document will assume that all standard config options are in the default\nconfig files (and thus will not need to be specified).\n\n## Usage Notes\n\n### User Queries\n\nWhen a user is required, tools and API functions accept a \"user query\" (unless specified).\nA user query is any object that can be used to uniquely identify a user.\nValid user queries are:\n - Canvas User ID (as an integer or string of digits)\n - Email\n - Full Name\n - \"email (id)\" where \"email\" is an email and \"id\" is a Canvas ID\n\nUser queries must be unambiguous within the pool of possible users (e.g., students in a course).\nIt is recommended to use an email or Canvas ID as a user query.\nResolving a user query that is not a Canvas ID will take longer,\nbecause a list of users must be fetched from Canvas.\n\n### Assignment Queries\n\nWhen an assignment is required, tools and API functions accept an \"assignment query\" (unless specified).\nAn assignment query is any object that can be used to uniquely identify an assignment.\nValid assignment queries are:\n - Canvas Assignment ID (as an integer or string of digits)\n - Full Name\n - \"name (id)\" where \"name\" is a full assignment name and \"id\" is a Canvas ID\n\nAssignment queries must be unambiguous within the pool of possible assignments (e.g., assignments in a course).\nResolving an assignment query that is not a Canvas ID will take longer,\nbecause a list of assignments must be fetched from Canvas.\n\n## CLI Tools\n\nAll CLI tools can be invoked with `-h` / `--help` to see the full usage and all options.\n\n### List Course Users\n\nCourse users can be listed using the `canvas.cli.user.list` tool.\nFor example:\n```\npython3 -m canvas.cli.user.list\n```\n\nTo list each user as a tab-separated row, use the `-t` / `--table` option:\n```\npython3 -m canvas.cli.user.list --table\n```\n\n### Fetch a Single User\n\nTo fetch information about a single course user, use the `canvas.cli.user.fetch` tool.\nFor example:\n```\npython3 -m canvas.cli.user.fetch 12345\n```\n\n### List Assignments\n\nCourse assignments can be listed using the `canvas.cli.assignment.list` tool.\nFor example:\n```\npython3 -m canvas.cli.assignment.list\n```\n\nTo list each assignment as a tab-separated row, use the `-t` / `--table` option:\n```\npython3 -m canvas.cli.assignment.list --table\n```\n\n### Fetch a Single Assignment\n\nFetch information about a single assignment using the `canvas.cli.assignment.fetch` tool.\nFor example:\n```\npython3 -m canvas.cli.assignment.fetch 123456\n\npython3 -m canvas.cli.assignment.fetch 'My Assignment'\n```\n\n### Fetch Assignment Scores\n\nTo fetch the scores for a specific assignment, use the `canvas.cli.assignment.fetch-scores` tool.\nFor example:\n```\npython3 -m canvas.cli.assignment.fetch-scores 123456\n\npython3 -m canvas.cli.assignment.fetch-scores 'My Assignment'\n```\n\nThe student's email and score will be written to stdout as a tab-separated row.\n\n### Upload Assignment Scores\n\nUploading scores for an assignment can be done with the `canvas.cli.assignment.upload-scores` tool:\n```\npython3 -m canvas.cli.assignment.upload-scores <assignment query> <path>\n```\n\nWhere `<path>` points to a tab-separated file where each row has 2-3 columns: email, score, and comment (optional).\nEach row does not need to have the same length (i.e., some rows can have comments where others do not).\nEmpty comments are ignored.\n\nThe `--skip-rows` argument can be used to skip a specified number of header rows.\nFor example:\n```\npython3 -m canvas.cli.assignment.upload-scores 'My Assignment' grades.txt --skip-rows 1\n```\n\nWhere `grades.txt` looks like:\n```\nuser\tscore\tcomment?\n1001\t75\nalice@uni.edu\t100\tGreat Job!\n```\n\n### Upload Single Assignment Score\n\nTo upload just one assignment score without a file, you can use the `canvas.cli.assignment.upload-score` tool:\n```\npython3 -m canvas.cli.assignment.upload-score <assignment query> <user query> <score> [comment]\n```\n\nNote that the comment is optional.\n\nFor example:\n```\npython3 -m canvas.cli.assignment.upload-score 'My Assignment' alice@uni.edu 100 'Great Job!'\n```\n\n### Fetch Gradebook\n\nTo fetch the full gradebook for a course, use the `canvas.cli.gradebook.fetch` tool.\nFor example:\n```\npython3 -m canvas.cli.gradebook.fetch\n```\n\nA gradebook will be written to stdout as a tab-separated file.\nTo output the gradebook to a file, you can redirect stdout to a file.\nExpect this command to take a few minutes for larger classes.\n\nYou can limit to gradebook to only specific students by specifying their IDs on the command line.\nAny number of students can be specified.\n```\npython3 -m canvas.cli.gradebook.fetch 12345 67890\n```\n\nBy default, assignments and users without submissions will be pruned.\nThey can be included by using the respective `--include-empty-assignments` and `--include-empty-users` flags.\n\nFor example, you can write a gradebook with all assignments and users to `grades.txt` using the following command:\n```\npython3 -m canvas.cli.gradebook.fetch --include-empty-assignments --include-empty-users > grades.txt\n```\n\n### Upload Gradebook\n\nTo upload a gradebook, use the `canvas.cli.gradebook.upload` tool:\n```\npython3 -m canvas.cli.gradebook.upload <path>\n```\n\nWhere `<path>` points to a gradebook file that has the same format as the output from `canvas.cli.gradebook.fetch`:\na tab-separated file with users down the rows and assignments along the columns.\nThe first column is user queries where the first cell is ignored,\nthe first row is assignment queries where the first cell is ignored,\nand the remaining cells are the associated scores.\nAny number of users and assignments can be specified as long as they exist in the course.\nEmpty cells will not be uploaded.\n\nA gradebook file can look like:\n```\nuser\t98765\tAssignment 2\n1001\t1\t2\nalice@uni.edu\t3\t\n```\n",
"bugtrack_url": null,
"license": "MIT License Copyright (c) 2023 Eriq Augustine Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the \"Software\"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. ",
"summary": "A suite of tools and Python interface for Instructure's Canvas LMS.",
"version": "0.0.5",
"project_urls": {
"Homepage": "https://github.com/edulinq/py-canvas",
"Repository": "https://github.com/edulinq/py-canvas"
},
"split_keywords": [
"education",
" lms",
" canvas",
" api"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "0c408448c7cbd9daf762c47039379e3f71b07334418fc808828b1d24bad4804f",
"md5": "d2c9d30283d10f8af8e730c6745c3614",
"sha256": "62e351d4aae86aca0834b568995ce1ae1b723a9a2934b259fc5c9ff12b4f917b"
},
"downloads": -1,
"filename": "edq_canvas-0.0.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d2c9d30283d10f8af8e730c6745c3614",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 33868,
"upload_time": "2024-04-11T23:02:30",
"upload_time_iso_8601": "2024-04-11T23:02:30.401123Z",
"url": "https://files.pythonhosted.org/packages/0c/40/8448c7cbd9daf762c47039379e3f71b07334418fc808828b1d24bad4804f/edq_canvas-0.0.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "248ec5d99ba26d1a4c9e41889f4746abf6a8d99e2106cc3471d95d437367b5c7",
"md5": "7131e6bef19a8c412cb4d887d4ac5534",
"sha256": "c8cf15a7956209c321348da5628355fe6f4196a146d823ab7f1d7a92114b8bc2"
},
"downloads": -1,
"filename": "edq-canvas-0.0.5.tar.gz",
"has_sig": false,
"md5_digest": "7131e6bef19a8c412cb4d887d4ac5534",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 23427,
"upload_time": "2024-04-11T23:02:32",
"upload_time_iso_8601": "2024-04-11T23:02:32.247774Z",
"url": "https://files.pythonhosted.org/packages/24/8e/c5d99ba26d1a4c9e41889f4746abf6a8d99e2106cc3471d95d437367b5c7/edq-canvas-0.0.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-11 23:02:32",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "edulinq",
"github_project": "py-canvas",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "json5",
"specs": [
[
">=",
"0.9.14"
]
]
},
{
"name": "platformdirs",
"specs": [
[
">=",
"3.10.0"
]
]
},
{
"name": "requests",
"specs": [
[
">=",
"2.31.0"
]
]
},
{
"name": "build",
"specs": []
},
{
"name": "packaging",
"specs": [
[
">=",
"21.3"
]
]
},
{
"name": "twine",
"specs": []
},
{
"name": "vermin",
"specs": []
}
],
"lcname": "edq-canvas"
}
