lms.model.scores

  1import typing
  2
  3import edq.util.json
  4import edq.util.time
  5
  6import lms.model.assignments
  7import lms.model.base
  8import lms.model.users
  9
 10class ScoreFragment(edq.util.json.DictConverter):
 11    """ A small subset of information about a score. """
 12
 13    def __init__(self,
 14            score: typing.Union[float, None] = None,
 15            comment: typing.Union[str, None] = None,
 16            **kwargs: typing.Any) -> None:
 17        self.score: typing.Union[float, None] = score
 18        """
 19        The numeric score.
 20        A None value indicates that the score should be cleared.
 21        """
 22
 23        self.comment: typing.Union[str, None] = comment
 24        """ An optional comment for this score. """
 25
 26class AssignmentScore(lms.model.base.BaseType):
 27    """
 28    The score assignment to a student for an assignment (or scorable object).
 29    """
 30
 31    CORE_FIELDS = [
 32        'id', 'user', 'assignment', 'score', 'submission_date', 'graded_date', 'comment',
 33    ]
 34
 35    def __init__(self,
 36            id: typing.Union[str, None] = None,
 37            score: typing.Union[float, None] = None,
 38            submission_date: typing.Union[edq.util.time.Timestamp, None] = None,
 39            graded_date: typing.Union[edq.util.time.Timestamp, None] = None,
 40            comment: typing.Union[str, None] = None,
 41            assignment: typing.Union[lms.model.assignments.AssignmentQuery, None] = None,
 42            user: typing.Union[lms.model.users.UserQuery, None] = None,
 43            **kwargs: typing.Any) -> None:
 44        super().__init__(**kwargs)
 45
 46        self.id: typing.Union[str, None] = id
 47        """ The LMS's identifier for this score. """
 48
 49        self.assignment: typing.Union[lms.model.assignments.AssignmentQuery, None] = assignment
 50        """ The assignment associated with this score. """
 51
 52        self.user: typing.Union[lms.model.users.UserQuery, None] = user
 53        """ The user associated with this score. """
 54
 55        self.score: typing.Union[float, None] = score
 56        """ The assignment score. """
 57
 58        self.submission_date: typing.Union[edq.util.time.Timestamp, None] = submission_date
 59        """ The datetime that the submission that received this score was submitted. """
 60
 61        self.graded_date: typing.Union[edq.util.time.Timestamp, None] = graded_date
 62        """ The datetime that the submission that received this score was graded. """
 63
 64        self.comment: typing.Union[str, None] = comment
 65        """ A comment attached to this score. """
 66
 67    def to_fragment(self) -> ScoreFragment:
 68        """ Get a score fragment from this assignment score. """
 69
 70        return ScoreFragment(score = self.score, comment = self.comment)
 71
 72class Gradebook(lms.model.base.BaseType):
 73    """
 74    A gradebook that contains scores for a set of users and assignments.
 75    """
 76
 77    CORE_FIELDS = [
 78        'assignments', 'users', '_entries',
 79    ]
 80
 81    def __init__(self,
 82            assignments: typing.List[lms.model.assignments.AssignmentQuery],
 83            users: typing.List[lms.model.users.UserQuery],
 84            **kwargs: typing.Any) -> None:
 85        super().__init__(**kwargs)
 86
 87        self.assignments: typing.List[lms.model.assignments.AssignmentQuery] = assignments
 88        """ The assignments represented in this gradebook. """
 89
 90        self.users: typing.List[lms.model.users.UserQuery] = users
 91        """ The users represented in this gradebook. """
 92
 93        self._entries: typing.Dict[str, AssignmentScore] = {}
 94        """ The scores held by this gradebook. """
 95
 96    def _make_key(self, assignment_query: lms.model.assignments.AssignmentQuery, user_query: lms.model.users.UserQuery) -> str:
 97        """ Create a key for this gradebook entry. """
 98
 99        return f"{assignment_query.id}::{user_query.id}"
100
101    def get(self,
102            assignment_query: lms.model.assignments.AssignmentQuery,
103            user_query: lms.model.users.UserQuery,
104            ) -> typing.Union[AssignmentScore, None]:
105        """ Get the target gradebook entry. """
106
107        found_assignment = None
108        for assignment in self.assignments:
109            if (assignment.match(assignment_query)):
110                found_assignment = assignment
111                break
112
113        if (found_assignment is None):
114            return None
115
116        found_user = None
117        for user in self.users:
118            if (user.match(user_query)):
119                found_user = user
120                break
121
122        if (found_user is None):
123            return None
124
125        return self._entries.get(self._make_key(found_assignment, found_user), None)
126
127    def get_scores_by_assignment(self,
128            ) -> typing.Dict[
129                lms.model.assignments.AssignmentQuery,
130                typing.Dict[lms.model.users.UserQuery, AssignmentScore]]:
131        """ Get all entries indexed by assignment. """
132
133        results: typing.Dict[
134                lms.model.assignments.AssignmentQuery,
135                typing.Dict[lms.model.users.UserQuery, AssignmentScore]] = {}
136
137        for assignment in self.assignments:
138            results[assignment] = {}
139
140            for user in self.users:
141                key = self._make_key(assignment, user)
142                if (key not in self._entries):
143                    continue
144
145                results[assignment][user] = self._entries[key]
146
147        return results
148
149    def add(self, score: AssignmentScore) -> None:
150        """
151        Add the score to this gradebook.
152        If the user or assignment is not already in this gradebook, raise an exception.
153
154        The gradebook takes ownership of the score.
155        """
156
157        found_assignment = None
158        for assignment in self.assignments:
159            if (assignment.match(score.assignment)):
160                found_assignment = assignment
161                break
162
163        if (found_assignment is None):
164            raise ValueError(f"Could not match gradebook assignment to score's assignment '{score.assignment}'.")
165
166        found_user = None
167        for user in self.users:
168            if (user.match(score.user)):
169                found_user = user
170                break
171
172        if (found_user is None):
173            raise ValueError(f"Could not match gradebook user to score's user '{score.user}'.")
174
175        # Update the score's queries.
176        score.assignment = found_assignment
177        score.user = found_user
178
179        self._entries[self._make_key(found_assignment, found_user)] = score
180
181    def update_queries(self,
182            assignment_queries: typing.List[lms.model.assignments.ResolvedAssignmentQuery],
183            user_queries: typing.List[lms.model.users.ResolvedUserQuery],
184            ) -> None:
185        """ Update any assignment/user queries with the supplied ones (matching on ID). """
186
187        assignment_map = {query.id: query for query in assignment_queries}
188        user_map = {query.id: query for query in user_queries}
189
190        self.assignments = [assignment_map.get(assignment.id, assignment) for assignment in self.assignments]
191        self.users = [user_map.get(user.id, user) for user in self.users]
192
193        for score in self._entries.values():
194            if (score.assignment is not None):
195                score.assignment = assignment_map.get(score.assignment.id, score.assignment)
196
197            if (score.user is not None):
198                score.user = user_map.get(score.user.id, score.user)
199
200    def as_text_rows(self,
201            skip_headers: bool = False,
202            pretty_headers: bool = False,
203            separator: str = ': ',
204            empty_value: str = '',
205            **kwargs: typing.Any) -> typing.List[str]:
206        rows: typing.List[str] = []
207        for user in sorted(self.users):
208            # Add in a user separator.
209            if (len(rows) > 0):
210                rows.append('')
211
212            rows.append(f"User{separator}{user}")
213
214            for assignment in sorted(self.assignments):
215                score = self.get(assignment, user)
216
217                text = empty_value
218                if (score is not None):
219                    text = str(score.score)
220
221                rows.append(f"{assignment}{separator}{text}")
222
223        return rows
224
225    def get_headers(self,
226            pretty_headers: bool = False,
227            **kwargs: typing.Any) -> typing.List[str]:
228        return ['User'] + [str(query) for query in sorted(self.assignments)]
229
230    def as_table_rows(self,
231            empty_value: str = '',
232            **kwargs: typing.Any) -> typing.List[typing.List[str]]:
233        rows = []
234        for user in sorted(self.users):
235            row = [str(user)]
236            for assignment in sorted(self.assignments):
237                score = self.get(assignment, user)
238
239                text = empty_value
240                if (score is not None):
241                    text = str(score.score)
242
243                row.append(text)
244
245            rows.append(row)
246
247        return rows
248
249    def as_json_dict(self,
250        include_extra_fields: bool = False,
251            **kwargs: typing.Any) -> typing.Dict[str, typing.Any]:
252        """
253        Get a dict representation of this object meant for display as JSON.
254        (Note that we are not returning JSON, just a dict that is ready to be converted to JSON.)
255        Calling this method differs from passing this object to json.dumps() (or any sibling),
256        because this method may not include all fields, may flatten or alter fields, and will order fields differently.
257        """
258
259        scores = []
260        for assignment in sorted(self.assignments):
261            row = []
262            for user in sorted(self.users):
263                score: typing.Any = self.get(assignment, user)
264                if (score is not None):
265                    score = score.as_json_dict(include_extra_fields = include_extra_fields, **kwargs)
266
267                row.append(score)
268
269            scores.append(row)
270
271        return {
272            'assignments': self.assignments,
273            'users': self.users,
274            'scores_assignment_user': scores,
275        }
276
277    def __len__(self) -> int:
278        return len(self._entries)