Submission API

cakecms/cakecms.py

@@ -59,6 +59,7 @@ class CakeCMS:
 		else:
 			raise Exception(str(result['state'])+': '+str(result['message']))
 
+
 	def courses_index(self):
 		"""
 		:return:all Course objects of the given instance that you can see.
@@ -84,6 +85,7 @@ class CakeCMS:
 				return course
 		return None
 
+
 	def students_index(self, course=None, columns=None, named_params={}, **kwargs):
 		if columns:
 			named_params['cols'] = '~'.join(columns)
@@ -106,6 +108,7 @@ class CakeCMS:
 		r = self.get('students/index', course=course, named_params={'limit': 1})
 		return json_decode_ordered(r.text)['compressionTable']
 
+
 	def testingresults_index_by_student_id(self, course=None, testing_id=1):
 		"""
 		:param course:
@@ -117,6 +120,7 @@ class CakeCMS:
 		key = 'Testingresult'+str(testing_id)
 		return {entry['Student']['id']: entry[key] for entry in students['students']}
 
+
 	def admissions_index(self, course=None, testing_id=None):
 		return self.get('admissions/index', course=course, named_params={'bytesting': testing_id or 0, 'limit': 0}).json()['admissions']
 
@@ -128,6 +132,66 @@ class CakeCMS:
 	def admissions_edit_many(self, data, course=None):
 		return self.post('admissions/edit_many', {'Admission': data}, course=course).json()
 
+
 	def calendar_events_index(self, course=None):
 		return self.get('full_calendar/events/index', course=course).json()
 
+
+	def submissions_index(self, course=None):
+		"""
+		:param course:
+		:return: A list of all submissions in the system (submission = something where students can submit to). Contains details.
+		"""
+		return self.get('submissions/index', course=course).json()['submissions']
+
+	def submission_items_index(self, course=None, submission_id=None, tutorial_id=None):
+		"""
+		:param course:
+		:param submission_id: the submission you want to get the file list for (optional)
+		:param tutorial_id: filter by tutorial (optional)
+		:return: A list of all submission items (files submitted to a single submission), including many details.
+		"""
+		named_params = {'limit': '0'}
+		if submission_id: named_params['bySub'] = submission_id
+		if tutorial_id: named_params['byTutorial'] = tutorial_id
+		return self.get('submission_items/index', course=course, named_params=named_params).json()['submissionItems']
+
+	def submission_items_download(self, course=None, submission_item_id=None):
+		"""
+		:param course:
+		:param submission_item_id: the submission item (file) id you want to download
+		:return: The file content of a single submission file
+		"""
+		assert submission_item_id
+		return self.get('submission_items/download/'+str(submission_item_id), course=course).content
+
+	def submission_items_download_all(self, course=None, submission_id=None, tutorial_id=None):
+		"""
+		Downloads a zip archive of submitted files. Be aware:
+		- The archive is stored in memory!
+		- Zip archives can't be larger than 2GB
+		:param course:
+		:param submission_id: the submission you want to get the file list for (optional)
+		:param tutorial_id: filter by tutorial (optional)
+		:return: A zip archive containing all files submitted to a "submission".
+		"""
+		named_params = {}
+		if submission_id: named_params['bySub'] = submission_id
+		if tutorial_id: named_params['byTutorial'] = tutorial_id
+		return self.get('submission_items/downloadAll', course=course, named_params=named_params).content
+
+	def submission_items_download_all_streamed(self, course=None, submission_id=None, tutorial_id=None):
+		"""
+		Downloads a zip archive of submitted files. Be aware:
+		- This method returns a file-descriptor-like object (that can be used to copy the data chunk by chunk)
+		- Zip archives can't be larger than 2GB
+		- You have to manually close the returned object. Use this function in a "with as" statement.
+		:param course:
+		:param submission_id: the submission you want to get the file list for (optional)
+		:param tutorial_id: filter by tutorial (optional)
+		:return: A file-like object that can be used to read a zip archive from the server. The zip file contains all submitted files.
+		"""
+		named_params = {}
+		if submission_id: named_params['bySub'] = submission_id
+		if tutorial_id: named_params['byTutorial'] = tutorial_id
+		return self.get('submission_items/downloadAll', course=course, named_params=named_params, stream=True).raw

examples/download_submissions.py

@@ -0,0 +1,44 @@
+import cakecms
+
+HOST = 'http://localhost/cakecms'
+SUBMISSION_ID = 12
+COURSE = 'np'
+TOKEN = 'yRUoMb4KmZwLOHdotB5t0W3h'
+
+# create an (unauthenticated) instance
+cms = cakecms.CakeCMS(HOST)
+# [optional] log queries to console
+cms.debug = True
+# get a course list (dictionary)
+courses = cms.courses_list()
+print courses
+for id, course in courses.items():
+	print '- #{}: {}  ( at {}/{} )'.format(id, course, HOST, course)
+
+# attach to a course (with admin token)
+cms.course = COURSE
+cms.token = TOKEN
+
+# list submissions
+for submission in cms.submissions_index():
+	print submission['Submission']['id'], ':', submission['Submission']['name']
+
+# list submission items (actual files for a single submission)
+result = cms.submission_items_index(submission_id=SUBMISSION_ID)
+print len(result), 'submissions'
+for subitem in result:
+	print 'Submission #', subitem['SubmissionItem']['id'],'by', subitem['User']['display'], ':', subitem['SubmissionItem']['filesize'], 'bytes (rev.', str(subitem['SubmissionItem']['revision'])+')'
+
+# download one submission
+content = cms.submission_items_download(submission_item_id=result[0]['SubmissionItem']['id'])
+print len(content), 'bytes'
+
+# download bundle to memory
+zip_archive = cms.submission_items_download_all(submission_id=SUBMISSION_ID)
+print len(zip_archive), 'bytes in zip (in memory)'
+
+# download bundle as stream
+with cms.submission_items_download_all_streamed(submission_id=SUBMISSION_ID) as f:
+	zip_archive_size = len(f.read())
+	print zip_archive_size, 'bytes in zip (streamed)'
+