~azzar1/unity/add-show-desktop-key

« back to all changes in this revision

Viewing changes to ivle/database.py

  • Committer: William Grant
  • Date: 2010-02-23 08:55:42 UTC
  • mto: This revision was merged to the branch mainline in revision 1674.
  • Revision ID: grantw@unimelb.edu.au-20100223085542-r8xw14bxxoraza51
Permit underscores in all names.

Show diffs side-by-side

added added

removed removed

Lines of Context:
17
17
 
18
18
# Author: Matt Giuca, Will Grant
19
19
 
20
 
"""
21
 
Database Classes and Utilities for Storm ORM
 
20
"""Database utilities and content classes.
22
21
 
23
22
This module provides all of the classes which map to database tables.
24
23
It also provides miscellaneous utility functions for database interaction.
25
24
"""
26
25
 
27
 
import md5
 
26
import hashlib
28
27
import datetime
 
28
import os
29
29
 
30
30
from storm.locals import create_database, Store, Int, Unicode, DateTime, \
31
31
                         Reference, ReferenceSet, Bool, Storm, Desc
 
32
from storm.expr import Select, Max
 
33
from storm.exceptions import NotOneError, IntegrityError
32
34
 
33
 
import ivle.conf
 
35
from ivle.worksheet.rst import rst
34
36
 
35
37
__all__ = ['get_store',
36
38
            'User',
37
39
            'Subject', 'Semester', 'Offering', 'Enrolment',
38
40
            'ProjectSet', 'Project', 'ProjectGroup', 'ProjectGroupMembership',
 
41
            'Assessed', 'ProjectSubmission', 'ProjectExtension',
39
42
            'Exercise', 'Worksheet', 'WorksheetExercise',
40
43
            'ExerciseSave', 'ExerciseAttempt',
41
44
            'TestCase', 'TestSuite', 'TestSuiteVar'
48
51
                % (self.__class__.__name__, k))
49
52
        setattr(self, k, v)
50
53
 
51
 
def get_conn_string():
52
 
    """
53
 
    Returns the Storm connection string, generated from the conf file.
 
54
def get_conn_string(config):
 
55
    """Create a Storm connection string to the IVLE database
 
56
 
 
57
    @param config: The IVLE configuration.
54
58
    """
55
59
 
56
60
    clusterstr = ''
57
 
    if ivle.conf.db_user:
58
 
        clusterstr += ivle.conf.db_user
59
 
        if ivle.conf.db_password:
60
 
            clusterstr += ':' + ivle.conf.db_password
 
61
    if config['database']['username']:
 
62
        clusterstr += config['database']['username']
 
63
        if config['database']['password']:
 
64
            clusterstr += ':' + config['database']['password']
61
65
        clusterstr += '@'
62
66
 
63
 
    host = ivle.conf.db_host or 'localhost'
64
 
    port = ivle.conf.db_port or 5432
 
67
    host = config['database']['host'] or 'localhost'
 
68
    port = config['database']['port'] or 5432
65
69
 
66
70
    clusterstr += '%s:%d' % (host, port)
67
71
 
68
 
    return "postgres://%s/%s" % (clusterstr, ivle.conf.db_dbname)
69
 
 
70
 
def get_store():
71
 
    """
72
 
    Open a database connection and transaction. Return a storm.store.Store
73
 
    instance connected to the configured IVLE database.
74
 
    """
75
 
    return Store(create_database(get_conn_string()))
 
72
    return "postgres://%s/%s" % (clusterstr, config['database']['name'])
 
73
 
 
74
def get_store(config):
 
75
    """Create a Storm store connected to the IVLE database.
 
76
 
 
77
    @param config: The IVLE configuration.
 
78
    """
 
79
    return Store(create_database(get_conn_string(config)))
76
80
 
77
81
# USERS #
78
82
 
79
83
class User(Storm):
80
 
    """
81
 
    Represents an IVLE user.
82
 
    """
 
84
    """An IVLE user account."""
83
85
    __storm_table__ = "login"
84
86
 
85
87
    id = Int(primary=True, name="loginid")
115
117
        return self.hash_password(password) == self.passhash
116
118
 
117
119
    @property
 
120
    def display_name(self):
 
121
        """Returns the "nice name" of the user or group."""
 
122
        return self.fullname
 
123
 
 
124
    @property
 
125
    def short_name(self):
 
126
        """Returns the database "identifier" name of the user or group."""
 
127
        return self.login
 
128
 
 
129
    @property
118
130
    def password_expired(self):
119
131
        fieldval = self.pass_exp
120
132
        return fieldval is not None and datetime.datetime.now() > fieldval
157
169
 
158
170
    # TODO: Invitations should be listed too?
159
171
    def get_groups(self, offering=None):
 
172
        """Get groups of which this user is a member.
 
173
 
 
174
        @param offering: An optional offering to restrict the search to.
 
175
        """
160
176
        preds = [
161
177
            ProjectGroupMembership.user_id == self.id,
162
178
            ProjectGroup.id == ProjectGroupMembership.project_group_id,
182
198
        '''A sanely ordered list of all of the user's enrolments.'''
183
199
        return self._get_enrolments(False) 
184
200
 
 
201
    def get_projects(self, offering=None, active_only=True):
 
202
        """Find projects that the user can submit.
 
203
 
 
204
        This will include projects for offerings in which the user is
 
205
        enrolled, as long as the project is not in a project set which has
 
206
        groups (ie. if maximum number of group members is 0).
 
207
 
 
208
        @param active_only: Whether to only search active offerings.
 
209
        @param offering: An optional offering to restrict the search to.
 
210
        """
 
211
        return Store.of(self).find(Project,
 
212
            Project.project_set_id == ProjectSet.id,
 
213
            ProjectSet.max_students_per_group == None,
 
214
            ProjectSet.offering_id == Offering.id,
 
215
            (offering is None) or (Offering.id == offering.id),
 
216
            Semester.id == Offering.semester_id,
 
217
            (not active_only) or (Semester.state == u'current'),
 
218
            Enrolment.offering_id == Offering.id,
 
219
            Enrolment.user_id == self.id,
 
220
            Enrolment.active == True)
 
221
 
185
222
    @staticmethod
186
223
    def hash_password(password):
187
 
        return md5.md5(password).hexdigest()
 
224
        """Hash a password with MD5."""
 
225
        return hashlib.md5(password).hexdigest()
188
226
 
189
227
    @classmethod
190
228
    def get_by_login(cls, store, login):
191
 
        """
192
 
        Get the User from the db associated with a given store and
193
 
        login.
194
 
        """
 
229
        """Find a user in a store by login name."""
195
230
        return store.find(cls, cls.login == unicode(login)).one()
196
231
 
197
 
    def get_permissions(self, user):
 
232
    def get_permissions(self, user, config):
 
233
        """Determine privileges held by a user over this object.
 
234
 
 
235
        If the user requesting privileges is this user or an admin,
 
236
        they may do everything. Otherwise they may do nothing.
 
237
        """
198
238
        if user and user.admin or user is self:
199
 
            return set(['view', 'edit'])
 
239
            return set(['view_public', 'view', 'edit', 'submit_project'])
200
240
        else:
201
 
            return set()
 
241
            return set(['view_public'])
202
242
 
203
243
# SUBJECTS AND ENROLMENTS #
204
244
 
205
245
class Subject(Storm):
 
246
    """A subject (or course) which is run in some semesters."""
 
247
 
206
248
    __storm_table__ = "subject"
207
249
 
208
250
    id = Int(primary=True, name="subjectid")
209
251
    code = Unicode(name="subj_code")
210
252
    name = Unicode(name="subj_name")
211
253
    short_name = Unicode(name="subj_short_name")
212
 
    url = Unicode()
213
254
 
214
255
    offerings = ReferenceSet(id, 'Offering.subject_id')
215
256
 
218
259
    def __repr__(self):
219
260
        return "<%s '%s'>" % (type(self).__name__, self.short_name)
220
261
 
221
 
    def get_permissions(self, user):
 
262
    def get_permissions(self, user, config):
 
263
        """Determine privileges held by a user over this object.
 
264
 
 
265
        If the user requesting privileges is an admin, they may edit.
 
266
        Otherwise they may only read.
 
267
        """
222
268
        perms = set()
223
269
        if user is not None:
224
270
            perms.add('view')
226
272
                perms.add('edit')
227
273
        return perms
228
274
 
 
275
    def active_offerings(self):
 
276
        """Find active offerings for this subject.
 
277
 
 
278
        Return a sequence of currently active offerings for this subject
 
279
        (offerings whose semester.state is "current"). There should be 0 or 1
 
280
        elements in this sequence, but it's possible there are more.
 
281
        """
 
282
        return self.offerings.find(Offering.semester_id == Semester.id,
 
283
                                   Semester.state == u'current')
 
284
 
 
285
    def offering_for_semester(self, year, semester):
 
286
        """Get the offering for the given year/semester, or None.
 
287
 
 
288
        @param year: A string representation of the year.
 
289
        @param semester: A string representation of the semester.
 
290
        """
 
291
        return self.offerings.find(Offering.semester_id == Semester.id,
 
292
                               Semester.year == unicode(year),
 
293
                               Semester.semester == unicode(semester)).one()
 
294
 
229
295
class Semester(Storm):
 
296
    """A semester in which subjects can be run."""
 
297
 
230
298
    __storm_table__ = "semester"
231
299
 
232
300
    id = Int(primary=True, name="semesterid")
246
314
        return "<%s %s/%s>" % (type(self).__name__, self.year, self.semester)
247
315
 
248
316
class Offering(Storm):
 
317
    """An offering of a subject in a particular semester."""
 
318
 
249
319
    __storm_table__ = "offering"
250
320
 
251
321
    id = Int(primary=True, name="offeringid")
253
323
    subject = Reference(subject_id, Subject.id)
254
324
    semester_id = Int(name="semesterid")
255
325
    semester = Reference(semester_id, Semester.id)
 
326
    description = Unicode()
 
327
    url = Unicode()
256
328
    groups_student_permissions = Unicode()
257
329
 
258
330
    enrolments = ReferenceSet(id, 'Enrolment.offering_id')
261
333
                           'Enrolment.user_id',
262
334
                           'User.id')
263
335
    project_sets = ReferenceSet(id, 'ProjectSet.offering_id')
 
336
    projects = ReferenceSet(id,
 
337
                            'ProjectSet.offering_id',
 
338
                            'ProjectSet.id',
 
339
                            'Project.project_set_id')
264
340
 
265
341
    worksheets = ReferenceSet(id, 
266
342
        'Worksheet.offering_id', 
267
 
        order_by="Worksheet.seq_no"
 
343
        order_by="seq_no"
268
344
    )
269
345
 
270
346
    __init__ = _kwarg_init
274
350
                                  self.semester)
275
351
 
276
352
    def enrol(self, user, role=u'student'):
277
 
        '''Enrol a user in this offering.'''
 
353
        """Enrol a user in this offering.
 
354
 
 
355
        Enrolments handle both the staff and student cases. The role controls
 
356
        the privileges granted by this enrolment.
 
357
        """
278
358
        enrolment = Store.of(self).find(Enrolment,
279
359
                               Enrolment.user_id == user.id,
280
360
                               Enrolment.offering_id == self.id).one()
286
366
        enrolment.active = True
287
367
        enrolment.role = role
288
368
 
289
 
    def get_permissions(self, user):
 
369
    def unenrol(self, user):
 
370
        '''Unenrol a user from this offering.'''
 
371
        enrolment = Store.of(self).find(Enrolment,
 
372
                               Enrolment.user_id == user.id,
 
373
                               Enrolment.offering_id == self.id).one()
 
374
        Store.of(enrolment).remove(enrolment)
 
375
 
 
376
    def get_permissions(self, user, config):
290
377
        perms = set()
291
378
        if user is not None:
292
 
            perms.add('view')
 
379
            enrolment = self.get_enrolment(user)
 
380
            if enrolment or user.admin:
 
381
                perms.add('view')
 
382
            if enrolment and enrolment.role == u'tutor':
 
383
                perms.add('view_project_submissions')
 
384
                # Site-specific policy on the role of tutors
 
385
                if config['policy']['tutors_can_enrol_students']:
 
386
                    perms.add('enrol')
 
387
                    perms.add('enrol_student')
 
388
                if config['policy']['tutors_can_edit_worksheets']:
 
389
                    perms.add('edit_worksheets')
 
390
                if config['policy']['tutors_can_admin_groups']:
 
391
                    perms.add('admin_groups')
 
392
            if (enrolment and enrolment.role in (u'lecturer')) or user.admin:
 
393
                perms.add('view_project_submissions')
 
394
                perms.add('admin_groups')
 
395
                perms.add('edit_worksheets')
 
396
                perms.add('edit')           # Can edit projects & details
 
397
                perms.add('enrol')          # Can see enrolment screen at all
 
398
                perms.add('enrol_student')  # Can enrol students
 
399
                perms.add('enrol_tutor')    # Can enrol tutors
293
400
            if user.admin:
294
 
                perms.add('edit')
 
401
                perms.add('enrol_lecturer') # Can enrol lecturers
295
402
        return perms
296
403
 
 
404
    def get_enrolment(self, user):
 
405
        """Find the user's enrolment in this offering."""
 
406
        try:
 
407
            enrolment = self.enrolments.find(user=user).one()
 
408
        except NotOneError:
 
409
            enrolment = None
 
410
 
 
411
        return enrolment
 
412
 
 
413
    def get_members_by_role(self, role):
 
414
        return Store.of(self).find(User,
 
415
                Enrolment.user_id == User.id,
 
416
                Enrolment.offering_id == self.id,
 
417
                Enrolment.role == role
 
418
                ).order_by(User.login)
 
419
 
 
420
    @property
 
421
    def students(self):
 
422
        return self.get_members_by_role(u'student')
 
423
 
 
424
    def get_open_projects_for_user(self, user):
 
425
        """Find all projects currently open to submissions by a user."""
 
426
        # XXX: Respect extensions.
 
427
        return self.projects.find(Project.deadline > datetime.datetime.now())
 
428
 
 
429
    def clone_worksheets(self, source):
 
430
        """Clone all worksheets from the specified source to this offering."""
 
431
        import ivle.worksheet.utils
 
432
        for worksheet in source.worksheets:
 
433
            newws = Worksheet()
 
434
            newws.seq_no = worksheet.seq_no
 
435
            newws.identifier = worksheet.identifier
 
436
            newws.name = worksheet.name
 
437
            newws.assessable = worksheet.assessable
 
438
            newws.data = worksheet.data
 
439
            newws.format = worksheet.format
 
440
            newws.offering = self
 
441
            Store.of(self).add(newws)
 
442
            ivle.worksheet.utils.update_exerciselist(newws)
 
443
 
 
444
 
297
445
class Enrolment(Storm):
 
446
    """An enrolment of a user in an offering.
 
447
 
 
448
    This represents the roles of both staff and students.
 
449
    """
 
450
 
298
451
    __storm_table__ = "enrolment"
299
452
    __storm_primary__ = "user_id", "offering_id"
300
453
 
320
473
        return "<%s %r in %r>" % (type(self).__name__, self.user,
321
474
                                  self.offering)
322
475
 
 
476
    def get_permissions(self, user, config):
 
477
        # A user can edit any enrolment that they could have created.
 
478
        perms = set()
 
479
        if ('enrol_' + str(self.role)) in self.offering.get_permissions(
 
480
            user, config):
 
481
            perms.add('edit')
 
482
        return perms
 
483
 
 
484
    def delete(self):
 
485
        """Delete this enrolment."""
 
486
        Store.of(self).remove(self)
 
487
 
 
488
 
323
489
# PROJECTS #
324
490
 
325
491
class ProjectSet(Storm):
 
492
    """A set of projects that share common groups.
 
493
 
 
494
    Each student project group is attached to a project set. The group is
 
495
    valid for all projects in the group's set.
 
496
    """
 
497
 
326
498
    __storm_table__ = "project_set"
327
499
 
328
500
    id = Int(name="projectsetid", primary=True)
339
511
        return "<%s %d in %r>" % (type(self).__name__, self.id,
340
512
                                  self.offering)
341
513
 
 
514
    def get_permissions(self, user, config):
 
515
        return self.offering.get_permissions(user, config)
 
516
 
 
517
    def get_groups_for_user(self, user):
 
518
        """List all groups in this offering of which the user is a member."""
 
519
        assert self.is_group
 
520
        return Store.of(self).find(
 
521
            ProjectGroup,
 
522
            ProjectGroupMembership.user_id == user.id,
 
523
            ProjectGroupMembership.project_group_id == ProjectGroup.id,
 
524
            ProjectGroup.project_set_id == self.id)
 
525
 
 
526
    def get_submission_principal(self, user):
 
527
        """Get the principal on behalf of which the user can submit.
 
528
 
 
529
        If this is a solo project set, the given user is returned. If
 
530
        the user is a member of exactly one group, all the group is
 
531
        returned. Otherwise, None is returned.
 
532
        """
 
533
        if self.is_group:
 
534
            groups = self.get_groups_for_user(user)
 
535
            if groups.count() == 1:
 
536
                return groups.one()
 
537
            else:
 
538
                return None
 
539
        else:
 
540
            return user
 
541
 
 
542
    @property
 
543
    def is_group(self):
 
544
        return self.max_students_per_group is not None
 
545
 
 
546
    @property
 
547
    def assigned(self):
 
548
        """Get the entities (groups or users) assigned to submit this project.
 
549
 
 
550
        This will be a Storm ResultSet.
 
551
        """
 
552
        #If its a solo project, return everyone in offering
 
553
        if self.is_group:
 
554
            return self.project_groups
 
555
        else:
 
556
            return self.offering.students
 
557
 
 
558
class DeadlinePassed(Exception):
 
559
    """An exception indicating that a project cannot be submitted because the
 
560
    deadline has passed."""
 
561
    def __init__(self):
 
562
        pass
 
563
    def __str__(self):
 
564
        return "The project deadline has passed"
 
565
 
342
566
class Project(Storm):
 
567
    """A student project for which submissions can be made."""
 
568
 
343
569
    __storm_table__ = "project"
344
570
 
345
571
    id = Int(name="projectid", primary=True)
 
572
    name = Unicode()
 
573
    short_name = Unicode()
346
574
    synopsis = Unicode()
347
575
    url = Unicode()
348
576
    project_set_id = Int(name="projectsetid")
349
577
    project_set = Reference(project_set_id, ProjectSet.id)
350
578
    deadline = DateTime()
351
579
 
 
580
    assesseds = ReferenceSet(id, 'Assessed.project_id')
 
581
    submissions = ReferenceSet(id,
 
582
                               'Assessed.project_id',
 
583
                               'Assessed.id',
 
584
                               'ProjectSubmission.assessed_id')
 
585
 
352
586
    __init__ = _kwarg_init
353
587
 
354
588
    def __repr__(self):
355
 
        return "<%s '%s' in %r>" % (type(self).__name__, self.synopsis,
 
589
        return "<%s '%s' in %r>" % (type(self).__name__, self.short_name,
356
590
                                  self.project_set.offering)
357
591
 
 
592
    def can_submit(self, principal, user):
 
593
        return (self in principal.get_projects() and
 
594
                not self.has_deadline_passed(user))
 
595
 
 
596
    def submit(self, principal, path, revision, who):
 
597
        """Submit a Subversion path and revision to a project.
 
598
 
 
599
        @param principal: The owner of the Subversion repository, and the
 
600
                          entity on behalf of whom the submission is being made
 
601
        @param path: A path within that repository to submit.
 
602
        @param revision: The revision of that path to submit.
 
603
        @param who: The user who is actually making the submission.
 
604
        """
 
605
 
 
606
        if not self.can_submit(principal, who):
 
607
            raise DeadlinePassed()
 
608
 
 
609
        a = Assessed.get(Store.of(self), principal, self)
 
610
        ps = ProjectSubmission()
 
611
        # Raise SubmissionError if the path is illegal
 
612
        ps.path = ProjectSubmission.test_and_normalise_path(path)
 
613
        ps.revision = revision
 
614
        ps.date_submitted = datetime.datetime.now()
 
615
        ps.assessed = a
 
616
        ps.submitter = who
 
617
 
 
618
        return ps
 
619
 
 
620
    def get_permissions(self, user, config):
 
621
        return self.project_set.offering.get_permissions(user, config)
 
622
 
 
623
    @property
 
624
    def latest_submissions(self):
 
625
        """Return the latest submission for each Assessed."""
 
626
        return Store.of(self).find(ProjectSubmission,
 
627
            Assessed.project_id == self.id,
 
628
            ProjectSubmission.assessed_id == Assessed.id,
 
629
            ProjectSubmission.date_submitted == Select(
 
630
                    Max(ProjectSubmission.date_submitted),
 
631
                    ProjectSubmission.assessed_id == Assessed.id,
 
632
                    tables=ProjectSubmission
 
633
            )
 
634
        )
 
635
 
 
636
    def has_deadline_passed(self, user):
 
637
        """Check whether the deadline has passed."""
 
638
        # XXX: Need to respect extensions.
 
639
        return self.deadline < datetime.datetime.now()
 
640
 
 
641
    def get_submissions_for_principal(self, principal):
 
642
        """Fetch a ResultSet of all submissions by a particular principal."""
 
643
        assessed = Assessed.get(Store.of(self), principal, self)
 
644
        if assessed is None:
 
645
            return
 
646
        return assessed.submissions
 
647
 
 
648
 
 
649
 
358
650
class ProjectGroup(Storm):
 
651
    """A group of students working together on a project."""
 
652
 
359
653
    __storm_table__ = "project_group"
360
654
 
361
655
    id = Int(name="groupid", primary=True)
378
672
        return "<%s %s in %r>" % (type(self).__name__, self.name,
379
673
                                  self.project_set.offering)
380
674
 
 
675
    @property
 
676
    def display_name(self):
 
677
        """Returns the "nice name" of the user or group."""
 
678
        return self.nick
 
679
 
 
680
    @property
 
681
    def short_name(self):
 
682
        """Returns the database "identifier" name of the user or group."""
 
683
        return self.name
 
684
 
 
685
    def get_projects(self, offering=None, active_only=True):
 
686
        '''Find projects that the group can submit.
 
687
 
 
688
        This will include projects in the project set which owns this group,
 
689
        unless the project set disallows groups (in which case none will be
 
690
        returned).
 
691
 
 
692
        @param active_only: Whether to only search active offerings.
 
693
        @param offering: An optional offering to restrict the search to.
 
694
        '''
 
695
        return Store.of(self).find(Project,
 
696
            Project.project_set_id == ProjectSet.id,
 
697
            ProjectSet.id == self.project_set.id,
 
698
            ProjectSet.max_students_per_group != None,
 
699
            ProjectSet.offering_id == Offering.id,
 
700
            (offering is None) or (Offering.id == offering.id),
 
701
            Semester.id == Offering.semester_id,
 
702
            (not active_only) or (Semester.state == u'current'))
 
703
 
 
704
 
 
705
    def get_permissions(self, user, config):
 
706
        if user.admin or user in self.members:
 
707
            return set(['submit_project'])
 
708
        else:
 
709
            return set()
 
710
 
381
711
class ProjectGroupMembership(Storm):
 
712
    """A student's membership in a project group."""
 
713
 
382
714
    __storm_table__ = "group_member"
383
715
    __storm_primary__ = "user_id", "project_group_id"
384
716
 
393
725
        return "<%s %r in %r>" % (type(self).__name__, self.user,
394
726
                                  self.project_group)
395
727
 
 
728
class Assessed(Storm):
 
729
    """A composite of a user or group combined with a project.
 
730
 
 
731
    Each project submission and extension refers to an Assessed. It is the
 
732
    sole specifier of the repository and project.
 
733
    """
 
734
 
 
735
    __storm_table__ = "assessed"
 
736
 
 
737
    id = Int(name="assessedid", primary=True)
 
738
    user_id = Int(name="loginid")
 
739
    user = Reference(user_id, User.id)
 
740
    project_group_id = Int(name="groupid")
 
741
    project_group = Reference(project_group_id, ProjectGroup.id)
 
742
 
 
743
    project_id = Int(name="projectid")
 
744
    project = Reference(project_id, Project.id)
 
745
 
 
746
    extensions = ReferenceSet(id, 'ProjectExtension.assessed_id')
 
747
    submissions = ReferenceSet(
 
748
        id, 'ProjectSubmission.assessed_id', order_by='date_submitted')
 
749
 
 
750
    def __repr__(self):
 
751
        return "<%s %r in %r>" % (type(self).__name__,
 
752
            self.user or self.project_group, self.project)
 
753
 
 
754
    @property
 
755
    def is_group(self):
 
756
        """True if the Assessed is a group, False if it is a user."""
 
757
        return self.project_group is not None
 
758
 
 
759
    @property
 
760
    def principal(self):
 
761
        return self.project_group or self.user
 
762
 
 
763
    @property
 
764
    def checkout_location(self):
 
765
        """Returns the location of the Subversion workspace for this piece of
 
766
        assessment, relative to each group member's home directory."""
 
767
        subjectname = self.project.project_set.offering.subject.short_name
 
768
        if self.is_group:
 
769
            checkout_dir_name = self.principal.short_name
 
770
        else:
 
771
            checkout_dir_name = "mywork"
 
772
        return subjectname + "/" + checkout_dir_name
 
773
 
 
774
    @classmethod
 
775
    def get(cls, store, principal, project):
 
776
        """Find or create an Assessed for the given user or group and project.
 
777
 
 
778
        @param principal: The user or group.
 
779
        @param project: The project.
 
780
        """
 
781
        t = type(principal)
 
782
        if t not in (User, ProjectGroup):
 
783
            raise AssertionError('principal must be User or ProjectGroup')
 
784
 
 
785
        a = store.find(cls,
 
786
            (t is User) or (cls.project_group_id == principal.id),
 
787
            (t is ProjectGroup) or (cls.user_id == principal.id),
 
788
            cls.project_id == project.id).one()
 
789
 
 
790
        if a is None:
 
791
            a = cls()
 
792
            if t is User:
 
793
                a.user = principal
 
794
            else:
 
795
                a.project_group = principal
 
796
            a.project = project
 
797
            store.add(a)
 
798
 
 
799
        return a
 
800
 
 
801
 
 
802
class ProjectExtension(Storm):
 
803
    """An extension granted to a user or group on a particular project.
 
804
 
 
805
    The user or group and project are specified by the Assessed.
 
806
    """
 
807
 
 
808
    __storm_table__ = "project_extension"
 
809
 
 
810
    id = Int(name="extensionid", primary=True)
 
811
    assessed_id = Int(name="assessedid")
 
812
    assessed = Reference(assessed_id, Assessed.id)
 
813
    deadline = DateTime()
 
814
    approver_id = Int(name="approver")
 
815
    approver = Reference(approver_id, User.id)
 
816
    notes = Unicode()
 
817
 
 
818
class SubmissionError(Exception):
 
819
    """Denotes a validation error during submission."""
 
820
    pass
 
821
 
 
822
class ProjectSubmission(Storm):
 
823
    """A submission from a user or group repository to a particular project.
 
824
 
 
825
    The content of a submission is a single path and revision inside a
 
826
    repository. The repository is that owned by the submission's user and
 
827
    group, while the path and revision are explicit.
 
828
 
 
829
    The user or group and project are specified by the Assessed.
 
830
    """
 
831
 
 
832
    __storm_table__ = "project_submission"
 
833
 
 
834
    id = Int(name="submissionid", primary=True)
 
835
    assessed_id = Int(name="assessedid")
 
836
    assessed = Reference(assessed_id, Assessed.id)
 
837
    path = Unicode()
 
838
    revision = Int()
 
839
    submitter_id = Int(name="submitter")
 
840
    submitter = Reference(submitter_id, User.id)
 
841
    date_submitted = DateTime()
 
842
 
 
843
    def get_verify_url(self, user):
 
844
        """Get the URL for verifying this submission, within the account of
 
845
        the given user."""
 
846
        # If this is a solo project, then self.path will be prefixed with the
 
847
        # subject name. Remove the first path segment.
 
848
        submitpath = self.path[1:] if self.path[:1] == '/' else self.path
 
849
        if not self.assessed.is_group:
 
850
            if '/' in submitpath:
 
851
                submitpath = submitpath.split('/', 1)[1]
 
852
            else:
 
853
                submitpath = ''
 
854
        return "/files/%s/%s/%s?r=%d" % (user.login,
 
855
            self.assessed.checkout_location, submitpath, self.revision)
 
856
 
 
857
    @staticmethod
 
858
    def test_and_normalise_path(path):
 
859
        """Test that path is valid, and normalise it. This prevents possible
 
860
        injections using malicious paths.
 
861
        Returns the updated path, if successful.
 
862
        Raises SubmissionError if invalid.
 
863
        """
 
864
        # Ensure the path is absolute to prevent being tacked onto working
 
865
        # directories.
 
866
        # Prevent '\n' because it will break all sorts of things.
 
867
        # Prevent '[' and ']' because they can be used to inject into the
 
868
        # svn.conf.
 
869
        # Normalise to avoid resulting in ".." path segments.
 
870
        if not os.path.isabs(path):
 
871
            raise SubmissionError("Path is not absolute")
 
872
        if any(c in path for c in "\n[]"):
 
873
            raise SubmissionError("Path must not contain '\\n', '[' or ']'")
 
874
        return os.path.normpath(path)
 
875
 
396
876
# WORKSHEETS AND EXERCISES #
397
877
 
398
878
class Exercise(Storm):
 
879
    """An exercise for students to complete in a worksheet.
 
880
 
 
881
    An exercise may be present in any number of worksheets.
 
882
    """
 
883
 
399
884
    __storm_table__ = "exercise"
400
885
    id = Unicode(primary=True, name="identifier")
401
886
    name = Unicode()
405
890
    include = Unicode()
406
891
    num_rows = Int()
407
892
 
 
893
    worksheet_exercises =  ReferenceSet(id,
 
894
        'WorksheetExercise.exercise_id')
 
895
 
408
896
    worksheets = ReferenceSet(id,
409
897
        'WorksheetExercise.exercise_id',
410
898
        'WorksheetExercise.worksheet_id',
411
899
        'Worksheet.id'
412
900
    )
413
 
    
414
 
    test_suites = ReferenceSet(id, 'TestSuite.exercise_id')
 
901
 
 
902
    test_suites = ReferenceSet(id, 
 
903
        'TestSuite.exercise_id',
 
904
        order_by='seq_no')
415
905
 
416
906
    __init__ = _kwarg_init
417
907
 
418
908
    def __repr__(self):
419
909
        return "<%s %s>" % (type(self).__name__, self.name)
420
910
 
421
 
    def get_permissions(self, user):
 
911
    def get_permissions(self, user, config):
 
912
        return self.global_permissions(user, config)
 
913
 
 
914
    @staticmethod
 
915
    def global_permissions(user, config):
 
916
        """Gets the set of permissions this user has over *all* exercises.
 
917
        This is used to determine who may view the exercises list, and create
 
918
        new exercises."""
422
919
        perms = set()
 
920
        roles = set()
423
921
        if user is not None:
424
922
            if user.admin:
425
923
                perms.add('edit')
426
924
                perms.add('view')
 
925
            elif u'lecturer' in set((e.role for e in user.active_enrolments)):
 
926
                perms.add('edit')
 
927
                perms.add('view')
 
928
            elif (config['policy']['tutors_can_edit_worksheets']
 
929
            and u'tutor' in set((e.role for e in user.active_enrolments))):
 
930
                # Site-specific policy on the role of tutors
 
931
                perms.add('edit')
 
932
                perms.add('view')
 
933
 
427
934
        return perms
428
935
 
 
936
    def get_description(self):
 
937
        """Return the description interpreted as reStructuredText."""
 
938
        return rst(self.description)
 
939
 
 
940
    def delete(self):
 
941
        """Deletes the exercise, providing it has no associated worksheets."""
 
942
        if (self.worksheet_exercises.count() > 0):
 
943
            raise IntegrityError()
 
944
        for suite in self.test_suites:
 
945
            suite.delete()
 
946
        Store.of(self).remove(self)
 
947
 
429
948
class Worksheet(Storm):
 
949
    """A worksheet with exercises for students to complete.
 
950
 
 
951
    Worksheets are owned by offerings.
 
952
    """
 
953
 
430
954
    __storm_table__ = "worksheet"
431
955
 
432
956
    id = Int(primary=True, name="worksheetid")
447
971
    # Use worksheet_exercises to get access to the *active* WorksheetExercise
448
972
    # objects binding worksheets to exercises. This is required to access the
449
973
    # "optional" field.
 
974
 
450
975
    @property
451
976
    def worksheet_exercises(self):
452
977
        return self.all_worksheet_exercises.find(active=True)
456
981
    def __repr__(self):
457
982
        return "<%s %s>" % (type(self).__name__, self.name)
458
983
 
459
 
    # XXX Refactor this - make it an instance method of Subject rather than a
460
 
    # class method of Worksheet. Can't do that now because Subject isn't
461
 
    # linked referentially to the Worksheet.
462
 
    @classmethod
463
 
    def get_by_name(cls, store, subjectname, worksheetname):
464
 
        """
465
 
        Get the Worksheet from the db associated with a given store, subject
466
 
        name and worksheet name.
467
 
        """
468
 
        return store.find(cls, cls.subject == unicode(subjectname),
469
 
            cls.name == unicode(worksheetname)).one()
 
984
    def remove_all_exercises(self):
 
985
        """Remove all exercises from this worksheet.
470
986
 
471
 
    def remove_all_exercises(self, store):
472
 
        """
473
 
        Remove all exercises from this worksheet.
474
987
        This does not delete the exercises themselves. It just removes them
475
988
        from the worksheet.
476
989
        """
 
990
        store = Store.of(self)
 
991
        for ws_ex in self.all_worksheet_exercises:
 
992
            if ws_ex.saves.count() > 0 or ws_ex.attempts.count() > 0:
 
993
                raise IntegrityError()
477
994
        store.find(WorksheetExercise,
478
995
            WorksheetExercise.worksheet == self).remove()
479
 
            
480
 
    def get_permissions(self, user):
481
 
        return self.offering.get_permissions(user)
 
996
 
 
997
    def get_permissions(self, user, config):
 
998
        # Almost the same permissions as for the offering itself
 
999
        perms = self.offering.get_permissions(user, config)
 
1000
        # However, "edit" permission is derived from the "edit_worksheets"
 
1001
        # permission of the offering
 
1002
        if 'edit_worksheets' in perms:
 
1003
            perms.add('edit')
 
1004
        else:
 
1005
            perms.discard('edit')
 
1006
        return perms
 
1007
 
 
1008
    def get_xml(self):
 
1009
        """Returns the xml of this worksheet, converts from rst if required."""
 
1010
        if self.format == u'rst':
 
1011
            ws_xml = rst(self.data)
 
1012
            return ws_xml
 
1013
        else:
 
1014
            return self.data
 
1015
 
 
1016
    def delete(self):
 
1017
        """Deletes the worksheet, provided it has no attempts on any exercises.
 
1018
 
 
1019
        Returns True if delete succeeded, or False if this worksheet has
 
1020
        attempts attached."""
 
1021
        for ws_ex in self.all_worksheet_exercises:
 
1022
            if ws_ex.saves.count() > 0 or ws_ex.attempts.count() > 0:
 
1023
                raise IntegrityError()
 
1024
 
 
1025
        self.remove_all_exercises()
 
1026
        Store.of(self).remove(self)
482
1027
 
483
1028
class WorksheetExercise(Storm):
 
1029
    """A link between a worksheet and one of its exercises.
 
1030
 
 
1031
    These may be marked optional, in which case the exercise does not count
 
1032
    for marking purposes. The sequence number is used to order the worksheet
 
1033
    ToC.
 
1034
    """
 
1035
 
484
1036
    __storm_table__ = "worksheet_exercise"
485
 
    
 
1037
 
486
1038
    id = Int(primary=True, name="ws_ex_id")
487
1039
 
488
1040
    worksheet_id = Int(name="worksheetid")
492
1044
    optional = Bool()
493
1045
    active = Bool()
494
1046
    seq_no = Int()
495
 
    
 
1047
 
496
1048
    saves = ReferenceSet(id, "ExerciseSave.ws_ex_id")
497
1049
    attempts = ReferenceSet(id, "ExerciseAttempt.ws_ex_id")
498
1050
 
502
1054
        return "<%s %s in %s>" % (type(self).__name__, self.exercise.name,
503
1055
                                  self.worksheet.identifier)
504
1056
 
 
1057
    def get_permissions(self, user, config):
 
1058
        return self.worksheet.get_permissions(user, config)
 
1059
 
 
1060
 
505
1061
class ExerciseSave(Storm):
506
 
    """
507
 
    Represents a potential solution to an exercise that a user has submitted
508
 
    to the server for storage.
509
 
    A basic ExerciseSave is just the current saved text for this exercise for
510
 
    this user (doesn't count towards their attempts).
511
 
    ExerciseSave may be extended with additional semantics (such as
512
 
    ExerciseAttempt).
513
 
    """
 
1062
    """A potential exercise solution submitted by a user for storage.
 
1063
 
 
1064
    This is not an actual tested attempt at an exercise, it's just a save of
 
1065
    the editing session.
 
1066
    """
 
1067
 
514
1068
    __storm_table__ = "exercise_save"
515
1069
    __storm_primary__ = "ws_ex_id", "user_id"
516
1070
 
529
1083
            self.exercise.name, self.user.login, self.date.strftime("%c"))
530
1084
 
531
1085
class ExerciseAttempt(ExerciseSave):
532
 
    """
533
 
    An ExerciseAttempt is a special case of an ExerciseSave. Like an
534
 
    ExerciseSave, it constitutes exercise solution data that the user has
535
 
    submitted to the server for storage.
536
 
    In addition, it contains additional information about the submission.
537
 
    complete - True if this submission was successful, rendering this exercise
538
 
        complete for this user.
539
 
    active - True if this submission is "active" (usually true). Submissions
540
 
        may be de-activated by privileged users for special reasons, and then
541
 
        they won't count (either as a penalty or success), but will still be
542
 
        stored.
543
 
    """
 
1086
    """An attempt at solving an exercise.
 
1087
 
 
1088
    This is a special case of ExerciseSave, used when the user submits a
 
1089
    candidate solution. Like an ExerciseSave, it constitutes exercise solution
 
1090
    data.
 
1091
 
 
1092
    In addition, it contains information about the result of the submission:
 
1093
 
 
1094
     - complete - True if this submission was successful, rendering this
 
1095
                  exercise complete for this user in this worksheet.
 
1096
     - active   - True if this submission is "active" (usually true).
 
1097
                  Submissions may be de-activated by privileged users for
 
1098
                  special reasons, and then they won't count (either as a
 
1099
                  penalty or success), but will still be stored.
 
1100
    """
 
1101
 
544
1102
    __storm_table__ = "exercise_attempt"
545
1103
    __storm_primary__ = "ws_ex_id", "user_id", "date"
546
1104
 
549
1107
    text = Unicode(name="attempt")
550
1108
    complete = Bool()
551
1109
    active = Bool()
552
 
    
553
 
    def get_permissions(self, user):
 
1110
 
 
1111
    def get_permissions(self, user, config):
554
1112
        return set(['view']) if user is self.user else set()
555
 
  
 
1113
 
556
1114
class TestSuite(Storm):
557
 
    """A Testsuite acts as a container for the test cases of an exercise."""
 
1115
    """A container to group an exercise's test cases.
 
1116
 
 
1117
    The test suite contains some information on how to test. The function to
 
1118
    test, variables to set and stdin data are stored here.
 
1119
    """
 
1120
 
558
1121
    __storm_table__ = "test_suite"
559
1122
    __storm_primary__ = "exercise_id", "suiteid"
560
 
    
 
1123
 
561
1124
    suiteid = Int()
562
1125
    exercise_id = Unicode(name="exerciseid")
563
1126
    description = Unicode()
565
1128
    function = Unicode()
566
1129
    stdin = Unicode()
567
1130
    exercise = Reference(exercise_id, Exercise.id)
568
 
    test_cases = ReferenceSet(suiteid, 'TestCase.suiteid')
569
 
    variables = ReferenceSet(suiteid, 'TestSuiteVar.suiteid')
 
1131
    test_cases = ReferenceSet(suiteid, 'TestCase.suiteid', order_by="seq_no")
 
1132
    variables = ReferenceSet(suiteid, 'TestSuiteVar.suiteid', order_by='arg_no')
 
1133
 
 
1134
    def delete(self):
 
1135
        """Delete this suite, without asking questions."""
 
1136
        for variable in self.variables:
 
1137
            variable.delete()
 
1138
        for test_case in self.test_cases:
 
1139
            test_case.delete()
 
1140
        Store.of(self).remove(self)
570
1141
 
571
1142
class TestCase(Storm):
572
 
    """A TestCase is a member of a TestSuite.
573
 
    
574
 
    It contains the data necessary to check if an exercise is correct"""
 
1143
    """A container for actual tests (see TestCasePart), inside a test suite.
 
1144
 
 
1145
    It is the lowest level shown to students on their pass/fail status."""
 
1146
 
575
1147
    __storm_table__ = "test_case"
576
1148
    __storm_primary__ = "testid", "suiteid"
577
 
    
 
1149
 
578
1150
    testid = Int()
579
1151
    suiteid = Int()
580
1152
    suite = Reference(suiteid, "TestSuite.suiteid")
581
1153
    passmsg = Unicode()
582
1154
    failmsg = Unicode()
583
 
    test_default = Unicode()
 
1155
    test_default = Unicode() # Currently unused - only used for file matching.
584
1156
    seq_no = Int()
585
 
    
 
1157
 
586
1158
    parts = ReferenceSet(testid, "TestCasePart.testid")
587
 
    
 
1159
 
588
1160
    __init__ = _kwarg_init
589
1161
 
 
1162
    def delete(self):
 
1163
        for part in self.parts:
 
1164
            part.delete()
 
1165
        Store.of(self).remove(self)
 
1166
 
590
1167
class TestSuiteVar(Storm):
591
 
    """A container for the arguments of a Test Suite"""
 
1168
    """A variable used by an exercise test suite.
 
1169
 
 
1170
    This may represent a function argument or a normal variable.
 
1171
    """
 
1172
 
592
1173
    __storm_table__ = "suite_variable"
593
1174
    __storm_primary__ = "varid"
594
 
    
 
1175
 
595
1176
    varid = Int()
596
1177
    suiteid = Int()
597
1178
    var_name = Unicode()
598
1179
    var_value = Unicode()
599
1180
    var_type = Unicode()
600
1181
    arg_no = Int()
601
 
    
 
1182
 
602
1183
    suite = Reference(suiteid, "TestSuite.suiteid")
603
 
    
 
1184
 
604
1185
    __init__ = _kwarg_init
605
 
    
 
1186
 
 
1187
    def delete(self):
 
1188
        Store.of(self).remove(self)
 
1189
 
606
1190
class TestCasePart(Storm):
607
 
    """A container for the test elements of a Test Case"""
 
1191
    """An actual piece of code to test an exercise solution."""
 
1192
 
608
1193
    __storm_table__ = "test_case_part"
609
1194
    __storm_primary__ = "partid"
610
 
    
 
1195
 
611
1196
    partid = Int()
612
1197
    testid = Int()
613
 
    
 
1198
 
614
1199
    part_type = Unicode()
615
1200
    test_type = Unicode()
616
1201
    data = Unicode()
617
1202
    filename = Unicode()
618
 
    
 
1203
 
619
1204
    test = Reference(testid, "TestCase.testid")
620
 
    
 
1205
 
621
1206
    __init__ = _kwarg_init
 
1207
 
 
1208
    def delete(self):
 
1209
        Store.of(self).remove(self)