Merge pull request #448 from ucfopen/develop

Release v2.1.0

.github/CONTRIBUTING.md

@@ -6,28 +6,31 @@ Below you'll find guidelines for contributing that will keep our codebase clean
 
 ## Table of Contents
 
-* [How can I contribute?](#how-can-i-contribute)
-    * [Bug reports](#bug-reports)
-    * [Resolving issues](#resolving-issues)
-    * [Making your first contribution](#making-your-first-contribution)
-        * [Setting up the environment](#setting-up-the-environment)
-        * [Writing tests](#writing-tests)
-            * [API Coverage Tests](#api-coverage-tests)
-            * [Engine tests](#engine-tests)
-        * [Running tests / coverage reports](#running-tests--coverage-reports)
-        * [Making a Pull Request](#making-a-pull-request)
-* [Code style guidelines](#code-style-guidelines)
-    * [Foolish consistency](#foolish-consistency)
-    * [Method docstrings](#method-docstrings)
-        * [Descriptions](#descriptions)
-        * [Links to related API endpoints](#links-to-related-api-endpoints)
-        * [Parameters](#parameters)
-        * [Returns](#returns)
-        * [Docstring examples](#docstring-examples)
+* [Contributing to CanvasAPI](#contributing-to-canvasapi)
+    * [Table of Contents](#table-of-contents)
+    * [How can I contribute?](#how-can-i-contribute)
+        * [Bug reports](#bug-reports)
+        * [Resolving issues](#resolving-issues)
+        * [Making your first contribution](#making-your-first-contribution)
+            * [Setting up the environment](#setting-up-the-environment)
+            * [Writing tests](#writing-tests)
+                * [API coverage tests](#api-coverage-tests)
+                * [Engine tests](#engine-tests)
+            * [Running tests / coverage reports](#running-tests--coverage-reports)
+            * [Making a pull request](#making-a-pull-request)
+    * [Code style guidelines](#code-style-guidelines)
+        * [Running code style checks](#running-code-style-checks)
+        * [Foolish consistency](#foolish-consistency)
+        * [Method docstrings](#method-docstrings)
+            * [Descriptions](#descriptions)
+            * [Links to related API endpoints](#links-to-related-api-endpoints)
+            * [Parameters](#parameters)
+            * [Returns](#returns)
+            * [Docstring Examples](#docstring-examples)
 
 ## How can I contribute?
 
-### Bug Reports
+### Bug reports
 
 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).
 
@@ -42,28 +45,29 @@ Here are a few things worth mentioning when making a report:
 
 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:
 
-* [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.
-* [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.
-* [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.
-* [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.
-* [bug](https://github.com/ucfopen/canvasapi/issues?q=sort%3Aid_desc-desc+is%3Aopen+label%3Abug) -- happy little code accidents.
-* [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.
-* [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.
-* [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!
-* [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/).
+* [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.
+* [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.
+* [bug](https://github.com/ucfopen/canvasapi/issues?q=sort%3Aid_desc-desc+is%3Aopen+label%3Abug): happy little code accidents.
+* [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.
+* [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/).
+* [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.
+* [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!
+* [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.
+* [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
+* [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.
 
 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.
 
 ### Making your first contribution
 
 #### Setting up the environment
 
-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.
+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.
 
-1. Clone our repository by executing `git clone git@github.com:ucfopen/canvasapi.git`
-2. Checkout (`git checkout develop`) and then pull the latest commit from the develop branch: `git pull origin develop`
+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))
+2. Checkout (`git checkout develop`) and then pull the latest commit from the develop branch: `git pull upstream develop`
 3. Create a new branch with the format **issue/[issue_number]-[issue-title]**: `git checkout -b issue/1-test-issue-for-documentation`
-4. Set up a new virtual environment ( `virtualenv env` ) and activate it (`source env/bin/activate`)
+4. Set up a new virtual environment ( `python3 -m venv ~/.virtualenvs/canvasapi` ) and activate it
 5. Install the required dependencies with `pip install -r dev_requirements.txt`
 
 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
 
 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.
 
-##### API Coverage Tests
+##### API coverage tests
 
 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:
 
@@ -196,17 +200,30 @@ TOTAL                             1586      0   100%
 
 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)!
 
-#### Making a Pull Request
+#### Making a pull request
 
 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.
 
-## Code Style Guidelines
+## Code style guidelines
 
 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:
 
 * We use four spaces for indentation.
 * 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.
 
+### Running code style checks
+
+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.
+
+You can use [pre-commit](https://pre-commit.com/) to force each check to run before you create a commit locally:
+
+```sh
+pip install pre-commit
+pre-commit install
+```
+
+Alternatively, each step can be run manually one-by-one, or all at once executing `./scripts/run_tests.sh`.
+
 We use `flake8` for linting:
 
 ```sh
@@ -225,6 +242,12 @@ We require methods to be in alphabetical order for ease of reading. Run this scr
 python scripts/alphabetic.py
 ```
 
+All endpoint methods should accept arbitrary keyword arguments to enable parameter pass-through to Canvas:
+
+```sh
+python scripts/find_missing_kwargs.py
+```
+
 ### Foolish consistency
 
 > A foolish consistency is the hobgoblin of little minds. -- Ralph Waldo Emerson

.gitignore

@@ -15,6 +15,7 @@
 /docs/_build/
 /env/
 /env3/
+venv/
 /htmlcov/
 \#*#
 .vscode/settings.json

.travis.yml

@@ -16,6 +16,7 @@ install:
 script:
   - coverage run -m unittest discover
   - black --check canvasapi tests
+  - isort --check canvasapi tests
   - flake8 canvasapi tests
   - mdl . .github
   - python scripts/alphabetic.py

AUTHORS.md

@@ -16,8 +16,10 @@ Patches and Suggestions
 - [@amorqiu](https://github.com/amorqiu)
 - Andrew Gardener [@andrew-gardener](https://github.com/andrew-gardener)
 - Anthony Rodriguez [@AnthonyRodriguez726](https://github.com/AnthonyRodriguez726)
+- Ashutosh Saxena [@Xx-Ashutosh-xX](https://github.com/Xx-Ashutosh-xX)
 - Ben Liblit [@liblit](https://github.com/liblit)
 - Bill Wrbican [@wjw27](https://github.com/wjw27)
+- [@blepabyte](https://github.com/blepabyte)
 - Bradford Lynch [@bradfordlynch](https://github.com/bradfordlynch)
 - Brian Bennett [@bennettscience](https://github.com/bennettscience)
 - Bruce Spang [@brucespang](https://github.com/brucespang)

CHANGELOG.md

@@ -2,6 +2,30 @@
 
 ## [Unreleased]
 
+## [2.1.0] - 2020-12-04
+
+### New Endpoint Coverage
+
+- Course TODO items (Thanks, [@onomou](https://github.com/onomou))
+- Create observer pairing code (Thanks, [@bennettscience](https://github.com/bennettscience))
+
+### General
+
+- 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))
+- `Canvas.get_announcement` now has a required parameter `context_codes`, which accepts a list of course IDs or `Course` objects.
+- Updated contributing guide
+- Added missing documentation for the "Smart DateTimes" feature
+- Added basic troubleshooting guide to documentation
+
+### Bugfixes
+
+- Fixed an issue where an `Announcement` object sometimes didn't have an associated course ID. (Thanks, [@bennettscience](https://github.com/bennettscience))
+- Fixed an issue where an encoding problem could lead to file downloads hanging indefinitely. (Thanks, [@blepabyte](https://github.com/blepabyte))
+
+### Deprecation Warnings
+
+- 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'})`
+
 ## [2.0.0] - 2020-08-14
 
 ### General
@@ -487,7 +511,8 @@ Huge thanks to [@liblit](https://github.com/liblit) for lots of issues, suggesti
 - Fixed some incorrectly defined parameters
 - Fixed an issue where tests would fail due to an improperly configured requires block
 
-[Unreleased]: https://github.com/ucfopen/canvasapi/compare/v2.0.0...develop
+[Unreleased]: https://github.com/ucfopen/canvasapi/compare/v2.1.0...develop
+[2.1.0]: https://github.com/ucfopen/canvasapi/compare/v2.0.0...v2.1.0
 [2.0.0]: https://github.com/ucfopen/canvasapi/compare/v1.0.0...v2.0.0
 [1.0.0]: https://github.com/ucfopen/canvasapi/compare/v0.16.1...v1.0.0
 [0.16.1]: https://github.com/ucfopen/canvasapi/compare/v0.16.0...v0.16.1

README.md

@@ -13,15 +13,18 @@ CanvasAPI is a Python library for accessing Instructure’s [Canvas LMS API](htt
 
 ## Table of Contents
 
-* [Installation](#installation)
-* [Documentation](#documentation)
-* [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)
-* [Contact Us](#contact-us)
+* [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)
+    * [Contact Us](#contact-us)
 
 ## Installation
 
@@ -33,6 +36,10 @@ You can install CanvasAPI with pip:
 
 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.
@@ -58,7 +65,7 @@ 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/latest/class-reference.html). Below, you’ll find a few examples of common CanvasAPI use cases.
+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
 
@@ -146,7 +153,7 @@ Most of Canvas’s API endpoints accept a variety of arguments. CanvasAPI allows
 >>> 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](http://canvasapi.readthedocs.io/en/latest/keyword-args.html).
+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).
 
 ## Contact Us
 

canvasapi/__init__.py

@@ -4,4 +4,4 @@
 
 __all__ = ["Canvas"]
 
-__version__ = "2.0.0"
+__version__ = "2.1.0"

canvasapi/account.py

@@ -1,8 +1,8 @@
 from canvasapi.canvas_object import CanvasObject
 from canvasapi.exceptions import CanvasException, RequiredFieldMissing
 from canvasapi.feature import Feature, FeatureFlag
-from canvasapi.grading_standard import GradingStandard
 from canvasapi.grading_period import GradingPeriod
+from canvasapi.grading_standard import GradingStandard
 from canvasapi.outcome_import import OutcomeImport
 from canvasapi.paginated_list import PaginatedList
 from canvasapi.rubric import Rubric

canvasapi/assignment.py

@@ -5,8 +5,7 @@
 from canvasapi.progress import Progress
 from canvasapi.submission import Submission
 from canvasapi.upload import Uploader
-from canvasapi.user import User
-from canvasapi.user import UserDisplay
+from canvasapi.user import User, UserDisplay
 from canvasapi.util import combine_kwargs, obj_or_id