Added example script and dedicated example resource config file

examples/example_script.py

@@ -0,0 +1,140 @@
+# An example script showing the functionality of the TinCanPython Library
+
+import uuid
+from resources import lrs_properties
+from tincan import (
+    RemoteLRS,
+    Statement,
+    Agent,
+    Verb,
+    Activity,
+    Context,
+    LanguageMap,
+    ActivityDefinition,
+    StateDocument,
+)
+
+# construct an LRS
+print "constructing the LRS..."
+lrs = RemoteLRS(
+    version=lrs_properties.version,
+    endpoint=lrs_properties.endpoint,
+    username=lrs_properties.username,
+    password=lrs_properties.password,
+)
+print "...done"
+
+# construct the actor of the statement
+print "constructing the Actor..."
+actor = Agent(
+    name='UserMan',
+    mbox='mailto:tincanpython@tincanapi.com',
+)
+print "...done"
+
+# construct the verb of the statement
+print "constructing the Verb..."
+verb = Verb(
+    id='http://adlnet.gov/expapi/verbs/experienced',
+    display=LanguageMap({'en-US': 'experienced'}),
+)
+print "...done"
+
+# construct the object of the statement
+print "constructing the Object..."
+object = Activity(
+    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'}),
+    ),
+)
+print "...done"
+
+# construct a context for the statement
+print "constructing the Context..."
+context = Context(
+    registration=uuid.uuid4(),
+    instructor=Agent(
+        name='Lord TinCan',
+        mbox='mailto:lordtincan@tincanapi.com',
+    ),
+    #language='en-US',
+)
+print "...done"
+
+# construct the actual statement
+print "constructing the Statement..."
+statement = Statement(
+    actor=actor,
+    verb=verb,
+    object=object,
+    context=context,
+)
+print "...done"
+
+# save our statement to the remote_lrs and store the response in 'response'
+print "saving the Statement..."
+response = lrs.save_statement(statement)
+
+if not response:
+    raise ValueError("statement failed to save")
+print "...done"
+
+# retrieve our statement from the remote_lrs using the id returned in the response
+print "Now, retrieving statement..."
+response = lrs.retrieve_statement(response.content.id)
+
+if not response.success:
+    raise ValueError("statement could not be retrieved")
+print "...done"
+
+print "constructing new Statement from retrieved statement data..."
+ret_statement = response.content
+print "...done"
+
+# now, using our old statement and our returned statement, we can send multiple statements
+# note: these statements are logically identical, but are 2 separate objects
+print "saving both Statements"
+response = lrs.save_statements([statement, ret_statement])
+
+if not response:
+    raise ValueError("statements failed to save")
+print "...done"
+
+# 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 API documentation:
+#   docs/build/html/tincan.html#module-tincan.remote_lrs
+query = {
+    "agent": actor,
+    "verb": verb,
+    "activity": object,
+    "related_activities": True,
+    "related_agents": True,
+    "limit": 2,
+}
+
+print "querying statements..."
+response = lrs.query_statements(query)
+
+if not response:
+    raise ValueError("statements could not be queried")
+print "...done"
+
+# now we will explore saving a document, e.g. a state document
+print "constructing a state document..."
+state_document = StateDocument(
+    activity=object,
+    agent=actor,
+    id='stateDoc',
+    content=bytearray('stateDocValue', encoding='utf-8'),
+)
+print "...done"
+
+print "saving state document..."
+response = lrs.save_state(state_document)
+
+if not response.success:
+    raise ValueError("could not save state document")
+print "...done"

examples/resources/lrs_properties.py.template

@@ -0,0 +1,9 @@
+"""
+Contains user-specific information for testing.
+"""
+
+
+endpoint="<endpoint>"
+version ="<valid_version>" # 1.0.1 | 1.0.0 | 0.95 | 0.9
+username="<username>"
+password="<password>"

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 = {}