fixed example script, added documentation

examples/__init__.py

@@ -1 +0,0 @@
-# empty for now

examples/example_script.py

@@ -1,16 +1,18 @@
-# An example script showing the functionality of the TinCan Python Library
+# An example script showing the functionality of the TinCanPython Library
 
 import uuid
 from resources import lrs_properties
-from tincan.remote_lrs import RemoteLRS
-from tincan.statement import Statement
-from tincan.agent import Agent
-from tincan.verb import Verb
-from tincan.activity import Activity
-from tincan.context import Context
-from tincan.language_map import LanguageMap
-from tincan.activity_definition import ActivityDefinition
-from tincan.documents import StateDocument
+from tincan import (
+    RemoteLRS,
+    Statement,
+    Agent,
+    Verb,
+    Activity,
+    Context,
+    LanguageMap,
+    ActivityDefinition,
+    StateDocument,
+)
 
 # construct an LRS
 print "constructing the LRS..."
@@ -41,7 +43,7 @@
 # construct the object of the statement
 print "constructing the Object..."
 object = Activity(
-    id='http://tincanapi.com/TinCanPython/Test/Unit/0',
+    id='http://tincanapi.com/TinCanPython/Example/0',
     definition=ActivityDefinition(
         name=LanguageMap({'en-US': 'TinCanPython Library'}),
         description=LanguageMap({'en-US': 'Use of, or interaction with, the TinCanPython Library'}),
@@ -55,7 +57,7 @@
     registration=uuid.uuid4(),
     instructor=Agent(
         name='Lord TinCan',
-        mbox='mailto:tincanpython@tincanapi.com',
+        mbox='mailto:lordtincan@tincanapi.com',
     ),
     #language='en-US',
 )
@@ -88,7 +90,7 @@
 print "...done"
 
 print "constructing new Statement from retrieved statement data..."
-ret_statement = Statement.from_json(response.data)
+ret_statement = response.content
 print "...done"
 
 # now, using our old statement and our returned statement, we can send multiple statements
@@ -102,8 +104,8 @@
 
 # we can query our statements using an object
 # constructing the query object with common fields
-# note: more information about queries can be found in the xAPI spec
-#   https://github.com/adlnet/xAPI-Spec/blob/master/xAPI.md#723-getstatements
+# note: more information about queries can be found in the API documentation:
+#   docs/build/html/tincan.html#module-tincan.remote_lrs
 query = {
     "agent": actor,
     "verb": verb,

setup.cfg

@@ -1,2 +1,2 @@
 [metadata]
-description-file = README.md
+description-file = README.md

test/languagemap_test.py

@@ -132,4 +132,4 @@ def mapVerificationHelper(self, lmap):
 
 if __name__ == '__main__':
     suite = unittest.TestLoader().loadTestsFromTestCase(LanguageMapTest)
-    unittest.TextTestRunner(verbosity=2).run(suite)
+    unittest.TextTestRunner(verbosity=2).run(suite)

test/test_utils.py

@@ -47,4 +47,4 @@ def assertSerializeDeserialize(self, obj, version=None):
                 orig_dict = obj.__dict__
                 clone_dict = clone.__dict__
 
-            self.assertEqual(orig_dict, clone_dict)
+            self.assertEqual(orig_dict, clone_dict)

tincan/remote_lrs.py

@@ -282,6 +282,26 @@ def query_statements(self, query):
         :type query: dict
         :return: LRS Response object with the returned StatementsResult object as content
         :rtype: :class:`tincan.lrs_response.LRSResponse`
+
+        .. note::
+           Optional query parameters are\n
+               **statementId:** (*str*) ID of the Statement to fetch\n
+               **voidedStatementId:** (*str*) ID of the voided Statement to fetch\n
+               **agent:** (*Agent* |*Group*) Filter to return Statements for which the specified Agent or Group is the Actor\n
+               **verb:** (*Verb id IRI*) Filter to return Statements matching the verb id\n
+               **activity:** (*Activity id IRI*) Filter to return Statements for which the specified Activity is the Object\n
+               **registration:** (*UUID*) Filter to return Statements matching the specified registration ID\n
+               **related_activities:** (*bool*) Include Statements for which the Object, Context Activities or any Sub-Statement
+               properties match the specified Activity\n
+               **related_agents:** (*bool*) Include Statements for which the Actor, Object, Authority, Instructor, Team, or
+               any Sub-Statement properties match the specified Agent\n
+               **since:** (*datetime*) Filter to return Statements stored since the specified datetime\n
+               **until:** (*datetime*) Filter to return Statements stored at or before the specified datetime\n
+               **limit:** (*positive int*) Allow <limit> Statements to be returned. 0 indicates the maximum supported by the LRS\n
+               **format:** (*str* {"ids"|"exact"|"canonical"}) Manipulates how the LRS handles importing and returning the statements\n
+               **attachments:** (*bool*) If true, the LRS will use multipart responses and include all attachment data per Statement returned.
+               Otherwise, application/json is used and no attachment information will be returned\n
+               **ascending:** (*bool*) If true, the LRS will return results in ascending order of stored time (oldest first)\n
         """
         params = {}