#!/usr/bin/python2.5

#

# Copyright 2008 the Melange authors.

#

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

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

# You may obtain a copy of the License at

#

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

#

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

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

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

# See the License for the specific language governing permissions and

# limitations under the License.

"""This module contains the Quiz Model."""

__authors__ = [

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

]

import reflistprop

from google.appengine.ext import db

from django.utils.translation import ugettext_lazy

import soc.models.answer

import soc.models.document

import soc.models.question

class Quiz(soc.models.document.Document):

  """Model of a Quiz, a collection of Questions to be asked.

  (named Quiz because Questionnaire was too much to type...)

  A Quiz collects a set of Questions to which Answers are given in the

  form of a separate Model called a Response.

  Quizzes can even be used as templates for comments and scoring

  annotations to various Works, such as Documents and Proposals.  A

  separate Review Model is derived from Quiz for these purposes.

  The specific way that the properties and relations inherited from

  Document, and also indirectly from Work, are used with a Quiz are

  described below.

    work.title:  the title of the Quiz

    work.abstract:  summary displayed as a snippet in Quiz list views

    work.authors:  the Authors of the Work referred to by this relation

      are the authors of the Quiz (but not necessarily the individual

      Questions themselves, see the Question Model)

    work.reviews:  even Quizzes can be "reviewed" (possibly commented

      on during creation or annotated once put into use).

    work.partial_path/work.link_name: used to scope and uniquely identify

      a Quiz in the same way these properties are used with Documents, etc.

    document.content:  the "preface" of the Quiz, displayed before any

      of the Questions, usually containing instructions for the Quiz

  In addition to any explicit ReferenceProperties in the Quiz Model and

  those inherited as described above, a Quiz entity participates in these

  relationships:

    responses)  a 1:many relationship where each Quiz can produce all of

      its many Response entities that indicate they contain specific

      Answers to each of the Questions contained in that Quiz. This relation

      is implemented as the 'responses' back-reference Query of the Response

      Model 'quiz' reference.

    solutions)  a 1:many relationship where some (or none, or all) of the

      Questions in the Quiz have "solutions" or "correct Answers".  The

      'solutions' back-reference Query of the Answer Model 'quiz' reference

      is used to point these "correct Answers" at the Quiz to which they

      apply.  One example of a Quiz having a "correct Answer" is a GSoC

      mentor survey that has a "pass" Question that gates if the student

      gets paid.  The desired Answer for this Question would be

      associated with the Quiz via the 'quiz' property and some controller

      logic could check if a survey "passed" by querying for these

      "solution" Answers and seeing if the survey Response had the "right"

      Answers (to the one Question that matters in this case...).

  """

  #: a many:many relationship (many:many because a given Question can be

  #: reused in more than one Quiz, and each Quiz is made up of one or more

  #: Questions) between Question entities and, when combined, the Quiz they

  #: form.

  #:

  #: A ReferenceListProperty is used instead of a special many:many

  #; relation Model for a number of reasons:

  #:   1) the Questions in a Quiz need to be ordered

  #:   2) Quizzes will have relatively few Questions, so the performance

  #:      ReferenceListProperty is not a major concern

  #:   3) querying a Question for all of the Quizzes that contain it is

  #:      a rare occurrence, so the expense of a ListProperty query is

  #:      not a real concern

  questions = reflistprop.ReferenceListProperty(

    soc.models.question.Question, default=None)