lms.model.base

  1import typing
  2
  3import edq.util.json
  4import edq.util.time
  5
  6import lms.model.constants
  7import lms.util.string
  8
  9TEXT_SEPARATOR: str = ': '
 10TEXT_EMPTY_VALUE: str = ''
 11
 12T = typing.TypeVar('T', bound = 'BaseType')
 13
 14class BaseType(edq.util.json.DictConverter):
 15    """
 16    The base class for all core LMS types.
 17    This class ensures that all children have the core functionality necessary for this package.
 18
 19    The typical structure of types in this package is that types in the model package extend this class.
 20    Then, backends may declare their own types that extend the other classes from the model package.
 21    For example: lms.model.base.BaseType -> lms.model.assignments.Assignment -> lms.backend.canvas.model.assignments.Assignment
 22
 23    General (but less efficient) implementations of core functions will be provided.
 24    """
 25
 26    CORE_FIELDS: typing.List[str] = []
 27    """
 28    The common fields shared across backends for this type that are used for comparison and other operations.
 29    Child classes should set this to define how comparisons are made.
 30    """
 31
 32    INT_COMPARISON_FIELDS: typing.Set[str] = {'id'}
 33    """
 34    Fields that should be compared like ints (even if they are strings).
 35    By default, this set will include 'id'.
 36    """
 37
 38    def __init__(self,
 39            **kwargs: typing.Any) -> None:
 40        self.extra_fields: typing.Dict[str, typing.Any] = kwargs.copy()
 41        """ Additional fields not common to all backends or explicitly used by the creating child backend. """
 42
 43    def __eq__(self, other: object) -> bool:
 44        if (not isinstance(other, BaseType)):
 45            return False
 46
 47        # Check the specified fields only.
 48        for field_name in self.CORE_FIELDS:
 49            if (not hasattr(other, field_name)):
 50                return False
 51
 52            value_self = getattr(self, field_name)
 53            value_other = getattr(other, field_name)
 54
 55            if (field_name in self.INT_COMPARISON_FIELDS):
 56                comparison = lms.util.string.compare_maybe_ints(value_self, value_other)
 57                if (comparison != 0):
 58                    return False
 59            elif (value_self != value_other):
 60                return False
 61
 62        return True
 63
 64    def __hash__(self) -> int:
 65        values = tuple(getattr(self, field_name) for field_name in self.CORE_FIELDS)
 66        return hash(values)
 67
 68    def __lt__(self, other: 'BaseType') -> bool:  # type: ignore[override]
 69        if (not isinstance(other, BaseType)):
 70            return False
 71
 72        # Check the specified fields only.
 73        for field_name in self.CORE_FIELDS:
 74            if (not hasattr(other, field_name)):
 75                return False
 76
 77            value_self = getattr(self, field_name)
 78            value_other = getattr(other, field_name)
 79
 80            if (field_name in self.INT_COMPARISON_FIELDS):
 81                comparison = lms.util.string.compare_maybe_ints(value_self, value_other)
 82                if (comparison == 0):
 83                    continue
 84
 85                return (comparison < 0)
 86
 87            if (value_self == value_other):
 88                continue
 89
 90            return bool(value_self < value_other)
 91
 92        return False
 93
 94    def as_text_rows(self,
 95            skip_headers: bool = False,
 96            pretty_headers: bool = False,
 97            **kwargs: typing.Any) -> typing.List[str]:
 98        """
 99        Create a representation of this object in the "text" style of this project meant for display.
100        A list of rows will be returned.
101        """
102
103        rows = []
104
105        kwargs['pretty_timestamps'] = True
106
107        for (field_name, row) in self._get_fields(**kwargs).items():
108            if (not skip_headers):
109                header = field_name
110                if (pretty_headers):
111                    header = header.replace('_', ' ').title()
112
113                row = f"{header}{TEXT_SEPARATOR}{row}"
114
115            rows.append(row)
116
117        return rows
118
119    def get_headers(self,
120            pretty_headers: bool = False,
121            **kwargs: typing.Any) -> typing.List[str]:
122        """
123        Get a list of headers to label the values represented by this object meant for display.
124        This method is a companion to as_table_rows(),
125        given the same options these two methods will produce rows with the same length and ordering.
126        """
127
128        headers = []
129
130        for field_name in self._get_fields(**kwargs):
131            header = field_name
132            if (pretty_headers):
133                header = header.replace('_', ' ').title()
134
135            headers.append(header)
136
137        return headers
138
139    def as_table_rows(self,
140            **kwargs: typing.Any) -> typing.List[typing.List[str]]:
141        """
142        Get a list of the values by this object meant for display.
143        This method is a companion to get_headers(),
144        given the same options these two methods will produce rows with the same length and ordering.
145
146        Note that the default implementation for this method always return a single row,
147        but children may override and return multiple rows per object.
148        """
149
150        return [list(self._get_fields(**kwargs).values())]
151
152    def as_json_dict(self,
153            **kwargs: typing.Any) -> typing.Dict[str, typing.Any]:
154        """
155        Get a dict representation of this object meant for display as JSON.
156        (Note that we are not returning JSON, just a dict that is ready to be converted to JSON.)
157        Calling this method differs from passing this object to json.dumps() (or any sibling),
158        because this method may not include all fields, may flatten or alter fields, and will order fields differently.
159        """
160
161        return {field_name: self._get_field_value(field_name) for field_name in self._get_fields(**kwargs)}
162
163    def _get_fields(self,
164            include_extra_fields: bool = False,
165            **kwargs: typing.Any) -> typing.Dict[str, str]:
166        """
167        Get a dictionary representing the "target" fields of this object meant for display.
168        Keys (field names) will not be modified, but values will be sent to self._value_to_text().
169        Keys are placed in the dictionary in a consistent ordering.
170        """
171
172        field_names = self.CORE_FIELDS.copy()
173
174        # Append any extra fields after the core fields.
175        if (include_extra_fields):
176            # First, include any fields that are not in self.extra_fields.
177            for extra_name in (list(vars(self).keys()) + list(self.extra_fields.keys())):
178                if (extra_name == 'extra_fields'):
179                    continue
180
181                if (extra_name not in field_names):
182                    field_names.append(extra_name)
183
184        fields = {}
185        for field_name in field_names:
186            fields[field_name] = self._value_to_text(self._get_field_value(field_name), **kwargs)
187
188        return fields
189
190    def _get_field_value(self, name: str, default: typing.Any = None) -> typing.Any:
191        """
192        Get the value for a field.
193        This is similar to `getattr(self, name, default)`,
194        but this will also check `extra_fields` if the field is not found at the top level.
195        """
196
197        if (hasattr(self, name)):
198            return getattr(self, name)
199
200        if (name in self.extra_fields):
201            return self.extra_fields[name]
202
203        return default
204
205    def _value_to_text(self,
206            value: typing.Any,
207            indent: typing.Union[int, None] = None,
208            pretty_timestamps: bool = False,
209            **kwargs: typing.Any) -> str:
210        """
211        Convert some arbitrary value (usually found within a BaseType) to a string.
212        None values will be returned as `TEXT_EMPTY_VALUE`.
213        """
214
215        if (value is None):
216            return TEXT_EMPTY_VALUE
217
218        if (hasattr(value, '_to_text')):
219            return str(value._to_text())
220
221        if (isinstance(value, (edq.util.json.DictConverter, dict, list, tuple))):
222            return str(edq.util.json.dumps(value, indent = indent))
223
224        if (pretty_timestamps and isinstance(value, edq.util.time.Timestamp)):
225            return value.pretty(short = True)
226
227        return str(value)
228
229    @classmethod
230    def from_json_dict(cls: typing.Type[T],
231            data: typing.Dict[str, typing.Any],
232            **kwargs: typing.Any) -> T:
233        """
234        Create an object from a dict that can be used for JSON.
235        This is the inverse of as_json_dict().
236        """
237
238        return typing.cast(T, cls.from_dict(data))
239
240def base_list_to_output_format(values: typing.Sequence[BaseType], output_format: str,
241        sort: bool = True,
242        skip_headers: bool = False,
243        pretty_headers: bool = False,
244        include_extra_fields: bool = False,
245        **kwargs: typing.Any) -> str:
246    """
247    Convert a list of base types to a string representation.
248    The returned string will not include a trailing newline.
249
250    The given list may be modified by this call.
251    """
252
253    values = list(values)
254
255    if (sort):
256        values.sort()
257
258    output = ''
259
260    if (output_format == lms.model.constants.OUTPUT_FORMAT_JSON):
261        output = base_list_to_json(values,
262                include_extra_fields = include_extra_fields,
263                **kwargs)
264    elif (output_format == lms.model.constants.OUTPUT_FORMAT_TABLE):
265        output = base_list_to_table(values,
266                skip_headers = skip_headers, pretty_headers = pretty_headers,
267                include_extra_fields = include_extra_fields,
268                **kwargs)
269    elif (output_format == lms.model.constants.OUTPUT_FORMAT_TEXT):
270        output = base_list_to_text(values,
271                skip_headers = skip_headers, pretty_headers = pretty_headers,
272                include_extra_fields = include_extra_fields,
273                **kwargs)
274    else:
275        raise ValueError(f"Unknown output format: '{output_format}'.")
276
277    return output
278
279def base_list_to_json(values: typing.Sequence[BaseType],
280        indent: int = 4,
281        extract_single_list: bool = False,
282        **kwargs: typing.Any) -> str:
283    """ Convert a list of base types to a JSON string representation. """
284
285    output_values = [value.as_json_dict(**kwargs) for value in values]
286    if (extract_single_list and (len(output_values) == 1)):
287        output_values = output_values[0]  # type: ignore[assignment]
288
289    return str(edq.util.json.dumps(output_values, indent = indent, sort_keys = False))
290
291def base_list_to_table(values: typing.Sequence[BaseType],
292        skip_headers: bool = False,
293        delim: str = "\t",
294        **kwargs: typing.Any) -> str:
295    """ Convert a list of base types to a table string representation. """
296
297    rows = []
298
299    if ((len(values) > 0) and (not skip_headers)):
300        rows.append(values[0].get_headers(**kwargs))
301
302    for value in values:
303        rows += value.as_table_rows(**kwargs)
304
305    return "\n".join([delim.join(row) for row in rows])
306
307def base_list_to_text(values: typing.Sequence[BaseType],
308        **kwargs: typing.Any) -> str:
309    """ Convert a list of base types to a text string representation. """
310
311    output = []
312
313    for value in values:
314        rows = value.as_text_rows(**kwargs)
315        output.append("\n".join(rows))
316
317    return "\n\n".join(output)