add Makefile for testing and updated README.rst

Author: Kevin Hansen

.gitignore

@@ -3,3 +3,4 @@ __pycache__
 *egg-info*
 *.eggs
 /dist/
+.cache

Makefile

@@ -0,0 +1,2 @@
+test:
+	nosetests tests

README.rst

@@ -1,41 +1,112 @@
 py_canvas_api
-=============
+#############
 
 The idea is to have a simple, easy to understand library for the Canvas API.
 
 The Canvas API (https://canvas.instructure.com/doc/api/index.html) has hundreds of endpoints.
+
 It seemed pointless to me to write a unique method for every one of them.
 Instead, I created a class, called `ResterAPI` that uses `__getattr__` to
-dynamically generate the URLS for an endpoint and `__call__` to make the actual
-request. The `Canvas` class is built on top of `ResterAPI`.
+dynamically generate the path for an endpoint and `__call__` to add a path
+element with a parameter. The `Canvas` class is built on top of `ResterAPI`.
 
 The result is a fairly small library that can handle the vast majority of
-Canvas API endpoints. There are a few unique cases that are addressed in special
-classes. For example, the `SIS Import API`_ takes a file upload and needs
-special handling.
+Canvas API endpoints. 
 
-Here is how to do an SIS Import.
+
+Instantiate the Canvas object like this.
 
 .. code-block:: py
 
-  from canvas_api import SISImporter
-  sis_importer = SISImporter('somedomain.instructure.com', CANVAS_ACCESS_TOKEN=os.getenv('ACCESS_TOKEN'))
-  sis_importer.do_sis_import(filepath)
+  from canvas_api import Canvas
+  c = Canvas('somedomain.instructure.com', CANVAS_ACCESS_TOKEN=os.getenv('ACCESS_TOKEN'))
 
 
-Instantiate the Canvas object like this.
+Building paths
+==============
+You build the path appending "methods" after the instanted canvas_api object.
+
+You will typically see a line like `GET /api/v1/accounts/:account_id/courses`
+in the Canvas API documentation. This tells you what the path is and the inline
+parameters it needs. You would build this path with the `py_canvas_api` library
+like this: `c.accounts(8423).courses`. Don't worry about the `/api/v1` part.
+
+The `py_canvas_api` library takes care of the path parameters like :user by taking
+them as method arguments. For example, here is how you would get courses in the
+account with the id of 10 using the path above.
+
+.. code-block:: py
+
+  # get a list of courses (paginated to 10) in the account
+  accounts = c.accounts('self').courses.get().json()
+
+Common Requests
+================
+
+GET
+-----
+
+To make a `GET` request, simply end with `get()`. This tells the library to
+make a GET request. This library uses the awesome `Requests`_ library so the
+return object in this case is simple a Response object. You will most often
+want the response as a json object. You get this by calling .json() with the
+Response.
+
+.. code-block:: py
+
+  # get a list of courses (paginated to 10) in the account
+  accounts_json = c.accounts('self').courses.get().json()
+
+If you need to send query parameters (key-value pairs added after a question
+mark), add these as keyword parameters in the `get()` call. Let's say you want
+a list of your own courses where you are a teacher and the enrollment is active. You would normally need to
+add `?enrollment_type=teacher&enrollment_state=active` to the URL to do this. With the `py_canvas_api`
+library, however, you would do it like this.
 
 .. code-block:: py
 
-  from canvas_api import Canvas
-  c = Canvas('somedomain.instructure.com', CANVAS_ACCESS_TOKEN=os.getenv('ACCESS_TOKEN'))
   # get a list of courses (paginated to 10) in the account
-  accounts = c.accounts('self').courses.get()
+  accounts_json = c.courses.get(enrollment_type='teacher', enrollment_state='active').json()
+
+Here are several more `GET` examples.
+
+.. code-block:: py
+
+  # list of users
+  users = c.accounts('self').users.get().json()
+
+  # assignments in course with canvas id 23423
+  assignments = c.courses(23423).assignments.get().json()
+
+  # assignments in course with sis id ENG101
+  assignments = c.courses('sis_course_id:ENG101').assignments.get().json()
+
+  # list communication channels for user with id 82
+  channels = c.users(82).communication_channels.get().json()
+
+  # list own communication channels
+  channels = c.users('self').communication_channels.get().json()
 
   # Get a list of all courses in the account. This will keep pulling results as
   # long as there are more pages. It uses generator functions to do this is a
   # smart way.
   accounts = c.accounts('self').course.get_paginated()
 
+Special Cases
+==============
+There are a few unique cases that are addressed in special
+classes. For example, the `SIS Import API`_ takes a file upload and needs
+special handling.
+
+Here is how to do an SIS Import.
+
+.. code-block:: py
+
+  from canvas_api import SISImporter
+  sis_importer = SISImporter('somedomain.instructure.com', CANVAS_ACCESS_TOKEN=os.getenv('ACCESS_TOKEN'))
+  sis_importer.do_sis_import(filepath)
+
 
 .. _`SIS Import API`: https://canvas.instructure.com/doc/api/sis_imports.html
+
+.. _`Requests`: http://docs.python-requests.org/en/master/

py_canvas_api/canvas_api.py

@@ -4,6 +4,7 @@
 import collections
 import mimetypes
 from .rester_api import ResterAPI, Paginates
+from .common import log
 
 class Canvas(ResterAPI, Paginates):
 

py_canvas_api/commons.py

@@ -1,6 +1,8 @@
 # -*- coding: utf-8 -*-
 import requests
+import json
 from .rester_api import ResterAPI, log
+from .canvas_api import Canvas
 
 class Commons(ResterAPI):
   def __init__(self, base_url, *args, **kwargs):

py_canvas_api/rester_api.py

@@ -1,5 +1,6 @@
 # -*- coding: utf-8 -*-
 import requests
+import json
 from .common import log
 
 class ResterAPI(object):

tests/test_init_canvas.py

@@ -9,7 +9,8 @@
 import json
 import requests
 
-import canvas_api
+from py_canvas_api import canvas_api
+
 BASE_URL = 'kevin.test.instructure.com'
 CANVAS_ACCESS_TOKEN='1~7GxKeS9cqHcNQxzKAZBhot6qurrWsJrYhPJiTY71lqxj37peuccu0ESl4fXh1VRL'
 
@@ -55,13 +56,13 @@ def test_upload_file(self):
     # TODO how do I mock this?
     pass
 
+from py_canvas_api import commons
 class TestCommonsAPI(TestCase):
   def setUp(self):
-    self.commons = canvas_api.Commons(BASE_URL, CANVAS_ACCESS_TOKEN=CANVAS_ACCESS_TOKEN)
+    self.commons = commons.Commons(BASE_URL, CANVAS_ACCESS_TOKEN=CANVAS_ACCESS_TOKEN)
     self.jwt_response = { "jwt_token": "eyJ0eXAiOiJ"}
     self.session_response = { "sessionId": u"lkjlklkjlkj"}
 
-    #self.commons.canvas2.req = MagicMock()
     res_list = json.load(open(os.path.join(BASE_DIR, 'resources_list.json'),'rU'))
     requests.get = MagicMock()
     requests.get.side_effect = [
@@ -74,7 +75,6 @@ def setUp(self):
         MagicMock(status_code=200, text=json.dumps(self.session_response), json=lambda: self.session_response)
         ]
 
-
   def test_get_jwt_token(self):
     jwt_token = self.commons.get_jwt_token()
     assert jwt_token == self.jwt_response