You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
*[Links to related API endpoints](#links-to-related-api-endpoints)
27
+
*[Parameters](#parameters)
28
+
*[Returns](#returns)
29
+
*[Docstring Examples](#docstring-examples)
27
30
28
31
## How can I contribute?
29
32
30
-
### Bug Reports
33
+
### Bug reports
31
34
32
35
Bug reports are awesome. Writing quality bug reports helps us identify issues and solve them even faster. You can submit bug reports directly to our [issue tracker](https://github.com/ucfopen/canvasapi/issues).
33
36
@@ -42,28 +45,29 @@ Here are a few things worth mentioning when making a report:
42
45
43
46
We welcome pull requests for bug fixes and new features! Feel free to browse our open, unassigned issues and assign yourself to them. You can also filter by labels:
44
47
45
-
*[simple](https://github.com/ucfopen/canvasapi/issues?q=sort%3Aid_desc-desc+is%3Aopen+label%3Asimple) -- easier issues to start working on; great for getting familiar with the codebase.
46
-
*[api coverage](https://github.com/ucfopen/canvasapi/issues?q=sort%3Aid_desc-desc+is%3Aopen+label%3Aapi-coverage) -- covering new endpoints or updating existing ones.
47
-
*[enhancement](https://github.com/ucfopen/canvasapi/issues?q=sort%3Aid_desc-desc+is%3Aopen+label%3Aenhancement) -- updates to the engine to improve performance or add new functionality.
48
-
*[major](https://github.com/ucfopen/canvasapi/issues?q=sort%3Aid_desc-desc+is%3Aopen+label%3Amajor) -- difficult or major changes or additions that require familiarity with the library.
49
-
*[bug](https://github.com/ucfopen/canvasapi/issues?q=sort%3Aid_desc-desc+is%3Aopen+label%3Abug) -- happy little code accidents.
50
-
*[fixed-in-develop](https://github.com/ucfopen/canvasapi/issues?q=sort%3Aid_desc-desc+is%3Aopen+label%3Afixed-in-develop) -- issues that have been resolved but the changes are not in the latest release yet.
51
-
*[canvas-bug](https://github.com/ucfopen/canvasapi/issues?q=sort%3Aid_desc-desc+is%3Aopen+label%3Acanvas-bug) -- confirmed to be an issue with the Canvas LMS rather than the CanvasAPI library.
52
-
*[help wanted](https://github.com/ucfopen/canvasapi/issues?q=sort%3Aid_desc-desc+is%3Aopen+label%3A"help%20wanted") -- we need *your* help to figure these out!
53
-
*[documentation](https://github.com/ucfopen/canvasapi/issues?q=sort%3Aid_desc-desc+is%3Aopen+label%3Adocumentation) -- issues relating to Documentation. Specifically, any of the `.md` files or our [class reference docs](http://canvasapi.readthedocs.io/en/latest/).
48
+
*[api coverage](https://github.com/ucfopen/canvasapi/issues?q=sort%3Aid_desc-desc+is%3Aopen+label%3Aapi-coverage): covering new endpoints or updating existing ones.
49
+
*[backstage](https://github.com/ucfopen/canvasapi/issues?q=sort%3Aid_desc-desc+is%3Aopen+label%3Abackstage): issues affecting the repository or project internals rather than user-facing features.
50
+
*[bug](https://github.com/ucfopen/canvasapi/issues?q=sort%3Aid_desc-desc+is%3Aopen+label%3Abug): happy little code accidents.
51
+
*[canvas](https://github.com/ucfopen/canvasapi/issues?q=sort%3Aid_desc-desc+is%3Aopen+label%3Acanvas-bug): confirmed to be an issue with the Canvas LMS rather than the CanvasAPI library.
52
+
*[documentation](https://github.com/ucfopen/canvasapi/issues?q=sort%3Aid_desc-desc+is%3Aopen+label%3Adocumentation): issues relating to Documentation. Specifically, any of the `.md` files or our [class reference docs](http://canvasapi.readthedocs.io/en/latest/).
53
+
*[enhancement](https://github.com/ucfopen/canvasapi/issues?q=sort%3Aid_desc-desc+is%3Aopen+label%3Aenhancement): updates to the engine to improve performance or add new functionality.
54
+
*[help wanted](https://github.com/ucfopen/canvasapi/issues?q=sort%3Aid_desc-desc+is%3Aopen+label%3A"help%20wanted"): we need *your* help to figure these out!
55
+
*[major](https://github.com/ucfopen/canvasapi/issues?q=sort%3Aid_desc-desc+is%3Aopen+label%3Amajor): difficult or major changes or additions that require familiarity with the library.
56
+
*[question](https://github.com/ucfopen/canvasapi/issues?q=sort%3Aid_desc-desc+is%3Aopen+label%3Aquestion): issues that aren't reporting functionality or requesting improvement but requesting clarification on existing behavior
57
+
*[simple](https://github.com/ucfopen/canvasapi/issues?q=sort%3Aid_desc-desc+is%3Aopen+label%3Asimple): easier issues to start working on; great for getting familiar with the codebase.
54
58
55
59
Once you've found an issue you're interested in tackling, take a look at our [first contribution tutorial](#making-your-first-contribution) for information on our pull request policy.
56
60
57
61
### Making your first contribution
58
62
59
63
#### Setting up the environment
60
64
61
-
Now that you've selected an issue to work on, you'll need to set up an environment for writing code. We'll assume you already have pip, virtualenv, and git installed and are using a terminal. If not, please set those up before continuing.
65
+
Now that you've selected an issue to work on, you'll need to set up an environment for writing code. We'll assume you already have Python 3 (pip / venv) and git installed and are using a terminal. If not, please set those up before continuing.
62
66
63
-
1.Clone our repository by executing `git clone git@github.com:ucfopen/canvasapi.git`
64
-
2. Checkout (`git checkout develop`) and then pull the latest commit from the develop branch: `git pull origin develop`
67
+
1.Fork CanvasAPI on GitHub ([see the docs here](https://docs.github.com/en/free-pro-team@latest/github/getting-started-with-github/fork-a-repo))
68
+
2. Checkout (`git checkout develop`) and then pull the latest commit from the develop branch: `git pull upstream develop`
65
69
3. Create a new branch with the format **issue/[issue_number]-[issue-title]**: `git checkout -b issue/1-test-issue-for-documentation`
66
-
4. Set up a new virtual environment ( `virtualenv env` ) and activate it (`source env/bin/activate`)
70
+
4. Set up a new virtual environment ( `python3 -m venv ~/.virtualenvs/canvasapi` ) and activate it
67
71
5. Install the required dependencies with `pip install -r dev_requirements.txt`
68
72
69
73
From here, you can go about working on your issue you normally would. Please make sure to adhere to our [style guidelines for both code and docstrings](#code-style-guidelines). Once you're satisfied with the result, it's time to write a unit test for it.
@@ -74,7 +78,7 @@ Tests are a critical part of building applications, and we [pity the fool who do
74
78
75
79
You'll notice our tests live in the creatively named `tests` directory. Within that directory, you'll see several files in the form `test_[class].py` and another directory named `fixtures`. Depending on the scope of the issue you're solving, you'll be writing two different kinds of tests.
76
80
77
-
##### API Coverage Tests
81
+
##### API coverage tests
78
82
79
83
We use the [requests-mock](https://pypi.python.org/pypi/requests-mock) library to simulate API responses. Those mock responses live inside the `fixtures` directory in JSON files. Each file's name describes the endpoints that are contained within. For example, course endpoints live in `course.json`. These fixtures are loaded on demand in a given test. Let's look at `test_get_user` in `test_course.py` as an example:
80
84
@@ -196,17 +200,30 @@ TOTAL 1586 0 100%
196
200
197
201
Certain statements can be omitted from the coverage report by adding `# pragma: no cover` but this should be used conservatively. If your tests pass and your coverage is at 100%, you're ready to [submit a pull request](https://github.com/ucfopen/canvasapi/pulls)!
198
202
199
-
#### Making a Pull Request
203
+
#### Making a pull request
200
204
201
205
Be sure to include the issue number in the title with a pound sign in front of it (#123) so we know which issue the code is addressing. Point the branch at `develop` and then submit it for review.
202
206
203
-
## Code Style Guidelines
207
+
## Code style guidelines
204
208
205
209
We try to adhere to Python's [PEP 8](https://www.python.org/dev/peps/pep-0008/) specification as much as possible. In short, that means:
206
210
207
211
* We use four spaces for indentation.
208
212
* Lines should be around 80 characters long, but up to 99 is allowed. Once you get into the 85+ territory, consider breaking your code into separate lines.
209
213
214
+
### Running code style checks
215
+
216
+
The following tools can help you check your code for style correctness. We run these tools in our CI pipeline, so running them locally is a great way to speed up acceptance of your pull requests.
217
+
218
+
You can use [pre-commit](https://pre-commit.com/) to force each check to run before you create a commit locally:
219
+
220
+
```sh
221
+
pip install pre-commit
222
+
pre-commit install
223
+
```
224
+
225
+
Alternatively, each step can be run manually one-by-one, or all at once executing `./scripts/run_tests.sh`.
226
+
210
227
We use `flake8` for linting:
211
228
212
229
```sh
@@ -225,6 +242,12 @@ We require methods to be in alphabetical order for ease of reading. Run this scr
225
242
python scripts/alphabetic.py
226
243
```
227
244
245
+
All endpoint methods should accept arbitrary keyword arguments to enable parameter pass-through to Canvas:
246
+
247
+
```sh
248
+
python scripts/find_missing_kwargs.py
249
+
```
250
+
228
251
### Foolish consistency
229
252
230
253
> A foolish consistency is the hobgoblin of little minds. -- Ralph Waldo Emerson
- Added missing documentation for the get_current_user method and clarifications to the `CurrentUser` class. (Thanks, [@Xx-Ashutosh-xX](https://github.com/Xx-Ashutosh-xX))
15
+
-`Canvas.get_announcement` now has a required parameter `context_codes`, which accepts a list of course IDs or `Course` objects.
16
+
- Updated contributing guide
17
+
- Added missing documentation for the "Smart DateTimes" feature
18
+
- Added basic troubleshooting guide to documentation
19
+
20
+
### Bugfixes
21
+
22
+
- Fixed an issue where an `Announcement` object sometimes didn't have an associated course ID. (Thanks, [@bennettscience](https://github.com/bennettscience))
23
+
- Fixed an issue where an encoding problem could lead to file downloads hanging indefinitely. (Thanks, [@blepabyte](https://github.com/blepabyte))
24
+
25
+
### Deprecation Warnings
26
+
27
+
- The `enrollment_type` argument on `Course.enroll_user` is now deprecated. Pass this information to `enrollment[type]` as a keyword argument instead. e.g. `enroll_user(enrollment={'type': 'StudentEnrollment'})`
28
+
5
29
## [2.0.0] - 2020-08-14
6
30
7
31
### General
@@ -487,7 +511,8 @@ Huge thanks to [@liblit](https://github.com/liblit) for lots of issues, suggesti
487
511
- Fixed some incorrectly defined parameters
488
512
- Fixed an issue where tests would fail due to an improperly configured requires block
Copy file name to clipboardExpand all lines: README.md
+18-11Lines changed: 18 additions & 11 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -13,15 +13,18 @@ CanvasAPI is a Python library for accessing Instructure’s [Canvas LMS API](htt
13
13
14
14
## Table of Contents
15
15
16
-
*[Installation](#installation)
17
-
*[Documentation](#documentation)
18
-
*[Quickstart](#quickstart)
19
-
*[Working with Canvas Objects](#working-with-canvas-objects)
20
-
*[Course Objects](#course-objects)
21
-
*[User Objects](#user-objects)
22
-
*[Paginated Lists](#paginated-lists)
23
-
*[Keyword Arguments](#keyword-arguments)
24
-
*[Contact Us](#contact-us)
16
+
*[CanvasAPI](#canvasapi)
17
+
*[Table of Contents](#table-of-contents)
18
+
*[Installation](#installation)
19
+
*[Documentation](#documentation)
20
+
*[Contributing](#contributing)
21
+
*[Quickstart](#quickstart)
22
+
*[Working with Canvas Objects](#working-with-canvas-objects)
23
+
* [Course objects](#course-objects)
24
+
* [User objects](#user-objects)
25
+
* [Paginated Lists](#paginated-lists)
26
+
* [Keyword arguments](#keyword-arguments)
27
+
*[Contact Us](#contact-us)
25
28
26
29
## Installation
27
30
@@ -33,6 +36,10 @@ You can install CanvasAPI with pip:
33
36
34
37
Full documentation is available at [Read the Docs](http://canvasapi.readthedocs.io/).
35
38
39
+
## Contributing
40
+
41
+
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.
42
+
36
43
## Quickstart
37
44
38
45
Getting started with CanvasAPI is easy.
@@ -58,7 +65,7 @@ You can now use `canvas` to begin making API calls.
58
65
59
66
### Working with Canvas Objects
60
67
61
-
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/latest/class-reference.html). Below, you’ll find a few examples of common CanvasAPI use cases.
68
+
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.
62
69
63
70
#### Course objects
64
71
@@ -146,7 +153,7 @@ Most of Canvas’s API endpoints accept a variety of arguments. CanvasAPI allows
146
153
>>> courses = user.get_courses(per_page=50)
147
154
```
148
155
149
-
For a more detailed description of how CanvasAPI handles more complex keyword arguments, check out the [Keyword Argument Documentation](http://canvasapi.readthedocs.io/en/latest/keyword-args.html).
156
+
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).
0 commit comments