1 #!/usr/bin/python2.5

     2 #

     3 # Copyright 2008 the Melange authors.

     4 #

     5 # Licensed under the Apache License, Version 2.0 (the "License");

     6 # you may not use this file except in compliance with the License.

     7 # You may obtain a copy of the License at

     8 # 

     9 #   http://www.apache.org/licenses/LICENSE-2.0

    10 # 

    11 # Unless required by applicable law or agreed to in writing, software

    12 # distributed under the License is distributed on an "AS IS" BASIS,

    13 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

    14 # See the License for the specific language governing permissions and

    15 # limitations under the License.

    16 

    17 """This module contains the Review Model."""

    18 

    19 __authors__ = [

    20   '"Todd Larsen" <tlarsen@google.com>',

    21   '"Sverre Rabbelier" <sverre@rabbelier.nl>',

    22 ]

    23 

    24 from google.appengine.ext import db

    25 

    26 from soc import models

    27 import soc.models.survey

    28 import soc.models.work

    29 import soc.models.reviewer

    30 

    31 

    32 class Review(db.Model):

    33   """Model of a review of a Proposal or a Task.

    34 

    35   A Review entity is a specific instance of a completed Survey, collecting

    36   the Answers to the Questions that are found in that Survey.

    37 

    38   Reviews are also used to implement comments and scoring annotations

    39   to Proposals and Tasks. For example, a commment attached to a

    40   Proposal is a Review with the Answer to a single "question" (with

    41   that answer being the comment itself).  A scoring  evaluation might

    42   be made up of Answers to two "questions", one containg the comment

    43   the other containing the score.

    44 

    45   A Review entity participates in the following relationships implemented 

    46   as a db.ReferenceProperty elsewhere in another db.Model:

    47 

    48    answers) A 1:many relationship (but not required, since initially

    49      none of the Questions to be answered by a Review will have

    50      Answers) that relates the specific answers to the Survey

    51      questions for a specfic Review instance. This relation is

    52      implemented as a back-reference Query of the Answer model

    53      'review' reference.

    54 

    55      Some (zero or more) of the Questions answered by a Review may

    56      define an 'approval_style' string and one or more

    57      'approval_answers'. See the Question and Answer models for

    58      details. All Questions answered in the Review that provide

    59      non-empty 'approval_style' and 'approval_answers' must meet the

    60      described approval conditions for the Review to represent 

    61      "approval" (or a "positive outcome" or a "passing grade", so to

    62      speak). Most Reviews answer Questions in a Survey that contains

    63      only a single "approval" question (if they contain one at all).

    64   """

    65 

    66   #: A required many:1 relationship with a Survey which acts as a

    67   #: "template" for the Review, containing the Questions that are

    68   #: anwered by the Answers associated with the Review. The

    69   #: back-reference in the Survey model is a Query named 'reviews'

    70   #: which represents all of the Reviews that contains Answers to the

    71   #: Questions in that particular Survey.

    72   survey = db.ReferenceProperty(reference_class=models.survey.Survey,

    73                                 required=True, collection_name="reviews")

    74 

    75   #: A required many:1 relationship with a Work, where the Review

    76   #: answers are attached to the Work as a comment, evaluation,

    77   #: review, report, acceptance, etc. Reviews are the mechanism by

    78   #: which non-authors of the Work make annotations to it. The

    79   #: back-reference in the Work model is a Query named 'reviews'

    80   #: which represents all of the annotations attached to that

    81   #: particular work.

    82   reviewed = db.ReferenceProperty(reference_class=models.work.Work, 

    83                                   required=True, collection_name="reviews")

    84                                   

    85   #: A required many:1 relationship with a Reviewer entity indicating

    86   #: the "author" of the actual answers for a specific Review

    87   #: instance. The back-reference in the Reviewer model is a Query

    88   #: named 'reviews' which represents all of the Reviews by that

    89   #: particular Reviewer.

    90   reviewer = db.ReferenceProperty(reference_class=models.reviewer.Reviewer,

    91                                   required=True, collection_name="reviews")

    92